Keyboard Configuration

Introduction

Now that UTF-8 is the standard encoding in Debian, it's a little bit tricky to get all the pieces working together smoothly, so you can type special characters (like Å, é, ½, ¢, and °) easily, and see them displayed correctly on your screen. At least three systems have to cooperate: the keyboard (so that the correct character can be produced); a keymap (which translates the code generated by the keyboard into the desired UTF-8 character); and the display font (so you can see it on the screen). Unfortunately, things are a little more complicated than that, because different subsystems are involved in “console” mode (the glass-tty display you see when NOT using the windowing system) and in X11.

In the Bad Old Days, the X Window System did everything differently from any other program; it was basically its own operating system, sitting on top of Linux (or whatever OS it ran on). As of Debian 6.0 (“Squeeze”), X has become a more normal application that uses the kernel's I/O facilities, instead of talking to the hardware directly. (There's a good, readable explanation of this improved integration here).

As a result, we no longer have to deal with the keyboard layout completely separately in X and in consoles (i.e., the so-called Virtual Terminals). The layout of the keyboard is handled for both systems by the keyboard-configuration package, whose configuration file is /etc/default/keyboard . Information describing the keyboard, which used to be in the InputDevice section of /etc/X11/xorg.conf, now goes in /etc/default/keyboard, and also describes the keyboard for the consoles.

