Set a Linux Console Keyboard with /etc/default/keyboard

A fresh install with the wrong layout is the usual reason to open /etc/default/keyboard. It configures the layout used by the Linux virtual console, and you can apply a fix without rebooting. This guide uses the keyboard(5) format supplied by Ubuntu's keyboard-configuration package, version 1.226ubuntu1.1 on the machine used for these checks.

Allow about ten minutes. You need a shell, sudo access to edit the system file, and a second way into the machine if you are changing a remote console or an unfamiliar physical keyboard. The configuration file is shared between the console and X on Debian systems, but applying it to the console and making X notice it are separate operations.

1. Record the current configuration

Read the existing file before changing it. This step is unprivileged and gives you the exact values to restore if a test goes badly.

$ sed -n '1,120p' /etc/default/keyboard

The file on this machine contains XKBMODEL="pc105", XKBLAYOUT="us", empty XKBVARIANT and XKBOPTIONS values, plus BACKSPACE="guess". Your file may differ. Keep the quotation marks and comments unless you have a reason to change them.

Checkpoint: make sure the file exists and that you know the current XKBLAYOUT value. A layout change can make the keys you need for the next command appear to move.

2. Choose valid XKB values

The file has one POSIX-style assignment per line. The main settings are:

XKBMODEL describes the physical keyboard model. The documented default is usually pc105.
XKBLAYOUT names the layout, usually by country or language. Layouts can be comma-separated, for example us,gr.
XKBVARIANT adds layout-specific variants. When layouts are comma-separated, variants occupy the corresponding positions, such as nodeadkeys,dvorak.
XKBOPTIONS changes special-key behaviour or layout switching. Multiple options are comma-separated.

Do not guess names. The installed list is /usr/share/X11/xkb/rules/base.lst. Search it first, using a term that identifies the layout or option you want:

$ rg -n 'English \(UK\)|Dvorak|grp:toggle|compose:menu' /usr/share/X11/xkb/rules/base.lst

For a straightforward British layout, the relevant assignment is XKBLAYOUT="gb". For a US layout with Greek as a second group and the right Alt key switching groups, the manpage documents XKBLAYOUT="us,gr", an empty variant, and XKBOPTIONS="grp:toggle".

3. Back up the file before editing

This changes system configuration, so create a dated copy before using elevated privileges. The command below writes only in /etc/default and does not activate anything:

$ sudo cp -a /etc/default/keyboard /etc/default/keyboard.before-layout-change

Checkpoint: no output and a new backup file. Confirm it exists:

$ sudo ls -l /etc/default/keyboard /etc/default/keyboard.before-layout-change

Do not overwrite the backup with a second experiment. If you need another attempt, use a different name, such as keyboard.before-layout-change-2.

4. Edit the assignments

Open the file with an editor that obtains privilege only for the save operation:

$ sudoedit /etc/default/keyboard

For example, this is a complete small configuration for a generic British keyboard:

XKBMODEL="pc105"
XKBLAYOUT="gb"
XKBVARIANT=""
XKBOPTIONS=""
BACKSPACE="guess"

There must be only one assignment per line. Comments begin with #. Leaving XKBVARIANT or XKBOPTIONS empty is different from accidentally putting a second value on the same line. Keep BACKSPACE="guess" unless you specifically need the documented bs or del behaviour.

Checkpoint: save the file, then inspect the result before applying it:

$ sed -n '1,120p' /etc/default/keyboard

5. Apply the console change

Run setupcon as root to activate the keyboard on the Linux console:

$ sudo setupcon

The command normally produces no useful output when it succeeds. If you are in a graphical terminal, it may refuse to configure the console because you are not on a virtual console. That is not proof that the file is invalid. The installed command offers --verbose for diagnosis and --print-commands-only to show the commands it would use without configuring anything:

$ sudo setupcon --print-commands-only

To limit the operation to keyboard setup, use the documented option:

$ sudo setupcon --keyboard-only

Warning: applying a layout can make the current console difficult to operate if you chose the wrong layout. Keep the backup path available, and do not test an unfamiliar layout over your only remote recovery channel.

6. Make X notice the change when needed

On Debian systems, changes to /etc/default/keyboard are not immediately visible to X. The manpage gives two supported choices: reboot, or trigger the input-device change event:

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

This can affect input devices and therefore deserves the same care as any desktop input change. If you are working remotely, keep an existing session open until you have confirmed that a new session accepts the expected keys. A reboot is the simpler alternative when a maintenance window already exists.

7. Recover if the layout is wrong

Recovery is a deliberate configuration change. If you can still access a shell, restore the saved file and reapply it:

$ sudo cp -a /etc/default/keyboard.before-layout-change /etc/default/keyboard
$ sudo setupcon

Then inspect the restored assignments:

$ sed -n '1,120p' /etc/default/keyboard

If the console is unusable, use an existing SSH session, a different virtual console, or your hosting provider's out-of-band console. Do not delete the configuration file to recover: an intact known-good copy is easier to audit and restore.

8. Understand the limits

keyboard(5) describes configuration, not a universal keyboard tester. A successful setupcon run means the console setup command accepted the configuration; it does not prove that every physical key, desktop session or application will behave as you expect.

Some options are console-specific. The documented grp_led:scroll option is ignored on the console, although it can control the ScrollLock indicator in X. The grp:shifts_toggle option is not supported on the console. Triple-layout console cycling is also unusual: the documented order is group 1, group 2, group 1, then group 3. If you need predictable switching, test the exact layout and option combination at the console where it will run.

The alternative KMAP setting is normally unset. It is for a keymap file suitable for loadkeys on Linux, rather than an XKB layout. Do not set both approaches casually: first decide whether this machine should use XKB settings or an alternative keymap, then verify the result on the target console.

Done means

File reviewed: /etc/default/keyboard contains one reviewed assignment per line.
Values verified: every layout, variant and option name came from the installed XKB rules list or a known working configuration.
Backup exists: a backup exists at /etc/default/keyboard.before-layout-change, or you made an equivalent recoverable copy.
Console applied: setupcon applied the console change, or its diagnostic output gave you a specific failure to investigate.
X refreshed: X was refreshed with the documented udev trigger or will be refreshed by a planned reboot.