dirmngr: New option --resolver-timeout.
[gnupg.git] / doc / dirmngr.texi
index 0f37cc4..5b4e68b 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
@@ -134,21 +142,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
@@ -229,7 +227,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.
 
@@ -246,6 +244,30 @@ 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.
 
+@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}
+Set the timeout for the DNS resolver to N seconds.  The default are 30
+seconds.
+
+@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, or
+if @option{use-tor} is active, the list is retrieved when 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.
+
 @item --keyserver @var{name}
 @opindex keyserver
 Use @var{name} as your keyserver.  This is the server that @command{gpg}
@@ -270,6 +292,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 +301,7 @@ 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-ldap
 @opindex disable-ldap
@@ -338,8 +361,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
 
@@ -419,7 +441,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 +477,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
 
 
@@ -493,7 +520,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 +566,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.
@@ -747,7 +774,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