GPG Configuration (Using the GNU Privacy Guard)

4.3 Configuration files

There are a few configuration files to control certain aspects of gpg’s operation. Unless noted, they are expected in the current home directory (see option --homedir).

gpg.conf: This is the standard configuration file read by gpg on startup. It may contain any valid long option; the leading two dashes may not be entered and the option may not be abbreviated. This default name may be changed on the command line (see gpg-option --options). You should backup this file.
common.conf: This is an optional configuration file read by gpg on startup. It may contain options pertaining to all components of GnuPG. Its current main use is for the "use-keyboxd" option. If the default home directory ~/.gnupg does not exist, GnuPG creates this directory and a common.conf file with "use_keyboxd".

Note that on larger installations, it is useful to put predefined files into the directory /usr/local/etc/skel/.gnupg so that newly created users start up with a working configuration. For existing users a small helper script is provided to create these files (see Create .gnupg home directories).

For internal purposes gpg creates and maintains a few other files; They all live in the current home directory (see option --homedir). Only the gpg program may modify these files.

~/.gnupg

This is the default home directory which is used if neither the environment variable GNUPGHOME nor the option --homedir is given.

~/.gnupg/pubring.gpg

The public keyring using a legacy format. You should backup this file.

If this file is not available, gpg defaults to the new keybox format and creates a file pubring.kbx unless that file already exists in which case that file will also be used for OpenPGP keys.

Note that in the case that both files, pubring.gpg and pubring.kbx exists but the latter has no OpenPGP keys, the legacy file pubring.gpg will be used. Take care: GnuPG versions before 2.1 will always use the file pubring.gpg because they do not know about the new keybox format. In the case that you have to use GnuPG 1.4 to decrypt archived data you should keep this file.

~/.gnupg/pubring.gpg.lock

The lock file for the public keyring.

~/.gnupg/pubring.kbx

The public keyring using the new keybox format. This file is shared with gpgsm. You should backup this file. See above for the relation between this file and it predecessor.

To convert an existing pubring.gpg file to the keybox format, you first backup the ownertrust values, then rename pubring.gpg to publickeys.backup, so it won’t be recognized by any GnuPG version, run import, and finally restore the ownertrust values:

  $ cd ~/.gnupg
  $ gpg --export-ownertrust >otrust.lst
  $ mv pubring.gpg publickeys.backup
  $ gpg --import-options restore --import publickeys.backup
  $ gpg --import-ownertrust otrust.lst

~/.gnupg/pubring.kbx.lock

The lock file for pubring.kbx.

~/.gnupg/secring.gpg

The legacy secret keyring as used by GnuPG versions before 2.1. It is not used by GnuPG 2.1 and later. You may want to keep it in case you have to use GnuPG 1.4 to decrypt archived data.

~/.gnupg/secring.gpg.lock

The lock file for the legacy secret keyring.

~/.gnupg/.gpg-v21-migrated

File indicating that a migration to GnuPG 2.1 has been done.

~/.gnupg/trustdb.gpg

The trust database. There is no need to backup this file; it is better to backup the ownertrust values (see option --export-ownertrust).

~/.gnupg/trustdb.gpg.lock

The lock file for the trust database.

~/.gnupg/random_seed

A file used to preserve the state of the internal random pool.

~/.gnupg/openpgp-revocs.d/

This is the directory where gpg stores pre-generated revocation certificates. The file name corresponds to the OpenPGP fingerprint of the respective key. It is suggested to backup those certificates and if the primary private key is not stored on the disk to move them to an external storage device. Anyone who can access these files is able to revoke the corresponding key. You may want to print them out. You should backup all files in this directory and take care to keep this backup closed away.

Operation is further controlled by a few environment variables:

HOME: Used to locate the default home directory.
GNUPGHOME: If set directory used instead of "~/.gnupg".
GPG_AGENT_INFO: This variable is obsolete; it was used by GnuPG versions before 2.1.
PINENTRY_USER_DATA: This value is passed via gpg-agent to pinentry. It is useful to convey extra information to a custom pinentry.
COLUMNS
LINES: Used to size some displays to the full size of the screen.
LANGUAGE: Apart from its use by GNU, it is used in the W32 version to override the language selection done through the Registry. If used and set to a valid and available language name (langid), the file with the translation is loaded from gpgdir/gnupg.nls/langid.mo. Here gpgdir is the directory out of which the gpg binary has been loaded. If it can’t be loaded the Registry is tried and as last resort the native Windows locale system is used.
GNUPG_BUILD_ROOT: This variable is only used by the regression test suite as a helper under operating systems without proper support to figure out the name of a process’ text file.
GNUPG_EXEC_DEBUG_FLAGS: This variable allows to enable diagnostics for process management. A numeric decimal value is expected. Bit 0 enables general diagnostics, bit 1 enables certain warnings on Windows.

When calling the gpg-agent component gpg sends a set of environment variables to gpg-agent. The names of these variables can be listed using the command:

  gpg-connect-agent 'getinfo std_env_names' /bye | awk '$1=="D" {print $2}'