- Reads configuration from file instead of from the default
per-user configuration file. The default configuration file is named
gpg-agent.conf and expected in the .gnupg directory directly
below the home directory of the user.
- 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
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.
To install GnuPG as a portable application under Windows, create an
empty file named gpgconf.ctl in the same directory as the tool
gpgconf.exe. 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/usr/local/var/cache/gnupg
for internal cache files.
- Outputs additional information while running.
You can increase the verbosity by giving several
verbose commands to gpgsm, such as ‘-vv’.
- Try to be as quiet as possible.
- Don't invoke a pinentry or do any other thing requiring human interaction.
- This option is only useful for testing; it sets the system time back or
forth to epoch which is the number of seconds elapsed since the year
- Select the debug level for investigating problems. level may be
a numeric value or a keyword:
- No debugging at all. A value of less than 1 may be used instead of
- Some basic debug messages. A value between 1 and 2 may be used
instead of the keyword.
- More verbose debug messages. A value between 3 and 5 may be used
instead of the keyword.
- Even more detailed messages. A value between 6 and 8 may be used
instead of the keyword.
- All of the debug messages you can get. A value greater than 8 may be
used instead of the keyword. The creation of hash tracing files is
only enabled if the keyword is used.
How these messages are mapped to the actual debugging flags is not
specified and may change with newer releases of this program. They are
however carefully selected to best aid in debugging.
- This option is only useful for debugging and the behavior may change at
any time without notice. FLAGS are bit encoded and may be given in
usual C-Syntax. The currently defined bits are:
- X.509 or OpenPGP protocol related data
- values of big number integers
- low level crypto operations
- memory allocation
- show memory statistics
- write hashed data to files named
- trace Assuan protocol
- bypass all certificate validation
- Same as
- When running in server mode, wait n seconds before entering the
actual processing loop and print the pid. This gives time to attach a
- This option inhibits the use of the very secure random quality level
GCRY_VERY_STRONG_RANDOM) and degrades all request
down to standard random quality. It is only used for testing and
should not be used for any production quality keys. This option is
only effective when given on the command line.
On GNU/Linux, another way to quickly generate insecure keys is to use
rngd to fill the kernel's entropy pool with lower quality
random data. rngd is typically provided by the
rng-tools package. It can be run as follows: ‘sudo
rngd -f -r /dev/urandom’.
- This option enables extra debug information pertaining to the
Pinentry. As of now it is only useful when used along with
- Don't detach the process from the console. This is mainly useful for
- Format the info output in daemon mode for use with the standard Bourne
shell or the C-shell respectively. The default is to guess it based on
the environment variable
SHELL which is correct in almost all
- Tell the pinentry not to grab the keyboard and mouse. This option
should in general not be used to avoid X-sniffing attacks.
- Append all logging output to file. This is very helpful in
seeing what the agent actually does. Use socket:// to log to
socket. If neither a log file nor a log file descriptor has been set
on a Windows platform, the Registry entry
HKCU\Software\GNU\GnuPG:DefaultLogFile, if set, is used to
specify the logging output.
- Do not allow clients to mark keys as trusted, i.e. put them into the
trustlist.txt file. This makes it harder for users to inadvertently
accept Root-CA keys.
- This option allows the use of gpg-preset-passphrase to seed the
internal cache of gpg-agent with passphrases.
- Disallow or allow clients to use the loopback pinentry features; see
the option pinentry-mode for details. Allow is the default.
The --force option of the Assuan command DELETE_KEY
is also controlled by this option: The option is ignored if a loopback
pinentry is disallowed.
- Tell Pinentry not to enable features which use an external cache for
Some desktop environments prefer to unlock all
credentials with one master password and may have installed a Pinentry
which employs an additional external cache to implement such a policy.
By using this option the Pinentry is advised not to make use of such a
cache and instead always ask the user for the requested passphrase.
- Tell Pinentry to allow features to divert the passphrase entry to a
running Emacs instance. How this is exactly handled depends on the
version of the used Pinentry.
- This option will let gpg-agent bypass the passphrase cache for all
signing operation. Note that there is also a per-session option to
control this behavior but this command line option takes precedence.
- Set the time a cache entry is valid to n seconds. The default
is 600 seconds. Each time a cache entry is accessed, the entry's
timer is reset. To set an entry's maximum lifetime, use
- Set the time a cache entry used for SSH keys is valid to n
seconds. The default is 1800 seconds. Each time a cache entry is
accessed, the entry's timer is reset. To set an entry's maximum
lifetime, use max-cache-ttl-ssh.
- Set the maximum time a cache entry is valid to n seconds. After
this time a cache entry will be expired even if it has been accessed
recently or has been set using gpg-preset-passphrase. The
default is 2 hours (7200 seconds).
- Set the maximum time a cache entry used for SSH keys is valid to
n seconds. After this time a cache entry will be expired even
if it has been accessed recently or has been set using
gpg-preset-passphrase. The default is 2 hours (7200
- Enforce the passphrase constraints by not allowing the user to bypass
them using the “Take it anyway” button.
- Set the minimal length of a passphrase. When entering a new passphrase
shorter than this value a warning will be displayed. Defaults to 8.
- Set the minimal number of digits or special characters required in a
passphrase. When entering a new passphrase with less than this number
of digits or special characters a warning will be displayed. Defaults
- Check the passphrase against the pattern given in file. When
entering a new passphrase matching one of these pattern a warning will
be displayed. file should be an absolute filename. The default is
not to use any pattern file.
Security note: It is known that checking a passphrase against a list of
pattern or even against a complete dictionary is not very effective to
enforce good passphrases. Users will soon figure up ways to bypass such
a policy. A better policy is to educate users on good security
behavior and optionally to run a passphrase cracker regularly on all
users passphrases to catch the very simple ones.
- Ask the user to change the passphrase if n days have passed since
the last change. With --enforce-passphrase-constraints set the
user may not bypass this check.
- This option does nothing yet.
- This option asks the Pinentry to use char for displaying hidden
characters. char must be one character UTF-8 string. A
Pinentry may or may not honor this request.
- This option asks the Pinentry to timeout after n seconds with no
user input. The default value of 0 does not ask the pinentry to
timeout, however a Pinentry may use its own default timeout value in
this case. A Pinentry may or may not honor this request.
- Use program filename as the PIN entry. The default is
installation dependent. With the default configuration the name of
the default pinentry is pinentry; if that file does not exist
but a pinentry-basic exist the latter is used.
On a Windows platform the default is to use the first existing program
from this list:
where the file names are relative to the GnuPG installation directory.
- By default the filename of the socket gpg-agent is listening for
requests is passed to Pinentry, so that it can touch that file before
exiting (it does this only in curses mode). This option changes the
file passed to Pinentry to filename. The special name
/dev/null may be used to completely disable this feature. Note
that Pinentry will not create that file, it will only change the
modification and access time.
- Use program filename as the Smartcard daemon. The default is
installation dependent and can be shown with the gpgconf
- Do not make use of the scdaemon tool. This option has the effect of
disabling the ability to do smartcard operations. Note, that enabling
this option at runtime does not kill an already forked scdaemon.
- gpg-agent employs a periodic self-test to detect a stolen
socket. This usually means a second instance of gpg-agent
has taken over the socket and gpg-agent will then terminate
itself. This option may be used to disable this self-test for
- Since GnuPG 2.1 the standard socket is always used. These options
have no more effect. The command
--use-standard-socket-p will thus always return success.
- These options are used with the server mode to pass localization
- Ignore requests to change the current
tty or X window system's
DISPLAY variable respectively. This is useful to lock the
pinentry to pop up at the
tty or display you started the agent.
- The extra socket is created by default, you may use this option to
change the name of the socket. To disable the creation of the socket
use “none” or “/dev/null” for name.
Also listen on native gpg-agent connections on the given socket. The
intended use for this extra socket is to setup a Unix domain socket
forwarding from a remote machine to this socket on the local machine.
A gpg running on the remote machine may then connect to the
local gpg-agent and use its private keys. This enables decrypting or
signing data on a remote machine without exposing the private keys to the
The OpenSSH Agent protocol is always enabled, but gpg-agent
will only set the
SSH_AUTH_SOCK variable if this flag is given.
In this mode of operation, the agent does not only implement the
gpg-agent protocol, but also the agent protocol used by OpenSSH
(through a separate socket). Consequently, it should be possible to use
the gpg-agent as a drop-in replacement for the well known ssh-agent.
SSH Keys, which are to be used through the agent, need to be added to
the gpg-agent initially through the ssh-add utility. When a key is
added, ssh-add will ask for the password of the provided key file and
send the unprotected key material to the agent; this causes the
gpg-agent to ask for a passphrase, which is to be used for encrypting
the newly received key and storing it in a gpg-agent specific
Once a key has been added to the gpg-agent this way, the gpg-agent
will be ready to use the key.
Note: in case the gpg-agent receives a signature request, the user might
need to be prompted for a passphrase, which is necessary for decrypting
the stored key. Since the ssh-agent protocol does not contain a
mechanism for telling the agent on which display/terminal it is running,
gpg-agent's ssh-support will use the TTY or X display where gpg-agent
has been started. To switch this display to the current one, the
following command may be used:
gpg-connect-agent updatestartuptty /bye
Although all GnuPG components try to start the gpg-agent as needed, this
is not possible for the ssh support because ssh does not know about it.
Thus if no GnuPG tool which accesses the agent has been run, there is no
guarantee that ssh is able to use gpg-agent for authentication. To fix
this you may start gpg-agent if needed using this simple command:
Adding the --verbose shows the progress of starting the agent.
The --enable-putty-support is only available under Windows
and allows the use of gpg-agent with the ssh implementation
putty. This is similar to the regular ssh-agent support but
makes use of Windows message queue as required by putty.
All the long options may also be given in the configuration file after
stripping off the two leading dashes.