1139 lines
31 KiB
HTML
1139 lines
31 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of GPGCONF</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>GPGCONF</H1>
|
|
Section: GNU Privacy Guard 2.2 (1)<BR>Updated: 2019-11-23<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
<B>gpgconf</B>
|
|
|
|
- Modify .gnupg home directories
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>gpgconf</B>
|
|
|
|
[<I>options</I>]
|
|
|
|
<B>--list-components</B>
|
|
|
|
<BR>
|
|
|
|
<B>gpgconf</B>
|
|
|
|
[<I>options</I>]
|
|
|
|
<B>--list-options</B>
|
|
|
|
<I>component</I>
|
|
|
|
<BR>
|
|
|
|
<B>gpgconf</B>
|
|
|
|
[<I>options</I>]
|
|
|
|
<B>--change-options</B>
|
|
|
|
<I>component</I>
|
|
|
|
<P>
|
|
<P>
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
The <B>gpgconf</B> is a utility to automatically and reasonable
|
|
safely query and modify configuration files in the '<I>.gnupg</I>' home
|
|
directory. It is designed not to be invoked manually by the user, but
|
|
automatically by graphical user interfaces (GUI). ([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.])
|
|
<P>
|
|
<B>gpgconf</B> 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
|
|
<B>gpgconf</B>. <B>gpgconf</B> provides a generic and abstract
|
|
method to access the most important configuration options that can
|
|
feasibly be controlled via such a mechanism.
|
|
<P>
|
|
<B>gpgconf</B> can be used to gather and change the options
|
|
available in each component, and can also provide their default
|
|
values. <B>gpgconf</B> will give detailed type information that
|
|
can be used to restrict the user's input without making an attempt to
|
|
commit the changes.
|
|
<P>
|
|
<B>gpgconf</B> 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 <B>gpgconf</B> again. Such a
|
|
program that uses <B>gpgconf</B> in this way will be called GUI
|
|
throughout this section.
|
|
<P>
|
|
<P>
|
|
<A NAME="lbAE"> </A>
|
|
<H2>COMMANDS</H2>
|
|
|
|
One of the following commands must be given:
|
|
<P>
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT id="1"><B>--list-components</B>
|
|
|
|
<DD>
|
|
List all components. This is the default command used if none is
|
|
specified.
|
|
<P>
|
|
<DT id="2"><B>--check-programs</B>
|
|
|
|
<DD>
|
|
List all available backend programs and test whether they are runnable.
|
|
<P>
|
|
<DT id="3"><B>--list-options </B><I>component</I>
|
|
|
|
<DD>
|
|
List all options of the component <I>component</I>.
|
|
<P>
|
|
<DT id="4"><B>--change-options </B><I>component</I>
|
|
|
|
<DD>
|
|
Change the options of the component <I>component</I>.
|
|
<P>
|
|
<DT id="5"><B>--check-options </B><I>component</I>
|
|
|
|
<DD>
|
|
Check the options for the component <I>component</I>.
|
|
<P>
|
|
<DT id="6"><B>--apply-profile </B><I>file</I>
|
|
|
|
<DD>
|
|
Apply the configuration settings listed in <I>file</I> to the
|
|
configuration files. If <I>file</I> has no suffix and no slashes the
|
|
command first tries to read a file with the suffix <B>.prf</B> from
|
|
the data directory (<B>gpgconf --list-dirs datadir</B>) 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.
|
|
<P>
|
|
<DT id="7"><B>--apply-defaults</B>
|
|
|
|
<DD>
|
|
Update all configuration files with values taken from the global
|
|
configuration file (usually '<I>/etc/gnupg/gpgconf.conf</I>').
|
|
<P>
|
|
<DT id="8"><B>--list-dirs [</B><I>names</I>]
|
|
|
|
<DD>
|
|
Lists the directories used by <B>gpgconf</B>. 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 <B>sysconfdir</B>)
|
|
and the second field contains the percent-escaped directory. Although
|
|
they are not directories, the socket file names used by
|
|
<B>gpg-agent</B> and <B>dirmngr</B> are printed as well. Note
|
|
that the socket file names and the <B>homedir</B> lines are the default
|
|
names and they may be overridden by command line switches. If
|
|
<I>names</I> are given only the directories or file names specified by
|
|
the list names are printed without any escaping.
|
|
<P>
|
|
<DT id="9"><B>--list-config [</B><I>filename</I>]
|
|
|
|
<DD>
|
|
List the global configuration file in a colon separated format. If
|
|
<I>filename</I> is given, check that file instead.
|
|
<P>
|
|
<DT id="10"><B>--check-config [</B><I>filename</I>]
|
|
|
|
<DD>
|
|
Run a syntax check on the global configuration file. If <I>filename</I>
|
|
is given, check that file instead.
|
|
<P>
|
|
<P>
|
|
<DT id="11"><B>--query-swdb </B><I>package_name</I> [<I>version_string</I>]
|
|
|
|
<DD>
|
|
Returns the current version for <I>package_name</I> and if
|
|
<I>version_string</I> is given also an indicator on whether an update
|
|
is available. The actual file with the software version is
|
|
automatically downloaded and checked by <B>dirmngr</B>.
|
|
<B>dirmngr</B> 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:
|
|
<P>
|
|
<DL COMPACT><DT id="12"><DD>
|
|
<PRE>
|
|
gpg-connect-agent --dirmngr 'loadswdb --force' /bye
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
<P>
|
|
<DT id="13"><B>--reload [</B><I>component</I>]
|
|
|
|
<DD>
|
|
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 <I>component</I> or by using "all" for
|
|
<I>component</I> all components which are daemons are reloaded.
|
|
<P>
|
|
<DT id="14"><B>--launch [</B><I>component</I>]
|
|
|
|
<DD>
|
|
If the <I>component</I> is not already running, start it.
|
|
<B>component</B> 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 <B>gpg-agent</B> or <B>dirmngr</B>
|
|
may use this command to ensure that they are started. Using "all" for
|
|
<I>component</I> launches all components which are daemons.
|
|
<P>
|
|
<DT id="15"><B>--kill [</B><I>component</I>]
|
|
|
|
<DD>
|
|
Kill the given component that runs as a daemon, including
|
|
<B>gpg-agent</B>, <B>dirmngr</B>, and <B>scdaemon</B>. A
|
|
<B>component</B> which does not run as a daemon will be ignored.
|
|
Using "all" for <I>component</I> kills all components running as
|
|
daemons. Note that as of now reload and kill have the same effect for
|
|
<B>scdaemon</B>.
|
|
<P>
|
|
<DT id="16"><B>--create-socketdir</B>
|
|
|
|
<DD>
|
|
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.
|
|
<P>
|
|
<DT id="17"><B>--remove-socketdir</B>
|
|
|
|
<DD>
|
|
Remove a directory created with command <B>--create-socketdir</B>.
|
|
<P>
|
|
</DL>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
<P>
|
|
The following options may be used:
|
|
<P>
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT id="18"><B>-o </B><I>file</I>
|
|
|
|
<DD>
|
|
|
|
<B>--output </B><I>file</I>
|
|
|
|
Write output to <I>file</I>. Default is to write to stdout.
|
|
<P>
|
|
<DT id="19"><B>-v</B>
|
|
|
|
<DD>
|
|
|
|
<B>--verbose</B>
|
|
|
|
Outputs additional information while running. Specifically, this
|
|
extends numerical field values by human-readable descriptions.
|
|
<P>
|
|
<DT id="20"><B>-q</B>
|
|
|
|
<DD>
|
|
|
|
<B>--quiet</B>
|
|
|
|
Try to be as quiet as possible.
|
|
<P>
|
|
<DT id="21"><B>--homedir </B><I>dir</I>
|
|
|
|
<DD>
|
|
Set the name of the home directory to <I>dir</I>. If this option is not
|
|
used, the home directory defaults to '<I>~/.gnupg</I>'. It is only
|
|
recognized when given on the command line. It also overrides any home
|
|
directory stated through the environment variable '<I>GNUPGHOME</I>' or
|
|
(on Windows systems) by means of the Registry entry
|
|
<I>HKCU\Software\GNU\GnuPG:HomeDir</I>.
|
|
<P>
|
|
On Windows systems it is possible to install GnuPG as a portable
|
|
application. In this case only this command line option is
|
|
considered, all other ways to set a home directory are ignored.
|
|
<P>
|
|
To install GnuPG as a portable application under Windows, create an
|
|
empty file named '<I>gpgconf.ctl</I>' in the same directory as the tool
|
|
'<I>gpgconf.exe</I>'. The root of the installation is then that
|
|
directory; or, if '<I>gpgconf.exe</I>' has been installed directly below
|
|
a directory named '<I>bin</I>', its parent directory. You also need to
|
|
make sure that the following directories exist and are writable:
|
|
'<I>ROOT/home</I>' for the GnuPG home and '<I>ROOT/var/cache/gnupg</I>'
|
|
for internal cache files.
|
|
<P>
|
|
<DT id="22"><B>-n</B>
|
|
|
|
<DD>
|
|
|
|
<B>--dry-run</B>
|
|
|
|
Do not actually change anything. This is currently only implemented
|
|
for <B>--change-options</B> and can be used for testing purposes.
|
|
<P>
|
|
<DT id="23"><B>-r</B>
|
|
|
|
<DD>
|
|
|
|
<B>--runtime</B>
|
|
|
|
Only used together with <B>--change-options</B>. 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.
|
|
<P>
|
|
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.
|
|
<P>
|
|
<DT id="24"><B>--status-fd </B><I>n</I>
|
|
|
|
<DD>
|
|
Write special status strings to the file descriptor <I>n</I>. 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.
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>USAGE</H2>
|
|
|
|
<P>
|
|
The command <B>--list-components</B> will list all components that can
|
|
be configured with <B>gpgconf</B>. 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
|
|
<B>gpgconf</B>. 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.
|
|
<P>
|
|
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.
|
|
<P>
|
|
The command <B>--list-components</B> lists all available
|
|
components, one per line. The format of each line is:
|
|
<P>
|
|
<B></B><I>name</I>:<I>description</I>:<I>pgmname</I>:
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT id="25"><B>name</B>
|
|
|
|
<DD>
|
|
This field contains a name tag of the component. The name tag is used
|
|
to specify the component in all communication with <B>gpgconf</B>.
|
|
The name tag is to be used <I>verbatim</I>. It is thus not in any
|
|
escaped format.
|
|
<P>
|
|
<DT id="26"><B>description</B>
|
|
|
|
<DD>
|
|
The <I>string</I> 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 <I>percent-escaped</I> and
|
|
<I>localized</I>.
|
|
<P>
|
|
<DT id="27"><B>pgmname</B>
|
|
|
|
<DD>
|
|
The <I>string</I> in this field contains the absolute name of the
|
|
program's file. It can be used to unambiguously invoke that program.
|
|
It is <I>percent-escaped</I>.
|
|
</DL>
|
|
<P>
|
|
|
|
<P>
|
|
Example:
|
|
<DL COMPACT><DT id="28"><DD>
|
|
<PRE>
|
|
$ 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:
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Checking programs</H3>
|
|
|
|
|
|
<P>
|
|
The command <B>--check-programs</B> is similar to
|
|
<B>--list-components</B> 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.
|
|
<P>
|
|
The command <B>--check-programs</B> lists all available
|
|
programs, one per line. The format of each line is:
|
|
<P>
|
|
<B></B><I>name</I>:<I>description</I>:<I>pgmname</I>:<I>avail</I>:<I>okay</I>:<I>cfgfile</I>:<I>line</I>:<I>error</I>:
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT id="29"><B>name</B>
|
|
|
|
<DD>
|
|
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 <I>verbatim</I>. 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.
|
|
<P>
|
|
<DT id="30"><B>description</B>
|
|
|
|
<DD>
|
|
The <I>string</I> 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 <I>percent-escaped</I> and
|
|
<I>localized</I>.
|
|
<P>
|
|
<DT id="31"><B>pgmname</B>
|
|
|
|
<DD>
|
|
The <I>string</I> in this field contains the absolute name of the
|
|
program's file. It can be used to unambiguously invoke that program.
|
|
It is <I>percent-escaped</I>.
|
|
<P>
|
|
<DT id="32"><B>avail</B>
|
|
|
|
<DD>
|
|
The <I>boolean value</I> in this field indicates whether the program is
|
|
installed and runnable.
|
|
<P>
|
|
<DT id="33"><B>okay</B>
|
|
|
|
<DD>
|
|
The <I>boolean value</I> in this field indicates whether the program's
|
|
config file is syntactically okay.
|
|
<P>
|
|
<DT id="34"><B>cfgfile</B>
|
|
|
|
<DD>
|
|
If an error occurred in the configuration file (as indicated by a false
|
|
value in the field <B>okay</B>), this field has the name of the failing
|
|
configuration file. It is <I>percent-escaped</I>.
|
|
<P>
|
|
<DT id="35"><B>line</B>
|
|
|
|
<DD>
|
|
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 <I>unsigned number</I>.
|
|
<P>
|
|
<DT id="36"><B>error</B>
|
|
|
|
<DD>
|
|
If an error occurred in the configuration file, this field has the error
|
|
text of the failing statement in the configuration file. It is
|
|
<I>percent-escaped</I> and <I>localized</I>.
|
|
<P>
|
|
</DL>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
In the following example the <B>dirmngr</B> is not runnable and the
|
|
configuration file of <B>scdaemon</B> is not okay.
|
|
<P>
|
|
<DL COMPACT><DT id="37"><DD>
|
|
<PRE>
|
|
$ 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:
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
<P>
|
|
The command configuration file in the same manner as <B>--check-programs</B>, but
|
|
only for the component <I>component</I>.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<A NAME="lbAI"> </A>
|
|
<H3>Listing options</H3>
|
|
|
|
|
|
<P>
|
|
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.
|
|
<P>
|
|
The command <B></B> lists
|
|
all options (and the groups they belong to) in the component
|
|
<I>component</I>, one per line. <I>component</I> must be the string in
|
|
the field <I>name</I> in the output of the <B>--list-components</B>
|
|
command.
|
|
<P>
|
|
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).
|
|
<P>
|
|
The format of each line is:
|
|
<P>
|
|
<B></B><I>name</I>:<I>flags</I>:<I>level</I>:<I>description</I>:<I>type</I>:<I>alt-type</I>:<I>argname</I>:<I>default</I>:<I>argdef</I>:<I>value</I>
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT id="38"><B>name</B>
|
|
|
|
<DD>
|
|
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
|
|
<B>gpgconf</B>. The name tag is to be used <I>verbatim</I>. It is
|
|
thus not in any escaped format.
|
|
<P>
|
|
<DT id="39"><B>flags</B>
|
|
|
|
<DD>
|
|
The flags field contains an <I>unsigned number</I>. Its value is the
|
|
OR-wise combination of the following flag values:
|
|
<P>
|
|
<DL COMPACT><DT id="40"><DD>
|
|
<DL COMPACT>
|
|
<DT id="41"><B>group (1)</B>
|
|
|
|
<DD>
|
|
If this flag is set, this is a line describing a group and not an
|
|
option.
|
|
</DL>
|
|
</DL>
|
|
|
|
<P>
|
|
The following flag values are only defined for options (that is, if
|
|
the <B>group</B> flag is not used).
|
|
<P>
|
|
<DL COMPACT><DT id="42"><DD>
|
|
<DL COMPACT>
|
|
<DT id="43"><B>optional arg (2)</B>
|
|
|
|
<DD>
|
|
If this flag is set, the argument is optional. This is never set for
|
|
<I>type</I> <B>0</B> (none) options.
|
|
<P>
|
|
<DT id="44"><B>list (4)</B>
|
|
|
|
<DD>
|
|
If this flag is set, the option can be given multiple times.
|
|
<P>
|
|
<DT id="45"><B>runtime (8)</B>
|
|
|
|
<DD>
|
|
If this flag is set, the option can be changed at runtime.
|
|
<P>
|
|
<DT id="46"><B>default (16)</B>
|
|
|
|
<DD>
|
|
If this flag is set, a default value is available.
|
|
<P>
|
|
<DT id="47"><B>default desc (32)</B>
|
|
|
|
<DD>
|
|
If this flag is set, a (runtime) default is available. This and the
|
|
<B>default</B> flag are mutually exclusive.
|
|
<P>
|
|
<DT id="48"><B>no arg desc (64)</B>
|
|
|
|
<DD>
|
|
If this flag is set, and the <B>optional arg</B> flag is set, then the
|
|
option has a special meaning if no argument is given.
|
|
<P>
|
|
<DT id="49"><B>no change (128)</B>
|
|
|
|
<DD>
|
|
If this flag is set, <B>gpgconf</B> ignores requests to change the
|
|
value. GUI frontends should grey out this option. Note, that manual
|
|
changes of the configuration files are still possible.
|
|
</DL>
|
|
</DL>
|
|
|
|
<P>
|
|
<DT id="50"><B>level</B>
|
|
|
|
<DD>
|
|
This field is defined for options and for groups. It contains an
|
|
<I>unsigned number</I> 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):
|
|
<P>
|
|
<DL COMPACT><DT id="51"><DD>
|
|
<DL COMPACT>
|
|
<DT id="52"><B>basic (0)</B>
|
|
|
|
<DD>
|
|
This option should always be offered to the user.
|
|
<P>
|
|
<DT id="53"><B>advanced (1)</B>
|
|
|
|
<DD>
|
|
This option may be offered to advanced users.
|
|
<P>
|
|
<DT id="54"><B>expert (2)</B>
|
|
|
|
<DD>
|
|
This option should only be offered to expert users.
|
|
<P>
|
|
<DT id="55"><B>invisible (3)</B>
|
|
|
|
<DD>
|
|
This option should normally never be displayed, not even to expert
|
|
users.
|
|
<P>
|
|
<DT id="56"><B>internal (4)</B>
|
|
|
|
<DD>
|
|
This option is for internal use only. Ignore it.
|
|
</DL>
|
|
</DL>
|
|
|
|
<P>
|
|
The level of a group will always be the lowest level of all options it
|
|
contains.
|
|
<P>
|
|
<DT id="57"><B>description</B>
|
|
|
|
<DD>
|
|
This field is defined for options and groups. The <I>string</I> 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 <I>percent-escaped</I> and <I>localized</I>.
|
|
<P>
|
|
<DT id="58"><B>type</B>
|
|
|
|
<DD>
|
|
This field is only defined for options. It contains an <I>unsigned
|
|
number</I> that specifies the type of the option's argument, if any. The
|
|
following types are defined:
|
|
<P>
|
|
Basic types:
|
|
<P>
|
|
<DL COMPACT><DT id="59"><DD>
|
|
<DL COMPACT>
|
|
<DT id="60"><B>none (0)</B>
|
|
|
|
<DD>
|
|
No argument allowed.
|
|
<P>
|
|
<DT id="61"><B>string (1)</B>
|
|
|
|
<DD>
|
|
An <I>unformatted string</I>.
|
|
<P>
|
|
<DT id="62"><B>int32 (2)</B>
|
|
|
|
<DD>
|
|
A <I>signed number</I>.
|
|
<P>
|
|
<DT id="63"><B>uint32 (3)</B>
|
|
|
|
<DD>
|
|
An <I>unsigned number</I>.
|
|
</DL>
|
|
</DL>
|
|
|
|
<P>
|
|
Complex types:
|
|
<P>
|
|
<DL COMPACT><DT id="64"><DD>
|
|
<DL COMPACT>
|
|
<DT id="65"><B>pathname (32)</B>
|
|
|
|
<DD>
|
|
A <I>string</I> that describes the pathname of a file. The file does
|
|
not necessarily need to exist.
|
|
<P>
|
|
<DT id="66"><B>ldap server (33)</B>
|
|
|
|
<DD>
|
|
A <I>string</I> that describes an LDAP server in the format:
|
|
<P>
|
|
<B></B><I>hostname</I>:<I>port</I>:<I>username</I>:<I>password</I>:<I>base_dn</I>
|
|
<P>
|
|
<DT id="67"><B>key fingerprint (34)</B>
|
|
|
|
<DD>
|
|
A <I>string</I> with a 40 digit fingerprint specifying a certificate.
|
|
<P>
|
|
<DT id="68"><B>pub key (35)</B>
|
|
|
|
<DD>
|
|
A <I>string</I> that describes a certificate by user ID, key ID or
|
|
fingerprint.
|
|
<P>
|
|
<DT id="69"><B>sec key (36)</B>
|
|
|
|
<DD>
|
|
A <I>string</I> that describes a certificate with a key by user ID,
|
|
key ID or fingerprint.
|
|
<P>
|
|
<DT id="70"><B>alias list (37)</B>
|
|
|
|
<DD>
|
|
A <I>string</I> 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.
|
|
</DL>
|
|
</DL>
|
|
|
|
<P>
|
|
More types will be added in the future. Please see the <I>alt-type</I>
|
|
field for information on how to cope with unknown types.
|
|
<P>
|
|
<DT id="71"><B>alt-type</B>
|
|
|
|
<DD>
|
|
This field is identical to <I>type</I>, except that only the types
|
|
<B>0</B> to <B>31</B> are allowed. The GUI is expected to present the
|
|
user the option in the format specified by <I>type</I>. But if the
|
|
argument type <I>type</I> is not supported by the GUI, it can still
|
|
display the option in the more generic basic type <I>alt-type</I>. 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.
|
|
<P>
|
|
<DT id="72"><B>argname</B>
|
|
|
|
<DD>
|
|
This field is only defined for options with an argument type
|
|
<I>type</I> that is not <B>0</B>. In this case it may contain a
|
|
<I>percent-escaped</I> and <I>localized string</I> that gives a short
|
|
name for the argument. The field may also be empty, though, in which
|
|
case a short name is not known.
|
|
<P>
|
|
<DT id="73"><B>default</B>
|
|
|
|
<DD>
|
|
This field is defined only for options for which the <B>default</B> or
|
|
<B>default desc</B> flag is set. If the <B>default</B> flag is set,
|
|
its format is that of an <I>option argument</I> (see: [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 <B>default desc</B> flag is set, the field is
|
|
either empty or contains a description of the effect if the option is
|
|
not given.
|
|
<P>
|
|
<DT id="74"><B>argdef</B>
|
|
|
|
<DD>
|
|
This field is defined only for options for which the <B>optional
|
|
arg</B> flag is set. If the <B>no arg desc</B> flag is not set, its
|
|
format is that of an <I>option argument</I> (see: [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 <B>no arg desc</B> flag is set, the field is
|
|
either empty or contains a description of the effect of this option if
|
|
no argument is given.
|
|
<P>
|
|
<DT id="75"><B>value</B>
|
|
|
|
<DD>
|
|
This field is defined only for options. Its format is that of an
|
|
<I>option argument</I>. 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).
|
|
</DL>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>Changing options</H3>
|
|
|
|
|
|
<P>
|
|
The command to change the options of the component <I>component</I> to the
|
|
specified values. <I>component</I> must be the string in the field
|
|
<I>name</I> in the output of the <B>--list-components</B> command. You
|
|
have to provide the options that shall be changed in the following
|
|
format on standard input:
|
|
<P>
|
|
<B></B><I>name</I>:<I>flags</I>:<I>new-value</I>
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT id="76"><B>name</B>
|
|
|
|
<DD>
|
|
This is the name of the option to change. <I>name</I> must be the
|
|
string in the field <I>name</I> in the output of the
|
|
<B>--list-options</B> command.
|
|
<P>
|
|
<DT id="77"><B>flags</B>
|
|
|
|
<DD>
|
|
The flags field contains an <I>unsigned number</I>. Its value is the
|
|
OR-wise combination of the following flag values:
|
|
<P>
|
|
<DL COMPACT><DT id="78"><DD>
|
|
<DL COMPACT>
|
|
<DT id="79"><B>default (16)</B>
|
|
|
|
<DD>
|
|
If this flag is set, the option is deleted and the default value is
|
|
used instead (if applicable).
|
|
</DL>
|
|
</DL>
|
|
|
|
<P>
|
|
<DT id="80"><B>new-value</B>
|
|
|
|
<DD>
|
|
The new value for the option. This field is only defined if the
|
|
<B>default</B> flag is not set. The format is that of an <I>option
|
|
argument</I>. 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.
|
|
</DL>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
The output of the command is the same as that of
|
|
<B>--check-options</B> for the modified configuration file.
|
|
<P>
|
|
Examples:
|
|
<P>
|
|
To set the force option, which is of basic type <B>none (0)</B>:
|
|
<P>
|
|
<DL COMPACT><DT id="81"><DD>
|
|
<PRE>
|
|
$ echo 'force:0:1' | gpgconf --change-options dirmngr
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
To delete the force option:
|
|
<P>
|
|
<DL COMPACT><DT id="82"><DD>
|
|
<PRE>
|
|
$ echo 'force:16:' | gpgconf --change-options dirmngr
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
The <B>--runtime</B> option can influence when the changes take
|
|
effect.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<A NAME="lbAK"> </A>
|
|
<H3>Listing global options</H3>
|
|
|
|
|
|
<P>
|
|
Sometimes it is useful for applications to look at the global options
|
|
file '<I>gpgconf.conf</I>'.
|
|
The colon separated listing format is record oriented and uses the first
|
|
field to identify the record type:
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT id="83"><B>k</B>
|
|
|
|
<DD>
|
|
This describes a key record to start the definition of a new ruleset for
|
|
a user/group. The format of a key record is:
|
|
<P>
|
|
<BR> <B>k:</B><I>user</I>:<I>group</I>:
|
|
<P>
|
|
<DL COMPACT><DT id="84"><DD>
|
|
<DL COMPACT>
|
|
<DT id="85"><B>user</B>
|
|
|
|
<DD>
|
|
This is the user field of the key. It is percent escaped. See the
|
|
definition of the gpgconf.conf format for details.
|
|
<P>
|
|
<DT id="86"><B>group</B>
|
|
|
|
<DD>
|
|
This is the group field of the key. It is percent escaped.
|
|
</DL>
|
|
</DL>
|
|
|
|
<P>
|
|
<DT id="87"><B>r</B>
|
|
|
|
<DD>
|
|
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:
|
|
<P>
|
|
<BR> <B>r:::</B><I>component</I>:<I>option</I>:<I>flag</I>:<I>value</I>:
|
|
<P>
|
|
<DL COMPACT><DT id="88"><DD>
|
|
<DL COMPACT>
|
|
<DT id="89"><B>component</B>
|
|
|
|
<DD>
|
|
This is the component part of a rule. It is a plain string.
|
|
<P>
|
|
<DT id="90"><B>option</B>
|
|
|
|
<DD>
|
|
This is the option part of a rule. It is a plain string.
|
|
<P>
|
|
<DT id="91"><B>flag</B>
|
|
|
|
<DD>
|
|
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.
|
|
<P>
|
|
<DT id="92"><B>value</B>
|
|
|
|
<DD>
|
|
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.
|
|
</DL>
|
|
</DL>
|
|
|
|
<P>
|
|
</DL>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
Unknown record types should be ignored. Note that there is intentionally
|
|
no feature to change the global option file through <B>gpgconf</B>.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<A NAME="lbAL"> </A>
|
|
<H3>Get and compare software versions.</H3>
|
|
|
|
|
|
<P>
|
|
The GnuPG Project operates a server to query the current versions of
|
|
software packages related to GnuPG. <B>gpgconf</B> can be used to
|
|
access this online database. To allow for offline operations, this
|
|
feature works by having <B>dirmngr</B> download a file from
|
|
<B><A HREF="https://versions.gnupg.org">https://versions.gnupg.org</A></B>, checking the signature of that file
|
|
and storing the file in the GnuPG home directory. If
|
|
<B>gpgconf</B> is used and <B>dirmngr</B> is running, it may ask
|
|
<B>dirmngr</B> to refresh that file before itself uses the file.
|
|
<P>
|
|
The command <B>--query-swdb</B> returns information for the given
|
|
package in a colon delimited format:
|
|
<P>
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT id="93"><B>name</B>
|
|
|
|
<DD>
|
|
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 <B>gpgconf</B> takes its own version in this case.
|
|
<P>
|
|
<DT id="94"><B>iversion</B>
|
|
|
|
<DD>
|
|
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.
|
|
<P>
|
|
<DT id="95"><B>status</B>
|
|
|
|
<DD>
|
|
The status of the software package according to this table:
|
|
<DL COMPACT><DT id="96"><DD>
|
|
<DL COMPACT>
|
|
<DT id="97"><B>-</B>
|
|
|
|
<DD>
|
|
No information available. This is either because no current version
|
|
has been specified or due to an error.
|
|
<DT id="98"><B>?</B>
|
|
|
|
<DD>
|
|
The given name is not known in the online database.
|
|
<DT id="99"><B>u</B>
|
|
|
|
<DD>
|
|
An update of the software is available.
|
|
<DT id="100"><B>c</B>
|
|
|
|
<DD>
|
|
The installed version of the software is current.
|
|
<DT id="101"><B>n</B>
|
|
|
|
<DD>
|
|
The installed version is already newer than the released version.
|
|
</DL>
|
|
</DL>
|
|
|
|
<P>
|
|
<DT id="102"><B>urgency</B>
|
|
|
|
<DD>
|
|
If the value (the empty string should be considered as zero) is
|
|
greater than zero an important update is available.
|
|
<P>
|
|
<DT id="103"><B>error</B>
|
|
|
|
<DD>
|
|
This returns an <B>gpg-error</B> error code to distinguish between
|
|
various failure modes.
|
|
<P>
|
|
<DT id="104"><B>filedate</B>
|
|
|
|
<DD>
|
|
This gives the date of the file with the version numbers in standard
|
|
ISO format (<B>yyyymmddThhmmss</B>). The date has been extracted by
|
|
<B>dirmngr</B> from the signature of the file.
|
|
<P>
|
|
<DT id="105"><B>verified</B>
|
|
|
|
<DD>
|
|
This gives the date in ISO format the file was downloaded. This value
|
|
can be used to evaluate the freshness of the information.
|
|
<P>
|
|
<DT id="106"><B>version</B>
|
|
|
|
<DD>
|
|
This returns the version string for the requested software from the
|
|
file.
|
|
<P>
|
|
<DT id="107"><B>reldate</B>
|
|
|
|
<DD>
|
|
This returns the release date in ISO format.
|
|
<P>
|
|
<DT id="108"><B>size</B>
|
|
|
|
<DD>
|
|
This returns the size of the package as decimal number of bytes.
|
|
<P>
|
|
<DT id="109"><B>hash</B>
|
|
|
|
<DD>
|
|
This returns a hexified SHA-2 hash of the package.
|
|
<P>
|
|
</DL>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
More fields may be added in future to the output.
|
|
<P>
|
|
<P>
|
|
<A NAME="lbAM"> </A>
|
|
<H2>FILES</H2>
|
|
|
|
<P>
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT id="110"><B>/etc/gnupg/gpgconf.conf</B>
|
|
|
|
<DD>
|
|
<BR> If this file exists, it is processed as a global configuration file.
|
|
<BR> A commented example can be found in the '<I>examples</I>' directory of
|
|
<BR> the distribution.
|
|
<P>
|
|
<DT id="111"><B></B><I>GNUPGHOME</I>/swdb.lst
|
|
|
|
<DD>
|
|
<BR> A file with current software versions. <B>dirmngr</B> creates
|
|
<BR> this file on demand from an online resource.
|
|
<P>
|
|
</DL>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
<A NAME="lbAN"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+gpg">gpg</A></B>(1),
|
|
<B><A HREF="/cgi-bin/man/man2html?1+gpgsm">gpgsm</A></B>(1),
|
|
<B><A HREF="/cgi-bin/man/man2html?1+gpg-agent">gpg-agent</A></B>(1),
|
|
<B><A HREF="/cgi-bin/man/man2html?1+scdaemon">scdaemon</A></B>(1),
|
|
<B><A HREF="/cgi-bin/man/man2html?1+dirmngr">dirmngr</A></B>(1)
|
|
<P>
|
|
The full documentation for this tool is maintained as a Texinfo manual.
|
|
If GnuPG and the info program are properly installed at your site, the
|
|
command
|
|
<P>
|
|
<DL COMPACT><DT id="112"><DD>
|
|
<PRE>
|
|
info gnupg
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
should give you access to the complete manual including a menu structure
|
|
and an index.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="113"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="114"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="115"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="116"><A HREF="#lbAE">COMMANDS</A><DD>
|
|
<DT id="117"><A HREF="#lbAF">OPTIONS</A><DD>
|
|
<DT id="118"><A HREF="#lbAG">USAGE</A><DD>
|
|
<DL>
|
|
<DT id="119"><A HREF="#lbAH">Checking programs</A><DD>
|
|
<DT id="120"><A HREF="#lbAI">Listing options</A><DD>
|
|
<DT id="121"><A HREF="#lbAJ">Changing options</A><DD>
|
|
<DT id="122"><A HREF="#lbAK">Listing global options</A><DD>
|
|
<DT id="123"><A HREF="#lbAL">Get and compare software versions.</A><DD>
|
|
</DL>
|
|
<DT id="124"><A HREF="#lbAM">FILES</A><DD>
|
|
<DT id="125"><A HREF="#lbAN">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:15 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|