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 pointof view. It covers basic configuration syntax and gives also a few examples.
This version covers Xorg server versions 1.8 and later, used with thedata files from the xkeyboard-config project.
The XKB configuration is decomposed into a number of components. Selectingproper parts and combining them back you can achieve most of the configurationsyou might need. Unless you have a completely atypical keyboard you really don'tneed to touch any of the xkb configuration files.
Some desktop environments now provide integrated graphical configurationtools for setting XKB configuration as part of your desktop session. Theinstructions in this document are provided for those without such support,those who need to configure XKB before the session startup (such as at thelogin screen), or those who need to perform more advanced configurationthan those tools provide.
The easiest and the most natural way to specify a keyboard mapping is to usethe rules component. As its name suggests it describes a number ofgeneral rules to combine all bits and pieces into a valid and useful keyboardmapping. All you need to do is to select a suitable rules file and then tofeed it with a few parameters that will adjust the keyboard behaviour tofulfill your needs.
The parameters are:
| files of rules to be used for keyboard mapping composition |
| name of the model of your keyboard type |
| layout(s) you intend to use |
| variant(s) of the layout you intend to use |
| extra xkb configuration options |
The rules file used depends on your system. The rules files commonlyused with Xorg are provided by the xkeyboard-config project.On Linux systems, the evdev rules are mostcommonly used, on other systems the base rulesare used. Some additional rules files exist for historical reasons,but are no longer widely used. In general, it's best to simply notspecify the rules file, in order to use the default rules selectedautomatically by the X server.
For each rules file there is a description file named<,for instance vendor-rules>.lstbase.lst which is located inthe xkb configuration subdirectory rules(for example /usr/share/X11/xkb/rules).
Let's say you want to configure a PC-style American keyboard with 104keys as described in base.lst. This can be doneby simply writing several lines from below to a new configuration filein /etc/X11/xorg.conf.d, suchas /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 arereally not surprising. The XkbOptionshas been explicitly set to the empty set of parameters.The XkbVariant option has been left out.That means the default variant named basicis loaded.
Of course, this can be also done at runtime using the utilitysetxkbmap.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 analogousfor most other layouts (internationalized mappings).
If you wanted to enable the Ctrl+Alt+Backspace sequence to killthe 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 differentkeyboard layouts at a time. Each such layout would reside in itsown group. The groups (unlike complete keyboard remapping) can beswitched very fast from one to another by a combination of keys.
Let's say you want to configure your new Logitech cordless desktopkeyboard, you intend to use three different layouts at the sametime - us, czech and german (in this order), and that you are used toAlt+Shiftcombination 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 utilitysetxkbmap.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 exampleabove but you want it to change a bit. Let's imagine you wantthe 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 variantsis the same as for layouts, that means the first and the third variantsettings are left out (set to basic),the second is set to bksl (a specialvariant 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"
Keymap configuration is the way formerly used to configure xkb. Theuser included a special keymap file which specified the direct xkbconfiguration. This method has been obsoleted by previously describedrules files which are far more flexible and allow simpler and moreintuitive syntax. It is preserved merely for compatibility reasons andshould be avoided if possible.
