1GPGCONF(1)                   GNU Privacy Guard 2.2                  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 GPG,  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       displays the current options, their default values, and allows the user
41       to make changes to the options.  These changes can then be made  active
42       with  gpgconf again.  Such a program that uses gpgconf in this way will
43       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-profile file
75              Apply the configuration settings listed in file to the  configu‐
76              ration  files.  If file has no suffix and no slashes the command
77              first tries to read a file with the suffix .prf  from  the  data
78              directory (gpgconf --list-dirs datadir) before it reads the file
79              verbatim.  A profile is divided into sections using  the  brack‐
80              eted   component name.  Each section then lists the option which
81              shall go into the respective configuration file.
82
83
84       --apply-defaults
85              Update all configuration files with values taken from the global
86              configuration file (usually ‘/etc/gnupg/gpgconf.conf’).
87
88
89       --list-dirs [names]
90              Lists  the directories used by gpgconf.  One directory is listed
91              per line, and each line consists of a colon-separated list where
92              the   first   field   names  the  directory  type  (for  example
93              sysconfdir) and the second field  contains  the  percent-escaped
94              directory.   Although  they are not directories, the socket file
95              names used by gpg-agent and dirmngr are printed as  well.   Note
96              that the socket file names and the homedir lines are the default
97              names and they may be overridden by command line  switches.   If
98              names  are given only the directories or file names specified by
99              the list names are printed without any escaping.
100
101
102       --list-config [filename]
103              List the global configuration file in a colon separated  format.
104              If filename is given, check that file instead.
105
106
107       --check-config [filename]
108              Run  a  syntax check on the global configuration file.  If file‐
109              name is given, check that file instead.
110
111
112
113       --query-swdb package_name [version_string]
114              Returns  the  current  version  for  package_name  and  if  ver‐
115              sion_string  is  given also an indicator on whether an update is
116              available.  The actual file with the software version  is  auto‐
117              matically  downloaded  and  checked  by dirmngr.  dirmngr uses a
118              thresholds to avoid download the file too often and it does this
119              by  default  only if it can be done via Tor.  To force an update
120              of that file this command can be used:
121
122                gpg-connect-agent --dirmngr 'loadswdb --force' /bye
123
124
125
126       --reload [component]
127              Reload all or the given component. This is basically the same as
128              sending  a SIGHUP to the component.  Components which don't sup‐
129              port reloading are ignored.  Without component or by using "all"
130              for component all components which are daemons are reloaded.
131
132
133       --launch [component]
134              If  the  component  is not already running, start it.  component
135              must be a daemon.  This is in general not required  because  the
136              system  starts these daemons as needed.  However, external soft‐
137              ware making direct use of gpg-agent or dirmngr may use this com‐
138              mand to ensure that they are started.  Using "all" for component
139              launches all components which are daemons.
140
141
142       --kill [component]
143              Kill the given component that runs as a daemon,  including  gpg-
144              agent, dirmngr, and scdaemon.  A component which does not run as
145              a daemon will be ignored.  Using "all" for component  kills  all
146              components  running  as daemons.  Note that as of now reload and
147              kill have the same effect for scdaemon.
148
149
150       --create-socketdir
151              Create a directory for sockets below /run/user or /var/run/user.
152              This is command is only required if a non default home directory
153              is used and the /run based  sockets  shall  be  used.   For  the
154              default home directory GnUPG creates a directory on the fly.
155
156
157       --remove-socketdir
158              Remove a directory created with command --create-socketdir.
159
160

OPTIONS

