The XKB Configuration Guide

Kamil Toman

Ivan U. Pascal

   X Version 11, Release 7.7

   November 2010

   This document describes how to configure Xorg XKB from a user's
   point of view. It covers basic configuration syntax and gives
   also a few examples.

   This version covers Xorg server versions 1.8 and later, used
   with the data files from the xkeyboard-config project.
     __________________________________________________________

   Table of Contents

   Overview
   Selecting XKB Configuration

        Basic Configuration
        Advanced Configuration
        Even More Advanced Configuration
        Basic Global Options

   Keymap XKB Configuration

Overview

   The XKB configuration is decomposed into a number of
   components. Selecting proper parts and combining them back you
   can achieve most of the configurations you might need. Unless
   you have a completely atypical keyboard you really don't need
   to touch any of the xkb configuration files.

   Some desktop environments now provide integrated graphical
   configuration tools for setting XKB configuration as part of
   your desktop session. The instructions in this document are
   provided for those without such support, those who need to
   configure XKB before the session startup (such as at the login
   screen), or those who need to perform more advanced
   configuration than those tools provide.

Selecting XKB Configuration

   The easiest and the most natural way to specify a keyboard
   mapping is to use the rules component. As its name suggests it
   describes a number of general rules to combine all bits and
   pieces into a valid and useful keyboard mapping. All you need
   to do is to select a suitable rules file and then to feed it
   with a few parameters that will adjust the keyboard behaviour
   to fulfill your needs.

   The parameters are:

   XkbRules

   files of rules to be used for keyboard mapping composition

   XkbModel

   name of the model of your keyboard type

   XkbLayout

   layout(s) you intend to use

   XkbVariant

   variant(s) of the layout you intend to use

   XkbOptions

   extra xkb configuration options

   The rules file used depends on your system. The rules files
   commonly used with Xorg are provided by the xkeyboard-config
   project. On Linux systems, the evdev rules are most commonly
   used, on other systems the base rules are used. Some additional
   rules files exist for historical reasons, but are no longer
   widely used. In general, it's best to simply not specify the
   rules file, in order to use the default rules selected
   automatically by the X server.

   For each rules file there is a description file named
   <vendor-rules>.lst, for instance base.lst which is located in
   the xkb configuration subdirectory rules (for example
   /usr/share/X11/xkb/rules).

Basic Configuration

   Let's say you want to configure a PC-style American keyboard
   with 104 keys as described in base.lst. This can be done by
   simply writing several lines from below to a new configuration
   file in /etc/X11/xorg.conf.d, such as
   /etc/X11/xorg.conf.d/90-custom-kbd.conf.
Section "InputClass"
    Identifier "keyboard defaults"
    MatchIsKeyboard "on"

    Option "XkbModel" "pc104"
    Option "XkbLayout" "us"
    Option "XKbOptions" ""
EndSection

   The values of XkbModel and XkbLayout are really not surprising.
   The XkbOptions has been explicitly set to the empty set of
   parameters. The XkbVariant option has been left out. That means
   the default variant named basic is loaded.

   Of course, this can be also done at runtime using the utility
   setxkbmap. The shell command loading the same keyboard mapping
   would look like:
setxkbmap -model pc104 -layout us -option ""

   The configuration and the shell command would be very analogous
   for most other layouts (internationalized mappings).

   If you wanted to enable the Ctrl+Alt+Backspace sequence to kill
   the X server by default, you could create a configuration
   snippet /etc/X11/xorg.conf.d/90-zap.conf containing:
Section "InputClass"
    Identifier "keyboard defaults"
    MatchIsKeyboard "on"

    Option "XKbOptions" "terminate:ctrl_alt_bksp"
EndSection

   This would be equivalent to running the shell command:
setxkbmap -option "terminate:ctrl_alt_bksp"

Advanced Configuration

   You can use multi-layouts xkb configuration. What does it mean?
   Basically it allows to load up to four different keyboard
   layouts at a time. Each such layout would reside in its own
   group. The groups (unlike complete keyboard remapping) can be
   switched very fast from one to another by a combination of
   keys.

   Let's say you want to configure your new Logitech cordless
   desktop keyboard, you intend to use three different layouts at
   the same time - us, czech and german (in this order), and that
   you are used to Alt+Shift combination for switching among them.

   Then the configuration snippet could look like this:
Section "InputClass"
    Identifier "Logitech Cordless"
    MatchIsKeyboard   "on"

    Option "XkbModel" "logicordless"
    Option "XkbLayout" "us,cz,de"
    Option "XKbOptions" "grp:alt_shift_toggle"
EndSection

   Of course, this can be also done at runtime using the utility
   setxkbmap. The shell command loading the same keyboard mapping
   would look like:
setxkbmap -model logicordless -layout "us,cz,de" \
         -option "grp:alt_shift_toggle"

Even More Advanced Configuration

   Okay, let's say you are more demanding. You do like the example
   above but you want it to change a bit. Let's imagine you want
   the czech keyboard mapping to use another variant but basic.
   The configuration snippet then changes into:
Section "InputClass"
    Identifier "Logitech Cordless"
    MatchIsKeyboard   "on"

    Option "XkbModel" "logicordless"
    Option "XkbLayout" "us,cz,de"
    Option "XkbVariant" ",bksl,"
    Option "XKbOptions" "grp:alt_shift_toggle"
EndSection

   That seems tricky but it is not. The logic for settings of
   variants is the same as for layouts, that means the first and
   the third variant settings are left out (set to basic), the
   second is set to bksl (a special variant with an enhanced
   definition of the backslash key).

   Analogously, the loading runtime will change to:
setxkbmap -model logicordless -layout "us,cz,de" \
         -variant ",bksl," -option "grp:alt_shift_toggle"

Basic Global Options

   For a list of available options, with a short description of
   what they do, see the section starting with "! option" in the
   rules/*.lst files.

Keymap XKB Configuration

   Keymap configuration is the way formerly used to configure xkb.
   The user included a special keymap file which specified the
   direct xkb configuration. This method has been obsoleted by
   previously described rules files which are far more flexible
   and allow simpler and more intuitive syntax. It is preserved
   merely for compatibility reasons and should be avoided if
   possible.
