Start and Check GnuPG's keyboxd Service Safely

Most people never run keyboxd by hand, which is exactly why it is confusing the first time you need to check it. This guide covers whether GnuPG's public-key service is available, who starts it, and how to launch or stop it manually only when that is appropriate. The examples use the installed GnuPG 2.4.4 package and should take about ten minutes. They do not change keys or configuration unless you deliberately choose the optional systemd masking step.

1. Confirm the installed program and version

keyboxd is a public key management service for GnuPG. On this Debian or Ubuntu installation the executable is in /usr/lib/gnupg, rather than a directory normally included in an interactive user's PATH. Check the package and invoke the executable by its full path:

$ dpkg-query -W -f='${Package} ${Version}\n' keyboxd
keyboxd 2.4.4-2ubuntu17.6
$ /usr/lib/gnupg/keyboxd --version
keyboxd (GnuPG) 2.4.4

Your distribution revision can differ. The installed manpage is labelled for GnuPG 2.4.1, while the executable reports 2.4.4, so treat the executable and local service files as the authority for this host when they differ in small details.

Checkpoint: if dpkg-query reports no package or the executable is absent, stop here. Do not download a replacement into a system directory just to make the example match.

2. Check the user socket before starting anything

On a systemd user session, the normal integration is a socket unit. It starts the service when a GnuPG component first needs the standard keyboxd socket, then systemd cleans up the process at logout. Inspect the unit without changing it:

$ systemctl --user is-enabled keyboxd.socket
enabled
$ systemctl --user is-active keyboxd.socket
active
$ systemctl --user status --no-pager keyboxd.socket

Expect enabled and active when this user session is managing keyboxd. The status output should identify keyboxd.socket and a listening socket. Exact timestamps, process IDs and the runtime path vary. A socket can be active even when the service process is not continuously running; socket activation is the point of this arrangement.

Do not run sudo systemctl ... for this check. keyboxd belongs to the user's GnuPG home and user service manager, not normally to the system-wide service manager. If the command says that the user manager is unavailable, investigate the session environment before switching to root.

3. Let GnuPG launch keyboxd on demand

Most users need no direct keyboxd command. Since GnuPG 2.4.x, GnuPG and related processes can auto-launch it when required. With systemd user integration, the first access to the standard socket activates the service. Use your normal GnuPG operation, then check the unit again if you need evidence that it was activated.

$ gpg --list-keys
$ systemctl --user is-active keyboxd.socket
active

The key listing can be empty on a new GnuPG home and still be a successful command. Do not interpret an empty key list as a failed keyboxd start. For a more direct check, inspect the socket unit's status and its recent journal entries:

$ systemctl --user status --no-pager keyboxd.socket

Checkpoint: record whether the socket is enabled and active before changing any startup policy. This avoids troubleshooting a healthy on-demand service by manually launching a second instance.

4. Launch it manually when systemd is not managing it

Manual startup is mainly for a non-systemd session or for an external tool that needs keyboxd available before it performs its first operation. Use GnuPG's component manager, not a hand-written background command:

$ gpgconf --launch keyboxd
$ gpgconf --list-dirs homedir

gpgconf --launch starts a daemon component if it is not already running. It uses the current user's GnuPG environment, including GNUPGHOME when that is set. The second command is a separate, read-only check of the GnuPG home directory. It may print a path such as /home/alice/.gnupg; never substitute another user's home without understanding the ownership and permissions.

Do not use /usr/lib/gnupg/keyboxd --daemon as a routine replacement for gpgconf --launch keyboxd. The manpage documents daemon mode, but GnuPG's component manager knows the correct home directory and runtime environment for this user.

5. Stop a manually managed instance cleanly

If you started keyboxd manually and it is not supervised by systemd, stop it through gpgconf when the session ends:

$ gpgconf --kill keyboxd

This asks GnuPG to terminate the daemon. It does not delete public keys or the database. If another GnuPG operation still needs the service, it may be started again on demand. Avoid sending broad signals such as pkill keyboxd, especially on a shared machine, because they make it harder to identify which user's service was affected.

There is no useful undo command for a successful stop beyond running gpgconf --launch keyboxd again. If a command is currently using the service, wait for it to finish before killing the daemon.

6. Keep configuration and the key database recoverable

The default configuration file is keyboxd.conf in the GnuPG home directory. The default public-key database is pubring.db, an SQLite database in the same home. The manpage recommends backing up both. Find the active home first, then make a backup in a location with suitable permissions:

$ GNUPG_HOME="$(gpgconf --list-dirs homedir)"
$ printf '%s\n' "$GNUPG_HOME"
/home/alice/.gnupg
$ ls -l "$GNUPG_HOME/keyboxd.conf" "$GNUPG_HOME/pubring.db"
$ install -m 600 "$GNUPG_HOME/pubring.db" "$GNUPG_HOME/pubring.db.backup"
$ test -f "$GNUPG_HOME/keyboxd.conf" && install -m 600 "$GNUPG_HOME/keyboxd.conf" "$GNUPG_HOME/keyboxd.conf.backup"

The install commands overwrite same-named backup files, so choose new backup names if preserving an older copy matters. Do not edit pubring.db with a generic SQLite tool while keyboxd is running. Use GnuPG operations for key changes and retain a known-good backup before experimenting with configuration.

7. Change systemd ownership only deliberately

If you do not want the user socket managed by systemd in future sessions, the Debian integration notes document this reversible command:

$ systemctl --user mask --now keyboxd.socket

Warning: this changes service startup policy and can interrupt GnuPG operations using the socket. It is not a troubleshooting shortcut. To restore systemd socket activation, use:

$ systemctl --user unmask keyboxd.socket
$ systemctl --user enable --now keyboxd.socket

Check the result with systemctl --user is-enabled keyboxd.socket and systemctl --user is-active keyboxd.socket. If you chose manual mode, use gpgconf --launch keyboxd and arrange gpgconf --kill keyboxd at logout instead of running competing supervisors.

Done means