User XKB Customization

Customization

I give here some information on XKB (X keyboard extension), in particular to modify the configuration as a simple user (without root access). Thus my XKB configuration completely replaced my old .xmodmaprc file (which didn't work correctly with the new kbd driver).

Two useful commands:

• To output the current settings: setxkbmap -print

• To dump the current XKB keyboard description to a file xkb.dump: xkbcomp $DISPLAY xkb.dump

In one's $HOME, create a directory .xkb and 2 or 3 subdirectories:

• keymap: this directory will contain a file with the keyboard settings. It may be based on the output of setxkbmap -print.

• symbols: this directory will contain a file with the remapped keys. Examples can be found thanks to xkbcomp $DISPLAY xkb.dump (see the xkb_symbols section) or files from the /usr/share/X11/xkb/symbols directory (for instance, see files latin and pc).

  Example: my ~/.xkb/symbols/local file.

• types (optional): this directory can contain a file with new key types, if need be.

  Example: my ~/.xkb/types/local file.

To use these local settings, I have the following lines in my ~/.xsession script:

if [ -d $HOME/.xkb/keymap ]; then
  setxkbmap -types local -print | \
    sed -e '/xkb_symbols/s/"[[:space:]]/+local&/' > $HOME/.xkb/keymap/custom
  xkbcomp -w0 -I$HOME/.xkb -R$HOME/.xkb keymap/custom $DISPLAY
fi

This creates a ~/.xkb/keymap/custom file looking like:

xkb_keymap {
  xkb_keycodes  { include "evdev+aliases(qwerty)" };
  xkb_types     { include "local" };
  xkb_compat    { include "complete" };
  xkb_symbols   { include "pc+gb+inet(evdev)+level3(ralt_switch)+local" };
  xkb_geometry  { include "pc(pc105)" };
};

(some parts may change depending on the keyboard, except the local's) and selects these settings when the user X session is started.

References:

• A message from Denis Barbier in the debian-user-french list.

• Extending the X keyboard map with xkb by Martin F. Krafft.

Note: This is here just keyboard configuration. Character set (encoding) configuration is another matter and depends on the locales. You can check what you get with the xev utility; look at the XLookupString line.

A Remark About Modifiers in the Default Configuration

I was quite surprised to see that in the default configuration, a modifier could modify another modifier:

key <RALT> { type= "TWO_LEVEL", symbols[Group1]= [ ISO_Level3_Shift, Multi_key ] };

so that Shift+AltGr gave Multi_key while AltGr+Shift gave Shift+LevelThree.

Restoring the XKB Settings After Suspend/Resume

Unfortunately, mainly for laptop users, XKB settings are lost after suspend/resume (this was also the case with xmodmap). There is a workaround: save them and restore them via pm-utils with a script in the /etc/pm/sleep.d directory, like my xkb-save-restore script, stored as /etc/pm/sleep.d/40xkb-save-restore for instance. You may also need to execute

xhost +si:localuser:root

in your ~/.xsession since the script is executed by root at suspend and resume time, and root's environment does not have the user's xauth information (MIT-MAGIC-COOKIE-1), which would allow him to have access to the keyboard configuration without a special authorization.

Note: The drawback (or advantage) of the above command is that root can permanently have access to the user's display. This is not really a security issue since root controls everything on the machine, and in particular, can have access to the magic cookie by various means. But the user should be careful not to start some X applications as root by mistake.

The only real issue is that when the settings are to be restored, though xkbcomp terminates with no errors, it sometimes has no effect.

Low-Level Remapping of Particular Keyboards

On some keyboards, keys are misplaced and for instance, one may want to swap keys. XKB must not be used for that, as the effect would be applied to every keyboard. One needs to modify the driver-level keymap file via udev.

For instance, for my Apple Aluminum USB keyboard (which I use with my laptop, so that it is a second keyboard), I have used the following solutions, depending on the udev version.

Note: The scancode of a physical key can be obtained with the evtest utility. It suffices to type the key and look at a line like:

Event: time 1452726874.519482, type 4 (EV_MSC), code 4 (MSC_SCAN), value 70068

The scancode is here 70068 (this is a hexadecimal value).

See Also

The Keyboards category of the Arch Linux wiki has interesting information.