Check Linux Console and Keyboard State with kbdinfo

kbdinfo tells you what a Linux virtual console is actually doing, which is not always what the ticket claims. It reports text or graphics mode, the keyboard input mode, meta-key handling and the state of one lock LED, all without touching the configuration. Allow about ten minutes, including time to get to the right terminal and repeat the checks from there.

The command reads kernel console state through ioctl interfaces. It is a diagnostic tool, not a general test for a graphical terminal, SSH session or terminal emulator. The examples below describe the kbd 2.6.4 package installed on this machine. Your distribution may ship a different release, so check the local binary before relying on the exact wording it prints.

1. Confirm the installed command

Start with an unprivileged version check and locate the executable:

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

The package version and path will vary on your system. If the command is missing, install the kbd package through your normal distribution process. Do not run a status query with sudo just because it concerns the keyboard: root access does not turn a graphical terminal into a Linux virtual console.

2. Run the query from a virtual console

Switch to a local Linux virtual console with a normal system key combination, log in, and run:

$ tty
/dev/tty2
$ kbdinfo getmode
text

The active console is used when -C is omitted. getmode prints either text or graphics when the query succeeds. A virtual console can be displaying text while a display manager or framebuffer setup gives it a different mode underneath, so treat the result as the kernel's console mode, not a description of what your monitor appears to show.

To query a particular console device, pass it with -C:

$ kbdinfo -C /dev/tty2 getmode
text

Use the device that actually represents the virtual console you intend to inspect. Do not guess at a device path on a production host. In a container, an SSH session, a terminal multiplexer attached to a different session, or a graphical terminal, the command may simply fail because there is no usable console file descriptor.

3. Check the keyboard input mode

Use gkbmode to read how the console keyboard driver presents input:

$ kbdinfo -C /dev/tty2 gkbmode
unicode

The documented values are:

• raw scancode-level input, straight from the keyboard controller.
• xlate translated keycodes, the traditional console behaviour.
• mediumraw an intermediate keycode form used by some input handling.
• unicode the common result on an ordinary modern console.

Do not write a script that assumes unicode just because it is common. Recovery tools, keyboard inspection programs and console setup utilities can deliberately select another mode.

A final value turns a read into a check. It prints nothing and exits with status 0 only when the value matches:

$ kbdinfo -C /dev/tty2 gkbmode unicode
$ printf 'status=%s\n' "$?"
status=0
$ kbdinfo -C /dev/tty2 gkbmode raw
$ printf 'status=%s\n' "$?"
status=1

This check form is useful in scripts because it avoids parsing human-readable output. Keep the expected value explicit and quote shell variables if you replace the literal value with one from configuration.

4. Inspect meta-key handling and one lock LED

Query the meta-key mode with gkbmeta:

$ kbdinfo -C /dev/tty2 gkbmeta
escprefix

The possible results are metabit and escprefix. These describe how the console keyboard layer represents meta keys, not the live state of the Alt key in a graphical desktop.

Query one LED at a time with gkbled, using scrolllock, numlock or capslock as the final argument:

$ kbdinfo -C /dev/tty2 gkbled capslock
off

The output is the state reported by the console driver, normally on or off. This does not change the LED and does not toggle the associated lock state. If another process is changing the keyboard state, a later query can legitimately differ.

5. Put checks into a script safely

For automation, test the exit status rather than comparing command output. This example checks that a named console is in Unicode keyboard mode:

#!/bin/sh
console=/dev/tty2
if kbdinfo -C "$console" gkbmode unicode; then
    printf '%s: unicode keyboard mode\n' "$console"
else
    status=$?
    printf '%s: not in unicode mode or not accessible (status %s)\n' "$console" "$status" >&2
    exit "$status"
fi

The script does not change console state. Its failure branch deliberately keeps the command's status, so a monitoring job can distinguish a mismatch or inaccessible device from success. Run it as the user who needs the check first. Add elevated privileges only if your host's device permissions require them, and review the policy before granting a service account access to a console device.

6. Diagnose the common failure

This message is common outside a local virtual console:

$ kbdinfo getmode
Couldn't get a file descriptor referring to the console.
$ printf 'status=%s\n' "$?"
status=1

It means the program could not obtain a usable console descriptor. It does not prove that the keyboard is broken, that the machine has no graphical display, or that changing permissions will fix the session. Check tty, try the command directly on a local virtual console, and specify the correct device with -C if you have one. On this machine, -C /dev/console also fails when that device is unavailable, which is an environment issue rather than a reason to alter device nodes.

There is no setter syntax here. kbdinfo only reads, so every example above is read-only and there is no undo step to worry about. If another utility changed the keyboard mode, use that utility's documented recovery procedure rather than guessing with kbdinfo.