NAME¶

gpgconf - Modify .gnupg home directories

SYNOPSIS¶

gpgconf [options] --list-components
gpgconf [options] --list-options component
gpgconf [options] --change-options component

DESCRIPTION¶

The gpgconf is a utility to automatically and reasonable safely query and modify configuration files in the ‘.gnupg’ home directory. It is designed not to be invoked manually by the user, but automatically by graphical user interfaces (GUI). ([Please note that currently no locking is done, so concurrent access should be avoided. There are some precautions to avoid corruption with concurrent usage, but results may be inconsistent and some changes may get lost. The stateless design makes it difficult to provide more guarantees.])

gpgconf provides access to the configuration of one or more components of the GnuPG system. These components correspond more or less to the programs that exist in the GnuPG framework, like GPG, GPGSM, DirMngr, etc. But this is not a strict one-to-one relationship. Not all configuration options are available through gpgconf. gpgconf provides a generic and abstract method to access the most important configuration options that can feasibly be controlled via such a mechanism.

gpgconf can be used to gather and change the options available in each component, and can also provide their default values. gpgconf will give detailed type information that can be used to restrict the user's input without making an attempt to commit the changes.

gpgconf provides the backend of a configuration editor. The configuration editor would usually be a graphical user interface program that displays the current options, their default values, and allows the user to make changes to the options. These changes can then be made active with gpgconf again. Such a program that uses gpgconf in this way will be called GUI throughout this section.

COMMANDS¶

One of the following commands must be given:

--list-components

List all components. This is the default command used if none is specified.

--check-programs

List all available backend programs and test whether they are runnable.

--list-options component

List all options of the component component.

--change-options component

Change the options of the component component.

--check-options component

Check the options for the component component.

--apply-profile file

Apply the configuration settings listed in file to the configuration files. If file has no suffix and no slashes the command first tries to read a file with the suffix .prf from the data directory (gpgconf --list-dirs datadir) before it reads the file verbatim. A profile is divided into sections using the bracketed component name. Each section then lists the option which shall go into the respective configuration file.

--apply-defaults

Update all configuration files with values taken from the global configuration file (usually ‘/etc/gnupg/gpgconf.conf’). Note: This is a legacy mechanism. Please use global configuration files instead.

--list-dirs [names]

-L

Lists the directories used by gpgconf. One directory is listed per line, and each line consists of a colon-separated list where the first field names the directory type (for example sysconfdir) and the second field contains the percent-escaped directory. Although they are not directories, the socket file names used by gpg-agent and dirmngr are printed as well. Note that the socket file names and the homedir lines are the default names and they may be overridden by command line switches. If names are given only the directories or file names specified by the list names are printed without any escaping.

--list-config [filename]

List the global configuration file in a colon separated format. If filename is given, check that file instead.

--check-config [filename]

Run a syntax check on the global configuration file. If filename is given, check that file instead.

--query-swdb package_name [version_string]

Returns the current version for package_name and if version_string is given also an indicator on whether an update is available. The actual file with the software version is automatically downloaded and checked by dirmngr. dirmngr uses a thresholds to avoid download the file too often and it does this by default only if it can be done via Tor. To force an update of that file this command can be used:

       gpg-connect-agent --dirmngr 'loadswdb --force' /bye

--reload [component]

-R

Reload all or the given component. This is basically the same as sending a SIGHUP to the component. Components which don't support reloading are ignored. Without component or by using "all" for component all components which are daemons are reloaded.

--launch [component]

If the component is not already running, start it. component must be a daemon. This is in general not required because the system starts these daemons as needed. However, external software making direct use of gpg-agent or dirmngr may use this command to ensure that they are started. Using "all" for component launches all components which are daemons.

--kill [component]

-K

Kill the given component that runs as a daemon, including gpg-agent, dirmngr, and scdaemon. A component which does not run as a daemon will be ignored. Using "all" for component kills all components running as daemons. Note that as of now reload and kill have the same effect for scdaemon.

--create-socketdir

Create a directory for sockets below /run/user or /var/run/user. This is command is only required if a non default home directory is used and the /run based sockets shall be used. For the default home directory GnuPG creates a directory on the fly.

--remove-socketdir

Remove a directory created with command --create-socketdir.

--unlock name

--lock name

Remove a stale lock file hold for ‘file’. The file is expected in the current GnuPG home directory. This command is usually not required because GnuPG is able to detect and remove stale lock files. Before using the command make sure that the file protected by the lock file is actually not in use. The lock command may be used to lock an accidentally removed lock file. Note that the commands have no effect on Windows because the mere existence of a lock file does not mean that the lock is active.

OPTIONS¶

The following options may be used:

-o file

--output file

Write output to file. Default is to write to stdout.

-v

--verbose

Outputs additional information while running. Specifically, this extends numerical field values by human-readable descriptions.

-q

--quiet

Try to be as quiet as possible.

--homedir dir

