doc: Add a hint about gpgsm and DECRYPTION_INFO.
[gnupg.git] / doc / dirmngr.texi
index 0f37cc4..76be528 100644 (file)
@@ -66,7 +66,7 @@ abbreviate this command.
 @item --help, -h
 @opindex help
 Print a usage message summarizing the most useful command-line options.
-Note that you can abbreviate this command.
+Note that you cannot abbreviate this command.
 
 @item --dump-options
 @opindex dump-options
@@ -82,8 +82,16 @@ This is only used for testing.
 @item --daemon
 @opindex daemon
 Run in background daemon mode and listen for commands on a socket.
-Note that this also changes the default home directory and enables the
-internal certificate validation code.  This mode is deprecated.
+This is the way @command{dirmngr} is started on demand by the other
+GnuPG components.  To force starting @command{dirmngr} it is in
+general best to use @code{gpgconf --launch dirmngr}.
+
+@item --supervised
+@opindex supervised
+Run in the foreground, sending logs to stderr, and listening on file
+descriptor 3, which must already be bound to a listening socket.  This
+is useful when running under systemd or other similar process
+supervision schemes.  This option is not supported on Windows.
 
 @item --list-crls
 @opindex list-crls
@@ -123,6 +131,10 @@ will thus trigger reading of fresh CRLs.
 @node Dirmngr Options
 @section Option Summary
 
+Note that all long options with the exception of @option{--options}
+and @option{--homedir} may also be given in the configuration file
+after stripping off the two leading dashes.
+
 @table @gnupgtabopt
 
 @item --options @var{file}
@@ -134,21 +146,11 @@ per-user configuration file.  The default configuration file is named
 @item --homedir @var{dir}
 @opindex options
 Set the name of the home directory to @var{dir}.  This option is only
-effective when used on the command line.  The default depends on the
-running mode:
-
-@table @asis
-
-@item With @code{--daemon} given on the commandline
-the directory named @file{@value{SYSCONFDIR}} is used for configuration files
-and @file{@value{LOCALCACHEDIR}} for cached CRLs.
-
-@item Without @code{--daemon} given on the commandline
+effective when used on the command line.  The default is
 the directory named @file{.gnupg} directly below the home directory
 of the user unless the environment variable @code{GNUPGHOME} has been set
-in which case its value will be used.  All kind of data is stored below
+in which case its value will be used.  Many kinds of data are stored within
 this directory.
-@end table
 
 
 @item -v
@@ -196,17 +198,20 @@ however carefully selected to best aid in debugging.
 
 @item --debug @var{flags}
 @opindex debug
-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.
+Set debugging flags.  This option is only useful for debugging and its
+behavior may change with a new release.  All flags are or-ed and 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.
 
 @item --debug-all
 @opindex debug-all
 Same as @code{--debug=0xffffffff}
 
-@item --gnutls-debug @var{level}
-@opindex gnutls-debug
-Enable debugging of GNUTLS at @var{level}.
+@item --tls-debug @var{level}
+@opindex tls-debug
+Enable debugging of the TLS layer at @var{level}.  The details of the
+debug level depend on the used TLS library and are not set in stone.
 
 @item --debug-wait @var{n}
 @opindex debug-wait
@@ -229,7 +234,7 @@ self-test for debugging purposes.
 @opindex c
 @opindex csh
 Format the info output in daemon mode for use with the standard Bourne
-shell respective the C-shell . The default ist to guess it based on the
+shell respective the C-shell. The default is to guess it based on the
 environment variable @code{SHELL} which is in almost all cases
 sufficient.
 
@@ -239,12 +244,63 @@ Enabling this option forces loading of expired CRLs; this is only
 useful for debugging.
 
 @item --use-tor
+@itemx --no-use-tor
 @opindex use-tor
