mirror of
git://git.gnupg.org/gnupg.git
synced 2024-12-22 10:19:57 +01:00
Remove what is now in the texi docs.
This commit is contained in:
Marcus Brinkmann
parent
502be0ce06
commit
5e41c3969c
@ -2,344 +2,7 @@
|
|||||||
GPG Conf
|
GPG Conf
|
||||||
============
|
============
|
||||||
|
|
||||||
CONCEPT
|
Main documentation for this tool can be found in doc/tools.texi.
|
||||||
=======
|
|
||||||
|
|
||||||
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 GnuPG, GPGSM,
|
|
||||||
DirMngr, etc. But this is not a strict one-to-one relationship. Not
|
|
||||||
all configuration options are available through GPGConf. GPGConf
|
|
||||||
provides a generic and abstract method to access the most important
|
|
||||||
configuration options that can feasibly be controlled via such a
|
|
||||||
mechanism.
|
|
||||||
|
|
||||||
GPGConf can be used to gather and change the options available in each
|
|
||||||
component, and can also provide their default values. GPGConf will
|
|
||||||
give detailed type information that can be used to restrict the user's
|
|
||||||
input without making an attempt to commit the changes.
|
|
||||||
|
|
||||||
GPGConf 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 GPGConf again. Such a program
|
|
||||||
that uses GPGConf in this way will be called 'GUI' throughout this
|
|
||||||
document.
|
|
||||||
|
|
||||||
|
|
||||||
Format Conventions
|
|
||||||
==================
|
|
||||||
|
|
||||||
Some lines in the output of GPGConf contain a list of colon-separated
|
|
||||||
fields. The following conventions apply:
|
|
||||||
|
|
||||||
The GUI program is required to strip off trailing newline and/or carriage
|
|
||||||
return characters from the output.
|
|
||||||
|
|
||||||
GPGConf will never leave out fields. If a certain version documents a
|
|
||||||
certain field, this field will always be present in all GPGConf
|
|
||||||
versions from that time on.
|
|
||||||
|
|
||||||
Future versions of 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.
|
|
||||||
|
|
||||||
Not all fields are defined under all conditions. You are required to
|
|
||||||
ignore the content of undefined fields.
|
|
||||||
|
|
||||||
Some fields contain strings that are not escaped in any way. Such
|
|
||||||
fields are described to be used "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.
|
|
||||||
|
|
||||||
Some fields contain strings that are described to be
|
|
||||||
"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 occurences of %XY by the byte that has the
|
|
||||||
hexadecimal value XY. X and Y are from the set { '0'..'9', 'a'..'f' }.
|
|
||||||
|
|
||||||
Some fields contain strings that are described to be "localised". Such
|
|
||||||
strings are translated to the active language and formatted in the
|
|
||||||
active character set.
|
|
||||||
|
|
||||||
Some fields contain an 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.
|
|
||||||
You should ignore everything in the field that follows the number.
|
|
||||||
|
|
||||||
Some fields contain a 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. You
|
|
||||||
should ignore everything in the field that follows the number.
|
|
||||||
|
|
||||||
Some fields contain an option argument. The format of an option
|
|
||||||
argument depends on the type of the option and on some flags:
|
|
||||||
|
|
||||||
The simplest case is that the option does not take an argument at all
|
|
||||||
(TYPE is 0). Then the option argument is an unsigned number that
|
|
||||||
specifies how often the option occurs. If the LIST flag is not set,
|
|
||||||
then the only valid number is 1. Options that don't take an argument
|
|
||||||
never have the "default" or "optional arg" flag set.
|
|
||||||
|
|
||||||
If the option takes a number argument (ALT-TYPE is 2 or 3), and it can
|
|
||||||
only occur once (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 ALT-TYPE).
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
If the option takes a string argument (ALT-TYPE is 1), and it can only
|
|
||||||
occur once (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 (") 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.
|
|
||||||
|
|
||||||
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 string arguments as described above.
|
|
||||||
|
|
||||||
FIXME: Document the active language and active character set. Allow
|
|
||||||
to change it via the command line?
|
|
||||||
|
|
||||||
|
|
||||||
Components
|
|
||||||
==========
|
|
||||||
|
|
||||||
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 following interface is provided to list the available components:
|
|
||||||
|
|
||||||
Command --list-components
|
|
||||||
-------------------------
|
|
||||||
|
|
||||||
Outputs a list of all components available, one per line. The format
|
|
||||||
of each line is:
|
|
||||||
|
|
||||||
NAME:DESCRIPTION
|
|
||||||
|
|
||||||
NAME
|
|
||||||
|
|
||||||
This field contains a name tag of the component. The name tag is used
|
|
||||||
to specify the component in all communication with GPGConf. The name
|
|
||||||
tag is to be used verbatim. It is not in any escaped format.
|
|
||||||
|
|
||||||
DESCRIPTION
|
|
||||||
|
|
||||||
The 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 percent-escaped and localized.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
$ gpgconf --list-components
|
|
||||||
gpg-agent:GPG Agent
|
|
||||||
dirmngr:CRL Manager
|
|
||||||
|
|
||||||
|
|
||||||
OPTIONS
|
|
||||||
=======
|
|
||||||
|
|
||||||
Every component contains one or more options. Options may belong to a
|
|
||||||
group. The following command lists all options and the groups they
|
|
||||||
belong to:
|
|
||||||
|
|
||||||
Command --list-options COMPONENT
|
|
||||||
--------------------------------
|
|
||||||
|
|
||||||
Lists all options (and the groups they belong to) in the component
|
|
||||||
COMPONENT. COMPONENT is the string in the field NAME in the
|
|
||||||
output of the --list-components 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.
|
|
||||||
|
|
||||||
The format of each line is:
|
|
||||||
|
|
||||||
NAME:FLAGS:LEVEL:DESCRIPTION:TYPE:ALT-TYPE:ARGNAME:DEFAULT:ARGDEF:VALUE
|
|
||||||
|
|
||||||
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
|
|
||||||
GPGConf. The name tag is to be used verbatim. It is not in any
|
|
||||||
escaped format.
|
|
||||||
|
|
||||||
FLAGS
|
|
||||||
|
|
||||||
The flags field contains an unsigned number. Its value is the
|
|
||||||
OR-wise combination of the following flag values:
|
|
||||||
|
|
||||||
1 group If this flag is set, this is a line describing
|
|
||||||
a group and not an option.
|
|
||||||
O 2 optional arg If this flag is set, the argument is optional.
|
|
||||||
This is never set for arg type 0 (none) options.
|
|
||||||
O 4 list If this flag is set, the option can be given
|
|
||||||
multiple times.
|
|
||||||
O 8 runtime If this flag is set, the option can be changed
|
|
||||||
at runtime.
|
|
||||||
O 16 default If this flag is set, a default value is available.
|
|
||||||
O 32 default desc If this flag is set, a (runtime) default is available.
|
|
||||||
This and the 'default' flag are mutually exclusive.
|
|
||||||
O 64 no arg desc If this flag is set, and the 'optional arg' flag
|
|
||||||
is set, then the option has a special meaning if no
|
|
||||||
argument is given.
|
|
||||||
|
|
||||||
Flags marked with a 'O' are only defined for options (ie, if the GROUP
|
|
||||||
flag is not set).
|
|
||||||
|
|
||||||
LEVEL
|
|
||||||
|
|
||||||
This field is defined for options and for groups. It contains an
|
|
||||||
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):
|
|
||||||
|
|
||||||
0 basic This option should always be offered to the user.
|
|
||||||
1 advanced This option may be offered to advanced users.
|
|
||||||
2 expert This option should only be offered to expert users.
|
|
||||||
3 invisible This option should normally never be displayed,
|
|
||||||
not even to expert users.
|
|
||||||
4 internal This option is for internal use only. Ignore it.
|
|
||||||
|
|
||||||
The level of a group will always be the lowest level of all options it
|
|
||||||
contains.
|
|
||||||
|
|
||||||
DESCRIPTION
|
|
||||||
|
|
||||||
This field is defined for options and groups. The 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 percent-escaped and localized.
|
|
||||||
|
|
||||||
TYPE
|
|
||||||
|
|
||||||
This field is only defined for options. It contains an unsigned
|
|
||||||
number that specifies the type of the option's argument, if any.
|
|
||||||
The following types are defined:
|
|
||||||
|
|
||||||
Basic types
|
|
||||||
0 none No argument allowed.
|
|
||||||
1 string An unformatted string.
|
|
||||||
2 int32 A signed integer number.
|
|
||||||
3 uint32 An unsigned integer number.
|
|
||||||
|
|
||||||
Complex types
|
|
||||||
32 pathname A string that describes the pathname of a file.
|
|
||||||
The file does not necessarily need to exist.
|
|
||||||
33 ldap server A string that describes an LDAP server in the format
|
|
||||||
HOSTNAME:PORT:USERNAME:PASSWORD:BASE_DN.
|
|
||||||
|
|
||||||
More types will be added in the future. Please see the ALT-TYPE field
|
|
||||||
for information on how to cope with unknown types.
|
|
||||||
|
|
||||||
ALT-TYPE
|
|
||||||
|
|
||||||
This field is identical to TYPE, except that only the types 0 to 31
|
|
||||||
are allowed. The GUI is expected to present the user the option in
|
|
||||||
the format specified by TYPE. But if the argument type TYPE is not
|
|
||||||
supported by the GUI, it can still display the option in the more
|
|
||||||
generic basic type 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.
|
|
||||||
|
|
||||||
ARGNAME
|
|
||||||
|
|
||||||
This field is only defined for options with an argument type TYPE that
|
|
||||||
is not 0. In this case it may contain a percent-escaped and localised
|
|
||||||
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.
|
|
||||||
|
|
||||||
DEFAULT
|
|
||||||
|
|
||||||
This field is defined only for options. Its format is that of an
|
|
||||||
option argument (see section 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. Note that this
|
|
||||||
field is also meaningful if the option itself does not take a real
|
|
||||||
argument.
|
|
||||||
|
|
||||||
ARGDEF
|
|
||||||
|
|
||||||
This field is defined only for options for which the "optional arg"
|
|
||||||
flag is set. If the "no arg desc" flag is not set, its format is that
|
|
||||||
of an option argument (see section 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 "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. Note that this
|
|
||||||
field is also meaningful if the option itself does not take a real
|
|
||||||
argument.
|
|
||||||
|
|
||||||
VALUE
|
|
||||||
|
|
||||||
This field is defined only for options. Its format is that of an
|
|
||||||
option argument. If it is empty, then the option is not explicitely
|
|
||||||
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.
|
|
||||||
|
|
||||||
|
|
||||||
CHANGING OPTIONS
|
|
||||||
================
|
|
||||||
|
|
||||||
To change the options for a component, you must provide them in the
|
|
||||||
following format:
|
|
||||||
|
|
||||||
NAME:FLAGS:NEW-VALUE
|
|
||||||
|
|
||||||
NAME
|
|
||||||
|
|
||||||
This is the name of the option to change.
|
|
||||||
|
|
||||||
FLAGS
|
|
||||||
|
|
||||||
The flags field contains an unsigned number. Its value is the
|
|
||||||
OR-wise combination of the following flag values:
|
|
||||||
|
|
||||||
16 default If this flag is set, the option is deleted and the
|
|
||||||
default value is used instead (if applicable).
|
|
||||||
|
|
||||||
NEW-VALUE
|
|
||||||
|
|
||||||
The new value for the option. This field is only defined if the
|
|
||||||
"default" flag is not set. The format is that of an 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.
|
|
||||||
|
|
||||||
|
|
||||||
Example:
|
|
||||||
To set the option force, which is of basic type 0 (none).
|
|
||||||
$ echo 'force:0:1' | gpgconf --change-options dirmngr
|
|
||||||
To delete the option force:
|
|
||||||
$ echo 'force:16:' | gpgconf --change-options dirmngr
|
|
||||||
|
|
||||||
|
|
||||||
Option --runtime
|
|
||||||
----------------
|
|
||||||
|
|
||||||
If this option is set, 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.
|
|
||||||
|
|
||||||
|
|
||||||
BACKENDS
|
BACKENDS
|
||||||
========
|
========
|
||||||
@ -409,14 +72,8 @@ max-replies:10
|
|||||||
TODO
|
TODO
|
||||||
----
|
----
|
||||||
|
|
||||||
|
* Implement --dry-run and --quiet.
|
||||||
|
|
||||||
* Extend the backend interface to include gettext domain and
|
* Extend the backend interface to include gettext domain and
|
||||||
description, if available, to avoid repeating this information in
|
description, if available, to avoid repeating this information in
|
||||||
gpgconf.
|
gpgconf.
|
||||||
|
|
||||||
* Left out string arguments (optional) are written out exactly as
|
|
||||||
empty string arguments. Should we do quoting?
|
|
||||||
|
|
||||||
* More string argument trouble: Special characters like newlines etc
|
|
||||||
cause trouble. Again, should we do quoting?
|
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user