Run xkbevd Safely as an XKB Event Prototype

You will finish with a controlled way to inspect and launch xkbevd, the XKB event daemon, against a chosen X display. You will also know where its limits are: this installed program is a rough, partially implemented developer prototype, not a general-purpose desktop automation service.

The examples target xkbevd 1.1.5 from Debian package x11-xkb-utils version 7.7+8build2. Allow about fifteen minutes. You need an X server you are allowed to access, a shell, and a configuration file if you want the daemon to perform an action. None of the checks below needs elevated privileges. Do not use sudo to solve a display or configuration mistake.

1. Confirm the installed program

Check which executable your shell will run, then ask it for its version. These are read-only commands:

$ command -v xkbevd
/usr/bin/xkbevd
$ xkbevd -version
xkbevd 1.1.5
$ dpkg-query -W -f='${Package} ${Version}\n' x11-xkb-utils
x11-xkb-utils 7.7+8build2

Use the local command's help as the final option reference. On this version it lists -cfg for a configuration file, -sc for a sound-playing command, -sd for a sound directory, -display (also accepted in the abbreviated form shown by help) for the X display, -bg for background operation, -synch for synchronous X requests, -v for verbose output, and -version.

Do not assume that an option accepted by another X utility belongs here. The program is old enough that its help output is more current than parts of its manual page.

2. Check the display before starting a daemon

xkbevd needs an X display. Unless you pass -display, it reads the DISPLAY environment variable. Inspect that value without changing anything:

$ printf 'DISPLAY=%s\n' "${DISPLAY-}" 
DISPLAY=:0

Your value may be different. An empty value means there is no display selected for this shell. Set it only to a display name you have been given and are authorised to use, for example:

$ export DISPLAY=':0'
$ xkbevd -display "$DISPLAY" -version
xkbevd 1.1.5

The version check does not open the display, so it cannot prove that the X connection will work. A remote display can also require an appropriate X authority cookie. Do not copy or weaken another user's authentication data to make this test pass.

3. Understand the configuration boundary

Pass a configuration file explicitly with -cfg. If you omit it, the documented search order is ~/.xkb/xkbevd.cf, followed by $(LIBDIR)/xkb/xkbevd.cf. The exact system library directory is build-dependent, so an explicit file is easier to review and reproduce.

The configuration is a list of event specification and action pairs, with optional variable definitions. An event specification has a short XKB event name and a qualifier in parentheses. Empty parentheses select the default action for events that do not match another specification. The manual documents qualifiers for bell names, message contents, and slow-key states of press, release, accept, or reject.

Keep this syntax distinction clear: the qualifier is part of the event specification, while the action is the operation to perform. The recognised actions are none, ignore, echo, printEvent, sound, and shell. If no action keyword is supplied, the argument is treated as a sound file unless it begins with !, in which case it is treated as a shell command.

That implicit shell form is a security boundary. Do not put untrusted message text, file names, or copied configuration into a shell action. Prefer echo or printEvent while learning the event stream. The manual also says that only soundDirectory and soundCmd variables are currently recognised, and that event parameters are not fully listed. Treat any other variable name as unverified rather than guessing.

4. Run a foreground observation test

Start with a reviewed configuration and stay in the foreground. Replace the path with a file you have inspected:

$ xkbevd -display "$DISPLAY" -cfg /path/to/reviewed-xkbevd.cf -v

Keep this terminal open. Verbose mode reports debugging information, and a second -v requests more output up to the program's limit. The daemon should remain attached while it listens for configured XKB events. Trigger only a harmless event that your configuration is meant to observe, then compare the output with the selected action.

5. Use sound settings only when they are real on this host

The -sc option selects the command used to play sounds, and -sd selects the top-level sound-file directory. They do not install a player or create sound files. The local manual warns that the sound action was implemented and tested only for SGI machines and launches an external program. On a modern Linux desktop, a successful daemon start is not evidence that sound playback will work.

For a first run, leave sound actions out of the configuration. If you later test one, use a command and directory that already exist, run it in the foreground, and verify the resulting process and output. Avoid a sound command that accepts event-derived text as shell syntax.

6. Background mode is a deliberate service change

Only add -bg after the foreground test behaves as expected:

$ xkbevd -display "$DISPLAY" -cfg /path/to/reviewed-xkbevd.cf -v -bg
$ pgrep -af '[x]kbevd'

The second command is a check, not a guarantee that every configured action works. The process may have forked and detached, so capture logs or use a supervision mechanism appropriate to your desktop before relying on it.

Background mode changes process lifetime and can leave a listener running after you forget which terminal started it. Before using it in a session startup file, record the exact command and a stop procedure. To undo this example, stop only the instance you started after checking the PID with pgrep:

$ kill PID_FROM_PGREP
$ pgrep -af '[x]kbevd' || echo 'no xkbevd process found'

Replace PID_FROM_PGREP with the numeric PID. Do not use a broad pattern or kill another user's process.

7. Diagnose without guessing

• No display: inspect DISPLAY, then verify that this account can connect to the selected X server. Changing -sd or using sudo will not repair X authentication.
• No configuration found: pass an explicit readable path with -cfg. Check it with test -r /path/to/reviewed-xkbevd.cf rather than relying on a guessed library directory.
• No useful event output: check that the event specification and qualifier match the event type. The manual explicitly says that the recognised event set is limited.
• Shell action surprises: remove the shell action and substitute printEvent or echo while isolating the problem. Do not debug by adding more interpolation.
• Slow behaviour: -synch forces synchronisation of X requests and is documented as slow. Use it only for diagnosis, not as a default performance setting.