Current File : //usr/share/man/man1/gpgconf.1

'\" te
.\" Created from Texinfo source by yat2m 1.0
.TH GPGCONF 1 2015-08-20 "GnuPG 2.0.27" "GNU Privacy Guard"
.SH NAME
.B gpgconf
\- Modify .gnupg home directories
.SH SYNOPSIS
.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


.SH DESCRIPTION
The \fBgpgconf\fR is a utility to automatically and reasonable
safely query and modify configuration files in the \(oq\fI.gnupg\fR\(cq 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.])

\fBgpgconf\fR 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 GnuPG,
GPGSM, DirMngr, etc.  But this is not a strict one-to-one
relationship.  Not all configuration options are available through
\fBgpgconf\fR.  \fBgpgconf\fR provides a generic and abstract
method to access the most important configuration options that can
feasibly be controlled via such a mechanism.

\fBgpgconf\fR can be used to gather and change the options
available in each component, and can also provide their default
values.  \fBgpgconf\fR will give detailed type information that
can be used to restrict the user's input without making an attempt to
commit the changes.

\fBgpgconf\fR provides the backend of a configuration editor.  The
configuration editor would usually be a graphical user interface
program, that allows to display the current options, their default
values, and allows the user to make changes to the options.  These
changes can then be made active with \fBgpgconf\fR again.  Such a
program that uses \fBgpgconf\fR in this way will be called GUI
throughout this section.


.SH COMMANDS
One of the following commands must be given:


.TP
.B  --list-components
List all components.  This is the default command used if none is
specified.

.TP
.B  --check-programs
List all available backend programs and test whether they are runnable.

.TP
.B  --list-options \fIcomponent\fR
List all options of the component \fIcomponent\fR.

.TP
.B  --change-options \fIcomponent\fR
Change the options of the component \fIcomponent\fR.

.TP
.B  --check-options \fIcomponent\fR
Check the options for the component \fIcomponent\fR.

.TP
.B  --apply-defaults
Update all configuration files with values taken from the global
configuration file (usually \(oq\fI/etc/gnupg/gpgconf.conf\fR\(cq).

.TP
.B  --list-dirs
Lists the directories used by \fBgpgconf\fR.  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 \fBsysconfdir\fR)
and the second field contains the percent-escaped directory.  Although
they are not directories, the socket file names used by
\fBgpg-agent\fR and \fBdirmngr\fR are printed as well.  Note
that the socket file names and the \fBhomedir\fR lines are the default
names and they may be overridden by command line switches.

.TP
.B  --list-config [\fIfilename\fR]
List the global configuration file in a colon separated format.  If
\fIfilename\fR is given, check that file instead.

.TP
.B  --check-config [\fIfilename\fR]
Run a syntax check on the global configuration file.  If \fIfilename\fR
is given, check that file instead.

.TP
.B  --reload [\fIcomponent\fR]
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.




.SH OPTIONS

The following options may be used:


.TP
.B  -v
.TP
.B  --verbose
Outputs additional information while running.  Specifically, this
extends numerical field values by human-readable descriptions.

.TP
.B  -n
.TP
.B  --dry-run
Do not actually change anything.  This is currently only implemented
for \fB--change-options\fR and can be used for testing purposes.

.TP
.B  -r
.TP
.B  --runtime
Only used together with \fB--change-options\fR.  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.
.SH USAGE

The command \fB--list-components\fR will list all components that can
be configured with \fBgpgconf\fR.  Usually, one component will
correspond to one GnuPG-related program and contain the options of
that programs configuration file that can be modified using
\fBgpgconf\fR.  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 argument \fB--list-components\fR lists all available
components, one per line.  The format of each line is:

\fB\fIname\fR:\fIdescription\fR:\fIpgmname\fR:\fR

.TP
.B  name
This field contains a name tag of the component.  The name tag is used
to specify the component in all communication with \fBgpgconf\fR.
The name tag is to be used \fIverbatim\fR.  It is thus not in any
escaped format.

.TP
.B  description
The \fIstring\fR 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 \fIpercent-escaped\fR and
\fIlocalized\fR.

.TP
.B  pgmname
The \fIstring\fR in this field contains the absolute name of the
program's file.  It can be used to unambiguously invoke that program.
It is \fIpercent-escaped\fR.

Example:
.RS 2
.nf
$ 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:
.fi
.RE




.SS  Checking programs
\ 

The command \fB--check-programs\fR is similar to
\fB--list-components\fR 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 argument \fB--check-programs\fR lists all available
programs, one per line.  The format of each line is:

\fB\fIname\fR:\fIdescription\fR:\fIpgmname\fR:\fIavail\fR:\fIokay\fR:\fIcfgfile\fR:\fIline\fR:\fIerror\fR:\fR

.TP
.B  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 \fIverbatim\fR.  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.

.TP
.B  description
The \fIstring\fR 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 \fIpercent-escaped\fR and
\fIlocalized\fR.

.TP
.B  pgmname
The \fIstring\fR in this field contains the absolute name of the
program's file.  It can be used to unambiguously invoke that program.
It is \fIpercent-escaped\fR.

.TP
.B  avail
The \fIboolean value\fR in this field indicates whether the program is
installed and runnable.

.TP
.B  okay
The \fIboolean value\fR in this field indicates whether the program's
config file is syntactically okay.

.TP
.B  cfgfile
If an error occurred in the configuration file (as indicated by a false
value in the field \fBokay\fR), this field has the name of the failing
configuration file.  It is \fIpercent-escaped\fR.

.TP
.B  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 \fIunsigned number\fR.

.TP
.B  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
\fIpercent-escaped\fR and \fIlocalized\fR.



In the following example the \fBdirmngr\fR is not runnable and the
configuration file of \fBscdaemon\fR is not okay.

.RS 2
.nf
$ 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:
.fi
.RE


The command configuration file in the same manner as \fB--check-programs\fR, but
only for the component \fIcomponent\fR.



.SS  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 argument \fB\fR lists
all options (and the groups they belong to) in the component
\fIcomponent\fR, one per line.  \fIcomponent\fR must be the string in
the field \fIname\fR in the output of the \fB--list-components\fR
command.

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:

\fB\fIname\fR:\fIflags\fR:\fIlevel\fR:\fIdescription\fR:\fItype\fR:\fIalt-type\fR:\fIargname\fR:\fIdefault\fR:\fIargdef\fR:\fIvalue\fR\fR

.TP
.B  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
\fBgpgconf\fR.  The name tag is to be used \fIverbatim\fR.  It is
thus not in any escaped format.

.TP
.B  flags
The flags field contains an \fIunsigned number\fR.  Its value is the
OR-wise combination of the following flag values:

.RS
.TP
.B  group (1)
If this flag is set, this is a line describing a group and not an
option.
.RE

The following flag values are only defined for options (that is, if
the \fBgroup\fR flag is not used).

.RS
.TP
.B  optional arg (2)
If this flag is set, the argument is optional.  This is never set for
\fItype\fR \fB0\fR (none) options.

.TP
.B  list (4)
If this flag is set, the option can be given multiple times.

.TP
.B  runtime (8)
If this flag is set, the option can be changed at runtime.

.TP
.B  default (16)
If this flag is set, a default value is available.

.TP
.B  default desc (32)
If this flag is set, a (runtime) default is available.  This and the
\fBdefault\fR flag are mutually exclusive.

.TP
.B  no arg desc (64)
If this flag is set, and the \fBoptional arg\fR flag is set, then the
option has a special meaning if no argument is given.

.TP
.B  no change (128)
If this flag is set, 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.
.RE

.TP
.B  level
This field is defined for options and for groups.  It contains an
\fIunsigned number\fR 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):

