KEYBOARD(5) Console-setup User's Manual KEYBOARD(5)
NAME
keyboard - keyboard configuration file
DESCRIPTION
The keyboard file describes the properties of the keyboard. It is read
by setupcon(1) in order to configure the keyboard on the console. In
Debian systems the default keyboard layout is described in /etc/de-
fault/keyboard and it is shared between X and the console.
The specification of the keyboard layout in the keyboard file is based
on the XKB options XkbModel, XkbLayout, XkbVariant and XkbOptions. Un-
fortunately, there is little documentation how to use them. Description
of all possible values for these options can be found in the file
base.lst.
You might want to read “The XKB Configuration Guide” by Kamil Toman and
Ivan U. Pascal:
http://www.xfree86.org/current/XKB-Config.html
Other possible readings are:
https://wiki.archlinux.org/index.php/X_KeyBoard_extension
http://pascal.tsu.ru/en/xkb/
http://www.charvolant.org/~doug/xkb/
The complete XKB-specification can be found on
http://xfree86.org/current/XKBproto.pdf
The file keyboard consists of variable settings in POSIX format:
VARIABLE=VALUE
Only one assignment is allowed per line. Comments (starting with '#')
are also allowed.
OPTIONS
The following variables can be set.
XKBMODEL
Specifies the XKB keyboard model name. Default: pc105 on most
platforms.
XKBLAYOUT
Specifies the XKB keyboard layout name. This is usually the coun-
try or language type of the keyboard. Default: us on most plat-
forms
XKBVARIANT
Specifies the XKB keyboard variant components. These can be used
to further specify the keyboard layout details. Default: not set.
XKBOPTIONS
Specifies the XKB keyboard option components. Options usually
relate to the behavior of the special keys (<Shift>, <Control>,
<Alt>, <CapsLock>, etc.) Default: not set.
BACKSPACE
Determines the behavior of <BackSpace> and <Delete> keys on the
console. Allowed values: bs, del and guess. In most cases you
can specify guess here, in which case the current terminal set-
tings and the kernel of your operating system will be used to de-
termine the correct value. Value bs specifies VT100-conformant
behavior: <BackSpace> will generate ^H (ASCII BS) and <Delete>
will generate ^? (ASCII DEL). Value del specifies VT220-confor-
mant behavior: <BackSpace> will generate ^? (ASCII DEL) and
<Delete> will generate a special function sequence.
KMAP Usually this variable will be unset but if you don't want to use
a XKB layout on the console, you can specify an alternative
keymap here. Specify a file that is suitable as input for load-
keys(1) on Linux or for kbdcontrol(1) on FreeBSD.
FILES
The standard location of the keyboard file is /etc/default/keyboard.
Description of all available keyboard models, layouts, variants and op-
tions is available in /usr/share/X11/xkb/rules/base.lst. In most cases,
in /usr/share/keymaps/ or /usr/share/syscons/keymaps/ you will find sev-
eral keymaps that can be used with the variable KMAP.
NOTES
In Debian systems, changes in /etc/default/keyboard do not become imme-
diately visible to X. You should either reboot the system, or use
udevadm trigger --subsystem-match=input --action=change
In order to activate the changes on the console, run setupcon(1).
BUGS
When a triple-layout is used on the console, i.e. a layout with three
XKB groups, then the group toggling happens in the following way: Group1
-> Group2 -> Group1 -> Group3.
On FreeBSD triple- and quadruple-layouts are not supported on the con-
sole (only the first and the second layout are taken into account).
The option grp:shifts_toggle is not supported on the console.
EXAMPLES
The following configuration will give you the standard US QWERTY layout
(us). The key <Menu> will act as a compose key (compose:menu) and
<CapsLock> will act as third control key (ctrl:nocaps).
XKBLAYOUT=us
XKBVARIANT=
XKBOPTIONS=compose:menu,ctrl:nocaps
In the following configuration the right <Alt> key (grp:toggle) will
toggle between US QWERTY layout (us) and Greek (gr) layout. The option
grp_led:scroll is ignored on the console but in X in means to use the
ScrollLock keyboard led as indicator for the current layout (US or
Greek).
XKBLAYOUT=us,gr
XKBVARIANT=
XKBOPTIONS=grp:toggle,grp_led:scroll
In the following configuration the <Control>+<Shift> key combination
will toggle (grp:ctrl_shift_toggle) between French keyboard (fr) without
dead keys (nodeadkeys) and British (gb) “Dvorak” (dvorak) keyboard. The
right <Win> key will be a compose-key (compose:rwin) and the right <Alt>
key will function as AltGr (lv3:lalt_switch).
XKBLAYOUT=fr,gb
XKBVARIANT=nodeadkeys,dvorak
XKBOPTIONS=grp:ctrl_shift_toggle,compose:rwin,lv3:ralt_switch
SEE ALSO
setupcon(1), ckbcomp(1), console-setup(5), loadkeys(1), kbdcontrol(1)
console-setup 2011-03-17 KEYBOARD(5)
Generated by dwww version 1.16 on Tue Dec 16 04:27:56 CET 2025.