1GPGCONF(1)                     GNU Privacy Guard                    GPGCONF(1)
2
3
4

NAME

6       gpgconf - Modify .gnupg home directories
7

SYNOPSIS

9       gpgconf [options] --list-components
10       gpgconf [options] --list-options component
11       gpgconf [options] --change-options component
12
13
14

DESCRIPTION

16       The  gpgconf  is a utility to automatically and reasonable safely query
17       and modify configuration files in the ‘.gnupg’ home directory.   It  is
18       designed  not  to be invoked manually by the user, but automatically by
19       graphical user interfaces (GUI). ([Please note that currently no  lock‐
20       ing  is  done,  so concurrent access should be avoided.  There are some
21       precautions to avoid corruption with concurrent usage, but results  may
22       be  inconsistent  and  some changes may get lost.  The stateless design
23       makes it difficult to provide more guarantees.])
24
25       gpgconf provides access to the configuration of one or more  components
26       of  the  GnuPG system.  These components correspond more or less to the
27       programs that exist in the GnuPG framework, like GnuPG, GPGSM, DirMngr,
28       etc.   But  this is not a strict one-to-one relationship.  Not all con‐
29       figuration options are available through gpgconf.  gpgconf  provides  a
30       generic  and abstract method to access the most important configuration
31       options that can feasibly be controlled via such a mechanism.
32
33       gpgconf can be used to gather and change the options available in  each
34       component,  and  can  also  provide their default values.  gpgconf will
35       give detailed type information that can be used to restrict the  user's
36       input without making an attempt to commit the changes.
37
38       gpgconf provides the backend of a configuration editor.  The configura‐
39       tion editor would usually be a graphical user interface  program,  that
40       allows to display the current options, their default values, and allows
41       the user to make changes to the options.  These  changes  can  then  be
42       made  active  with  gpgconf again.  Such a program that uses gpgconf in
43       this way will be called GUI throughout this section.
44
45
46

COMMANDS

48       One of the following commands must be given:
49
50
51
52       --list-components
53              List all components.  This is the default command used  if  none
54              is specified.
55
56
57       --check-programs
58              List  all  available  backend programs and test whether they are
59              runnable.
60
61
62       --list-options component
63              List all options of the component component.
64
65
66       --change-options component
67              Change the options of the component component.
68
69
70       --check-options component
71              Check the options for the component component.
72
73
74       --apply-defaults
75              Update all configuration files with values taken from the global
76              configuration file (usually ‘/etc/gnupg/gpgconf.conf’).
77
78
79       --list-dirs
80              Lists  the directories used by gpgconf.  One directory is listed
81              per line, and each line consists of a colon-separated list where
82              the   first   field   names  the  directory  type  (for  example
83              sysconfdir) and the second field  contains  the  percent-escaped
84              directory.   Although  they are not directories, the socket file
85              names used by gpg-agent and dirmngr are printed as  well.   Note
86              that the socket file names and the homedir lines are the default
87              names and they may be overridden by command line switches.
88
89
90       --list-config [filename]
91              List the global configuration file in a colon separated  format.
92              If filename is given, check that file instead.
93
94
95       --check-config [filename]
96              Run  a  syntax check on the global configuration file.  If file‐
97              name is given, check that file instead.
98
99
100       --reload [component]
101              Reload all or the given component. This is basically the same as
102              sending  a SIGHUP to the component.  Components which don't sup‐
103              port reloading are ignored.
104
105
106       --kill [component]
107              Kill the given component.  Components which support killing  are
108              gpg-agent  and scdaemon.  Components which don't support reload‐
109              ing are ignored.  Note that as of now reload and kill  have  the
110              same effect for scdaemon.
111
112
113
114

OPTIONS

116       The following options may be used:
117
118
119
120       -v
121
122       --verbose
123              Outputs  additional  information  while  running.  Specifically,
124              this extends numerical field values by  human-readable  descrip‐
125              tions.
126
127
128       -n
129
130       --dry-run
131              Do  not actually change anything.  This is currently only imple‐
132              mented for --change-options and can be  used  for  testing  pur‐
133              poses.
134
135
136       -r
137
138       --runtime
139              Only  used  together with --change-options.  If one of the modi‐
140              fied options can be changed in a running daemon process,  signal
141              the  running  daemon to ask it to reparse its configuration file
142              after changing.
143
144              This means that the changes will take effect at run-time, as far
145              as  this  is  possible.  Otherwise, they will take effect at the
146              next start of the respective backend programs.
147

USAGE