.RS
.TP
.B  basic (0)
This option should always be offered to the user.

.TP
.B  advanced (1)
This option may be offered to advanced users.

.TP
.B  expert (2)
This option should only be offered to expert users.

.TP
.B  invisible (3)
This option should normally never be displayed, not even to expert
users.

.TP
.B  internal (4)
This option is for internal use only.  Ignore it.
.RE

The level of a group will always be the lowest level of all options it
contains.

.TP
.B  description
This field is defined for options and groups.  The \fIstring\fR 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 \fIpercent-escaped\fR and \fIlocalized\fR.

.TP
.B  type
This field is only defined for options.  It contains an \fIunsigned
number\fR that specifies the type of the option's argument, if any.  The
following types are defined:

Basic types:

.RS
.TP
.B  none (0)
No argument allowed.

.TP
.B  string (1)
An \fIunformatted string\fR.

.TP
.B  int32 (2)
A \fIsigned number\fR.

.TP
.B  uint32 (3)
An \fIunsigned number\fR.
.RE

Complex types:

.RS
.TP
.B  pathname (32)
A \fIstring\fR that describes the pathname of a file.  The file does
not necessarily need to exist.

.TP
.B  ldap server (33)
A \fIstring\fR that describes an LDAP server in the format:

\fB\fIhostname\fR:\fIport\fR:\fIusername\fR:\fIpassword\fR:\fIbase_dn\fR\fR

.TP
.B  key fingerprint (34)
A \fIstring\fR with a 40 digit fingerprint specifying a certificate.

.TP
.B  pub key (35)
A \fIstring\fR that describes a certificate by user ID, key ID or
fingerprint.

.TP
.B  sec key (36)
A \fIstring\fR that describes a certificate with a key by user ID,
key ID or fingerprint.

.TP
.B  alias list (37)
A \fIstring\fR 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.
.RE

More types will be added in the future.  Please see the \fIalt-type\fR
field for information on how to cope with unknown types.

