1GPGCONF(1) GNU Privacy Guard 2.2 GPGCONF(1)
2
3
4
6 gpgconf - Modify .gnupg home directories
7
9 gpgconf [options] --list-components
10 gpgconf [options] --list-options component
11 gpgconf [options] --change-options component
12
13
14
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
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
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
188 ‘GNUPGHOME’ 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
202 ‘ROOT/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
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
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
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.18 2019-11-23 GPGCONF(1)