149       The command --list-components will list all components that can be con‐
150       figured  with  gpgconf.   Usually, one component will correspond to one
151       GnuPG-related program and contain the options of that programs configu‐
152       ration  file  that can be modified using gpgconf.  However, this is not
153       necessarily the case.  A component might also be a  group  of  selected
154       options from several programs, or contain entirely virtual options that
155       have a special effect rather than changing exactly one  option  in  one
156       configuration file.
157
158       A  component is a set of configuration options that semantically belong
159       together.  Furthermore, several changes to a component can be  made  in
160       an  atomic way with a single operation.  The GUI could for example pro‐
161       vide a menu with one entry for each component, or  a  window  with  one
162       tabulator sheet per component.
163
164       The  command argument --list-components lists all available components,
165       one per line.  The format of each line is:
166
167       name:description:pgmname:
168
169
170       name   This field contains a name tag of the component.  The  name  tag
171              is  used to specify the component in all communication with gpg‐
172              conf.  The name tag is to be used verbatim.  It is thus  not  in
173              any escaped format.
174
175
176       description
177              The  string  in this field contains a human-readable description
178              of the component.  It can be displayed to the user  of  the  GUI
179              for  informational  purposes.   It is percent-escaped and local‐
180              ized.
181
182
183       pgmname
184              The string in this field contains the absolute name of the  pro‐
185              gram's  file.   It can be used to unambiguously invoke that pro‐
186              gram.  It is percent-escaped.
187
188              Example:
189         $ gpgconf --list-components
190         gpg:GPG for OpenPGP:/usr/local/bin/gpg2:
191         gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:
192         scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:
193         gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:
194         dirmngr:Directory Manager:/usr/local/bin/dirmngr:
195
196
197
198
199
200   Checking programs
201
202
203       The command --check-programs is similar to --list-components but  works
204       on  backend  programs  and  not on components.  It runs each program to
205       test whether it is installed and runnable.  This also includes a syntax
206       check of all config file options of the program.
207
208       The command argument --check-programs lists all available programs, one
209       per line.  The format of each line is:
210
211       name:description:pgmname:avail:okay:cfgfile:line:error:
212
213
214       name   This field contains a name tag of the program which is identical
215              to the name of the component.  The name tag is to be used verba‐
216              tim.  It is thus not in any escaped format.  This field  may  be
217              empty  to  indicate a continuation of error descriptions for the
218              last name.  The description and pgmname  fields  are  then  also
219              empty.
220
221
222       description
223              The  string  in this field contains a human-readable description
224              of the component.  It can be displayed to the user  of  the  GUI
225              for  informational  purposes.   It is percent-escaped and local‐
226              ized.
227
228
229       pgmname
230              The string in this field contains the absolute name of the  pro‐
231              gram's  file.   It can be used to unambiguously invoke that pro‐
232              gram.  It is percent-escaped.
233
234
235       avail  The boolean value in this field indicates whether the program is
236              installed and runnable.
237
238
239       okay   The  boolean value in this field indicates whether the program's
240              config file is syntactically okay.
241
242
243       cfgfile
244              If an error occurred in the configuration file (as indicated  by
245              a false value in the field okay), this field has the name of the
246              failing configuration file.  It is percent-escaped.
247
248
249       line   If an error occurred in the configuration file, this  field  has
250              the  line  number  of the failing statement in the configuration
251              file.  It is an unsigned number.
252
253
254       error  If an error occurred in the configuration file, this  field  has
255              the  error  text  of  the failing statement in the configuration
256              file.  It is percent-escaped and localized.
257
258
259
260              In the following example the dirmngr is  not  runnable  and  the
261              configuration file of scdaemon is not okay.
262
263         $ gpgconf --check-programs
264         gpg:GPG for OpenPGP:/usr/local/bin/gpg2:1:1:
265         gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:1:1:
266         scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:1:0:
267         gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:1:1:
268         dirmngr:Directory Manager:/usr/local/bin/dirmngr:0:0:
269
270
271       The  command configuration file in the same manner as --check-programs,
272       but only for the component component.
273
274
275
276
277   Listing options
278
279
280       Every component contains one or more options.  Options may be  gathered
281       into  option  groups  to allow the GUI to give visual hints to the user
282       about which options are related.
283
284       The command argument  lists all options (and the groups they belong to)
285       in the component component, one per line.  component must be the string
286       in the field name in the output of the --list-components command.
287
288       There is one line for each option  and  each  group.   First  come  all
289       options  that  are  not  in  any group.  Then comes a line describing a
290       group.  Then come all options that belong into each group.  Then  comes
291       the  next group and so on.  There does not need to be any group (and in
292       this case the output will stop after the last non-grouped option).
293
294       The format of each line is:
295
296       name:flags:level:description:type:alt-type:argname:default:argdef:value
297
298
299       name   This field contains a name tag for the  group  or  option.   The
300              name  tag is used to specify the group or option in all communi‐
301              cation with gpgconf.  The name tag is to be used  verbatim.   It
302              is thus not in any escaped format.
303
304
305       flags  The  flags  field contains an unsigned number.  Its value is the
306              OR-wise combination of the following flag values:
307
308
309              group (1)
310                     If this flag is set, this is a line  describing  a  group
311                     and not an option.
312
313       The following flag values are only defined for options (that is, if the
314       group flag is not used).
315
316
317              optional arg (2)
318                     If this flag is set, the argument is optional.   This  is
319                     never set for type 0 (none) options.
320
321
322              list (4)
323                     If  this  flag  is  set, the option can be given multiple
324                     times.
325
326
327              runtime (8)
328                     If this flag is set, the option can be  changed  at  run‐
329                     time.
330
331
332              default (16)
333                     If this flag is set, a default value is available.
334
335
336              default desc (32)
337                     If  this  flag  is set, a (runtime) default is available.
338                     This and the default flag are mutually exclusive.
339
340
341              no arg desc (64)
342                     If this flag is set, and the optional arg  flag  is  set,
343                     then  the  option has a special meaning if no argument is
344                     given.
345
346
347              no change (128)
348                     If this flag is set, gpgconf ignores requests  to  change
349                     the  value.   GUI  frontends should grey out this option.
350                     Note, that manual changes of the configuration files  are
351                     still possible.
352
353
354       level  This  field  is defined for options and for groups.  It contains
355              an unsigned number that specifies the expert level  under  which
356              this  group or option should be displayed.  The following expert
357              levels are defined for options (they have analogous meaning  for
358              groups):
359
360
361              basic (0)
362                     This option should always be offered to the user.
363
364
365              advanced (1)
366                     This option may be offered to advanced users.
367
368
369              expert (2)
370                     This option should only be offered to expert users.
371
372
373              invisible (3)
374                     This  option should normally never be displayed, not even
375                     to expert users.
376
377
378              internal (4)
379                     This option is for internal use only.  Ignore it.
380
381       The level of a group will always be the lowest level of all options  it
382       contains.
383
384
385       description
386              This  field  is  defined  for options and groups.  The string in
387              this field contains a human-readable description of  the  option
388              or group.  It can be displayed to the user of the GUI for infor‐
389              mational purposes.  It is percent-escaped and localized.
390
391
392       type   This field is only defined for options.  It contains an unsigned
393              number that specifies the type of the option's argument, if any.
394              The following types are defined:
395
396              Basic types:
397
398
399              none (0)
400                     No argument allowed.
401
402
403              string (1)
404                     An unformatted string.
405
406
407              int32 (2)
408                     A signed number.
409
410
411              uint32 (3)
412                     An unsigned number.
413
414       Complex types:
415
416
417              pathname (32)
418                     A string that describes the pathname of a file.  The file
419                     does not necessarily need to exist.
420
421
422              ldap server (33)
423                     A string that describes an LDAP server in the format:
424
425                     hostname:port:username:password:base_dn
426
427
428              key fingerprint (34)
429                     A  string  with  a 40 digit fingerprint specifying a cer‐
430                     tificate.
431
432
433              pub key (35)
434                     A string that describes a certificate by user ID, key  ID
435                     or fingerprint.
436
437
438              sec key (36)
439                     A  string that describes a certificate with a key by user
440                     ID, key ID or fingerprint.
441
442
443              alias list (37)
444                     A string that describes an alias list, like the one  used
445                     with  gpg's group option.  The list consists of a key, an
446                     equal sign and space separated values.
447
448       More types will be added in the future.  Please see the alt-type  field
449       for information on how to cope with unknown types.
450
451
452       alt-type
453              This field is identical to type, except that only the types 0 to
454              31 are allowed.  The GUI is expected to  present  the  user  the
455              option  in  the  format  specified by type.  But if the argument
456              type type is not supported by the GUI, it can still display  the
457              option  in  the  more generic basic type alt-type.  The GUI must
458              support all the defined basic types to be able  to  display  all
459              options.   More basic types may be added in future versions.  If
460              the GUI encounters a basic type it doesn't  support,  it  should
461              report an error and abort the operation.
462
463
464       argname
465              This  field  is  only  defined for options with an argument type
466              type that is not 0.  In this case  it  may  contain  a  percent-
467              escaped  and  localised  string  that gives a short name for the
468              argument.  The field may also be empty, though, in which case  a
469              short name is not known.
470
471
472       default
473              This  field is defined only for options for which the default or
474              default desc flag is set.  If the default flag is set, its  for‐
475              mat  is  that  of an option argument (see: [Format conventions],
476              for details).  If the default value is empty, then no default is
477              known.   Otherwise,  the  value  specifies the default value for
478              this option.  If the default desc flag  is  set,  the  field  is
479              either  empty  or  contains  a  description of the effect if the
480              option is not given.
481
482
483       argdef This field is defined only for options for  which  the  optional
484              arg flag is set.  If the no arg desc flag is not set, its format
485              is that of an option argument (see:  [Format  conventions],  for
486              details).   If  the  default  value is empty, then no default is
487              known.  Otherwise, the value specifies the default argument  for
488              this  option.   If  the  no  arg  desc flag is set, the field is
489              either empty or contains a description of  the  effect  of  this
490              option if no argument is given.
491
492
493       value  This  field  is defined only for options.  Its format is that of
494              an option argument.  If it is empty,  then  the  option  is  not
495              explicitly  set  in  the  current configuration, and the default
496              applies (if any).  Otherwise, it contains the current  value  of
497              the  option.   Note  that  this  field is also meaningful if the
498              option itself does not take a real argument (in  this  case,  it
499              contains the number of times the option appears).
500
501
502
503
504   Changing options
505
506
507       The  command  to  change  the options of the component component to the
508       specified values.  component must be the string in the  field  name  in
509       the  output  of the --list-components command.  You have to provide the
510       options that shall be changed  in  the  following  format  on  standard
511       input:
512
513       name:flags:new-value
514
515
516       name   This  is  the  name  of  the option to change.  name must be the
517              string in the field name in the  output  of  the  --list-options
518              command.
519
520
521       flags  The  flags  field contains an unsigned number.  Its value is the
522              OR-wise combination of the following flag values:
523
524
525              default (16)
526                     If this flag is  set,  the  option  is  deleted  and  the
527                     default value is used instead (if applicable).
528
529
530       new-value
531              The new value for the option.  This field is only defined if the
532              default flag is not set.  The format is that of an option  argu‐
533              ment.   If  it  is  empty (or the field is omitted), the default
534              argument is used (only allowed if the argument is  optional  for
535              this  option).   Otherwise, the option will be set to the speci‐
536              fied value.
537
538
539              The output of the command is the same as that of --check-options
540              for the modified configuration file.
541
542              Examples:
543
544              To set the force option, which is of basic type none (0):
545
546         $ echo 'force:0:1' | gpgconf --change-options dirmngr
547
548       To delete the force option:
549
550         $ echo 'force:16:' | gpgconf --change-options dirmngr
551
552       The --runtime option can influence when the changes take effect.
553
554
555
556
557   Listing global options
558
559
560       Sometimes  it  is useful for applications to look at the global options
561       file ‘gpgconf.conf’.  The colon separated listing format is record ori‐
562       ented and uses the first field to identify the record type:
563
564
565       k      This  describes  a  key  record to start the definition of a new
566              ruleset for a user/group.  The format of a key record is:
567
568                k:user:group:
569
570
571              user   This is the  user  field  of  the  key.   It  is  percent
572                     escaped.   See  the definition of the gpgconf.conf format
573                     for details.
574
575
576              group  This is the group  field  of  the  key.   It  is  percent
577                     escaped.
578
579
580       r      This  describes  a  rule record. All rule records up to the next
581              key record make up a rule set for that key.   The  format  of  a
582              rule record is:
583
584                r:::component:option:flags:value:
585
586
587              component
588                     This  is  the  component  part  of a rule.  It is a plain
589                     string.
590
591
592              option This is the option part of a rule.  It is a plain string.
593
594
595              flag   This is the flags part of a rule.  There may be only  one
596                     flag per rule but by using the same component and option,
597                     several flags may be assigned to  an  option.   It  is  a
598                     plain string.
599
600
601              value  This  is the optional value for the option.  It is a per‐
602                     cent escaped string with a single quotation mark to indi‐
603                     cate  a  string.   The quotation mark is only required to
604                     distinguish between  no  value  specified  and  an  empty
605                     string.
606
607
608
609       Unknown  record types should be ignored.  Note that there is intention‐
610       ally no feature to change the global option file through gpgconf.
611
612
613
614

FILES

616       /etc/gnupg/gpgconf.conf
617                If this file exists, it is processed as a global configuration
618              file.
619                A  commented  example can be found in the ‘examples’ directory
620              of
621                the distribution.
622
623
624

SEE ALSO

626       gpg(1), gpgsm(1), gpg-agent(1), scdaemon(1), dirmngr(1)
627
628       The full documentation for this tool is maintained as a Texinfo manual.
629       If  GnuPG and the info program are properly installed at your site, the
630       command
631
632         info gnupg
633
634       should give you access to the complete manual including a  menu  struc‐
635       ture and an index.
636
637
638
639
640
641
642
643GnuPG 2.0.18                      2011-09-20                        GPGCONF(1)
Impressum