-This option switches Dirmngr and thus GnuPG into ``Tor mode'' to route
-all network access via Tor (an anonymity network).  WARNING: As of now
-this still leaks the DNS queries; e.g. to lookup the hosts in a
-keyserver pool.  Certain other features are disabled if this mode is
-active.
+@opindex no-use-tor
+The option @option{--use-tor} switches Dirmngr and thus GnuPG into
+``Tor mode'' to route all network access via Tor (an anonymity
+network).  Certain other features are disabled in this mode.  The
+effect of @option{--use-tor} cannot be overridden by any other command
+or even be reloading gpg-agent.  The use of @option{--no-use-tor}
+disables the use of Tor.  The default is to use Tor if it is available
+on startup or after reloading dirmngr.
+
+@item --standard-resolver
+@opindex standard-resolver
+This option forces the use of the system's standard DNS resolver code.
+This is mainly used for debugging.  Note that on Windows a standard
+resolver is not used and all DNS access will return the error ``Not
+Implemented'' if this function is used.
+
+@item --recursive-resolver
+@opindex recursive-resolver
+When possible use a recursive resolver instead of a stub resolver.
+
+@item --resolver-timeout @var{n}
+@opindex resolver-timeout
+Set the timeout for the DNS resolver to N seconds.  The default are 30
+seconds.
+
+@item --connect-timeout @var{n}
+@item --connect-quick-timeout @var{n}
+@opindex connect-timeout
+@opindex connect-quick-timeout
+Set the timeout for HTTP and generic TCP connection attempts to N
+seconds.  The value set with the quick variant is used when the
+--quick option has been given to certain Assuan commands.  The quick
+value is capped at the value of the regular connect timeout.  The
+default values are 15 and 2 seconds.  Note that the timeout values are
+for each connection attempt; the connection code will attempt to
+connect all addresses listed for a server.
+
+@item --listen-backlog @var{n}
+@opindex listen-backlog
+Set the size of the queue for pending connections.  The default is 64.
+
+@item --allow-version-check
+@opindex allow-version-check
+Allow Dirmngr to connect to @code{https://versions.gnupg.org} to get
+the list of current software versions.  If this option is enabled
+the list is retrieved in case the local
+copy does not exist or is older than 5 to 7 days.  See the option
+@option{--query-swdb} of the command @command{gpgconf} for more
+details.  Note, that regardless of this option a version check can
+always be triggered using this command:
+
+@example
+       gpg-connect-agent --dirmngr 'loadswdb --force' /bye
+@end example
+
 
 @item --keyserver @var{name}
 @opindex keyserver
@@ -270,6 +326,8 @@ service (.onion), Dirmngr selects the keyserver to use depending on
 whether Tor is locally running or not.  The check for a running Tor is
 done for each new connection.
 
+If no keyserver is explicitly configured, dirmngr will use the
+built-in default of hkps://hkps.pool.sks-keyservers.net.
 
 @item --nameserver @var{ipaddr}
 @opindex nameserver
@@ -277,8 +335,13 @@ In ``Tor mode'' Dirmngr uses a public resolver via Tor to resolve DNS
 names.  If the default public resolver, which is @code{8.8.8.8}, shall
 not be used a different one can be given using this option.  Note that
 a numerical IP address must be given (IPv6 or IPv4) and that no error
-checking is done for @var{ipaddr}.  DNS queries in Tor mode do only
-work if GnuPG as been build with ADNS support.
+checking is done for @var{ipaddr}.
+
+@item --disable-ipv4
+@item --disable-ipv6
+@opindex disable-ipv4
+@opindex disable-ipv6
+Disable the use of all IPv4 or IPv6 addresses.
 
 @item --disable-ldap
 @opindex disable-ldap
@@ -338,8 +401,7 @@ configured LDAP server if the connection using the "proxy" failed.
 @opindex ldapserverlist-file
 Read the list of LDAP servers to consult for CRLs and certificates from
 file instead of the default per-user ldap server list file. The default
-value for @var{file} is @file{dirmngr_ldapservers.conf} or
-@file{ldapservers.conf} when running in @option{--daemon} mode.
+value for @var{file} is @file{dirmngr_ldapservers.conf}.
 
 This server list file contains one LDAP server per line in the format
 
@@ -359,7 +421,7 @@ percent-escaped strings.}
 @item --ldaptimeout @var{secs}
 @opindex ldaptimeout
 Specify the number of seconds to wait for an LDAP query before timing
-out. The default is currently 100 seconds.  0 will never timeout.
+out.  The default are 15 seconds.  0 will never timeout.
 
 
 @item --add-servers
@@ -419,7 +481,7 @@ prefix with a hash mark are ignored.
 @item --ocsp-max-clock-skew @var{n}
 @opindex ocsp-max-clock-skew
 The number of seconds a skew between the OCSP responder and them local
