Watch GnuPG Logs Safely with watchgnupg

GnuPG fails silently more often than it should, and watchgnupg is the tool that turns that silence into timestamped log lines you can actually read. Run it as a foreground listener, connect GnuPG logging to its Unix socket, and watch entries arrive as the real event happens. The examples use GnuPG 2.4.4 from the Ubuntu gnupg-utils package installed on this machine. Allow about 15 minutes if GnuPG is already installed.

This is a diagnostic workflow. It does not need sudo when your GnuPG home directory belongs to you. Logs can contain paths, usernames and other sensitive details, so keep the listener local unless you have a specific, protected debugging arrangement.

1. Check the installed command

Confirm which executable will run, then record its version:

$ command -v watchgnupg
/usr/bin/watchgnupg
$ watchgnupg --version
watchgnupg (GnuPG) 2.4.4

The installed manpage is dated 25 January 2024 and documents GnuPG 2.4.4. Keep that version boundary in mind if you copy this procedure to another machine. The local help also advertises newer interface details, including --clock and a port form; those are not part of the manpage workflow here. Check watchgnupg --help on the target system before relying on them.

2. Find the default log socket

With no socket name, the documented shorthand uses gpgconf to find the GnuPG socket directory and listens on S.log. Print the path without starting a listener:

$ socketdir=$(gpgconf --list-dirs socketdir)
$ printf '%s\n' "$socketdir/S.log"
/run/user/1000/gnupg/S.log

Do not set GNUPGHOME and assume watchgnupg will follow it. The manpage says this program ignores that environment variable. For another home directory, use --homedir explicitly and let gpgconf resolve the matching socket.

$ watchgnupg --homedir /path/to/gnupg-home

Replace the path with a real directory. This command stays in the foreground until you stop it with Ctrl-C.

3. Start a local listener

Start the default listener in a terminal of its own. --time-only removes the date from each timestamp, which is convenient during a short debugging session:

$ watchgnupg --time-only

At this point it is waiting for connections. The default socket is created by the listener, not by a GnuPG command. If a stale socket file prevents startup, stop any other diagnostic listener first. Only then consider:

$ watchgnupg --force --time-only

4. Configure the modules you want to observe

A listener alone produces no useful entries. Each GnuPG module whose logs you want must be configured with a log-file setting. The documented setting for the default listener is:

log-file socket://

Put that line in the relevant GnuPG configuration file, using the file and module you are actually diagnosing. Do not paste it into a shell: it is configuration syntax, not a command. The manpage says this setting is needed for all modules whose logs should appear. Existing configuration is outside this command's control, so inspect it before adding a duplicate or changing an unrelated log destination.

After saving a configuration change, repeat the operation that was producing the problem, then watch the listener terminal for timestamped lines. A quiet terminal is not proof that the command failed: it can mean the module did not log, the wrong configuration file was edited, or the event did not occur.

5. Verify the socket with an isolated test

You can verify the listener without touching your real GnuPG socket by using a temporary Unix socket. This test sends one harmless line, then removes the temporary directory when it finishes:

$ testdir=$(mktemp -d)
$ socket="$testdir/watch.sock"
$ (timeout 3 watchgnupg --time-only "$socket" >"$testdir/output" 2>"$testdir/error"; printf '%s\n' "$?" >"$testdir/status") &
$ listener=$!
$ for n in 1 2 3 4 5; do test -S "$socket" && break; sleep 0.1; done
$ python3 -c 'import socket, sys; s=socket.socket(socket.AF_UNIX); s.connect(sys.argv[1]); s.sendall(b"test diagnostic line\\n"); s.close()' "$socket"
$ wait "$listener"
$ grep -F 'test diagnostic line' "$testdir/output"
test diagnostic line

The listener may exit with a timeout status after three seconds; the useful check is that the sent line appears. Clean up the temporary files afterwards:

$ rm -rf -- "$testdir"

This is the only removal in the guide, and it targets the directory created by mktemp. Never substitute a real GnuPG directory for $testdir.

6. Treat TCP logging as exposed diagnostic data

The manpage also describes a TCP mode. A configuration such as this sends logs to an IP address and port:

log-file tcp://192.0.2.10:4711

Start the listener with the corresponding TCP option, for example watchgnupg --tcp 4711. Only IP addresses are supported by the documented format, not hostnames.

7. Stop cleanly and troubleshoot the common traps

Press Ctrl-C in the listener terminal when the diagnostic session is over. This stops watchgnupg; it does not restart GnuPG services or undo configuration edits. If you added log-file socket:// only for this session, remove or comment that line afterwards and repeat the original operation to confirm normal behaviour.

• No output: check that the relevant module has a log-file setting and that you triggered an event it actually logs.
• Address already in use: identify the existing listener before using --force; deleting its socket can disrupt that diagnostic session.
• Wrong home directory: use --homedir DIR. Do not rely on GNUPGHOME.
• Unexpected disclosure: stop a TCP listener and return to the local socket. Review any captured logs as sensitive data.