summaryrefslogtreecommitdiffstats
path: root/doc/tools.texi
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/tools.texi2136
1 files changed, 2136 insertions, 0 deletions
diff --git a/doc/tools.texi b/doc/tools.texi
new file mode 100644
index 0000000..6b9a9fe
--- /dev/null
+++ b/doc/tools.texi
@@ -0,0 +1,2136 @@
+@c Copyright (C) 2004, 2008 Free Software Foundation, Inc.
+@c This is part of the GnuPG manual.
+@c For copying conditions, see the file GnuPG.texi.
+
+@include defs.inc
+
+@node Helper Tools
+@chapter Helper Tools
+
+GnuPG comes with a couple of smaller tools:
+
+@menu
+* watchgnupg:: Read logs from a socket.
+* gpgv:: Verify OpenPGP signatures.
+* addgnupghome:: Create .gnupg home directories.
+* gpgconf:: Modify .gnupg home directories.
+* applygnupgdefaults:: Run gpgconf for all users.
+* gpg-preset-passphrase:: Put a passphrase into the cache.
+* gpg-connect-agent:: Communicate with a running agent.
+* dirmngr-client:: How to use the Dirmngr client tool.
+* gpgparsemail:: Parse a mail message into an annotated format
+* gpgtar:: Encrypt or sign files into an archive.
+* gpg-check-pattern:: Check a passphrase on stdin against the patternfile.
+@end menu
+
+@c
+@c WATCHGNUPG
+@c
+@manpage watchgnupg.1
+@node watchgnupg
+@section Read logs from a socket
+@ifset manverb
+.B watchgnupg
+\- Read and print logs from a socket
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B watchgnupg
+.RB [ \-\-force ]
+.RB [ \-\-verbose ]
+.I socketname
+@end ifset
+
+@mansect description
+Most of the main utilities are able to write their log files to a Unix
+Domain socket if configured that way. @command{watchgnupg} is a simple
+listener for such a socket. It ameliorates the output with a time stamp
+and makes sure that long lines are not interspersed with log output from
+other utilities. This tool is not available for Windows.
+
+
+@noindent
+@command{watchgnupg} is commonly invoked as
+
+@example
+watchgnupg --force $(gpgconf --list-dirs socketdir)/S.log
+@end example
+@manpause
+
+@noindent
+This starts it on the current terminal for listening on the standard
+logging socket (which is either @file{~/.gnupg/S.log} or
+@file{/var/run/user/UID/gnupg/S.log}).
+
+@mansect options
+@noindent
+@command{watchgnupg} understands these options:
+
+@table @gnupgtabopt
+
+@item --force
+@opindex force
+Delete an already existing socket file.
+
+@anchor{option watchgnupg --tcp}
+@item --tcp @var{n}
+Instead of reading from a local socket, listen for connects on TCP port
+@var{n}.
+
+@item --time-only
+@opindex time-only
+Do not print the date part of the timestamp.
+
+@item --verbose
+@opindex verbose
+Enable extra informational output.
+
+@item --version
+@opindex version
+Print version of the program and exit.
+
+@item --help
+@opindex help
+Display a brief help page and exit.
+
+@end table
+
+@noindent
+@mansect examples
+@chapheading Examples
+
+@example
+$ watchgnupg --force --time-only $(gpgconf --list-dirs socketdir)/S.log
+@end example
+
+This waits for connections on the local socket
+(e.g. @file{/home/foo/.gnupg/S.log}) and shows all log entries. To
+make this work the option @option{log-file} needs to be used with all
+modules which logs are to be shown. The suggested entry for the
+configuration files is:
+
+@example
+log-file socket://
+@end example
+
+If the default socket as given above and returned by "echo $(gpgconf
+--list-dirs socketdir)/S.log" is not desired an arbitrary socket name
+can be specified, for example @file{socket:///home/foo/bar/mysocket}.
+For debugging purposes it is also possible to do remote logging. Take
+care if you use this feature because the information is send in the
+clear over the network. Use this syntax in the conf files:
+
+@example
+log-file tcp://192.168.1.1:4711
+@end example
+
+You may use any port and not just 4711 as shown above; only IP
+addresses are supported (v4 and v6) and no host names. You need to
+start @command{watchgnupg} with the @option{tcp} option. Note that
+under Windows the registry entry
+@var{HKCU\Software\GNU\GnuPG:DefaultLogFile} can be used to change the
+default log output from @code{stderr} to whatever is given by that
+entry. However the only useful entry is a TCP name for remote
+debugging.
+
+
+@mansect see also
+@ifset isman
+@command{gpg}(1),
+@command{gpgsm}(1),
+@command{gpg-agent}(1),
+@command{scdaemon}(1)
+@end ifset
+@include see-also-note.texi
+
+
+@c
+@c GPGV
+@c
+@include gpgv.texi
+
+
+@c
+@c ADDGNUPGHOME
+@c
+@manpage addgnupghome.8
+@node addgnupghome
+@section Create .gnupg home directories
+@ifset manverb
+.B addgnupghome
+\- Create .gnupg home directories
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B addgnupghome
+.I account_1
+.IR account_2 ... account_n
+@end ifset
+
+@mansect description
+If GnuPG is installed on a system with existing user accounts, it is
+sometimes required to populate the GnuPG home directory with existing
+files. Especially a @file{trustlist.txt} and a keybox with some
+initial certificates are often desired. This script helps to do this
+by copying all files from @file{/etc/skel/.gnupg} to the home
+directories of the accounts given on the command line. It takes care
+not to overwrite existing GnuPG home directories.
+
+@noindent
+@command{addgnupghome} is invoked by root as:
+
+@example
+addgnupghome account1 account2 ... accountn
+@end example
+
+
+@c
+@c GPGCONF
+@c
+@manpage gpgconf.1
+@node gpgconf
+@section Modify .gnupg home directories
+@ifset manverb
+.B gpgconf
+\- Modify .gnupg home directories
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B gpgconf
+.RI [ options ]
+.B \-\-list-components
+.br
+.B gpgconf
+.RI [ options ]
+.B \-\-list-options
+.I component
+.br
+.B gpgconf
+.RI [ options ]
+.B \-\-change-options
+.I component
+@end ifset
+
+
+@mansect description
+The @command{gpgconf} is a utility to automatically and reasonable
+safely query and modify configuration files in the @file{.gnupg} home
+directory. It is designed not to be invoked manually by the user, but
+automatically by graphical user interfaces (GUI).@footnote{Please note
+that currently no locking is done, so concurrent access should be
+avoided. There are some precautions to avoid corruption with
+concurrent usage, but results may be inconsistent and some changes may
+get lost. The stateless design makes it difficult to provide more
+guarantees.}
+
+@command{gpgconf} provides access to the configuration of one or more
+components of the GnuPG system. These components correspond more or
+less to the programs that exist in the GnuPG framework, like GPG,
+GPGSM, DirMngr, etc. But this is not a strict one-to-one
+relationship. Not all configuration options are available through
+@command{gpgconf}. @command{gpgconf} provides a generic and abstract
+method to access the most important configuration options that can
+feasibly be controlled via such a mechanism.
+
+@command{gpgconf} can be used to gather and change the options
+available in each component, and can also provide their default
+values. @command{gpgconf} will give detailed type information that
+can be used to restrict the user's input without making an attempt to
+commit the changes.
+
+@command{gpgconf} provides the backend of a configuration editor. The
+configuration editor would usually be a graphical user interface
+program that displays the current options, their default
+values, and allows the user to make changes to the options. These
+changes can then be made active with @command{gpgconf} again. Such a
+program that uses @command{gpgconf} in this way will be called GUI
+throughout this section.
+
+@menu
+* Invoking gpgconf:: List of all commands and options.
+* Format conventions:: Formatting conventions relevant for all commands.
+* Listing components:: List all gpgconf components.
+* Checking programs:: Check all programs known to gpgconf.
+* Listing options:: List all options of a component.
+* Changing options:: Changing options of a component.
+* Listing global options:: List all global options.
+* Querying versions:: Get and compare software versions.
+* Files used by gpgconf:: What files are used by gpgconf.
+@end menu
+
+@manpause
+@node Invoking gpgconf
+@subsection Invoking gpgconf
+
+@mansect commands
+One of the following commands must be given:
+
+@table @gnupgtabopt
+
+@item --list-components
+List all components. This is the default command used if none is
+specified.
+
+@item --check-programs
+List all available backend programs and test whether they are runnable.
+
+@item --list-options @var{component}
+List all options of the component @var{component}.
+
+@item --change-options @var{component}
+Change the options of the component @var{component}.
+
+@item --check-options @var{component}
+Check the options for the component @var{component}.
+
+@item --apply-profile @var{file}
+Apply the configuration settings listed in @var{file} to the
+configuration files. If @var{file} has no suffix and no slashes the
+command first tries to read a file with the suffix @code{.prf} from
+the data directory (@code{gpgconf --list-dirs datadir}) before it
+reads the file verbatim. A profile is divided into sections using the
+bracketed component name. Each section then lists the option which
+shall go into the respective configuration file.
+
+@item --apply-defaults
+Update all configuration files with values taken from the global
+configuration file (usually @file{/etc/gnupg/gpgconf.conf}).
+Note: This is a legacy mechanism. Please use global configuraion
+files instead.
+
+@item --list-dirs [@var{names}]
+@itemx -L
+Lists the directories used by @command{gpgconf}. One directory is
+listed per line, and each line consists of a colon-separated list where
+the first field names the directory type (for example @code{sysconfdir})
+and the second field contains the percent-escaped directory. Although
+they are not directories, the socket file names used by
+@command{gpg-agent} and @command{dirmngr} are printed as well. Note
+that the socket file names and the @code{homedir} lines are the default
+names and they may be overridden by command line switches. If
+@var{names} are given only the directories or file names specified by
+the list names are printed without any escaping.
+
+@item --list-config [@var{filename}]
+List the global configuration file in a colon separated format. If
+@var{filename} is given, check that file instead.
+
+@item --check-config [@var{filename}]
+Run a syntax check on the global configuration file. If @var{filename}
+is given, check that file instead.
+
+
+@item --query-swdb @var{package_name} [@var{version_string}]
+Returns the current version for @var{package_name} and if
+@var{version_string} is given also an indicator on whether an update
+is available. The actual file with the software version is
+automatically downloaded and checked by @command{dirmngr}.
+@command{dirmngr} uses a thresholds to avoid download the file too
+often and it does this by default only if it can be done via Tor. To
+force an update of that file this command can be used:
+
+@example
+ gpg-connect-agent --dirmngr 'loadswdb --force' /bye
+@end example
+
+@item --reload [@var{component}]
+@itemx -R
+@opindex reload
+Reload all or the given component. This is basically the same as
+sending a SIGHUP to the component. Components which don't support
+reloading are ignored. Without @var{component} or by using "all" for
+@var{component} all components which are daemons are reloaded.
+
+@item --launch [@var{component}]
+@opindex launch
+If the @var{component} is not already running, start it.
+@command{component} must be a daemon. This is in general not required
+because the system starts these daemons as needed. However, external
+software making direct use of @command{gpg-agent} or @command{dirmngr}
+may use this command to ensure that they are started. Using "all" for
+@var{component} launches all components which are daemons.
+
+@item --kill [@var{component}]
+@itemx -K
+@opindex kill
+Kill the given component that runs as a daemon, including
+@command{gpg-agent}, @command{dirmngr}, and @command{scdaemon}. A
+@command{component} which does not run as a daemon will be ignored.
+Using "all" for @var{component} kills all components running as
+daemons. Note that as of now reload and kill have the same effect for
+@command{scdaemon}.
+
+@item --create-socketdir
+@opindex create-socketdir
+Create a directory for sockets below /run/user or /var/run/user. This
+is command is only required if a non default home directory is used
+and the /run based sockets shall be used. For the default home
+directory GnUPG creates a directory on the fly.
+
+@item --remove-socketdir
+@opindex remove-socketdir
+Remove a directory created with command @option{--create-socketdir}.
+
+@end table
+
+
+@mansect options
+
+The following options may be used:
+
+@table @gnupgtabopt
+
+@item -o @var{file}
+@itemx --output @var{file}
+Write output to @var{file}. Default is to write to stdout.
+
+@item -v
+@itemx --verbose
+Outputs additional information while running. Specifically, this
+extends numerical field values by human-readable descriptions.
+
+@item -q
+@itemx --quiet
+@opindex quiet
+Try to be as quiet as possible.
+
+@include opt-homedir.texi
+
+@item -n
+@itemx --dry-run
+Do not actually change anything. This is currently only implemented
+for @code{--change-options} and can be used for testing purposes.
+
+@item -r
+@itemx --runtime
+Only used together with @code{--change-options}. If one of the
+modified options can be changed in a running daemon process, signal
+the running daemon to ask it to reparse its configuration file after
+changing.
+
+This means that the changes will take effect at run-time, as far as
+this is possible. Otherwise, they will take effect at the next start
+of the respective backend programs.
+
+@item --status-fd @var{n}
+@opindex status-fd
+Write special status strings to the file descriptor @var{n}. This
+program returns the status messages SUCCESS or FAILURE which are
+helpful when the caller uses a double fork approach and can't easily
+get the return code of the process.
+
+@manpause
+@end table
+
+
+@node Format conventions
+@subsection Format conventions
+
+Some lines in the output of @command{gpgconf} contain a list of
+colon-separated fields. The following conventions apply:
+
+@itemize @bullet
+@item
+The GUI program is required to strip off trailing newline and/or
+carriage return characters from the output.
+
+@item
+@command{gpgconf} will never leave out fields. If a certain version
+provides a certain field, this field will always be present in all
+@command{gpgconf} versions from that time on.
+
+@item
+Future versions of @command{gpgconf} might append fields to the list.
+New fields will always be separated from the previously last field by
+a colon separator. The GUI should be prepared to parse the last field
+it knows about up until a colon or end of line.
+
+@item
+Not all fields are defined under all conditions. You are required to
+ignore the content of undefined fields.
+@end itemize
+
+There are several standard types for the content of a field:
+
+@table @asis
+@item verbatim
+Some fields contain strings that are not escaped in any way. Such
+fields are described to be used @emph{verbatim}. These fields will
+never contain a colon character (for obvious reasons). No de-escaping
+or other formatting is required to use the field content. This is for
+easy parsing of the output, when it is known that the content can
+never contain any special characters.
+
+@item percent-escaped
+Some fields contain strings that are described to be
+@emph{percent-escaped}. Such strings need to be de-escaped before
+their content can be presented to the user. A percent-escaped string
+is de-escaped by replacing all occurrences of @code{%XY} by the byte
+that has the hexadecimal value @code{XY}. @code{X} and @code{Y} are
+from the set @code{0-9a-f}.
+
+@item localized
+Some fields contain strings that are described to be @emph{localized}.
+Such strings are translated to the active language and formatted in
+the active character set.
+
+@item @w{unsigned number}
+Some fields contain an @emph{unsigned number}. This number will
+always fit into a 32-bit unsigned integer variable. The number may be
+followed by a space, followed by a human readable description of that
+value (if the verbose option is used). You should ignore everything
+in the field that follows the number.
+
+@item @w{signed number}
+Some fields contain a @emph{signed number}. This number will always
+fit into a 32-bit signed integer variable. The number may be followed
+by a space, followed by a human readable description of that value (if
+the verbose option is used). You should ignore everything in the
+field that follows the number.
+
+@item @w{boolean value}
+Some fields contain a @emph{boolean value}. This is a number with
+either the value 0 or 1. The number may be followed by a space,
+followed by a human readable description of that value (if the verbose
+option is used). You should ignore everything in the field that follows
+the number; checking just the first character is sufficient in this
+case.
+
+@item option
+Some fields contain an @emph{option} argument. The format of an
+option argument depends on the type of the option and on some flags:
+
+@table @asis
+@item no argument
+The simplest case is that the option does not take an argument at all
+(@var{type} @code{0}). Then the option argument is an unsigned number
+that specifies how often the option occurs. If the @code{list} flag
+is not set, then the only valid number is @code{1}. Options that do
+not take an argument never have the @code{default} or @code{optional
+arg} flag set.
+
+@item number
+If the option takes a number argument (@var{alt-type} is @code{2} or
+@code{3}), and it can only occur once (@code{list} flag is not set),
+then the option argument is either empty (only allowed if the argument
+is optional), or it is a number. A number is a string that begins
+with an optional minus character, followed by one or more digits. The
+number must fit into an integer variable (unsigned or signed,
+depending on @var{alt-type}).
+
+@item number list
+If the option takes a number argument and it can occur more than once,
+then the option argument is either empty, or it is a comma-separated
+list of numbers as described above.
+
+@item string
+If the option takes a string argument (@var{alt-type} is 1), and it
+can only occur once (@code{list} flag is not set) then the option
+argument is either empty (only allowed if the argument is optional),
+or it starts with a double quote character (@code{"}) followed by a
+percent-escaped string that is the argument value. Note that there is
+only a leading double quote character, no trailing one. The double
+quote character is only needed to be able to differentiate between no
+value and the empty string as value.
+
+@item string list
+If the option takes a string argument and it can occur more than once,
+then the option argument is either empty, or it is a comma-separated
+list of string arguments as described above.
+@end table
+@end table
+
+The active language and character set are currently determined from
+the locale environment of the @command{gpgconf} program.
+
+@c FIXME: Document the active language and active character set. Allow
+@c to change it via the command line?
+
+
+@mansect usage
+@node Listing components
+@subsection Listing components
+
+The command @code{--list-components} will list all components that can
+be configured with @command{gpgconf}. Usually, one component will
+correspond to one GnuPG-related program and contain the options of
+that program's configuration file that can be modified using
+@command{gpgconf}. However, this is not necessarily the case. A
+component might also be a group of selected options from several
+programs, or contain entirely virtual options that have a special
+effect rather than changing exactly one option in one configuration
+file.
+
+A component is a set of configuration options that semantically belong
+together. Furthermore, several changes to a component can be made in
+an atomic way with a single operation. The GUI could for example
+provide a menu with one entry for each component, or a window with one
+tabulator sheet per component.
+
+The command @code{--list-components} lists all available
+components, one per line. The format of each line is:
+
+@code{@var{name}:@var{description}:@var{pgmname}:}
+
+@table @var
+@item name
+This field contains a name tag of the component. The name tag is used
+to specify the component in all communication with @command{gpgconf}.
+The name tag is to be used @emph{verbatim}. It is thus not in any
+escaped format.
+
+@item description
+The @emph{string} in this field contains a human-readable description
+of the component. It can be displayed to the user of the GUI for
+informational purposes. It is @emph{percent-escaped} and
+@emph{localized}.
+
+@item pgmname
+The @emph{string} in this field contains the absolute name of the
+program's file. It can be used to unambiguously invoke that program.
+It is @emph{percent-escaped}.
+@end table
+
+Example:
+@example
+$ gpgconf --list-components
+gpg:GPG for OpenPGP:/usr/local/bin/gpg2:
+gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:
+scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:
+gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:
+dirmngr:Directory Manager:/usr/local/bin/dirmngr:
+@end example
+
+
+
+@node Checking programs
+@subsection Checking programs
+
+The command @code{--check-programs} is similar to
+@code{--list-components} but works on backend programs and not on
+components. It runs each program to test whether it is installed and
+runnable. This also includes a syntax check of all config file options
+of the program.
+
+The command @code{--check-programs} lists all available
+programs, one per line. The format of each line is:
+
+@code{@var{name}:@var{description}:@var{pgmname}:@var{avail}:@var{okay}:@var{cfgfile}:@var{line}:@var{error}:}
+
+@table @var
+@item name
+This field contains a name tag of the program which is identical to the
+name of the component. The name tag is to be used @emph{verbatim}. It
+is thus not in any escaped format. This field may be empty to indicate
+a continuation of error descriptions for the last name. The description
+and pgmname fields are then also empty.
+
+@item description
+The @emph{string} in this field contains a human-readable description
+of the component. It can be displayed to the user of the GUI for
+informational purposes. It is @emph{percent-escaped} and
+@emph{localized}.
+
+@item pgmname
+The @emph{string} in this field contains the absolute name of the
+program's file. It can be used to unambiguously invoke that program.
+It is @emph{percent-escaped}.
+
+@item avail
+The @emph{boolean value} in this field indicates whether the program is
+installed and runnable.
+
+@item okay
+The @emph{boolean value} in this field indicates whether the program's
+config file is syntactically okay.
+
+@item cfgfile
+If an error occurred in the configuration file (as indicated by a false
+value in the field @code{okay}), this field has the name of the failing
+configuration file. It is @emph{percent-escaped}.
+
+@item line
+If an error occurred in the configuration file, this field has the line
+number of the failing statement in the configuration file.
+It is an @emph{unsigned number}.
+
+@item error
+If an error occurred in the configuration file, this field has the error
+text of the failing statement in the configuration file. It is
+@emph{percent-escaped} and @emph{localized}.
+
+@end table
+
+@noindent
+In the following example the @command{dirmngr} is not runnable and the
+configuration file of @command{scdaemon} is not okay.
+
+@example
+$ gpgconf --check-programs
+gpg:GPG for OpenPGP:/usr/local/bin/gpg2:1:1:
+gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:1:1:
+scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:1:0:
+gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:1:1:
+dirmngr:Directory Manager:/usr/local/bin/dirmngr:0:0:
+@end example
+
+@noindent
+The command @w{@code{--check-options @var{component}}} will verify the
+configuration file in the same manner as @code{--check-programs}, but
+only for the component @var{component}.
+
+
+@node Listing options
+@subsection Listing options
+
+Every component contains one or more options. Options may be gathered
+into option groups to allow the GUI to give visual hints to the user
+about which options are related.
+
+The command @code{@w{--list-options @var{component}}} lists
+all options (and the groups they belong to) in the component
+@var{component}, one per line. @var{component} must be the string in
+the field @var{name} in the output of the @code{--list-components}
+command.
+
+Take care if system-wide options are used: gpgconf may not be able to
+properly show the options and the listed options may have no actual
+effect in case the system-wide options enforced their own settings.
+
+There is one line for each option and each group. First come all
+options that are not in any group. Then comes a line describing a
+group. Then come all options that belong into each group. Then comes
+the next group and so on. There does not need to be any group (and in
+this case the output will stop after the last non-grouped option).
+
+The format of each line is:
+
+@code{@var{name}:@var{flags}:@var{level}:@var{description}:@var{type}:@var{alt-type}:@var{argname}:@var{default}:@var{argdef}:@var{value}}
+
+@table @var
+@item name
+This field contains a name tag for the group or option. The name tag
+is used to specify the group or option in all communication with
+@command{gpgconf}. The name tag is to be used @emph{verbatim}. It is
+thus not in any escaped format.
+
+@item flags
+The flags field contains an @emph{unsigned number}. Its value is the
+OR-wise combination of the following flag values:
+
+@table @code
+@item group (1)
+If this flag is set, this is a line describing a group and not an
+option.
+@end table
+
+The following flag values are only defined for options (that is, if
+the @code{group} flag is not used).
+
+@table @code
+@item optional arg (2)
+If this flag is set, the argument is optional. This is never set for
+@var{type} @code{0} (none) options.
+
+@item list (4)
+If this flag is set, the option can be given multiple times.
+
+@item runtime (8)
+If this flag is set, the option can be changed at runtime.
+
+@item default (16)
+If this flag is set, a default value is available.
+
+@item default desc (32)
+If this flag is set, a (runtime) default is available. This and the
+@code{default} flag are mutually exclusive.
+
+@item no arg desc (64)
+If this flag is set, and the @code{optional arg} flag is set, then the
+option has a special meaning if no argument is given.
+
+@item no change (128)
+If this flag is set, @command{gpgconf} ignores requests to change the
+value. GUI frontends should grey out this option. Note, that manual
+changes of the configuration files are still possible.
+@end table
+
+@item level
+This field is defined for options and for groups. It contains an
+@emph{unsigned number} that specifies the expert level under which
+this group or option should be displayed. The following expert levels
+are defined for options (they have analogous meaning for groups):
+
+@table @code
+@item basic (0)
+This option should always be offered to the user.
+
+@item advanced (1)
+This option may be offered to advanced users.
+
+@item expert (2)
+This option should only be offered to expert users.
+
+@item invisible (3)
+This option should normally never be displayed, not even to expert
+users.
+
+@item internal (4)
+This option is for internal use only. Ignore it.
+@end table
+
+The level of a group will always be the lowest level of all options it
+contains.
+
+@item description
+This field is defined for options and groups. The @emph{string} in
+this field contains a human-readable description of the option or
+group. It can be displayed to the user of the GUI for informational
+purposes. It is @emph{percent-escaped} and @emph{localized}.
+
+@item type
+This field is only defined for options. It contains an @emph{unsigned
+number} that specifies the type of the option's argument, if any. The
+following types are defined:
+
+Basic types:
+
+@table @code
+@item none (0)
+No argument allowed.
+
+@item string (1)
+An @emph{unformatted string}.
+
+@item int32 (2)
+A @emph{signed number}.
+
+@item uint32 (3)
+An @emph{unsigned number}.
+@end table
+
+Complex types:
+
+@table @code
+@item pathname (32)
+A @emph{string} that describes the pathname of a file. The file does
+not necessarily need to exist.
+
+@item ldap server (33)
+A @emph{string} that describes an LDAP server in the format:
+
+@code{@var{hostname}:@var{port}:@var{username}:@var{password}:@var{base_dn}}
+
+@item key fingerprint (34)
+A @emph{string} with a 40 digit fingerprint specifying a certificate.
+
+@item pub key (35)
+A @emph{string} that describes a certificate by user ID, key ID or
+fingerprint.
+
+@item sec key (36)
+A @emph{string} that describes a certificate with a key by user ID,
+key ID or fingerprint.
+
+@item alias list (37)
+A @emph{string} that describes an alias list, like the one used with
+gpg's group option. The list consists of a key, an equal sign and space
+separated values.
+@end table
+
+More types will be added in the future. Please see the @var{alt-type}
+field for information on how to cope with unknown types.
+
+@item alt-type
+This field is identical to @var{type}, except that only the types
+@code{0} to @code{31} are allowed. The GUI is expected to present the
+user the option in the format specified by @var{type}. But if the
+argument type @var{type} is not supported by the GUI, it can still
+display the option in the more generic basic type @var{alt-type}. The
+GUI must support all the defined basic types to be able to display all
+options. More basic types may be added in future versions. If the
+GUI encounters a basic type it doesn't support, it should report an
+error and abort the operation.
+
+@item argname
+This field is only defined for options with an argument type
+@var{type} that is not @code{0}. In this case it may contain a
+@emph{percent-escaped} and @emph{localized string} that gives a short
+name for the argument. The field may also be empty, though, in which
+case a short name is not known.
+
+@item default
+This field is defined only for options for which the @code{default} or
+@code{default desc} flag is set. If the @code{default} flag is set,
+its format is that of an @emph{option argument} (@pxref{Format
+conventions}, for details). If the default value is empty, then no
+default is known. Otherwise, the value specifies the default value
+for this option. If the @code{default desc} flag is set, the field is
+either empty or contains a description of the effect if the option is
+not given.
+
+@item argdef
+This field is defined only for options for which the @code{optional
+arg} flag is set. If the @code{no arg desc} flag is not set, its
+format is that of an @emph{option argument} (@pxref{Format
+conventions}, for details). If the default value is empty, then no
+default is known. Otherwise, the value specifies the default argument
+for this option. If the @code{no arg desc} flag is set, the field is
+either empty or contains a description of the effect of this option if
+no argument is given.
+
+@item value
+This field is defined only for options. Its format is that of an
+@emph{option argument}. If it is empty, then the option is not
+explicitly set in the current configuration, and the default applies
+(if any). Otherwise, it contains the current value of the option.
+Note that this field is also meaningful if the option itself does not
+take a real argument (in this case, it contains the number of times
+the option appears).
+@end table
+
+
+@node Changing options
+@subsection Changing options
+
+The command @w{@code{--change-options @var{component}}} will attempt
+to change the options of the component @var{component} to the
+specified values. @var{component} must be the string in the field
+@var{name} in the output of the @code{--list-components} command. You
+have to provide the options that shall be changed in the following
+format on standard input:
+
+@code{@var{name}:@var{flags}:@var{new-value}}
+
+@table @var
+@item name
+This is the name of the option to change. @var{name} must be the
+string in the field @var{name} in the output of the
+@code{--list-options} command.
+
+@item flags
+The flags field contains an @emph{unsigned number}. Its value is the
+OR-wise combination of the following flag values:
+
+@table @code
+@item default (16)
+If this flag is set, the option is deleted and the default value is
+used instead (if applicable).
+@end table
+
+@item new-value
+The new value for the option. This field is only defined if the
+@code{default} flag is not set. The format is that of an @emph{option
+argument}. If it is empty (or the field is omitted), the default
+argument is used (only allowed if the argument is optional for this
+option). Otherwise, the option will be set to the specified value.
+@end table
+
+@noindent
+The output of the command is the same as that of
+@code{--check-options} for the modified configuration file.
+
+Examples:
+
+To set the force option, which is of basic type @code{none (0)}:
+
+@example
+$ echo 'force:0:1' | gpgconf --change-options dirmngr
+@end example
+
+To delete the force option:
+
+@example
+$ echo 'force:16:' | gpgconf --change-options dirmngr
+@end example
+
+The @code{--runtime} option can influence when the changes take
+effect.
+
+
+@node Listing global options
+@subsection Listing global options
+
+Some legacy applications look at the global configuration file for the
+gpgconf tool itself; this is the file @file{gpgconf.conf}. Modern
+applications should not use it but use per component global
+configuration files which are more flexible than the
+@file{gpgconf.conf}. Using both files is not suggested.
+
+The colon separated listing format is record oriented and uses the first
+field to identify the record type:
+
+@table @code
+@item k
+This describes a key record to start the definition of a new ruleset for
+a user/group. The format of a key record is:
+
+ @code{k:@var{user}:@var{group}:}
+
+@table @var
+@item user
+This is the user field of the key. It is percent escaped. See the
+definition of the gpgconf.conf format for details.
+
+@item group
+This is the group field of the key. It is percent escaped.
+@end table
+
+@item r
+This describes a rule record. All rule records up to the next key record
+make up a rule set for that key. The format of a rule record is:
+
+ @code{r:::@var{component}:@var{option}:@var{flag}:@var{value}:}
+
+@table @var
+@item component
+This is the component part of a rule. It is a plain string.
+
+@item option
+This is the option part of a rule. It is a plain string.
+
+@item flag
+This is the flags part of a rule. There may be only one flag per rule
+but by using the same component and option, several flags may be
+assigned to an option. It is a plain string.
+
+@item value
+This is the optional value for the option. It is a percent escaped
+string with a single quotation mark to indicate a string. The quotation
+mark is only required to distinguish between no value specified and an
+empty string.
+@end table
+
+@end table
+
+@noindent
+Unknown record types should be ignored. Note that there is intentionally
+no feature to change the global option file through @command{gpgconf}.
+
+
+@node Querying versions
+@subsection Get and compare software versions.
+
+The GnuPG Project operates a server to query the current versions of
+software packages related to GnuPG. @command{gpgconf} can be used to
+access this online database. To allow for offline operations, this
+feature works by having @command{dirmngr} download a file from
+@code{https://versions.gnupg.org}, checking the signature of that file
+and storing the file in the GnuPG home directory. If
+@command{gpgconf} is used and @command{dirmngr} is running, it may ask
+@command{dirmngr} to refresh that file before itself uses the file.
+
+The command @option{--query-swdb} returns information for the given
+package in a colon delimited format:
+
+@table @var
+
+@item name
+This is the name of the package as requested. Note that "gnupg" is a
+special name which is replaced by the actual package implementing this
+version of GnuPG. For this name it is also not required to specify a
+version because @command{gpgconf} takes its own version in this case.
+
+@item iversion
+The currently installed version or an empty string. The value is
+taken from the command line argument but may be provided by gpg
+if not given.
+
+@item status
+The status of the software package according to this table:
+@table @code
+@item -
+No information available. This is either because no current version
+has been specified or due to an error.
+@item ?
+The given name is not known in the online database.
+@item u
+An update of the software is available.
+@item c
+The installed version of the software is current.
+@item n
+The installed version is already newer than the released version.
+@end table
+
+@item urgency
+If the value (the empty string should be considered as zero) is
+greater than zero an important update is available.
+
+@item error
+This returns an @command{gpg-error} error code to distinguish between
+various failure modes.
+
+@item filedate
+This gives the date of the file with the version numbers in standard
+ISO format (@code{yyyymmddThhmmss}). The date has been extracted by
+@command{dirmngr} from the signature of the file.
+
+@item verified
+This gives the date in ISO format the file was downloaded. This value
+can be used to evaluate the freshness of the information.
+
+@item version
+This returns the version string for the requested software from the
+file.
+
+@item reldate
+This returns the release date in ISO format.
+
+@item size
+This returns the size of the package as decimal number of bytes.
+
+@item hash
+This returns a hexified SHA-2 hash of the package.
+
+@end table
+
+@noindent
+More fields may be added in future to the output.
+
+
+@mansect files
+@node Files used by gpgconf
+@subsection Files used by gpgconf
+
+@table @file
+
+@item /etc/gnupg/gpgconf.conf
+@cindex gpgconf.conf
+ If this file exists, it is processed as a global configuration file.
+ This is a legacy mechanism which should not be used tigether with
+ the modern global per component configuration files. A commented
+ example can be found in the @file{examples} directory of the
+ distribution.
+
+@item @var{GNUPGHOME}/swdb.lst
+@cindex swdb.lst
+ A file with current software versions. @command{dirmngr} creates
+ this file on demand from an online resource.
+
+@end table
+
+
+@mansect see also
+@ifset isman
+@command{gpg}(1),
+@command{gpgsm}(1),
+@command{gpg-agent}(1),
+@command{scdaemon}(1),
+@command{dirmngr}(1)
+@end ifset
+@include see-also-note.texi
+
+
+
+@c
+@c APPLYGNUPGDEFAULTS
+@c
+@manpage applygnupgdefaults.8
+@node applygnupgdefaults
+@section Run gpgconf for all users
+@ifset manverb
+.B applygnupgdefaults
+\- Run gpgconf --apply-defaults for all users.
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B applygnupgdefaults
+@end ifset
+
+@mansect description
+This is a legacy script. Modern application should use the per
+component global configuration files under @file{/etc/gnupg/}.
+
+This script is a wrapper around @command{gpgconf} to run it with the
+command @code{--apply-defaults} for all real users with an existing
+GnuPG home directory. Admins might want to use this script to update he
+GnuPG configuration files for all users after
+@file{/etc/gnupg/gpgconf.conf} has been changed. This allows enforcing
+certain policies for all users. Note, that this is not a bulletproof way to
+force a user to use certain options. A user may always directly edit
+the configuration files and bypass gpgconf.
+
+@noindent
+@command{applygnupgdefaults} is invoked by root as:
+
+@example
+applygnupgdefaults
+@end example
+
+
+@c
+@c GPG-PRESET-PASSPHRASE
+@c
+@node gpg-preset-passphrase
+@section Put a passphrase into the cache
+@manpage gpg-preset-passphrase.1
+@ifset manverb
+.B gpg-preset-passphrase
+\- Put a passphrase into gpg-agent's cache
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B gpg-preset-passphrase
+.RI [ options ]
+.RI [ command ]
+.I cache-id
+@end ifset
+
+@mansect description
+The @command{gpg-preset-passphrase} is a utility to seed the internal
+cache of a running @command{gpg-agent} with passphrases. It is mainly
+useful for unattended machines, where the usual @command{pinentry} tool
+may not be used and the passphrases for the to be used keys are given at
+machine startup.
+
+This program works with GnuPG 2 and later. GnuPG 1.x is not supported.
+
+Passphrases set with this utility don't expire unless the
+@option{--forget} option is used to explicitly clear them from the
+cache --- or @command{gpg-agent} is either restarted or reloaded (by
+sending a SIGHUP to it). Note that the maximum cache time as set with
+@option{--max-cache-ttl} is still honored. It is necessary to allow
+this passphrase presetting by starting @command{gpg-agent} with the
+@option{--allow-preset-passphrase}.
+
+@menu
+* Invoking gpg-preset-passphrase:: List of all commands and options.
+@end menu
+
+@manpause
+@node Invoking gpg-preset-passphrase
+@subsection List of all commands and options
+@mancont
+
+@noindent
+@command{gpg-preset-passphrase} is invoked this way:
+
+@example
+gpg-preset-passphrase [options] [command] @var{cacheid}
+@end example
+
+@var{cacheid} is either a 40 character keygrip of hexadecimal
+characters identifying the key for which the passphrase should be set
+or cleared. The keygrip is listed along with the key when running the
+command: @code{gpgsm --with-keygrip --list-secret-keys}.
+Alternatively an arbitrary string may be used to identify a
+passphrase; it is suggested that such a string is prefixed with the
+name of the application (e.g @code{foo:12346}). Scripts should always
+use the option @option{--with-colons}, which provides the keygrip in a
+"grp" line (cf. @file{doc/DETAILS})/
+
+@noindent
+One of the following command options must be given:
+
+@table @gnupgtabopt
+@item --preset
+@opindex preset
+Preset a passphrase. This is what you usually will
+use. @command{gpg-preset-passphrase} will then read the passphrase from
+@code{stdin}.
+
+@item --forget
+@opindex forget
+Flush the passphrase for the given cache ID from the cache.
+
+@end table
+
+@noindent
+The following additional options may be used:
+
+@table @gnupgtabopt
+@item -v
+@itemx --verbose
+@opindex verbose
+Output additional information while running.
+
+@item -P @var{string}
+@itemx --passphrase @var{string}
+@opindex passphrase
+Instead of reading the passphrase from @code{stdin}, use the supplied
+@var{string} as passphrase. Note that this makes the passphrase visible
+for other users.
+@end table
+
+@mansect see also
+@ifset isman
+@command{gpg}(1),
+@command{gpgsm}(1),
+@command{gpg-agent}(1),
+@command{scdaemon}(1)
+@end ifset
+@include see-also-note.texi
+
+
+
+
+@c
+@c GPG-CONNECT-AGENT
+@c
+@node gpg-connect-agent
+@section Communicate with a running agent
+@manpage gpg-connect-agent.1
+@ifset manverb
+.B gpg-connect-agent
+\- Communicate with a running agent
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B gpg-connect-agent
+.RI [ options ] [commands]
+@end ifset
+
+@mansect description
+The @command{gpg-connect-agent} is a utility to communicate with a
+running @command{gpg-agent}. It is useful to check out the commands
+@command{gpg-agent} provides using the Assuan interface. It might
+also be useful for scripting simple applications. Input is expected
+at stdin and output gets printed to stdout.
+
+It is very similar to running @command{gpg-agent} in server mode; but
+here we connect to a running instance.
+
+@menu
+* Invoking gpg-connect-agent:: List of all options.
+* Controlling gpg-connect-agent:: Control commands.
+@end menu
+
+@manpause
+@node Invoking gpg-connect-agent
+@subsection List of all options
+
+@noindent
+@command{gpg-connect-agent} is invoked this way:
+
+@example
+gpg-connect-agent [options] [commands]
+@end example
+@mancont
+
+@noindent
+The following options may be used:
+
+@table @gnupgtabopt
+@item -v
+@itemx --verbose
+@opindex verbose
+Output additional information while running.
+
+@item -q
+@item --quiet
+@opindex q
+@opindex quiet
+Try to be as quiet as possible.
+
+@include opt-homedir.texi
+
+@item --agent-program @var{file}
+@opindex agent-program
+Specify the agent program to be started if none is running. The
+default value is determined by running @command{gpgconf} with the
+option @option{--list-dirs}. Note that the pipe symbol (@code{|}) is
+used for a regression test suite hack and may thus not be used in the
+file name.
+
+@item --dirmngr-program @var{file}
+@opindex dirmngr-program
+Specify the directory manager (keyserver client) program to be started
+if none is running. This has only an effect if used together with the
+option @option{--dirmngr}.
+
+@item --dirmngr
+@opindex dirmngr
+Connect to a running directory manager (keyserver client) instead of
+to the gpg-agent. If a dirmngr is not running, start it.
+
+@item -S
+@itemx --raw-socket @var{name}
+@opindex raw-socket
+Connect to socket @var{name} assuming this is an Assuan style server.
+Do not run any special initializations or environment checks. This may
+be used to directly connect to any Assuan style socket server.
+
+@item -E
+@itemx --exec
+@opindex exec
+Take the rest of the command line as a program and it's arguments and
+execute it as an Assuan server. Here is how you would run @command{gpgsm}:
+@smallexample
+ gpg-connect-agent --exec gpgsm --server
+@end smallexample
+Note that you may not use options on the command line in this case.
+
+@item --no-ext-connect
+@opindex no-ext-connect
+When using @option{-S} or @option{--exec}, @command{gpg-connect-agent}
+connects to the Assuan server in extended mode to allow descriptor
+passing. This option makes it use the old mode.
+
+@item --no-autostart
+@opindex no-autostart
+Do not start the gpg-agent or the dirmngr if it has not yet been
+started.
+
+@item -r @var{file}
+@itemx --run @var{file}
+@opindex run
+Run the commands from @var{file} at startup and then continue with the
+regular input method. Note, that commands given on the command line are
+executed after this file.
+
+@item -s
+@itemx --subst
+@opindex subst
+Run the command @code{/subst} at startup.
+
+@item --hex
+@opindex hex
+Print data lines in a hex format and the ASCII representation of
+non-control characters.
+
+@item --decode
+@opindex decode
+Decode data lines. That is to remove percent escapes but make sure that
+a new line always starts with a D and a space.
+
+@end table
+
+@mansect control commands
+@node Controlling gpg-connect-agent
+@subsection Control commands
+
+While reading Assuan commands, gpg-agent also allows a few special
+commands to control its operation. These control commands all start
+with a slash (@code{/}).
+
+@table @code
+
+@item /echo @var{args}
+Just print @var{args}.
+
+@item /let @var{name} @var{value}
+Set the variable @var{name} to @var{value}. Variables are only
+substituted on the input if the @command{/subst} has been used.
+Variables are referenced by prefixing the name with a dollar sign and
+optionally include the name in curly braces. The rules for a valid name
+are identically to those of the standard bourne shell. This is not yet
+enforced but may be in the future. When used with curly braces no
+leading or trailing white space is allowed.
+
+If a variable is not found, it is searched in the environment and if
+found copied to the table of variables.
+
+Variable functions are available: The name of the function must be
+followed by at least one space and the at least one argument. The
+following functions are available:
+
+@table @code
+@item get
+Return a value described by the argument. Available arguments are:
+
+@table @code
+@item cwd
+The current working directory.
+@item homedir
+The gnupg homedir.
+@item sysconfdir
+GnuPG's system configuration directory.
+@item bindir
+GnuPG's binary directory.
+@item libdir
+GnuPG's library directory.
+@item libexecdir
+GnuPG's library directory for executable files.
+@item datadir
+GnuPG's data directory.
+@item serverpid
+The PID of the current server. Command @command{/serverpid} must
+have been given to return a useful value.
+@end table
+
+@item unescape @var{args}
+Remove C-style escapes from @var{args}. Note that @code{\0} and
+@code{\x00} terminate the returned string implicitly. The string to be
+converted are the entire arguments right behind the delimiting space of
+the function name.
+
+@item unpercent @var{args}
+@itemx unpercent+ @var{args}
+Remove percent style escaping from @var{args}. Note that @code{%00}
+terminates the string implicitly. The string to be converted are the
+entire arguments right behind the delimiting space of the function
+name. @code{unpercent+} also maps plus signs to a spaces.
+
+@item percent @var{args}
+@itemx percent+ @var{args}
+Escape the @var{args} using percent style escaping. Tabs, formfeeds,
+linefeeds, carriage returns and colons are escaped. @code{percent+} also
+maps spaces to plus signs.
+
+@item errcode @var{arg}
+@itemx errsource @var{arg}
+@itemx errstring @var{arg}
+Assume @var{arg} is an integer and evaluate it using @code{strtol}. Return
+the gpg-error error code, error source or a formatted string with the
+error code and error source.
+
+
+@item +
+@itemx -
+@itemx *
+@itemx /
+@itemx %
+Evaluate all arguments as long integers using @code{strtol} and apply
+this operator. A division by zero yields an empty string.
+
+@item !
+@itemx |
+@itemx &
+Evaluate all arguments as long integers using @code{strtol} and apply
+the logical operators NOT, OR or AND. The NOT operator works on the
+last argument only.
+
+
+@end table
+
+
+@item /definq @var{name} @var{var}
+Use content of the variable @var{var} for inquiries with @var{name}.
+@var{name} may be an asterisk (@code{*}) to match any inquiry.
+
+
+@item /definqfile @var{name} @var{file}
+Use content of @var{file} for inquiries with @var{name}.
+@var{name} may be an asterisk (@code{*}) to match any inquiry.
+
+@item /definqprog @var{name} @var{prog}
+Run @var{prog} for inquiries matching @var{name} and pass the
+entire line to it as command line arguments.
+
+@item /datafile @var{name}
+Write all data lines from the server to the file @var{name}. The file
+is opened for writing and created if it does not exists. An existing
+file is first truncated to 0. The data written to the file fully
+decoded. Using a single dash for @var{name} writes to stdout. The
+file is kept open until a new file is set using this command or this
+command is used without an argument.
+
+@item /showdef
+Print all definitions
+
+@item /cleardef
+Delete all definitions
+
+@item /sendfd @var{file} @var{mode}
+Open @var{file} in @var{mode} (which needs to be a valid @code{fopen}
+mode string) and send the file descriptor to the server. This is
+usually followed by a command like @code{INPUT FD} to set the
+input source for other commands.
+
+@item /recvfd
+Not yet implemented.
+
+@item /open @var{var} @var{file} [@var{mode}]
+Open @var{file} and assign the file descriptor to @var{var}. Warning:
+This command is experimental and might change in future versions.
+
+@item /close @var{fd}
+Close the file descriptor @var{fd}. Warning: This command is
+experimental and might change in future versions.
+
+@item /showopen
+Show a list of open files.
+
+@item /serverpid
+Send the Assuan command @command{GETINFO pid} to the server and store
+the returned PID for internal purposes.
+
+@item /sleep
+Sleep for a second.
+
+@item /hex
+@itemx /nohex
+Same as the command line option @option{--hex}.
+
+@item /decode
+@itemx /nodecode
+Same as the command line option @option{--decode}.
+
+@item /subst
+@itemx /nosubst
+Enable and disable variable substitution. It defaults to disabled
+unless the command line option @option{--subst} has been used.
+If /subst as been enabled once, leading whitespace is removed from
+input lines which makes scripts easier to read.
+
+@item /while @var{condition}
+@itemx /end
+These commands provide a way for executing loops. All lines between
+the @code{while} and the corresponding @code{end} are executed as long
+as the evaluation of @var{condition} yields a non-zero value or is the
+string @code{true} or @code{yes}. The evaluation is done by passing
+@var{condition} to the @code{strtol} function. Example:
+
+@smallexample
+ /subst
+ /let i 3
+ /while $i
+ /echo loop counter is $i
+ /let i $@{- $i 1@}
+ /end
+@end smallexample
+
+@item /if @var{condition}
+@itemx /end
+These commands provide a way for conditional execution. All lines between
+the @code{if} and the corresponding @code{end} are executed only if
+the evaluation of @var{condition} yields a non-zero value or is the
+string @code{true} or @code{yes}. The evaluation is done by passing
+@var{condition} to the @code{strtol} function.
+
+@item /run @var{file}
+Run commands from @var{file}.
+
+@item /bye
+Terminate the connection and the program.
+
+@item /help
+Print a list of available control commands.
+
+@end table
+
+
+@ifset isman
+@mansect see also
+@command{gpg-agent}(1),
+@command{scdaemon}(1)
+@include see-also-note.texi
+@end ifset
+
+@c
+@c DIRMNGR-CLIENT
+@c
+@node dirmngr-client
+@section The Dirmngr Client Tool
+
+@manpage dirmngr-client.1
+@ifset manverb
+.B dirmngr-client
+\- Tool to access the Dirmngr services
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B dirmngr-client
+.RI [ options ]
+.RI [ certfile | pattern ]
+@end ifset
+
+@mansect description
+The @command{dirmngr-client} is a simple tool to contact a running
+dirmngr and test whether a certificate has been revoked --- either by
+being listed in the corresponding CRL or by running the OCSP protocol.
+If no dirmngr is running, a new instances will be started but this is
+in general not a good idea due to the huge performance overhead.
+
+@noindent
+The usual way to run this tool is either:
+
+@example
+dirmngr-client @var{acert}
+@end example
+
+@noindent
+or
+
+@example
+dirmngr-client <@var{acert}
+@end example
+
+Where @var{acert} is one DER encoded (binary) X.509 certificates to be
+tested.
+@ifclear isman
+The return value of this command is
+@end ifclear
+
+@mansect return value
+@ifset isman
+@command{dirmngr-client} returns these values:
+@end ifset
+@table @code
+
+@item 0
+The certificate under question is valid; i.e. there is a valid CRL
+available and it is not listed there or the OCSP request returned that
+that certificate is valid.
+
+@item 1
+The certificate has been revoked
+
+@item 2 (and other values)
+There was a problem checking the revocation state of the certificate.
+A message to stderr has given more detailed information. Most likely
+this is due to a missing or expired CRL or due to a network problem.
+
+@end table
+
+@mansect options
+@noindent
+@command{dirmngr-client} may be called with the following options:
+
+
+@table @gnupgtabopt
+@item --version
+@opindex version
+Print the program version and licensing information. Note that you cannot
+abbreviate this command.
+
+@item --help, -h
+@opindex help
+Print a usage message summarizing the most useful command-line options.
+Note that you cannot abbreviate this command.
+
+@item --quiet, -q
+@opindex quiet
+Make the output extra brief by suppressing any informational messages.
+
+@item -v
+@item --verbose
+@opindex v
+@opindex verbose
+Outputs additional information while running.
+You can increase the verbosity by giving several
+verbose commands to @sc{dirmngr}, such as @samp{-vv}.
+
+@item --pem
+@opindex pem
+Assume that the given certificate is in PEM (armored) format.
+
+@item --ocsp
+@opindex ocsp
+Do the check using the OCSP protocol and ignore any CRLs.
+
+@item --force-default-responder
+@opindex force-default-responder
+When checking using the OCSP protocol, force the use of the default OCSP
+responder. That is not to use the Reponder as given by the certificate.
+
+@item --ping
+@opindex ping
+Check whether the dirmngr daemon is up and running.
+
+@item --cache-cert
+@opindex cache-cert
+Put the given certificate into the cache of a running dirmngr. This is
+mainly useful for debugging.
+
+@item --validate
+@opindex validate
+Validate the given certificate using dirmngr's internal validation code.
+This is mainly useful for debugging.
+
+@item --load-crl
+@opindex load-crl
+This command expects a list of filenames with DER encoded CRL files.
+With the option @option{--url} URLs are expected in place of filenames
+and they are loaded directly from the given location. All CRLs will be
+validated and then loaded into dirmngr's cache.
+
+@item --lookup
+@opindex lookup
+Take the remaining arguments and run a lookup command on each of them.
+The results are Base-64 encoded outputs (without header lines). This
+may be used to retrieve certificates from a server. However the output
+format is not very well suited if more than one certificate is returned.
+
+@item --url
+@itemx -u
+@opindex url
+Modify the @command{lookup} and @command{load-crl} commands to take an URL.
+
+@item --local
+@itemx -l
+@opindex url
+Let the @command{lookup} command only search the local cache.
+
+@item --squid-mode
+@opindex squid-mode
+Run @sc{dirmngr-client} in a mode suitable as a helper program for
+Squid's @option{external_acl_type} option.
+
+
+@end table
+
+@ifset isman
+@mansect see also
+@command{dirmngr}(8),
+@command{gpgsm}(1)
+@include see-also-note.texi
+@end ifset
+
+
+@c
+@c GPGPARSEMAIL
+@c
+@node gpgparsemail
+@section Parse a mail message into an annotated format
+
+@manpage gpgparsemail.1
+@ifset manverb
+.B gpgparsemail
+\- Parse a mail message into an annotated format
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B gpgparsemail
+.RI [ options ]
+.RI [ file ]
+@end ifset
+
+@mansect description
+The @command{gpgparsemail} is a utility currently only useful for
+debugging. Run it with @code{--help} for usage information.
+
+
+
+@c
+@c GPGTAR
+@c
+@manpage gpgtar.1
+@node gpgtar
+@section Encrypt or sign files into an archive
+@ifset manverb
+.B gpgtar
+\- Encrypt or sign files into an archive
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B gpgtar
+.RI [ options ]
+.I filename1
+.I [ filename2, ... ]
+.I directory1
+.I [ directory2, ... ]
+@end ifset
+
+@mansect description
+@command{gpgtar} encrypts or signs files into an archive. It is an
+gpg-ized tar using the same format as used by PGP's PGP Zip.
+
+@manpause
+@noindent
+@command{gpgtar} is invoked this way:
+
+@example
+gpgtar [options] @var{filename1} [@var{filename2}, ...] @var{directory} [@var{directory2}, ...]
+@end example
+
+@mansect options
+@noindent
+@command{gpgtar} understands these options:
+
+@table @gnupgtabopt
+
+@item --create
+@opindex create
+Put given files and directories into a vanilla ``ustar'' archive.
+
+@item --extract
+@opindex extract
+Extract all files from a vanilla ``ustar'' archive.
+
+@item --encrypt
+@itemx -e
+@opindex encrypt
+Encrypt given files and directories into an archive. This option may
+be combined with option @option{--symmetric} for an archive that may
+be decrypted via a secret key or a passphrase.
+
+@item --decrypt
+@itemx -d
+@opindex decrypt
+Extract all files from an encrypted archive.
+
+@item --sign
+@itemx -s
+Make a signed archive from the given files and directories. This can
+be combined with option @option{--encrypt} to create a signed and then
+encrypted archive.
+
+@item --list-archive
+@itemx -t
+@opindex list-archive
+List the contents of the specified archive.
+
+@item --symmetric
+@itemx -c
+Encrypt with a symmetric cipher using a passphrase. The default
+symmetric cipher used is @value{GPGSYMENCALGO}, but may be chosen with the
+@option{--cipher-algo} option to @command{gpg}.
+
+@item --recipient @var{user}
+@itemx -r @var{user}
+@opindex recipient
+Encrypt for user id @var{user}. For details see @command{gpg}.
+
+@item --local-user @var{user}
+@itemx -u @var{user}
+@opindex local-user
+Use @var{user} as the key to sign with. For details see @command{gpg}.
+
+@item --output @var{file}
+@itemx -o @var{file}
+@opindex output
+Write the archive to the specified file @var{file}.
+
+@item --verbose
+@itemx -v
+@opindex verbose
+Enable extra informational output.
+
+@item --quiet
+@itemx -q
+@opindex quiet
+Try to be as quiet as possible.
+
+@item --skip-crypto
+@opindex skip-crypto
+Skip all crypto operations and create or extract vanilla ``ustar''
+archives.
+
+@item --dry-run
+@opindex dry-run
+Do not actually output the extracted files.
+
+@item --directory @var{dir}
+@itemx -C @var{dir}
+@opindex directory
+Extract the files into the directory @var{dir}. The default is to
+take the directory name from the input filename. If no input filename
+is known a directory named @file{GPGARCH} is used. For tarball
+creation, switch to directory @var{dir} before performing any
+operations.
+
+@item --files-from @var{file}
+@itemx -T @var{file}
+Take the file names to work from the file @var{file}; one file per
+line.
+
+@item --null
+@opindex null
+Modify option @option{--files-from} to use a binary nul instead of a
+linefeed to separate file names.
+
+@item --utf8-strings
+@opindex utf8-strings
+Assume that the file names read by @option{--files-from} are UTF-8
+encoded. This option has an effect only on Windows where the active
+code page is otherwise assumed.
+
+@item --openpgp
+@opindex openpgp
+This option has no effect because OpenPGP encryption and signing is
+the default.
+
+@item --cms
+@opindex cms
+This option is reserved and shall not be used. It will eventually be
+used to encrypt or sign using the CMS protocol; but that is not yet
+implemented.
+
+@item --batch
+@opindex batch
+Use batch mode. Never ask but use the default action. This option is
+passed directly to @command{gpg}.
+
+@item --yes
+@opindex yes
+Assume "yes" on most questions. Often used together with
+@option{--batch} to overwrite existing files. This option is passed
+directly to @command{gpg}.
+
+@item --no
+@opindex no
+Assume "no" on most questions. This option is passed directly to
+@command{gpg}.
+
+@item --require-compliance
+@opindex require-compliance
+This option is passed directly to @command{gpg}.
+
+@item --status-fd @var{n}
+@opindex status-fd
+Write special status strings to the file descriptor @var{n}.
+See the file DETAILS in the documentation for a listing of them.
+
+@item --with-log
+@opindex with-log
+When extracting an encrypted tarball also write a log file with the
+gpg output to a file named after the extraction directory with the
+suffix ".log".
+
+@item --set-filename @var{file}
+@opindex set-filename
+Use the last component of @var{file} as the output directory. The
+default is to take the directory name from the input filename. If no
+input filename is known a directory named @file{GPGARCH} is used.
+This option is deprecated in favor of option @option{--directory}.
+
+@item --gpg @var{gpgcmd}
+@opindex gpg
+Use the specified command @var{gpgcmd} instead of @command{gpg}.
+
+@item --gpg-args @var{args}
+@opindex gpg-args
+Pass the specified extra options to @command{gpg}.
+
+@item --tar-args @var{args}
+@opindex tar-args
+Assume @var{args} are standard options of the command @command{tar}
+and parse them. The only supported tar options are "--directory",
+"--files-from", and "--null" This is an obsolete options because those
+supported tar options can also be given directly.
+
+@item --version
+@opindex version
+Print version of the program and exit.
+
+@item --help
+@opindex help
+Display a brief help page and exit.
+
+@end table
+
+@mansect diagnostics
+@noindent
+The program returns 0 if everything was fine, 1 otherwise.
+
+
+@mansect examples
+@ifclear isman
+@noindent
+Some examples:
+
+@end ifclear
+@noindent
+Encrypt the contents of directory @file{mydocs} for user Bob to file
+@file{test1}:
+
+@example
+gpgtar --encrypt --output test1 -r Bob mydocs
+@end example
+
+@noindent
+List the contents of archive @file{test1}:
+
+@example
+gpgtar --list-archive test1
+@end example
+
+
+@mansect see also
+@ifset isman
+@command{gpg}(1),
+@command{tar}(1),
+@end ifset
+@include see-also-note.texi
+
+@c
+@c GPG-CHECK-PATTERN
+@c
+@manpage gpg-check-pattern.1
+@node gpg-check-pattern
+@section Check a passphrase on stdin against the patternfile
+@ifset manverb
+.B gpg-check-pattern
+\- Check a passphrase on stdin against the patternfile
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B gpg\-check\-pattern
+.RI [ options ]
+.I patternfile
+@end ifset
+
+@mansect description
+@command{gpg-check-pattern} checks a passphrase given on stdin against
+a specified pattern file.
+
+The pattern file is line based with comment lines beginning on the
+@emph{first} position with a @code{#}. Empty lines and lines with
+only white spaces are ignored. The actual pattern lines may either be
+verbatim string pattern and match as they are (trailing spaces are
+ignored) or extended regular expressions indicated by a @code{/} or
+@code{!/} in the first column and terminated by another @code{/} or
+end of line. If a regular expression starts with @code{!/} the match
+result is reversed. By default all comparisons are case insensitive.
+
+Tag lines may be used to further control the operation of this tool.
+The currently defined tags are:
+
+@table @code
+@item [icase]
+Switch to case insensitive comparison for all further patterns. This
+is the default.
+
+@item [case]
+Switch to case sensitive comparison for all further patterns.
+
+@item [reject]
+Switch to reject mode. This is the default mode.
+
+@item [accept]
+Switch to accept mode.
+@end table
+
+In the future more tags may be introduced and thus it is advisable not to
+start a plain pattern string with an open bracket. The tags must be
+given verbatim on the line with no spaces to the left or any non white
+space characters to the right.
+
+In reject mode the program exits on the first match with an exit code
+of 1 (failure). If at the end of the pattern list the reject mode is
+still active the program exits with code 0 (success).
+
+In accept mode blocks of patterns are used. A block starts at the
+next pattern after an "accept" tag and ends with the last pattern
+before the next "accept" or "reject" tag or at the end of the pattern
+list. If all patterns in a block match the program exits with an exit
+code of 0 (success). If any pattern in a block do not match the next
+pattern block is evaluated. If at the end of the pattern list the
+accept mode is still active the program exits with code 1 (failure).
+
+
+@mansect options
+@noindent
+
+@table @gnupgtabopt
+
+@item --verbose
+@opindex verbose
+Enable extra informational output.
+
+@item --check
+@opindex check
+Run only a syntax check on the patternfile.
+
+@item --null
+@opindex null
+Input is expected to be null delimited.
+
+@end table
+
+@mansect see also
+@ifset isman
+@command{gpg-agent}(1),
+@end ifset
+@include see-also-note.texi