-clock is accepted.  Default is 600 (20 minutes).
+clock is accepted.  Default is 600 (10 minutes).
 
 @item --ocsp-max-period @var{n}
 @opindex ocsp-max-period
@@ -455,6 +517,11 @@ the file is in PEM format a suffix of @code{.pem} is expected for
 @var{file}.  This option may be given multiple times to add more
 root certificates.  Tilde expansion is supported.
 
+If no @code{hkp-cacert} directive is present, dirmngr will make a
+reasonable choice: if the keyserver in question is the special pool
+@code{hkps.pool.sks-keyservers.net}, it will use the bundled root
+certificate for that pool.  Otherwise, it will use the system CAs.
+
 @end table
 
 
@@ -466,11 +533,20 @@ root certificates.  Tilde expansion is supported.
 @section Configuration
 
 Dirmngr makes use of several directories when running in daemon mode:
+There are a few configuration files whih control the operation of
+dirmngr.  By default they may all be found in the current home
+directory (@pxref{option --homedir}).
 
 @table @file
 
-@item ~/.gnupg
-This is the standard home directory for all configuration files.
+@item dirmngr.conf
+@efindex dirmngr.conf
+This is the standard configuration file read by @command{dirmngr} 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 file
+is also read after a @code{SIGHUP} however not all options will
+actually have an effect.  This default name may be changed on the
+command line (@pxref{option --options}).  You should backup this file.
 
 @item /etc/gnupg/trusted-certs
 This directory should be filled with certificates of Root CAs you
@@ -493,7 +569,7 @@ Note that for OCSP responses the certificate specified using the option
 
 @item /etc/gnupg/extra-certs
 This directory may contain extra certificates which are preloaded
-into the interal cache on startup. Applications using dirmngr (e.g. gpgsm)
+into the internal cache on startup. Applications using dirmngr (e.g. gpgsm)
 can request cached certificates to complete a trust chain.
 This is convenient in cases you have a couple intermediate CA certificates
 or certificates usually used to sign OCSP responses.
@@ -539,7 +615,7 @@ certificates have been loaded correctly.
 @c
 @mansect signals
 @node Dirmngr Signals
-@section Use of signals.
+@section Use of signals
 
 A running @command{dirmngr} may be controlled by signals, i.e. using
 the @command{kill} command to send a signal to the process.
@@ -724,7 +800,7 @@ configuration.
 @end table
 
 If DirMngr has not enough information about the given certificate (which
-is the case for not yet cached certificates), it will will inquire the
+is the case for not yet cached certificates), it will inquire the
 missing data:
 
 @example
@@ -747,7 +823,7 @@ this the root certificate:
   C: END
 @end example
 
-Only this answer will let Dirmngr consider the CRL as valid.
+Only this answer will let Dirmngr consider the certificate as valid.
 
 
 @node Dirmngr CHECKCRL
@@ -987,7 +1063,7 @@ as a binary blob.
 @c  c) No authorityKeyIdentifier exits: The certificate is retrieved
 @c     using @code{find_cert_bysubject} without the key ID argument.  If
 @c     the certificate is in the certificate cache the first one with a
-@c     matching subject is is directly returned.  Then the requester is
+@c     matching subject is directly returned.  Then the requester is
 @c     asked via the Assuan inquiry ``SENDCERT'' and an exact
 @c     specification of the subject whether he can
 @c     provide this certificate.  If this succeed the returned
@@ -1064,7 +1140,7 @@ as a binary blob.
 @c respectively. The have already been described above under the
 @c description of @code{crl_cache_insert}.  If no certificate was found
 @c or with no authorityKeyIdentifier, only the cache is consulted using
-@c @code{get_cert_bysubject}.  The latter is is done under the assumption
+@c @code{get_cert_bysubject}.  The latter is done under the assumption
 @c that a matching certificate has explicitly been put into the
 @c certificate cache.  If the issuer's certificate could not be found,
 @c the validation terminates with the error code @code{GPG_ERR_MISSING_CERT}.
@@ -1089,7 +1165,7 @@ as a binary blob.
 @c recursive process because a CRL has to be checked for each certificate
 @c in the chain except for the root certificate, of which we already know
 @c that it is trusted and we avoid checking a CRL here due to common
-@c setup problems and the assumption that a revoked root certifcate has
+@c setup problems and the assumption that a revoked root certificate has
 @c been removed from the list of trusted certificates.
 @c
 @c