From 502be0ce06b747900628364ca0f560114b042b72 Mon Sep 17 00:00:00 2001 From: Marcus Brinkmann Date: Wed, 29 Sep 2004 23:06:02 +0000 Subject: [PATCH] 2004-09-30 Marcus Brinkmann * tools.texi (Changing options): Add documentation for gpgconf. --- doc/ChangeLog | 2 + doc/tools.texi | 500 ++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 500 insertions(+), 2 deletions(-) diff --git a/doc/ChangeLog b/doc/ChangeLog index eabebbfd1..4c2eaf216 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,5 +1,7 @@ 2004-09-30 Marcus Brinkmann + * tools.texi (Changing options): Add documentation for gpgconf. + * contrib.texi (Contributors): Add two missing periods. 2004-09-29 Werner Koch diff --git a/doc/tools.texi b/doc/tools.texi index d04b01277..72707639c 100644 --- a/doc/tools.texi +++ b/doc/tools.texi @@ -9,7 +9,8 @@ GnuPG comes with a couple of smaller tools: @menu * watchgnupg:: Read logs from a socket. -* addgnupghome:: Create .gnupg home directories +* addgnupghome:: Create .gnupg home directories. +* gpgconf:: Modify .gnupg home directories. @end menu @@ -57,7 +58,7 @@ Display a brief help page and exit @node addgnupghome -@section Create .gnupg home directories +@section Create .gnupg home directories. If GnuPG is installed on a system with existing user accounts, it is sometimes required to populate the GnuPG home directory with existing @@ -72,3 +73,498 @@ addgnupghome is invoked by root as: @samp{addgnupghome account1 account2 ... accountn} + +@node gpgconf +@section Modify .gnupg home directories. + +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 GnuPG, +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 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 @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. +* Listing options:: List all options of a component. +* Changing options:: Changing options of a component. +@end menu + + +@node Invoking gpgconf +@subsection Invoking gpgconf + +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 --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}. +@end table + +The following options may be used: + +@table @gnupgtabopt +@c FIXME: Not yet supported. +@c @item -o @var{file} +@c @itemx --output @var{file} +@c Use @var{file} as output file. + +@item -v +@itemx --verbose +Outputs additional information while running. Specifically, this +extends numerical field values by human-readable descriptions. + +@c FIXME: Not yet supported. +@c @item -n +@c @itemx --dry-run +@c Do not actually change anything. Useful together with +@c @code{--change-options} 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. +@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 occurences 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 localised +Some fields contain strings that are described to be @emph{localised}. +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 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 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. +@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? + + +@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 programs 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 argument @code{--list-components} lists all available +components, one per line. The format of each line is: + +@code{@var{name}:@var{description}} + +@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}. +@end table + +Example: +@example +$ gpgconf --list-components +gpg:GPG for OpenPGP +gpg-agent:GPG Agent +scdaemon:Smartcard Daemon +gpgsm:GPG for S/MIME +dirmngr:Directory Manager +@end example + + +@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 argument @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. + +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. +@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}} +@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{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. + +@item default +This field is defined only for options. Its format is that of an +@emph{option argument} (@xref{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. + +@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} (@xref{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{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. + +@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 +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. +@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 + +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.