Inspect and Safely Change GnuPG Settings with gpgconf

You will use gpgconf to find the GnuPG components installed on a Linux host, inspect the typed options exposed by one component, preview a change, and apply a reversible setting. The examples are based on GnuPG 2.4.4, installed here as Ubuntu package gpgconf 2.4.4-2ubuntu17.6. Output such as component names and paths will differ on another host.

Allow about fifteen minutes. You need a shell and a working GnuPG installation. Most discovery commands are ordinary unprivileged reads. Changing a user's configuration normally needs no sudo; use elevated privileges only when you intentionally target a system-owned home or global configuration. This guide uses a temporary home for the write test, so it does not alter your normal keyring or agent settings.

1. Confirm the installed command

Check which executable is being used, then record its version:

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

The version matters because the component set and option metadata are provided by the installed GnuPG build. Do not copy an option name from a different host without checking it locally.

Checkpoint: if command -v finds nothing, stop here and install or repair GnuPG through your normal package-management process. Do not download a replacement binary into a user's home directory just to make this guide continue.

2. Discover the component names

List the components that this installation exposes:

$ gpgconf --list-components
gpg:OpenPGP:/usr/bin/gpg
gpgsm:S/MIME:/usr/bin/gpgsm
keyboxd:Public Keys:/usr/lib/gnupg/keyboxd
gpg-agent:Private Keys:/usr/bin/gpg-agent
scdaemon:Smartcards:/usr/lib/gnupg/scdaemon
dirmngr:Network:/usr/bin/dirmngr
pinentry:Passphrase Entry:/usr/bin/pinentry

Each record is colon-separated. The first field is the component name, and it is the exact value to pass to commands such as --list-options and --change-options. The description and executable path are informative; they are not a promise that every component has a simple one-to-one configuration file.

Checkpoint: choose a component from your own first field. The rest of this guide uses gpg-agent because it exposes a small, easy-to-restore option. Your output may omit it or use different paths.

3. Check program availability and syntax

Before changing anything, ask gpgconf to test the backend programs:

$ gpgconf --check-programs
gpg:OpenPGP:/usr/bin/gpg:1:1:
gpg-agent:Private Keys:/usr/bin/gpg-agent:1:1:
dirmngr:Network:/usr/bin/dirmngr:1:1:

The output has more fields than this abbreviated example. The availability and configuration-status fields are numeric 1 or 0. A zero does not necessarily mean your whole GnuPG installation is unusable: this machine reports an unavailable scdaemon while the other backends remain runnable. Read the component name and error fields before deciding what to repair.

This command can start backend checks and may report diagnostics on standard error. It does not edit your configuration. If you are checking a host with a deliberately disabled smart-card stack, treat that as an expected local condition rather than enabling it blindly.

4. Read option metadata before writing

List the options for the component you selected:

$ gpgconf --list-options gpg-agent
Monitor:1:0:Options controlling the diagnostic output:0:0::::
verbose:12:0:verbose:0:0::::
quiet:8:0:be somewhat more quiet:0:0::::
debug-level:24:1::1:1::"none::
log-file:8:1:write server mode logs to FILE:32:1:FILE:::
Configuration:1:0:Options controlling the configuration:0:0::::
enable-ssh-support:0:0:enable ssh support:0:0::::

Every line describes either an option or a group. The fields include flags, an expert level, a type, default information and the current value. In the example, enable-ssh-support has type 0, meaning that it takes no argument. Its current value is empty because it is not explicitly present in the configuration. Do not infer a setting from a human description alone: use the type and flags reported by your own command.

A list flag means an option may occur more than once. A runtime flag means the component can accept the change while running, but it does not mean that every related application will immediately behave differently. A no-change flag tells a front end not to submit that option through gpgconf. Manual edits may still be possible, but they are a separate workflow.

5. Preview a reversible change

For a safe demonstration, create a temporary GnuPG home and use --dry-run. Replace the placeholder with a private directory that is not used by another GnuPG process:

$ TEST_GNUPGHOME=/tmp/gpgconf-example-XXXXXX
$ mkdir -m 700 "$TEST_GNUPGHOME"
$ printf '%s\n' 'enable-ssh-support:0:1' |
>   gpgconf --homedir "$TEST_GNUPGHOME" --dry-run --change-options gpg-agent
gpg-agent:Private Keys:/usr/bin/gpg-agent:1:1:

The input format is name:flags:new-value. Here, flag 0 sets the option and value 1 requests the presence of a no-argument option. The dry run checks the proposed configuration and prints the resulting program check without committing the edit. A zero exit status is the useful success signal:

$ printf '%s\n' "$?"
0

Do not use this example with a real home until you have inspected the exact option metadata. A malformed value can make a daemon reject its configuration, and a setting such as a log path can expose sensitive data.

6. Apply the setting and verify it

Apply the same input without --dry-run:

$ printf '%s\n' 'enable-ssh-support:0:1' |
>   gpgconf --homedir "$TEST_GNUPGHOME" --change-options gpg-agent
gpg-agent:Private Keys:/usr/bin/gpg-agent:1:1:

gpgconf writes the component configuration and then reports the component check. Inspect the option again and look for a final value of 1:

$ gpgconf --homedir "$TEST_GNUPGHOME" --list-options gpg-agent |
>   grep '^enable-ssh-support:'
enable-ssh-support:0:0:enable ssh support:0:0::::1

The exact line can contain local descriptions and field variations, but the last field is the current value in this record. The command changes configuration data; it does not automatically prove that every already-running client has adopted the new behaviour. If the option has a runtime flag, use --runtime only after checking what the component supports.

7. Restore the default and avoid concurrent edits

Flag 16 means delete the explicit option and use its default where one exists. Restore the temporary configuration like this:

$ printf '%s\n' 'enable-ssh-support:16:' |
>   gpgconf --homedir "$TEST_GNUPGHOME" --change-options gpg-agent
gpg-agent:Private Keys:/usr/bin/gpg-agent:1:1:
$ gpgconf --homedir "$TEST_GNUPGHOME" --list-options gpg-agent |
>   grep '^enable-ssh-support:'
enable-ssh-support:0:0:enable ssh support:0:0::::

This removes the explicit setting. It does not promise that the default is disabled; the option metadata is the authority for the default description. Once you have checked the result, remove only the temporary directory if you created it solely for this test. Never remove your real ~/.gnupg directory as cleanup.

gpgconf does not provide locking for concurrent access. Avoid running it at the same time as another configuration editor or a manual edit. Concurrent changes can be lost or produce inconsistent results. If a daemon needs a reload, use the documented gpgconf --reload COMPONENT command only after reviewing the service impact. --kill is more disruptive and can interrupt applications using that daemon.

8. Keep system-wide files separate

Most examples target a user's GnuPG home with --homedir. The global file /etc/gnupg/gpgconf.conf is a legacy mechanism, and the manual advises against combining it with modern per-component global configuration files. Use --check-config to syntax-check a global file without applying changes:

$ gpgconf --check-config /path/to/gpgconf.conf
$ printf '%s\n' "$?"
0

Use a real path only when you know which administrator-owned file you intend to inspect. Reading it may be unprivileged, but editing or checking a protected file can require elevated access. Do not run the whole workflow as root to avoid a permission error: that can inspect and modify root's GnuPG home instead of the account whose configuration you meant to manage.