November 2010
Abstract
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
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.
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 xkeyboard-config.
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
<,
for instance vendor-rules>.lstbase.lst which is located in
the xkb configuration subdirectory rules
(for example /usr/share/X11/xkb/rules).
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"
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"
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"
Generally, you can directly prescribe what configuration of each of basic xkb components should be used to form the resulting keyboard mapping. This method is rather “brute force”. You precisely need to know the structure and the meaning of all of used configuration components.
This method also exposes all xkb configuration details directly into xorg.conf configuration file which is a not very fortunate fact. In rare occasions it may be needed, though. So how does it work?
There are five basic components used to form a keyboard mapping:
| key codes | a translation of the scan codes produced by the keyboard into a suitable symbolic form |
| types | a specification of what various combinations of modifiers produce |
| key symbols | a translation of symbolic key codes into actual symbols |
| geometry | a description of physical keyboard geometry |
| compatibility maps | a specification of what action should each key produce in order to preserve compatibility with XKB-unware clients |
Look at the following example:
Section "InputClass"
Identifier "keyboard defaults"
MatchIsKeyboard "on"
Option "XkbKeycodes" "xfree86"
Option "XkbTypes" "default"
Option "XkbSymbols" "en_US(pc104)+de+swapcaps"
Option "XkbGeometry" "pc(pc104)"
Option "XkbCompat" "basic+pc+iso9995"
EndSection
This configuration sets the standard X server default interpretation of keyboard keycodes, and sets the default modifier types. The symbol table is composed of extended US keyboard layout in its variant for pc keyboards with 104 keys plus all keys for german layout are redefined respectively. Also the logical meaning of Caps-lock and Control keys is swapped. The standard keyboard geometry (physical look) is set to pc style keyboard with 104 keys. The compatibility map is set to allow basic shifting, to allow Alt keys to be interpreted and also to allow iso9995 group shifting.
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.