KEYBOARD(5)

💖 KEYBOARD(5) 💖

okay bestie, welcome to the keyboard manual page, straight out of the Console-setup User's Manual. it's giving "your keyboard's whole personality lives in one lil file." let's get into it 🎀

---

✨ NAME ✨

keyboard — the keyboard configuration file, aka the glow-up document for your keys ⌨️💅

---

🌸 DESCRIPTION 🌸

so the keyboard file describes the properties of your keyboard. like, all of them. it gets read by setupcon(1) so it can configure the keyboard on the console. on Debian systems, the default keyboard layout lives in /etc/default/keyboard, and — plot twist — it's shared between X and the console. one file, two worlds, iconic behavior honestly 🫶

the way this works is that the layout spec in the keyboard file is based on the XKB options XkbModel, XkbLayout, XkbVariant and XkbOptions. and yeah, ngl, there's little documentation on how to actually use them 😭 but bestie, the description of all possible values for these options can be found in the file base.lst. so that's your girl. go there.

you might also wanna read "The XKB Configuration Guide" by Kamil Toman and Ivan U. Pascal:

http://www.xfree86.org/current/XKB-Config.html

other possible readings (the reading list is reading, fr fr):

https://wiki.archlinux.org/index.php/X_KeyBoard_extension
http://pascal.tsu.ru/en/xkb/
http://www.charvolant.org/~doug/xkb/

and if you want the complete XKB-specification, it's on:

http://xfree86.org/current/XKBproto.pdf

now, the keyboard file itself? it's just variable settings in POSIX format:

VARIABLE=VALUE

⚠️ only ONE assignment per line, bestie. do not get cute with it. comments starting with # are also allowed, so you can leave lil notes for yourself 💌

---

💅 OPTIONS 💅

here's the whole squad of variables you can set. no skipping, we're covering every single one 👑

• XKBMODEL — specifies the XKB keyboard model name. Default: pc105 on most platforms. she's the blueprint 🦋
• XKBLAYOUT — specifies the XKB keyboard layout name. this is usually the country or language type of the keyboard. Default: us on most platforms 🌎
• 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. these are the divas of your keyboard 🎀
• 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 settings and the kernel of your operating system will be used to determine 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-conformant behavior: <BackSpace> will generate ^? (ASCII DEL) and <Delete> will generate a special function sequence. choose wisely bestie 😌
• 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 loadkeys(1) on Linux or for kbdcontrol(1) on FreeBSD. the backup plan energy ✨

---

🦋 FILES 🦋

• the standard location of the keyboard file is /etc/default/keyboard. home sweet home 🏠
• description of all available keyboard models, layouts, variants and options is available in /usr/share/X11/xkb/rules/base.lst. the lore document 📜
• in most cases, in /lib/kbd/keymaps/ you will find several keymaps that can be used with the variable KMAP. the options are options-ing 🧚

---

🌈 NOTES 🌈

on Debian systems, changes in /etc/default/keyboard do not become immediately visible to X. rude, i know 💀 you should either reboot the system, or use:

udevadm trigger --subsystem-match=input --action=change

and to activate the changes on the console, run setupcon(1). slay 🫶

---

💀 BUGS 💀

okay so these are the known quirks, no cap, be aware:

• 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. it's giving chaos but that's literally how it is 😭
• on FreeBSD triple- and quadruple-layouts are not supported on the console (only the first and the second layout are taken into account). FreeBSD said two is enough bestie 🙈
• the option grp:shifts_toggle is not supported on the console. periodt 💅

---

⭐ EXAMPLES ⭐

example 1 — 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

example 2 — 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 it 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

example 3 — 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)

---

and that's the whole page bestie, you ate that 💖 this was console-setup, dated 2011-03-17, and it's the KEYBOARD(5) manual. go forth and configure your keys, main character ⌨️✨🦋