Set the name of the home directory to dir. If this option is not used, the home directory defaults to ‘~/.gnupg’. It is only recognized when given on the command line. It also overrides any home directory stated through the environment variable ‘GNUPGHOME’ or (on Windows systems) by means of the Registry entry HKCU\Software\GNU\GnuPG:HomeDir.

On Windows systems it is possible to install GnuPG as a portable application. In this case only this command line option is considered, all other ways to set a home directory are ignored.

--chuid uid

Change the current user to uid which may either be a number or a name. This can be used from the root account to get information on the GnuPG environment of the specified user or to start or kill daemons. If uid is not the current UID a standard PATH is set and the envvar GNUPGHOME is unset. To override the latter the option --homedir can be used. This option has currently no effect on Windows.

-n

--dry-run

Do not actually change anything. This is currently only implemented for --change-options and can be used for testing purposes.

-r

--runtime

Only used together with --change-options. If one of the modified options can be changed in a running daemon process, signal the running daemon to ask it to reparse its configuration file after changing.

This means that the changes will take effect at run-time, as far as this is possible. Otherwise, they will take effect at the next start of the respective backend programs.

--status-fd n

Write special status strings to the file descriptor n. This program returns the status messages SUCCESS or FAILURE which are helpful when the caller uses a double fork approach and can't easily get the return code of the process.

USAGE¶

The command --list-components will list all components that can be configured with gpgconf. Usually, one component will correspond to one GnuPG-related program and contain the options of that program's configuration file that can be modified using gpgconf. However, this is not necessarily the case. A component might also be a group of selected options from several programs, or contain entirely virtual options that have a special effect rather than changing exactly one option in one configuration file.

A component is a set of configuration options that semantically belong together. Furthermore, several changes to a component can be made in an atomic way with a single operation. The GUI could for example provide a menu with one entry for each component, or a window with one tabulator sheet per component.

The command --list-components lists all available components, one per line. The format of each line is:

name:description:pgmname:

name

This field contains a name tag of the component. The name tag is used to specify the component in all communication with gpgconf. The name tag is to be used verbatim. It is thus not in any escaped format.

description

The string in this field contains a human-readable description of the component. It can be displayed to the user of the GUI for informational purposes. It is percent-escaped and localized.

pgmname

The string in this field contains the absolute name of the program's file. It can be used to unambiguously invoke that program. It is percent-escaped.

Example:

$ gpgconf --list-components
gpg:GPG for OpenPGP:/usr/local/bin/gpg2:
gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:
scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:
gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:
dirmngr:Directory Manager:/usr/local/bin/dirmngr:

$ gpgconf --check-programs
gpg:GPG for OpenPGP:/usr/local/bin/gpg2:1:1:
gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:1:1:
scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:1:0:
gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:1:1:
dirmngr:Directory Manager:/usr/local/bin/dirmngr:0:0:

$ echo 'force:0:1' | gpgconf --change-options dirmngr

$ echo 'force:16:' | gpgconf --change-options dirmngr

FILES¶

gpgconf.ctl

Under Unix ‘gpgconf.ctl’ may be used to change some of the
compiled in directories where the GnuPG components are expected. This
file is expected in the same directory as ‘gpgconf’. The
physical installation directories are evaluated and no symlinks.
Blank lines and lines starting with pound sign are ignored in the
file. The keywords must be followed by optional white space, an equal
sign, optional white space, and the value. Environment variables are
substituted in standard shell manner, the final value must start with
a slash, trailing slashes are stripped. Valid keywords are
rootdir, sysconfdir, socketdir, and
.enable. No errors are printed for unknown keywords. The
.enable keyword is special: if the keyword is used and its
value evaluates to true the entire file is ignored.

Under Windows this file is used to install GnuPG as a portable
application. An empty file named ‘gpgconf.ctl’ is expected in
the same directory as the tool ‘gpgconf.exe’ or the file must
have a keyword portable with the value true. The root of the
installation is then that directory; or, if ‘gpgconf.exe’ has
been installed directly below a directory named ‘bin’, its parent
directory. You also need to make sure that the following directories
exist and are writable: ‘ROOT/home’ for the GnuPG home and
‘ROOT/var/cache/gnupg’ for internal cache files.

On both platforms the keyword gnupg can be used to change the
standard home directory. For example a value of "gnupg-vsd" will
change the default home directory on unix from ‘~/.gnupg’ to
‘~/.gnupg-vsd’. The socket directory is changed accordingly
unless the socketdir keyword has been used. On Windows the
Registry keys are modified as well.

/etc/gnupg/gpgconf.conf

If this file exists, it is processed as a global configuration file.
This is a legacy mechanism which should not be used together with
the modern global per component configuration files. A commented
example can be found in the ‘examples’ directory of the
distribution.

GNUPGHOME/swdb.lst

A file with current software versions. dirmngr creates
this file on demand from an online resource.

SEE ALSO¶

gpg(1), gpgsm(1), gpg-agent(1), scdaemon(1), dirmngr(1)

The full documentation for this tool is maintained as a Texinfo manual. If GnuPG and the info program are properly installed at your site, the command

info gnupg

should give you access to the complete manual including a menu structure and an index.