162       The following options may be used:
163
164
165
166       -o file
167       --output file
168              Write output to file.  Default is to write to stdout.
169
170
171       -v
172       --verbose
173              Outputs  additional  information  while  running.  Specifically,
174              this extends numerical field values by  human-readable  descrip‐
175              tions.
176
177
178       -q
179       --quiet
180              Try to be as quiet as possible.
181
182
183       --homedir dir
184              Set the name of the home directory to dir. If this option is not
185              used, the home directory defaults to  ‘~/.gnupg’.   It  is  only
186              recognized  when  given  on the command line.  It also overrides
187              any home  directory  stated  through  the  environment  variable
188GNUPGHOME’  or  (on  Windows  systems) by means of the Registry
189              entry HKCU\Software\GNU\GnuPG:HomeDir.
190
191              On Windows systems it is possible to install GnuPG as a portable
192              application.  In this case only this command line option is con‐
193              sidered, all other ways to set a home directory are ignored.
194
195              To install GnuPG as a portable application under Windows, create
196              an  empty  file named ‘gpgconf.ctl’ in the same directory as the
197              tool ‘gpgconf.exe’.  The root of the installation is  then  that
198              directory;  or,  if  ‘gpgconf.exe’  has  been installed directly
199              below a directory named ‘bin’, its parent directory.   You  also
200              need  to  make sure that the following directories exist and are
201              writable:    ‘ROOT/home’    for    the    GnuPG     home     and
202ROOT/var/cache/gnupg’ for internal cache files.
203
204
205       -n
206       --dry-run
207              Do  not actually change anything.  This is currently only imple‐
208              mented for --change-options and can be  used  for  testing  pur‐
209              poses.
210
211
212       -r
213       --runtime
214              Only  used  together with --change-options.  If one of the modi‐
215              fied options can be changed in a running daemon process,  signal
216              the  running  daemon to ask it to reparse its configuration file
217              after changing.
218
219              This means that the changes will take effect at run-time, as far
220              as  this  is  possible.  Otherwise, they will take effect at the
221              next start of the respective backend programs.
222
223
224       --status-fd n
225              Write special status strings to the  file  descriptor  n.   This
226              program returns the status messages SUCCESS or FAILURE which are
227              helpful when the caller uses a double fork  approach  and  can't
228              easily get the return code of the process.
229
230

USAGE