It's still possible to have completely different arrangements for the consoles and X, if you like. This means that it's still necessary to do some of the configuration for consoles separately. That part is handled by the console-setup package. (In particular, it's still necessary to define Compose sequences separately for consoles and for X.) And console-setup does things that used to be done by packages like console-tools , which is now being superseded by kbd .

Furthermore, you may need to have things properly set up for various “application” programs, particularly under X. (For example, you not only need a UTF-8-aware terminal emulator, like urxvt or uxterm ; you need to have it behave properly when sent the Print code, if you want the “Print Scrn” key to work.)

Finally, the 2002 HOWTO file /usr/share/doc/HOWTO/en-txt/Keyboard-and-Console-HOWTO.gz (available on the Web at http://tldp.org/HOWTO/Keyboard-and-Console-HOWTO.html) is by now quite obsolete, although some of its information is still useful. In particular, the ISO-8859-1 setups it described as the latest thing a decade ago are completely superseded by UTF-8. (Also, the file /usr/share/doc/doc-linux-html/HOWTO/Font-HOWTO/index.html has almost equally stale info on fonts.) So we need a new guide to setting things up.

This page is a start.

Instructions

Preliminaries

Locale

Make sure your locale is one of the UTF-8 ones. The command

locale

should show UTF-8 in most of the lines of output, especially LANG and LC_CTYPE. If not, edit (as root) /etc/default/locale , which should contain something ending in UTF-8, such as:

LANG=en_US.UTF-8

Or, run

dpkg-reconfigure locales (see http://wiki.debian.org/Locale for details).

Keyboard

Keyboard geometry, or layout

It's important to distinguish between the geometry or layout of the keyboard and the conversion of keystrokes to character codes. Keyboard layout has to do with the arrangement of the keys: qwerty vs. azerty vs. dvorak, for example; and the presence or absence of a numeric keypad at the right side. These things are taken care of by the keyboard-configuration package, so that

dpkg-reconfigure keyboard-configuration

sets up the keyboard geometry for both the consoles and X.

It's often helpful to see how the package is currently configured. The command

debconf-show keyboard-configuration

will show you the answers to all the many questions asked by the dpkg-reconfigure command, and may reveal what's wrong. Then you'll know what to change when you reconfigure the package.

Although the keyboard-geometry description in /etc/default/keyboard sets XKB variables inherited from Xorg.conf, don't be misled into thinking that these determine just the X keyboard: they also set the console keyboard geometry.

However, the documentation for these things is all under X. So, see man X , especially the KEYBOARDS section near the end, and the various XKB environment variables. The directories /usr/share/X11/xkb/* have the keyboard-layout definitions. A clear introduction to these directories is here.

Because these definitions are complex and difficult for a beginner to understand, it's probably simpler just to draw a picture of the keyboard:

Keyboard pictures

There is a program called xkbprint that will produce a PostScript drawing of a keyboard. Its man page is very cryptic; it refers to a “compiled keymap (.xkm) file”; but there are no .xkm files in the filesystem. However, it mentions xkbcomp in the “SEE ALSO” items at the end.

In turn, the man page for xkbcomp says it can convert an .xkb file into an .xkm file, but without saying where you can find the .xkb description of a keyboard; again, there are no files of this kind among the distributed X files.

However, if you Google long enough for this suffix, you eventually find that the program setxkbmap can produce this format as output. And setxkbmap has all sorts of options that refer to keyboard models that actually exist — see, for example, any of the identical files:

/usr/share/X11/xkb/rules/base.lst /usr/share/X11/xkb/rules/xfree86.lst /usr/share/X11/xkb/rules/evdev.lst /usr/share/X11/xkb/rules/xorg.lst

So the process of generating a keyboard image for the Logitech keyboard called “logiik” in these list-files goes like this:

	setxkbmap -model logiik -print  > logiik.map
	xkbcomp -xkm logiik.map
	xkbprint -label symbols logiik.xkm logiik.ps

Use gv to display the PostScript file logiik.ps ; you'll need to change the orientation from “Landscape” to “Seascape”, and increase the scale to about 4 to read all the small annotations. Notice that the keycode of each key is printed in very tiny numbers below each key; if you want to read these numbers easily, replace “symbols” with “code” in the xkbprint command line.

Unspecified values and components always default to your current configuration. So, if you want to see what X thinks your current keyboard looks like, just omit the “model” specification to setxkbmap and use

	setxkbmap -print  > current.map

to get your current map; then you can use current instead of logiik as the base name of the resulting files. If you want to see what a French keyboard looks like, use -layout fr instead of -model logiik in the example; that produces a picture of your keyboard with an azerty layout.

Keyboard discussion

Because the X description of keyboards was more comprehensive than the console description, the X version has been become the basis for the common treatment of keyboard configuration. However, this forces users to deal with all the complexity of the XKB system.

The reasons for this complexity are historical. For one thing, X has been around for a long time, during which hardware features have evolved considerably. Keyboards have become more complicated, adding power-control and special internet and “media” keys. And, as keyboard styles have proliferated, configuration schemes that were adequate for a small selection of features have become unwieldy. So new configuration methods have been added, while older ones had to be kept for backward compatibility.

As a result, we now have three or four different ways to configure the X keyboard, as explained by Ivan Pascal. (Again, see here for a discussion of the two main approaches.) All of them are complicated enough that you are unlikely to get everything exactly right on the first try. On the other hand, you don't really have to: once the alphabetic keys are in the right places, so you can type commands and edit configuration files, the more obscure details — usually involving those special keys, like Print Screen and Page Up, between the alphabetic keys and the numeric keypad on “pc104” keyboards — can be handled as final adjustments (see the discussion of xmodmap, below.)

So you can regard keyboard configuration as a matter of successive approximations, and tweak the fine details until you're happy with the result.

See http://madduck.net/docs/extending-xkb/ for more information on selecting the keyboard model, as well as examples of how to make XKB work. All the gory details are given at the X.Org website, which also has the XKB Configuration Guide, (which you should already have in several formats in the /usr/share/doc/xorg-docs/input directory, if you have installed the xorg-docs package).

Consoles

Consoles are variously referred to as Linux consoles, Linux terminals, virtual terminals or VTs, etc. Most of the console-setup documents just call them “consoles”, so I'll do that here, too.

REMEMBER: “console” means the bootup glass-tty mode, NOT an Xterm.
You must be root, and at a console, to set up the consoles properly.

After running

dpkg-reconfigure keyboard-configuration

to set the keyboard geometry, most of what needs to be done is accomplished by running:

setupcon -v

as ROOT from a CONSOLE — NOT over the wire, or in an X terminal session !!

The setupcon script reads configuration data from /etc/default/keyboard , converts the keyboard configuration specified by the XKB parameters in that file to console-type data with ckbcomp , saves the result in the compressed keymap file /etc/console-setup/cached.kmap.gz , and loads the console from /etc/console-setup/cached.kmap.gz by invoking loadkeys .

If you need (or want) special features, such as unusual key translations not included in the standard alternatives, minor changes to the console keymap can be put in /etc/console-setup/remap.inc , which will be appended to the cached.kmap file.

4. See man install-keymap for final steps. This installs the console keymap used at boot-time,

/etc/console/boottime.kmap.gz .

This boot-time keymap is used only during the early stages of the boot process. Normally, you'll never deal with it; so it doesn't need a lot of compose sequences, or other fancy stuff. However, it's essential that it be reliable, as it's all you have if booting fails in early stages. Therefore, a backup version of this is kept in the “default” keymap (either /etc/console-tools/default.kmap.gz or /etc/kbd/default.kmap.gz — depending on which of these two conflicting packages you have installed.)

Notice that all console keymap files have the .kmap extension, and are all normally used in gzipped format (*.gz). For the format of these files, see:

man keymaps

Terminology: "keynumber" means the key's I.D. number; use showkey in a console to find it.

"keysym" is the symbolic name of the associated action; "dumpkeys -l" shows the full list.

A large library of *.kmap.gz files for most standard keyboards is in /usr/share/keymaps/*/ ...

5. Note that the format of the console is set during the boot sequence.

In particular, if the framebuffer takes over, you may need to add a parameter like "video=640x480" to the kernel command line, in the configuration file(s) for your bootloader (e.g., lilo or grub).

Furthermore, there is a sed script called "remap" that lives in either /etc/console-setup or /etc/kbd (depending on which package you use), and is called during the init sequence, when it modifies the output of dumpkeys to the form actually in use once the system is up. This is typically used to swap pairs of keys like <Ctrl>/<Shift>, or <BS>/<DEL>.

X-Window keyboard

Reference manual on XKB:
on the Web:
http://www.freedesktop.org/wiki/Software/XKeyboardConfig/
or read:
/usr/share/doc/xorg-docs/input/XKB-Config.html

IMPORTANT: Make sure you are using a Unicode-capable terminal emulator (like urxvt or uxterm) in your .xsession file!

Adjusting the X-keyboard with `xmodmap`

To see the current keycode and keysym for a particular key in X, use

xev

(see man xev ).

To see the current X keyboard mapping, use

xmodmap -pke

So, to see what lines to put in your .Xmodmap file, you get the keycodes from xev, and the desired character or action from

/usr/include/X11/keysymdef.h ,

which lists all the regular keysyms, prefixed by XK_ . This file is in package x11proto-core-dev, which is still in "jessie" (Debian 8).

System Files

Console files:
--------------
/etc/default/keyboard	refers to the default keyboard *layout*,
			not the full key-mapping.  See:

		/usr/share/doc/console-setup/README.gz

/usr/share/doc/keyboard-configuration/README.Debian	tells more about this.
							(See  man setupcon )

(These both come from the keyboard-configuration package.)

X-Window files:
---------------
/usr/include/X11/keysymdef.h	All regular keysyms, prefixed by XK_
/usr/include/X11/XF86keysym.h	All vendor-specific keysyms, prefixed by XF86K_
/usr/share/X11/XKeysymDB	All special X functions, mapped or not
/usr/share/X11/locale/en_US.UTF-8/Compose	Compose-key database


LOCAL FILES:
============
default.kmap	gunzipped from /etc/console-tools/default.kmap.gz
defkeymap.kmap	gunzipped from /usr/share/keymaps/i386/qwerty/defkeymap.kmap.gz

Special keys

BS and DEL

This is nicely handled in the console if ROOT runs the command

fix_bs_and_del

in a console; it's in the console-tools package. [It's missing from that package's modern replacement, kbd.]

Print Scrn

In debian “squeeze”, this key was disabled (for the good reason that one frequently hits it by mistake while aiming for the key). However, the problem can be nicely solved by re-enabling it when or or are pressed, while making the key generate BackSpace in normal mode. To do this, put

keycode 107 = BackSpace Print Print Print

in your .Xmodmap file. This makes the key print what's on the screen if is held down while pressing the key. Furthermore, it prints the whole stored scrollback buffer if you also press either or .

Note that these key-presses generate the “Print” keysym, which is sent to the terminal emulator (urxvt) in X. However, there's still a problem if there are Unicode characters that need to be mapped before being sent to the printer.

Back to the . . .
main LaTeX page

or the alphabetic index page

or the GF home page

or the website overview page