.TP
.B  alt-type
This field is identical to \fItype\fR, except that only the types
\fB0\fR to \fB31\fR are allowed.  The GUI is expected to present the
user the option in the format specified by \fItype\fR.  But if the
argument type \fItype\fR is not supported by the GUI, it can still
display the option in the more generic basic type \fIalt-type\fR.  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.

.TP
.B  argname
This field is only defined for options with an argument type
\fItype\fR that is not \fB0\fR.  In this case it may contain a
\fIpercent-escaped\fR and \fIlocalised string\fR that gives a short
name for the argument.  The field may also be empty, though, in which
case a short name is not known.

.TP
.B  default
This field is defined only for options for which the \fBdefault\fR or
\fBdefault desc\fR flag is set.  If the \fBdefault\fR flag is set,
its format is that of an \fIoption argument\fR (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 \fBdefault desc\fR flag is set, the field is
either empty or contains a description of the effect if the option is
not given.

.TP
.B  argdef
This field is defined only for options for which the \fBoptional
arg\fR flag is set.  If the \fBno arg desc\fR flag is not set, its
format is that of an \fIoption argument\fR (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 \fBno arg desc\fR flag is set, the field is
either empty or contains a description of the effect of this option if
no argument is given.

.TP
.B  value
This field is defined only for options.  Its format is that of an
\fIoption argument\fR.  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).



.SS  Changing options
\ 

The command to change the options of the component \fIcomponent\fR to the
specified values.  \fIcomponent\fR must be the string in the field
\fIname\fR in the output of the \fB--list-components\fR command.  You
have to provide the options that shall be changed in the following
format on standard input:

\fB\fIname\fR:\fIflags\fR:\fInew-value\fR\fR

.TP
.B  name
This is the name of the option to change.  \fIname\fR must be the
string in the field \fIname\fR in the output of the
\fB--list-options\fR command.

.TP
.B  flags
The flags field contains an \fIunsigned number\fR.  Its value is the
OR-wise combination of the following flag values:

.RS
.TP
.B  default (16)
If this flag is set, the option is deleted and the default value is
used instead (if applicable).
.RE

.TP
.B  new-value
The new value for the option.  This field is only defined if the
\fBdefault\fR flag is not set.  The format is that of an \fIoption
argument\fR.  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.


The output of the command is the same as that of
\fB--check-options\fR for the modified configuration file.

Examples:

To set the force option, which is of basic type \fBnone (0)\fR:

.RS 2
.nf
$ echo 'force:0:1' | gpgconf --change-options dirmngr
.fi
.RE

To delete the force option:

.RS 2
.nf
$ echo 'force:16:' | gpgconf --change-options dirmngr
.fi
.RE

The \fB--runtime\fR option can influence when the changes take
effect.



.SS  Listing global options
\ 

Sometimes it is useful for applications to look at the global options
file \(oq\fIgpgconf.conf\fR\(cq.
The colon separated listing format is record oriented and uses the first
field to identify the record type:

.TP
.B  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:

  \fBk:\fIuser\fR:\fIgroup\fR:\fR

.RS
.TP
.B  user
This is the user field of the key.  It is percent escaped.  See the
definition of the gpgconf.conf format for details.

.TP
.B  group
This is the group field of the key.  It is percent escaped.
.RE

.TP
.B  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:

  \fBr:::\fIcomponent\fR:\fIoption\fR:\fIflags\fR:\fIvalue\fR:\fR

.RS
.TP
.B  component
This is the component part of a rule.  It is a plain string.

.TP
.B  option
This is the option part of a rule.  It is a plain string.

.TP
.B  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.

.TP
.B  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.
.RE



Unknown record types should be ignored.  Note that there is intentionally
no feature to change the global option file through \fBgpgconf\fR.



.SH FILES


.TP
.B  /etc/gnupg/gpgconf.conf
  If this file exists, it is processed as a global configuration file.
  A commented example can be found in the \(oq\fIexamples\fR\(cq directory of
  the distribution.



.\" Oracle has added the ARC stability level to this manual page
.SH ATTRIBUTES
See
.BR attributes (5)
for descriptions of the following attributes:
.sp
.TS
box;
cbp-1 | cbp-1
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE 
=
Availability	crypto/gnupg
=
Stability	Uncommitted
.TE 
.PP
.SH SEE ALSO
\fBgpg\fR(1),
\fBgpgsm\fR(1),
\fBgpg-agent\fR(1),
\fBscdaemon\fR(1),
\fBdirmngr\fR(1)

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

.RS 2
.nf
info gnupg
.fi
.RE

should give you access to the complete manual including a menu structure
and an index.






.SH NOTES

.\" Oracle has added source availability information to this manual page
This software was built from source available at https://java.net/projects/solaris-userland.  The original community source was downloaded from  ftp://ftp.gnupg.org/gcrypt/gnupg/gnupg-2.0.27.tar.bz2

Further information about this software can be found on the open source community website at http://www.gnupg.org/.