Check Linux Console and Keyboard State with kbdinfo

You will use kbdinfo to query a Linux virtual console without changing its configuration. It can report whether the console is in text or graphics mode, the keyboard input mode, meta-key handling, and the state of one lock LED. Allow about ten minutes, including time to repeat the checks from the correct terminal.

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 output wording.

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. If the command is missing, install the kbd package using 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. The getmode command 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, so treat the result as the kernel's console mode rather than 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. If you are in a container, an SSH session, a terminal multiplexer attached to a different session, or a graphical terminal, the command may 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, xlate, mediumraw, and unicode. In ordinary console use, unicode is a common result, but do not write a script that assumes it. Recovery tools, keyboard inspection programs and console setup utilities can deliberately select another mode.

The 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. They are not a report of the current state of the Alt key in a graphical desktop.

Query one LED at a time with gkbled:

$ kbdinfo -C /dev/tty2 gkbled capslock
off

Use scrolllock, numlock or capslock as the final argument. 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.

Do not use kbdinfo to make changes. It has no setter syntax in this interface, and the examples above are read-only. If another utility changed the keyboard mode, use that utility's documented recovery procedure rather than guessing with kbdinfo. There is no undo step because these commands do not modify persistent files, services or console state.