Build and Safely Test a Linux Console Keymap

You will finish with a small keymap file that changes one console key, passes the installed parser, and can be loaded with a clear way back. This guide uses kbd 2.6.4 on Linux and covers the console keymap format read by loadkeys, not X11 or Wayland keyboard configuration.

Allow about fifteen minutes. You need a shell, the kbd package, and a Linux virtual console if you intend to load the map. Creating and parsing the file is normally unprivileged. Loading it changes the kernel keyboard table for every virtual console, so that step may need elevated privileges and should wait until you have a recovery command ready.

1. Confirm the installed tools

Check the version and locations before relying on examples. These are read-only commands:

$ loadkeys --version
loadkeys from kbd 2.6.4
$ command -v loadkeys
/usr/bin/loadkeys
$ command -v dumpkeys
/usr/bin/dumpkeys

Your package revision may differ while the kbd version remains the same. The examples below use symbolic keysyms such as a, A and Caps_Lock; these are preferable to numeric action codes, whose meanings can vary between kernels.

Checkpoint: if loadkeys is missing, stop here and install kbd through your normal distribution process. Do not copy a keymap into a system directory as a substitute.

2. Inspect the current map and available actions

dumpkeys prints the active console translation tables in keymap syntax. Save a reference in your working directory if you want to compare your change later:

$ dumpkeys > before.map
$ sed -n '1,12p' before.map
keymaps 0-2,4-5,8,9,12,13
...

The first line matters. A key definition's columns correspond to the modifier combinations named by keymaps. If you omit that line, loadkeys infers maps from the longest definition, which is easy to misunderstand when a file is edited later.

Ask the installed program which symbolic actions it supports:

$ dumpkeys --long-info | less

On a machine without a usable Linux console, dumpkeys may report that it cannot read the keyboard driver. That does not prevent syntax checking, but it does prevent a meaningful live-map comparison.

3. Write a minimal, reversible map

Create caps-to-control.map in your working directory with this content:

keymaps 0-1
keycode 58 = Control
keycode 29 = Caps_Lock

Keycode 58 is normally Caps Lock and keycode 29 is normally left Control on the common PC console map. The file exchanges their actions for the plain and Shift maps selected by keymaps 0-1. Key numbers are internal identifiers, roughly related to scan codes, so confirm them for unusual hardware before loading a map.

Comments begin with ! or # and continue to the end of the line. A logical line can continue onto another physical line with a final backslash. Keep each definition simple while testing: one malformed continuation can make the next line part of the same definition.

Checkpoint: inspect the exact file before parsing it:

$ sed -n '1,10p' caps-to-control.map
keymaps 0-1
keycode 58 = Control
keycode 29 = Caps_Lock

4. Parse the file without changing the keyboard

Use loadkeys --parse for a syntax-only check. It searches for and parses the keymap without loading it into the kernel:

$ loadkeys --parse caps-to-control.map
$ printf 'parse status: %s\n' "$?"
parse status: 0

Successful parsing produces no normal output in this example. A non-zero status means the file needs attention; read the reported line number and check the keymaps line, keycode spelling and action names. Parsing does not prove that the current kernel supports every requested action, and it does not test your physical keyboard's key numbers.

5. Record a recovery map before loading

Loading is the state-changing step. Keep the current table and a reset command available in a second terminal or on another access path:

$ dumpkeys > before.map
$ loadkeys --default

The --default option asks loadkeys to load a default map, usually defkeymap.map from a standard keymap location. It may not match your preferred national layout. If the new map makes typing difficult, run that command from another virtual console, through a trusted remote shell, or with a previously prepared command. The saved file is useful for inspection, but it is not a universal recovery guarantee because it can include host-specific driver state.

Do not run the next command on a production host during an active session without a recovery path. The kernel keyboard table is shared by virtual consoles and the change can remain in force at the login prompt.

6. Load and verify the change

Load the map only after the parse check and recovery preparation:

$ sudo loadkeys ./caps-to-control.map

Use sudo only if the console device requires it. On a local virtual console, test the physical keys: Caps Lock should now act as Control and the former left Control key should act as Caps Lock. Then inspect the active table:

$ dumpkeys | grep -E 'keycode (29|58) ='
keycode  29 = Caps_Lock
keycode  58 = Control

Spacing can vary, and a map may print extra columns depending on the active modifiers. The useful check is that the two keycode assignments are present. If the output is unchanged, confirm that you loaded the file on the console you are testing and that the file was not shadowed by another keymap service.

7. Use narrower edits for real layouts

A complete definition applies its listed actions across the modifier combinations selected by the map. Trailing VoidSymbol values can be omitted. For a single modifier-specific change, use the single-action form:

plain keycode 14 = BackSpace
control alt keycode 83 = Boot

The first line changes only the unmodified action for keycode 14. The second binds a reboot action to a modifier combination, so treat it as a dangerous example to study, not a test to load. Never attach Boot or console-switch actions to an unfamiliar key while experimenting.

For ordinary character keys, one action has special shorthand behaviour. A single non-letter action is repeated through the defined columns, while a single ASCII letter receives case and control or meta forms according to the selected modifiers. Write the expanded form when the result matters more than brevity.

8. Undo the test

The map is not persistent merely because it was loaded, but it affects later users of the virtual consoles until another map replaces it. Restore your normal layout with your distribution's known keymap, or use the default map as a fallback:

$ sudo loadkeys --default

If your system normally loads a named layout, use that exact map instead of guessing. Do not delete the saved reference until the keyboard behaves normally. To remove the test file from your working directory after checking it, delete that file deliberately; nothing in this guide changes system keymap files.