232       The command --list-components will list all components that can be con‐
233       figured with gpgconf.  Usually, one component will  correspond  to  one
234       GnuPG-related program and contain the options of that program's config‐
235       uration file that can be modified using gpgconf.  However, this is  not
236       necessarily  the  case.   A component might also be a group of selected
237       options from several programs, or contain entirely virtual options that
238       have  a  special  effect rather than changing exactly one option in one
239       configuration file.
240
241       A component is a set of configuration options that semantically  belong
242       together.   Furthermore,  several changes to a component can be made in
243       an atomic way with a single operation.  The GUI could for example  pro‐
244       vide  a  menu  with  one entry for each component, or a window with one
245       tabulator sheet per component.
246
247       The command --list-components lists all available components,  one  per
248       line.  The format of each line is:
249
250       name:description:pgmname:
251
252
253       name   This  field  contains a name tag of the component.  The name tag
254              is used to specify the component in all communication with  gpg‐
255              conf.   The  name tag is to be used verbatim.  It is thus not in
256              any escaped format.
257
258
259       description
260              The string in this field contains a  human-readable  description
261              of  the  component.   It can be displayed to the user of the GUI
262              for informational purposes.  It is  percent-escaped  and  local‐
263              ized.
264
265
266       pgmname
267              The  string in this field contains the absolute name of the pro‐
268              gram's file.  It can be used to unambiguously invoke  that  pro‐
269              gram.  It is percent-escaped.
270
271       Example:
272         $ gpgconf --list-components
273         gpg:GPG for OpenPGP:/usr/local/bin/gpg2:
274         gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:
275         scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:
276         gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:
277         dirmngr:Directory Manager:/usr/local/bin/dirmngr:
278
279
280
281
282
283   Checking programs
284
285
286       The  command --check-programs is similar to --list-components but works
287       on backend programs and not on components.  It  runs  each  program  to
288       test whether it is installed and runnable.  This also includes a syntax
289       check of all config file options of the program.
290
291       The command --check-programs lists  all  available  programs,  one  per
292       line.  The format of each line is:
293
294       name:description:pgmname:avail:okay:cfgfile:line:error:
295
296
297       name   This field contains a name tag of the program which is identical
298              to the name of the component.  The name tag is to be used verba‐
299              tim.   It  is thus not in any escaped format.  This field may be
300              empty to indicate a continuation of error descriptions  for  the
301              last  name.   The  description  and pgmname fields are then also
302              empty.
303
304
305       description
306              The string in this field contains a  human-readable  description
307              of  the  component.   It can be displayed to the user of the GUI
308              for informational purposes.  It is  percent-escaped  and  local‐
309              ized.
310
311
312       pgmname
313              The  string in this field contains the absolute name of the pro‐
314              gram's file.  It can be used to unambiguously invoke  that  pro‐
315              gram.  It is percent-escaped.
316
317
318       avail  The boolean value in this field indicates whether the program is
319              installed and runnable.
320
321
322       okay   The boolean value in this field indicates whether the  program's
323              config file is syntactically okay.
324
325
326       cfgfile
327              If  an error occurred in the configuration file (as indicated by
328              a false value in the field okay), this field has the name of the
329              failing configuration file.  It is percent-escaped.
330
331
332       line   If  an  error occurred in the configuration file, this field has
333              the line number of the failing statement  in  the  configuration
334              file.  It is an unsigned number.
335
336
337       error  If  an  error occurred in the configuration file, this field has
338              the error text of the failing  statement  in  the  configuration
339              file.  It is percent-escaped and localized.
340
341
342       In the following example the dirmngr is not runnable and the configura‐
343       tion file of scdaemon is not okay.
344
345         $ gpgconf --check-programs
346         gpg:GPG for OpenPGP:/usr/local/bin/gpg2:1:1:
347         gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:1:1:
348         scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:1:0:
349         gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:1:1:
350         dirmngr:Directory Manager:/usr/local/bin/dirmngr:0:0:
351
352
353       The command configuration file in the same manner as  --check-programs,
354       but only for the component component.
355
356
357
358
359   Listing options
360
361
362       Every  component contains one or more options.  Options may be gathered
363       into option groups to allow the GUI to give visual hints  to  the  user
364       about which options are related.
365
366       The  command   lists all options (and the groups they belong to) in the
367       component component, one per line.  component must be the string in the
368       field name in the output of the --list-components command.
369
370       There  is  one  line  for  each  option and each group.  First come all
371       options that are not in any group.  Then  comes  a  line  describing  a
372       group.   Then come all options that belong into each group.  Then comes
373       the next group and so on.  There does not need to be any group (and  in
374       this case the output will stop after the last non-grouped option).
375
376       The format of each line is:
377
378       name:flags:level:description:type:alt-type:argname:default:argdef:value
379
380
381       name   This  field  contains  a  name tag for the group or option.  The
382              name tag is used to specify the group or option in all  communi‐
383              cation  with  gpgconf.  The name tag is to be used verbatim.  It
384              is thus not in any escaped format.
385
386
387       flags  The flags field contains an unsigned number.  Its value  is  the
388              OR-wise combination of the following flag values:
389
390
391              group (1)
392                     If  this  flag  is set, this is a line describing a group
393                     and not an option.
394
395       The following flag values are only defined for options (that is, if the
396       group flag is not used).
397
398
399              optional arg (2)
400                     If  this  flag is set, the argument is optional.  This is
401                     never set for type 0 (none) options.
402
403
404              list (4)
405                     If this flag is set, the option  can  be  given  multiple
406                     times.
407
408
409              runtime (8)
410                     If  this  flag  is set, the option can be changed at run‐
411                     time.
412
413
414              default (16)
415                     If this flag is set, a default value is available.
416
417
418              default desc (32)
419                     If this flag is set, a (runtime)  default  is  available.
420                     This and the default flag are mutually exclusive.
421
422
423              no arg desc (64)
424                     If  this  flag  is set, and the optional arg flag is set,
425                     then the option has a special meaning if no  argument  is
426                     given.
427
428
429              no change (128)
430                     If  this  flag is set, gpgconf ignores requests to change
431                     the value.  GUI frontends should grey  out  this  option.
432                     Note,  that manual changes of the configuration files are
433                     still possible.
434
435
436       level  This field is defined for options and for groups.   It  contains
437              an  unsigned  number that specifies the expert level under which
438              this group or option should be displayed.  The following  expert
439              levels  are defined for options (they have analogous meaning for
440              groups):
441
442
443              basic (0)
444                     This option should always be offered to the user.
445
446
447              advanced (1)
448                     This option may be offered to advanced users.
449
450
451              expert (2)
452                     This option should only be offered to expert users.
453
454
455              invisible (3)
456                     This option should normally never be displayed, not  even
457                     to expert users.
458
459
460              internal (4)
461                     This option is for internal use only.  Ignore it.
462
463       The  level of a group will always be the lowest level of all options it
464       contains.
465
466
467       description
468              This field is defined for options and  groups.   The  string  in
469              this  field  contains a human-readable description of the option
470              or group.  It can be displayed to the user of the GUI for infor‐
471              mational purposes.  It is percent-escaped and localized.
472
473
474       type   This field is only defined for options.  It contains an unsigned
475              number that specifies the type of the option's argument, if any.
476              The following types are defined:
477
478              Basic types:
479
480
481              none (0)
482                     No argument allowed.
483
484
485              string (1)
486                     An unformatted string.
487
488
489              int32 (2)
490                     A signed number.
491
492
493              uint32 (3)
494                     An unsigned number.
495
496       Complex types:
497
498
499              pathname (32)
500                     A string that describes the pathname of a file.  The file
501                     does not necessarily need to exist.
502
503
504              ldap server (33)
505                     A string that describes an LDAP server in the format:
506
507                     hostname:port:username:password:base_dn
508
509
510              key fingerprint (34)
511                     A string with a 40 digit fingerprint  specifying  a  cer‐
512                     tificate.
513
514
515              pub key (35)
516                     A  string that describes a certificate by user ID, key ID
517                     or fingerprint.
518
519
520              sec key (36)
521                     A string that describes a certificate with a key by  user
522                     ID, key ID or fingerprint.
523
524
525              alias list (37)
526                     A  string that describes an alias list, like the one used
527                     with gpg's group option.  The list consists of a key,  an
528                     equal sign and space separated values.
529
530       More  types will be added in the future.  Please see the alt-type field
531       for information on how to cope with unknown types.
532
533
534       alt-type
535              This field is identical to type, except that only the types 0 to
536              31  are  allowed.   The  GUI is expected to present the user the
537              option in the format specified by type.   But  if  the  argument
538              type  type is not supported by the GUI, it can still display the
539              option in the more generic basic type alt-type.   The  GUI  must
540              support  all  the  defined basic types to be able to display all
541              options.  More basic types may be added in future versions.   If
542              the  GUI  encounters  a basic type it doesn't support, it should
543              report an error and abort the operation.
544
545
546       argname
547              This field is only defined for options  with  an  argument  type
548              type  that  is  not  0.   In this case it may contain a percent-
549              escaped and localized string that gives a  short  name  for  the
550              argument.   The field may also be empty, though, in which case a
551              short name is not known.
552
553
554       default
555              This field is defined only for options for which the default  or
556              default  desc flag is set.  If the default flag is set, its for‐
557              mat is that of an option argument  (see:  [Format  conventions],
558              for details).  If the default value is empty, then no default is
559              known.  Otherwise, the value specifies  the  default  value  for
560              this  option.   If  the  default  desc flag is set, the field is
561              either empty or contains a description  of  the  effect  if  the
562              option is not given.
563
564
565       argdef This  field  is  defined only for options for which the optional
566              arg flag is set.  If the no arg desc flag is not set, its format
567              is  that  of  an option argument (see: [Format conventions], for
568              details).  If the default value is empty,  then  no  default  is
569              known.   Otherwise, the value specifies the default argument for
570              this option.  If the no arg desc  flag  is  set,  the  field  is
571              either  empty  or  contains  a description of the effect of this
572              option if no argument is given.
573
574
575       value  This field is defined only for options.  Its format is  that  of
576              an  option  argument.   If  it  is empty, then the option is not
577              explicitly set in the current  configuration,  and  the  default
578              applies  (if  any).  Otherwise, it contains the current value of
579              the option.  Note that this field  is  also  meaningful  if  the
580              option  itself  does  not take a real argument (in this case, it
581              contains the number of times the option appears).
582
583   Changing options
584
585
586       The command to change the options of the  component  component  to  the
587       specified  values.   component  must be the string in the field name in
588       the output of the --list-components command.  You have to  provide  the
589       options  that  shall  be  changed  in  the following format on standard
590       input:
591
592       name:flags:new-value
593
594
595       name   This is the name of the option to  change.   name  must  be  the
596              string  in  the  field  name in the output of the --list-options
597              command.
598
599
600       flags  The flags field contains an unsigned number.  Its value  is  the
601              OR-wise combination of the following flag values:
602
603
604              default (16)
605                     If  this  flag  is  set,  the  option  is deleted and the
606                     default value is used instead (if applicable).
607
608
609       new-value
610              The new value for the option.  This field is only defined if the
611              default  flag is not set.  The format is that of an option argu‐
612              ment.  If it is empty (or the field  is  omitted),  the  default
613              argument  is  used (only allowed if the argument is optional for
614              this option).  Otherwise, the option will be set to  the  speci‐
615              fied value.
616
617       The  output  of  the command is the same as that of --check-options for
618       the modified configuration file.
619
620       Examples:
621
622       To set the force option, which is of basic type none (0):
623
624         $ echo 'force:0:1' | gpgconf --change-options dirmngr
625
626       To delete the force option:
627
628         $ echo 'force:16:' | gpgconf --change-options dirmngr
629
630       The --runtime option can influence when the changes take effect.
631
632
633
634
635   Listing global options
636
637
638       Sometimes it is useful for applications to look at the  global  options
639       file ‘gpgconf.conf’.  The colon separated listing format is record ori‐
640       ented and uses the first field to identify the record type:
641
642
643       k      This describes a key record to start the  definition  of  a  new
644              ruleset for a user/group.  The format of a key record is:
645
646                k:user:group:
647
648
649              user   This  is  the  user  field  of  the  key.   It is percent
650                     escaped.  See the definition of the  gpgconf.conf  format
651                     for details.
652
653
654              group  This  is  the  group  field  of  the  key.  It is percent
655                     escaped.
656
657
658       r      This describes a rule record. All rule records up  to  the  next
659              key  record  make  up  a rule set for that key.  The format of a
660              rule record is:
661
662                r:::component:option:flag:value:
663
664
665              component
666                     This is the component part of a  rule.   It  is  a  plain
667                     string.
668
669
670              option This is the option part of a rule.  It is a plain string.
671
672
673              flag   This  is the flags part of a rule.  There may be only one
674                     flag per rule but by using the same component and option,
675                     several  flags  may  be  assigned  to an option.  It is a
676                     plain string.
677
678
679              value  This is the optional value for the option.  It is a  per‐
680                     cent escaped string with a single quotation mark to indi‐
681                     cate a string.  The quotation mark is  only  required  to
682                     distinguish  between  no  value  specified  and  an empty
683                     string.
684
685
686       Unknown record types should be ignored.  Note that there is  intention‐
687       ally no feature to change the global option file through gpgconf.
688
689
690
691
692   Get and compare software versions.
693
694
695       The  GnuPG  Project  operates a server to query the current versions of
696       software packages related to GnuPG.  gpgconf can be used to access this
697       online  database.   To allow for offline operations, this feature works
698       by having dirmngr  download  a  file  from  https://versions.gnupg.org,
699       checking  the  signature of that file and storing the file in the GnuPG
700       home directory.  If gpgconf is used and dirmngr is running, it may  ask
701       dirmngr to refresh that file before itself uses the file.
702
703       The command --query-swdb returns information for the given package in a
704       colon delimited format:
705
706
707
708       name   This is the name of the package as requested.  Note that "gnupg"
709              is a special name which is replaced by the actual package imple‐
710              menting this version of GnuPG.  For this name  it  is  also  not
711              required to specify a version because gpgconf takes its own ver‐
712              sion in this case.
713
714
715       iversion
716              The currently installed version or an empty string.   The  value
717              is  taken  from the command line argument but may be provided by
718              gpg if not given.
719
720
721       status The status of the software package according to this table:
722
723              -      No information available.  This is either because no cur‐
724                     rent version has been specified or due to an error.
725
726              ?      The given name is not known in the online database.
727
728              u      An update of the software is available.
729
730              c      The installed version of the software is current.
731
732              n      The  installed version is already newer than the released
733                     version.
734
735
736       urgency
737              If the value (the empty string should be considered as zero)  is
738              greater than zero an important update is available.
739
740
741       error  This returns an gpg-error error code to distinguish between var‐
742              ious failure modes.
743
744
745       filedate
746              This gives the date of the file  with  the  version  numbers  in
747              standard  ISO  format  (yyyymmddThhmmss).   The  date  has  been
748              extracted by dirmngr from the signature of the file.
749
750
751       verified
752              This gives the date in ISO format the file was downloaded.  This
753              value can be used to evaluate the freshness of the information.
754
755
756       version
757              This  returns the version string for the requested software from
758              the file.
759
760
761       reldate
762              This returns the release date in ISO format.
763
764
765       size   This returns the size of the package as decimal number of bytes.
766
767
768       hash   This returns a hexified SHA-2 hash of the package.
769
770
771       More fields may be added in future to the output.
772
773
774

FILES

776       /etc/gnupg/gpgconf.conf
777                If this file exists, it is processed as a global configuration
778              file.
779                A  commented  example can be found in the ‘examples’ directory
780              of
781                the distribution.
782
783
784       GNUPGHOME/swdb.lst
785                A file with current software versions.  dirmngr creates
786                this file on demand from an online resource.
787
788

SEE ALSO

790       gpg(1), gpgsm(1), gpg-agent(1), scdaemon(1), dirmngr(1)
791
792       The full documentation for this tool is maintained as a Texinfo manual.
793       If  GnuPG and the info program are properly installed at your site, the
794       command
795
796         info gnupg
797
798       should give you access to the complete manual including a  menu  struc‐
799       ture and an index.
800
801
802
803
804
805
806
807GnuPG 2.2.20                      2020-03-18                        GPGCONF(1)
Impressum