doc: Add a hint about gpgsm and DECRYPTION_INFO.
[gnupg.git] / doc / dirmngr.texi
index bb8281d..76be528 100644 (file)
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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