Set the Linux Meta Key Mode with setmetamode

If Alt-modified keys are arriving as the wrong bytes on a bare console, setmetamode is the tool that decides how Meta gets encoded. You will check or change how the Meta key is handled on one Linux virtual terminal: the command can make Meta send an Escape prefix, or set the high bit of the character. Allow about ten minutes for a one-off check, or about twenty minutes if you are making a persistent console configuration.

This guide uses setmetamode from the installed kbd package, version 2.6.4-2ubuntu2, which reports itself as kbd 2.6.4. You need a real virtual terminal such as /dev/tty1, not a graphical terminal emulator or an ordinary pseudo-terminal. Reading the current mode is unprivileged when the device permits it. Changing another virtual terminal normally needs access to that device, so use the least privilege your system allows.

Checkpoint: the read-only inspection is complete once you have identified the target VT. Do not change a shared console until you know which users or services depend on its keyboard behaviour.

1. Confirm the installed command

Check the executable, package and supported syntax. These commands only read local information:

$ command -v setmetamode
/usr/bin/setmetamode
$ dpkg-query -W -f='${Package} ${Version}\n' kbd
kbd 2.6.4-2ubuntu2
$ setmetamode --version
setmetamode from kbd 2.6.4

The command accepts one optional argument. The documented mode names are esc, prefix and escprefix for Escape-prefix handling, and meta, bit and metabit for high-bit handling. The installed help describes the same two behaviours as escprefix and metabit.

2. Read the current mode on the active VT

Switch to the virtual terminal whose keyboard you want to inspect, then run the command without an argument:

$ setmetamode
<the command reports the current mode>

The command reports either Escape-prefix or high-bit handling. The exact diagnostic wording is not specified by the manual, so check the reported mode rather than matching the whole line in a script. No argument asks for the current Meta key mode. The mode is per VT, and the VT associated with standard input is the one used, so a result from one console does not describe every other console.

To name the device explicitly, use -C or --console:

$ setmetamode --console=/dev/tty1
<the command reports the mode for /dev/tty1>

Replace /dev/tty1 with the actual target. If this reports an ioctl or device error, check the path is a Linux virtual console and that you have permission to access it:

$ stat /dev/tty1
$ test -r /dev/tty1 && echo 'device is readable'

A graphical terminal's pseudo-terminal is not a substitute for a VT: its terminal emulator may interpret Alt and Meta before the kernel console keyboard handler ever sees them.

3. Choose the encoding deliberately

Use Escape-prefix mode when applications should receive an Escape character before the Meta-modified key. Use high-bit mode when applications expect the Meta key to set the most significant bit of the character. These are different byte sequences, so pick the mode to match the software using that console.

Warning: the next commands change keyboard handling on the selected VT. They are not destructive to files, but they can disrupt a person working on that console. Record the current result from step 2 before changing it.

To request Escape-prefix mode:

$ setmetamode escprefix
<the command reports the old mode and escprefix as the new mode>

To request high-bit mode instead:

$ setmetamode metabit
<the command reports the old mode and metabit as the new mode>

The command reports the mode before and after the change, though the exact starting value in the first line depends on that VT. The aliases esc and prefix select the same Escape-prefix behaviour; meta and bit select the same high-bit behaviour.

4. Verify the result and recover if needed

Read the mode again, using the same VT and device as before:

$ setmetamode
<the command reports escprefix or metabit>

For an application-level check, use a program whose Meta binding you understand, and test only on the intended console. Do not assume seeing a key binding fire proves which byte sequence arrived. If the new mode breaks an application, restore the value recorded before step 3. For example, if it was metabit:

$ setmetamode metabit
<the command reports the old mode and metabit as the new mode>

Recovery: there is no persistent undo file for this command. The immediate change applies to the selected VT, so restoring the previous argument is the practical recovery. If you do not know the old value, run the read-only command first on another unaffected console, or recreate the session's expected keyboard setup before experimenting further.

5. Apply a setting to several consoles

The manual's boot-time pattern loops over device names and feeds each device to standard input. Adapt the list to the VTs that actually exist on your machine:

for tty in /dev/tty1 /dev/tty2 /dev/tty3; do
    setmetamode escprefix < "$tty" || {
        printf 'could not configure %s\n' "$tty" >&2
        exit 1
    }
done

This changes state on every listed console, so test one VT first. Do not paste a broad /dev/tty* glob into a startup script without checking what it matches: a device can be absent, reserved, or not be a virtual terminal at all. The command is also not a general terminal-emulator setting.

If you place this in an early-boot or login configuration, keep a recovery path. A typo in the device list or an unexpected mode can make console interaction confusing, although it does not alter files or keyboard hardware. Remove or correct the configuration entry and rerun setmetamode with the desired mode on each affected VT.

6. Keep options and limits straight

-C DEV and --console=DEV select the console device. -V or --version prints the version, and -h or --help prints usage. There is no option here to configure a graphical terminal emulator, remap a key, or make the setting system-wide across every possible VT.

The command operates on the VT connected to standard input when -C is omitted. That default is easy to miss in scripts, especially when input is redirected. Use an explicit device when the target matters, quote the path, and verify the result on the same device. Elevated privileges only grant access to a protected console device; they do not make an unsuitable pseudo-terminal behave like a VT.

Done means