File: gnupg.info,  Node: Agent Options,  Next: Agent Configuration,  Prev: Agent Commands,  Up: Invoking GPG-AGENT

2.2 Option Summary
==================

Options may either be used on the command line or, after stripping off
the two leading dashes, in the configuration file.

'--options FILE'
     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.  This option is ignored if
     used in an options file.

'--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.

'-v'
'--verbose'
     Outputs additional information while running.  You can increase the
     verbosity by giving several verbose commands to 'gpg-agent', such
     as '-vv'.

'-q'
'--quiet'
     Try to be as quiet as possible.

'--batch'
     Don't invoke a pinentry or do any other thing requiring human
     interaction.

'--faked-system-time EPOCH'
     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 1970.

'--debug-level LEVEL'
     Select the debug level for investigating problems.  LEVEL may be a
     numeric value or a keyword:

     'none'
          No debugging at all.  A value of less than 1 may be used
          instead of the keyword.
     'basic'
          Some basic debug messages.  A value between 1 and 2 may be
          used instead of the keyword.
     'advanced'
          More verbose debug messages.  A value between 3 and 5 may be
          used instead of the keyword.
     'expert'
          Even more detailed messages.  A value between 6 and 8 may be
          used instead of the keyword.
     'guru'
          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.

'--debug FLAGS'
     Set debug flags.  All flags are or-ed and FLAGS may be given in C
     syntax (e.g.  0x0042) or as a comma separated list of flag names.
     To get a list of all supported flags the single word "help" can be
     used.  This option is only useful for debugging and the behavior
     may change at any time without notice.

'--debug-all'
     Same as '--debug=0xffffffff'

'--debug-wait N'
     When running in server mode, wait N seconds before entering the
     actual processing loop and print the pid.  This gives time to
     attach a debugger.

'--debug-quick-random'
     This option inhibits the use of the very secure random quality
     level (Libgcrypt’s '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'.

'--debug-pinentry'
     This option enables extra debug information pertaining to the
     Pinentry.  As of now it is only useful when used along with
     '--debug 1024'.

'--no-detach'
     Don't detach the process from the console.  This is mainly useful
     for debugging.

'--steal-socket'
     In '--daemon' mode, gpg-agent detects an already running gpg-agent
     and does not allow one to start a new instance.  This option can be
     used to override this check: the new gpg-agent process will try to
     take over the communication sockets from the already running
     process and start anyway.  This option should in general not be
     used.

'-s'
'--sh'
'-c'
'--csh'
     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 cases.

'--grab'
'--no-grab'
     Tell the pinentry to grab the keyboard and mouse.  This option
     should be used on X-Servers to avoid X-sniffing attacks.  Any use
     of the option '--grab' overrides an used option '--no-grab'.  The
     default is '--no-grab'.

'--log-file FILE'
     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.

'--no-allow-mark-trusted'
     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.

'--no-user-trustlist'
     Entirely ignore the user trust list and consider only the global
     trustlist ('/usr/local/etc/gnupg/trustlist.txt').  This implies the
     *note option --no-allow-mark-trusted::.

'--sys-trustlist-name FILE'
     Changes the default name for the global trustlist from
     "trustlist.txt" to FILE.  If FILE does not contain any slashes and
     does not start with "~/" it is searched in the system configuration
     directory ('/usr/local/etc/gnupg').

'--allow-preset-passphrase'
     This option allows the use of 'gpg-preset-passphrase' to seed the
     internal cache of 'gpg-agent' with passphrases.

'--no-allow-loopback-pinentry'
'--allow-loopback-pinentry'
     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.

'--no-allow-external-cache'
     Tell Pinentry not to enable features which use an external cache
     for passphrases.

     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.

'--allow-emacs-pinentry'
     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.

'--ignore-cache-for-signing'
     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.

'--default-cache-ttl N'
     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
     'max-cache-ttl'.  Note that a cached passphrase may not be evicted
     immediately from memory if no client requests a cache operation.
     This is due to an internal housekeeping function which is only run
     every few seconds.

'--default-cache-ttl-ssh N'
     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'.

'--max-cache-ttl N'
     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).

'--max-cache-ttl-ssh N'
     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 seconds).

'--enforce-passphrase-constraints'
     Enforce the passphrase constraints by not allowing the user to
     bypass them using the "Take it anyway" button.

'--min-passphrase-len N'
     Set the minimal length of a passphrase.  When entering a new
     passphrase shorter than this value a warning will be displayed.
     Defaults to 8.

'--min-passphrase-nonalpha N'
     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 to 1.

'--check-passphrase-pattern FILE'
'--check-sym-passphrase-pattern FILE'
     Check the passphrase against the pattern given in FILE.  When
     entering a new passphrase matching one of these pattern a warning
     will be displayed.  If FILE does not contain any slashes and does
     not start with "~/" it is searched in the system configuration
     directory ('/usr/local/etc/gnupg').  The default is not to use any
     pattern file.  The second version of this option is only used when
     creating a new symmetric key to allow the use of different patterns
     for such passphrases.

     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.

'--max-passphrase-days N'
     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.

'--enable-passphrase-history'
     This option does nothing yet.

'--pinentry-invisible-char CHAR'
     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.

'--pinentry-timeout N'
     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.

