2004-09-30 Marcus Brinkmann <marcus@g10code.de>
[gnupg.git] / doc / tools.texi
1 @c Copyright (C) 2004 Free Software Foundation, Inc.
2 @c This is part of the GnuPG manual.
3 @c For copying conditions, see the file GnuPG.texi.
4
5 @node Helper Tools
6 @chapter Helper Tools
7
8 GnuPG comes with a couple of smaller tools:
9
10 @menu
11 * watchgnupg::            Read logs from a socket.
12 * addgnupghome::          Create .gnupg home directories.
13 * gpgconf::               Modify .gnupg home directories.
14 @end menu
15
16
17 @node watchgnupg
18 @section Read logs from a socket
19
20 Most of the main utilities are able to write there log files to a
21 Unix Domain socket if configured that way.  watchgnupg is a simple
22 listener for such a socket.  It ameliorates the output with a time
23 stamp and makes sure that long lines are not interspersed with log
24 output from other utilities.
25
26 @noindent
27 watchgnupg is commonly invoked as
28
29 @samp{watchgnupg --force ~/.gnupg/S.log}
30
31 @noindent
32 This starts it on the current terminal for listening on the socket
33 @file{~/.gnupg/S.log}.  
34
35 @noindent
36 watchgnupg understands these options:
37
38 @table @gnupgtabopt
39
40 @item --force 
41 @opindex force
42 Delete an already existing socket file.
43
44 @item --verbose
45 @opindex verbose
46 Enable extra informational output.
47
48 @item --version
49 @opindex version
50 print version of the program and exit
51
52 @item --help
53 @opindex help
54 Display a brief help page and exit
55
56 @end table
57
58
59
60 @node addgnupghome
61 @section Create .gnupg home directories.
62
63 If GnuPG is installed on a system with existing user accounts, it is
64 sometimes required to populate the GnuPG home directory with existing
65 files.  Especially a @file{trustlist.txt} and a keybox with some
66 initial certificates are often desired.  This scripts help to do this
67 by copying all files from @file{/etc/skel/.gnupg} to the home
68 directories of the accounts given on the command line.  It takes care
69 not to overwrite existing GnuPG home directories.
70
71 @noindent
72 addgnupghome is invoked by root as:
73
74 @samp{addgnupghome account1 account2 ... accountn}
75
76
77 @node gpgconf
78 @section Modify .gnupg home directories.
79
80 The @command{gpgconf} is a utility to automatically and reasonable
81 safely query and modify configuration files in the @file{.gnupg} home
82 directory.  It is designed not to be invoked manually by the user, but
83 automatically by graphical user interfaces (GUI).@footnote{Please note
84 that currently no locking is done, so concurrent access should be
85 avoided.  There are some precautions to avoid corruption with
86 concurrent usage, but results may be inconsistent and some changes may
87 get lost.  The stateless design makes it difficult to provide more
88 guarantees.}
89
90 @command{gpgconf} provides access to the configuration of one or more
91 components of the GnuPG system.  These components correspond more or
92 less to the programs that exist in the GnuPG framework, like GnuPG,
93 GPGSM, DirMngr, etc.  But this is not a strict one-to-one
94 relationship.  Not all configuration options are available through
95 @command{gpgconf}.  @command{gpgconf} provides a generic and abstract
96 method to access the most important configuration options that can
97 feasibly be controlled via such a mechanism.
98
99 @command{gpgconf} can be used to gather and change the options
100 available in each component, and can also provide their default
101 values.  @command{gpgconf} will give detailed type information that
102 can be used to restrict the user's input without making an attempt to
103 commit the changes.
104
105 @command{gpgconf} provides the backend of a configuration editor.  The
106 configuration editor would usually be a graphical user interface
107 program, that allows to display the current options, their default
108 values, and allows the user to make changes to the options.  These
109 changes can then be made active with @command{gpgconf} again.  Such a
110 program that uses @command{gpgconf} in this way will be called GUI
111 throughout this section.
112
113 @menu
114 * Invoking gpgconf::      List of all commands and options.
115 * Format conventions::    Formatting conventions relevant for all commands.
116 * Listing components::    List all gpgconf components.
117 * Listing options::       List all options of a component.
118 * Changing options::      Changing options of a component.
119 @end menu
120
121
122 @node Invoking gpgconf
123 @subsection Invoking gpgconf
124
125 One of the following commands must be given:
126
127 @table @gnupgtabopt
128 @item --list-components
129 List all components.  This is the default command used if none is
130 specified.
131
132 @item --list-options @var{component}
133 List all options of the component @var{component}.
134
135 @item --change-options @var{component}
136 Change the options of the component @var{component}.
137 @end table
138
139 The following options may be used:
140
141 @table @gnupgtabopt
142 @c FIXME: Not yet supported.
143 @c @item -o @var{file}
144 @c @itemx --output @var{file}
145 @c Use @var{file} as output file.
146
147 @item -v
148 @itemx --verbose
149 Outputs additional information while running.  Specifically, this
150 extends numerical field values by human-readable descriptions.
151
152 @c FIXME: Not yet supported.
153 @c @item -n
154 @c @itemx --dry-run
155 @c Do not actually change anything.  Useful together with
156 @c @code{--change-options} for testing purposes.
157
158 @item -r
159 @itemx --runtime
160 Only used together with @code{--change-options}.  If one of the
161 modified options can be changed in a running daemon process, signal
162 the running daemon to ask it to reparse its configuration file after
163 changing.
164
165 This means that the changes will take effect at run-time, as far as
166 this is possible.  Otherwise, they will take effect at the next start
167 of the respective backend programs.
168 @end table
169
170
171 @node Format conventions
172 @subsection Format conventions
173
174 Some lines in the output of @command{gpgconf} contain a list of
175 colon-separated fields.  The following conventions apply:
176
177 @itemize @bullet
178 @item
179 The GUI program is required to strip off trailing newline and/or
180 carriage return characters from the output.
181
182 @item
183 @command{gpgconf} will never leave out fields.  If a certain version
184 provides a certain field, this field will always be present in all
185 @command{gpgconf} versions from that time on.
186
187 @item
188 Future versions of @command{gpgconf} might append fields to the list.
189 New fields will always be separated from the previously last field by
190 a colon separator.  The GUI should be prepared to parse the last field
191 it knows about up until a colon or end of line.
192
193 @item
194 Not all fields are defined under all conditions.  You are required to
195 ignore the content of undefined fields.
196 @end itemize
197
198 There are several standard types for the content of a field:
199
200 @table @asis
201 @item verbatim
202 Some fields contain strings that are not escaped in any way.  Such
203 fields are described to be used @emph{verbatim}.  These fields will
204 never contain a colon character (for obvious reasons).  No de-escaping
205 or other formatting is required to use the field content.  This is for
206 easy parsing of the output, when it is known that the content can
207 never contain any special characters.
208
209 @item percent-escaped
210 Some fields contain strings that are described to be
211 @emph{percent-escaped}.  Such strings need to be de-escaped before
212 their content can be presented to the user.  A percent-escaped string
213 is de-escaped by replacing all occurences of @code{%XY} by the byte
214 that has the hexadecimal value @code{XY}.  @code{X} and @code{Y} are
215 from the set @code{0-9a-f}.
216
217 @item localised
218 Some fields contain strings that are described to be @emph{localised}.
219 Such strings are translated to the active language and formatted in
220 the active character set.
221
222 @item @w{unsigned number}
223 Some fields contain an @emph{unsigned number}.  This number will
224 always fit into a 32-bit unsigned integer variable.  The number may be
225 followed by a space, followed by a human readable description of that
226 value (if the verbose option is used).  You should ignore everything
227 in the field that follows the number.
228
229 @item @w{signed number}
230 Some fields contain a @emph{signed number}.  This number will always
231 fit into a 32-bit signed integer variable.  The number may be followed
232 by a space, followed by a human readable description of that value (if
233 the verbose option is used).  You should ignore everything in the
234 field that follows the number.
235
236 @item option
237 Some fields contain an @emph{option} argument.  The format of an
238 option argument depends on the type of the option and on some flags:
239
240 @table @asis
241 @item no argument
242 The simplest case is that the option does not take an argument at all
243 (@var{type} @code{0}).  Then the option argument is an unsigned number
244 that specifies how often the option occurs.  If the @code{list} flag
245 is not set, then the only valid number is @code{1}.  Options that do
246 not take an argument never have the @code{default} or @code{optional
247 arg} flag set.
248
249 @item number
250 If the option takes a number argument (@var{alt-type} is @code{2} or
251 @code{3}), and it can only occur once (@code{list} flag is not set),
252 then the option argument is either empty (only allowed if the argument
253 is optional), or it is a number.  A number is a string that begins
254 with an optional minus character, followed by one or more digits.  The
255 number must fit into an integer variable (unsigned or signed,
256 depending on @var{alt-type}).
257
258 @item number list
259 If the option takes a number argument and it can occur more than once,
260 then the option argument is either empty, or it is a comma-separated
261 list of numbers as described above.
262
263 @item string
264 If the option takes a string argument (@var{alt-type} is 1), and it
265 can only occur once (@code{list} flag is not set) then the option
266 argument is either empty (only allowed if the argument is optional),
267 or it starts with a double quote character (@code{"}) followed by a
268 percent-escaped string that is the argument value.  Note that there is
269 only a leading double quote character, no trailing one.  The double
270 quote character is only needed to be able to differentiate between no
271 value and the empty string as value.
272
273 @item string list
274 If the option takes a number argument and it can occur more than once,
275 then the option argument is either empty, or it is a comma-separated
276 list of string arguments as described above.
277 @end table
278 @end table
279
280 The active language and character set are currently determined from
281 the locale environment of the @command{gpgconf} program.
282
283 @c FIXME: Document the active language and active character set.  Allow
284 @c to change it via the command line?
285
286
287 @node Listing components
288 @subsection Listing components
289
290 The command @code{--list-components} will list all components that can
291 be configured with @command{gpgconf}.  Usually, one component will
292 correspond to one GnuPG-related program and contain the options of
293 that programs configuration file that can be modified using
294 @command{gpgconf}.  However, this is not necessarily the case.  A
295 component might also be a group of selected options from several
296 programs, or contain entirely virtual options that have a special
297 effect rather than changing exactly one option in one configuration
298 file.
299
300 A component is a set of configuration options that semantically belong
301 together.  Furthermore, several changes to a component can be made in
302 an atomic way with a single operation.  The GUI could for example
303 provide a menu with one entry for each component, or a window with one
304 tabulator sheet per component.
305
306 The command argument @code{--list-components} lists all available
307 components, one per line.  The format of each line is:
308
309 @code{@var{name}:@var{description}}
310
311 @table @var
312 @item name
313 This field contains a name tag of the component.  The name tag is used
314 to specify the component in all communication with @command{gpgconf}.
315 The name tag is to be used @emph{verbatim}.  It is thus not in any
316 escaped format.
317
318 @item description
319 The @emph{string} in this field contains a human-readable description
320 of the component.  It can be displayed to the user of the GUI for
321 informational purposes.  It is @emph{percent-escaped} and
322 @emph{localized}.
323 @end table
324
325 Example:
326 @example
327 $ gpgconf --list-components
328 gpg:GPG for OpenPGP
329 gpg-agent:GPG Agent
330 scdaemon:Smartcard Daemon
331 gpgsm:GPG for S/MIME
332 dirmngr:Directory Manager
333 @end example
334
335
336 @node Listing options
337 @subsection Listing options
338
339 Every component contains one or more options.  Options may be gathered
340 into option groups to allow the GUI to give visual hints to the user
341 about which options are related.
342
343 The command argument @code{@w{--list-options @var{component}}} lists
344 all options (and the groups they belong to) in the component
345 @var{component}, one per line.  @var{component} must be the string in
346 the field @var{name} in the output of the @code{--list-components}
347 command.
348
349 There is one line for each option and each group.  First come all
350 options that are not in any group.  Then comes a line describing a
351 group.  Then come all options that belong into each group.  Then comes
352 the next group and so on.  There does not need to be any group (and in
353 this case the output will stop after the last non-grouped option).
354
355 The format of each line is:
356
357 @code{@var{name}:@var{flags}:@var{level}:@var{description}:@var{type}:@var{alt-type}:@var{argname}:@var{default}:@var{argdef}:@var{value}}
358
359 @table @var
360 @item name
361 This field contains a name tag for the group or option.  The name tag
362 is used to specify the group or option in all communication with
363 @command{gpgconf}.  The name tag is to be used @emph{verbatim}.  It is
364 thus not in any escaped format.
365
366 @item flags
367 The flags field contains an @emph{unsigned number}.  Its value is the
368 OR-wise combination of the following flag values:
369
370 @table @code
371 @item group (1)
372 If this flag is set, this is a line describing a group and not an
373 option.
374 @end table
375
376 The following flag values are only defined for options (that is, if
377 the @code{group} flag is not used).
378
379 @table @code
380 @item optional arg (2)
381 If this flag is set, the argument is optional.  This is never set for
382 @var{type} @code{0} (none) options.
383
384 @item list (4)
385 If this flag is set, the option can be given multiple times.
386
387 @item runtime (8)
388 If this flag is set, the option can be changed at runtime.
389
390 @item default (16)
391 If this flag is set, a default value is available.
392
393 @item default desc (32)
394 If this flag is set, a (runtime) default is available.  This and the
395 @code{default} flag are mutually exclusive.
396
397 @item no arg desc (64)
398 If this flag is set, and the @code{optional arg} flag is set, then the
399 option has a special meaning if no argument is given.
400 @end table
401
402 @item level
403 This field is defined for options and for groups.  It contains an
404 @emph{unsigned number} that specifies the expert level under which
405 this group or option should be displayed.  The following expert levels
406 are defined for options (they have analogous meaning for groups):
407
408 @table @code
409 @item basic (0)
410 This option should always be offered to the user.
411
412 @item advanced (1)
413 This option may be offered to advanced users.
414
415 @item expert (2)
416 This option should only be offered to expert users.
417
418 @item invisible (3)
419 This option should normally never be displayed, not even to expert
420 users.
421
422 @item internal (4)
423 This option is for internal use only.  Ignore it.
424 @end table
425
426 The level of a group will always be the lowest level of all options it
427 contains.
428
429 @item description
430 This field is defined for options and groups.  The @emph{string} in
431 this field contains a human-readable description of the option or
432 group.  It can be displayed to the user of the GUI for informational
433 purposes.  It is @emph{percent-escaped} and @emph{localized}.
434
435 @item type
436 This field is only defined for options.  It contains an @emph{unsigned
437 number} that specifies the type of the option's argument, if any.  The
438 following types are defined:
439
440 Basic types:
441
442 @table @code
443 @item none (0)
444 No argument allowed.
445
446 @item string (1)
447 An @emph{unformatted string}.
448
449 @item int32 (2)
450 A @emph{signed number}.
451
452 @item uint32 (3)
453 An @emph{unsigned number}.
454 @end table
455
456 Complex types:
457
458 @table @code
459 @item pathname (32)
460 A @emph{string} that describes the pathname of a file.  The file does
461 not necessarily need to exist.
462
463 @item ldap server (33)
464 A @emph{string} that describes an LDAP server in the format:
465
466 @code{@var{hostname}:@var{port}:@var{username}:@var{password}:@var{base_dn}}
467 @end table
468
469 More types will be added in the future.  Please see the @var{alt-type}
470 field for information on how to cope with unknown types.
471
472 @item alt-type
473 This field is identical to @var{type}, except that only the types
474 @code{0} to @code{31} are allowed.  The GUI is expected to present the
475 user the option in the format specified by @var{type}.  But if the
476 argument type @var{type} is not supported by the GUI, it can still
477 display the option in the more generic basic type @var{alt-type}.  The
478 GUI must support all the defined basic types to be able to display all
479 options.  More basic types may be added in future versions.  If the
480 GUI encounters a basic type it doesn't support, it should report an
481 error and abort the operation.
482
483 @item argname
484 This field is only defined for options with an argument type
485 @var{type} that is not @code{0}.  In this case it may contain a
486 @emph{percent-escaped} and @emph{localised string} that gives a short
487 name for the argument.  The field may also be empty, though, in which
488 case a short name is not known.
489
490 @item default
491 This field is defined only for options.  Its format is that of an
492 @emph{option argument} (@xref{Format conventions}, for details).  If
493 the default value is empty, then no default is known.  Otherwise, the
494 value specifies the default value for this option.  Note that this
495 field is also meaningful if the option itself does not take a real
496 argument.
497
498 @item argdef
499 This field is defined only for options for which the @code{optional
500 arg} flag is set.  If the @code{no arg desc} flag is not set, its
501 format is that of an @emph{option argument} (@xref{Format
502 conventions}, for details).  If the default value is empty, then no
503 default is known.  Otherwise, the value specifies the default value
504 for this option.  If the @code{no arg desc} flag is set, the field is
505 either empty or contains a description of the effect of this option if
506 no argument is given.  Note that this field is also meaningful if the
507 option itself does not take a real argument.
508
509 @item value
510 This field is defined only for options.  Its format is that of an
511 @emph{option argument}.  If it is empty, then the option is not
512 explicitely set in the current configuration, and the default applies
513 (if any).  Otherwise, it contains the current value of the option.
514 Note that this field is also meaningful if the option itself does not
515 take a real argument.
516 @end table
517
518
519 @node Changing options
520 @subsection Changing options
521
522 The command @w{@code{--change-options @var{component}}} will attempt
523 to change the options of the component @var{component} to the
524 specified values.  @var{component} must be the string in the field
525 @var{name} in the output of the @code{--list-components} command.  You
526 have to provide the options that shall be changed in the following
527 format on standard input:
528
529 @code{@var{name}:@var{flags}:@var{new-value}}
530
531 @table @var
532 @item name
533 This is the name of the option to change.  @var{name} must be the
534 string in the field @var{name} in the output of the
535 @code{--list-options} command.
536
537 @item flags
538 The flags field contains an @emph{unsigned number}.  Its value is the
539 OR-wise combination of the following flag values:
540
541 @table @code
542 @item default (16)
543 If this flag is set, the option is deleted and the default value is
544 used instead (if applicable).
545 @end table
546
547 @item new-value
548 The new value for the option.  This field is only defined if the
549 @code{default} flag is not set.  The format is that of an @emph{option
550 argument}.  If it is empty (or the field is omitted), the default
551 argument is used (only allowed if the argument is optional for this
552 option).  Otherwise, the option will be set to the specified value.
553 @end table
554
555 Examples:
556
557 To set the force option, which is of basic type @code{none (0)}:
558
559 @example
560 $ echo 'force:0:1' | gpgconf --change-options dirmngr
561 @end example
562
563 To delete the force option:
564
565 @example
566 $ echo 'force:16:' | gpgconf --change-options dirmngr
567 @end example
568
569 The @code{--runtime} option can influence when the changes take
570 effect.