File: gnupg.info,  Node: GPG Configuration,  Next: GPG Examples,  Prev: GPG Options,  Up: Invoking GPG

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 (*note 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 (*note 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 (*note
addgnupghome::).

   For internal purposes 'gpg' creates and maintains a few other files;
They all live in the current home directory (*note 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 (*note 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 one 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}'