'--pinentry-formatted-passphrase'
     This option asks the Pinentry to enable passphrase formatting when
     asking the user for a new passphrase and masking of the passphrase
     is turned off.

     If passphrase formatting is enabled, then all non-breaking space
     characters are stripped from the entered passphrase.  Passphrase
     formatting is mostly useful in combination with passphrases
     generated with the GENPIN feature of some Pinentries.  Note that
     such a generated passphrase, if not modified by the user, skips all
     passphrase constraints checking because such constraints would
     actually weaken the generated passphrase.

'--pinentry-program FILENAME'
     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: 'bin\pinentry.exe',
     '..\Gpg4win\bin\pinentry.exe', '..\Gpg4win\pinentry.exe',
     '..\GNU\GnuPG\pinentry.exe', '..\GNU\bin\pinentry.exe',
     'bin\pinentry-basic.exe' where the file names are relative to the
     GnuPG installation directory.

'--pinentry-touch-file FILENAME'
     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.

'--scdaemon-program FILENAME'
     Use program FILENAME as the Smartcard daemon.  The default is
     installation dependent and can be shown with the 'gpgconf' command.

'--disable-scdaemon'
     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.

'--disable-check-own-socket'
     '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 debugging purposes.

'--use-standard-socket'
'--no-use-standard-socket'
'--use-standard-socket-p'
     Since GnuPG 2.1 the standard socket is always used.  These options
     have no more effect.  The command 'gpg-agent
     --use-standard-socket-p' will thus always return success.

'--display STRING'
'--ttyname STRING'
'--ttytype STRING'
'--lc-ctype STRING'
'--lc-messages STRING'
'--xauthority STRING'
     These options are used with the server mode to pass localization
     information.

'--keep-tty'
'--keep-display'
     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.

'--listen-backlog N'
     Set the size of the queue for pending connections.  The default is
     64.

'--extra-socket NAME'
     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 remote machine.

'--enable-extended-key-format'
'--disable-extended-key-format'
     These options are obsolete and have no effect.  The extended key
     format is used for years now and has been supported since 2.1.12.
     Existing keys in the old format are migrated to the new format as
     soon as they are touched.

'--enable-ssh-support'
'--enable-win32-openssh-support'
'--enable-putty-support'

     On Unix platforms the OpenSSH Agent protocol is always enabled, but
     'gpg-agent' will only set the 'SSH_AUTH_SOCK' variable if the
     option 'enable-ssh-support' is given.  Some Linux distributions use
     the presence of this option to decide whether the old ssh-agent
     shall be started.

     On Windows support for the native ssh implementation must be
     enabled using the the option 'enable-win32-openssh-support'.  For
     using gpg-agent as a replacement for PuTTY's Pageant, the option
     'enable-putty-support' must be enabled.

     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 or via Named Pipes) or the protocol used
     by PuTTY. Consequently, this allows one to use the gpg-agent as a
     drop-in replacement for the 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 directory.

     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:

          gpg-connect-agent /bye

     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'.

     The order in which keys are presented to ssh are:

     'Negative Use-for-ssh values'
          If a key file has the attribute "Use-for-ssh" and its value is
          negative, these keys are presented first to ssh.  The negative
          values are capped at -999 with -999 being lower ranked than
          -1.  These values can be used to prefer on-disk keys over keys
          taken from active cards.

     'Active cards'
          Active cards (inserted into a card reader or plugged in
          tokens) are always tried; they are ordered by their serial
          numbers.

     'Keys listed in the sshcontrol file'
          Non-disabled keys from the sshcontrol file are presented in
          the order they appear in this file.  Note that the sshcontrol
          file is deprecated.

     'Positive Use-for-ssh values'
          If a key file has the attribute "Use-for-ssh" and its value is
          "yes", "true", or any positive number the key is presented in
          the order of their values.  "yes" and "true" have a value of
          1; other values are capped at 99999.

     Editing the "Use-for-ssh" values can be done with an editor or
     using 'gpg-connect-agent' and "KEYATTR" (Remember to append a colon
     to the key; i.e.  use "Use-for-ssh:").

'--ssh-fingerprint-digest'

     Select the digest algorithm used to compute ssh fingerprints that
     are communicated to the user, e.g.  in pinentry dialogs.  OpenSSH
     has transitioned from using MD5 to the more secure SHA256.

'--auto-expand-secmem N'
     Allow Libgcrypt to expand its secure memory area as required.  The
     optional value N is a non-negative integer with a suggested size in
     bytes of each additionally allocated secure memory area.  The value
     is rounded up to the next 32 KiB; usual C style prefixes are
     allowed.  For an heavy loaded gpg-agent with many concurrent
     connection this option avoids sign or decrypt errors due to out of
     secure memory error returns.

'--s2k-calibration MILLISECONDS'
     Change the default calibration time to MILLISECONDS.  The given
     value is capped at 60 seconds; a value of 0 resets to the
     compiled-in default.  This option is re-read on a SIGHUP (or
     'gpgconf --reload gpg-agent') and the S2K count is then
     re-calibrated.

'--s2k-count N'
     Specify the iteration count used to protect the passphrase.  This
     option can be used to override the auto-calibration done by
     default.  The auto-calibration computes a count which requires by
     default 100ms to mangle a given passphrase.  See also
     '--s2k-calibration'.

     To view the actually used iteration count and the milliseconds
     required for an S2K operation use:

          gpg-connect-agent 'GETINFO s2k_count' /bye
          gpg-connect-agent 'GETINFO s2k_time' /bye

     To view the auto-calibrated count use:

          gpg-connect-agent 'GETINFO s2k_count_cal' /bye