1GPGCONF(1) GNU Privacy Guard 2.2 GPGCONF(1)
2
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
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 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 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 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
48 One of the following commands must be given:
49 --list-components
53 List all components. This is the default command used if none
54 is specified.
55 --check-programs
58 List all available backend programs and test whether they are
59 runnable.
60 --list-options component
63 List all options of the component component.
64 --change-options component
67 Change the options of the component component.
68 --check-options component
71 Check the options for the component component.
72 --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 --apply-defaults
85 Update all configuration files with values taken from the global
86 configuration file (usually ‘/etc/gnupg/gpgconf.conf’).
87 --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 --list-config [filename]
103 List the global configuration file in a colon separated format.
104 If filename is given, check that file instead.
105 --check-config [filename]
108 Run a syntax check on the global configuration file. If file‐
109 name is given, check that file instead.
110 --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 gpg-connect-agent --dirmngr 'loadswdb --force' /bye
123 --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 --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 --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 --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 de‐
154 fault home directory GnUPG creates a directory on the fly.
155 --remove-socketdir
158 Remove a directory created with command --create-socketdir.
159
162 The following options may be used:
163 -o file
167 --output file
168 Write output to file. Default is to write to stdout.
169 -v
172 --verbose
173 Outputs additional information while running. Specifically,
174 this extends numerical field values by human-readable descrip‐
175 tions.
176 -q
179 --quiet
180 Try to be as quiet as possible.
181 --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 en‐
189 try HKCU\Software\GNU\GnuPG:HomeDir.
190 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 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 be‐
199 low 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 --chuid uid
206 Change the current user to uid which may either be a number or a
207 name. This can be used from the root account to get information
208 on the GnuPG environment of the specified user or to start or
209 kill daemons. If uid is not the current UID a standard PATH is
210 set and the envvar GNUPGHOME is unset. To override the latter
211 the option --homedir can be used. This option has currently no
212 effect on Windows.
213 -n
216 --dry-run
217 Do not actually change anything. This is currently only imple‐
218 mented for --change-options and can be used for testing pur‐
219 poses.
220 -r
223 --runtime
224 Only used together with --change-options. If one of the modi‐
225 fied options can be changed in a running daemon process, signal
226 the running daemon to ask it to reparse its configuration file
227 after changing.
228 This means that the changes will take effect at run-time, as far
230 as this is possible. Otherwise, they will take effect at the
231 next start of the respective backend programs.
232 --status-fd n
235 Write special status strings to the file descriptor n. This
236 program returns the status messages SUCCESS or FAILURE which are
237 helpful when the caller uses a double fork approach and can't
238 easily get the return code of the process.
239
242 The command --list-components will list all components that can be con‐
243 figured with gpgconf. Usually, one component will correspond to one
244 GnuPG-related program and contain the options of that program's config‐
245 uration file that can be modified using gpgconf. However, this is not
246 necessarily the case. A component might also be a group of selected
247 options from several programs, or contain entirely virtual options that
248 have a special effect rather than changing exactly one option in one
249 configuration file.
250 A component is a set of configuration options that semantically belong
252 together. Furthermore, several changes to a component can be made in
253 an atomic way with a single operation. The GUI could for example pro‐
254 vide a menu with one entry for each component, or a window with one
255 tabulator sheet per component.
256 The command --list-components lists all available components, one per
258 line. The format of each line is:
259 name:description:pgmname:
261 name This field contains a name tag of the component. The name tag
264 is used to specify the component in all communication with gpg‐
265 conf. The name tag is to be used verbatim. It is thus not in
266 any escaped format.
267 description
270 The string in this field contains a human-readable description
271 of the component. It can be displayed to the user of the GUI
272 for informational purposes. It is percent-escaped and local‐
273 ized.
274 pgmname
277 The string in this field contains the absolute name of the pro‐
278 gram's file. It can be used to unambiguously invoke that pro‐
279 gram. It is percent-escaped.
280 Example:
282 $ gpgconf --list-components
283 gpg:GPG for OpenPGP:/usr/local/bin/gpg2:
284 gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:
285 scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:
286 gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:
287 dirmngr:Directory Manager:/usr/local/bin/dirmngr:
288 Checking programs
294 The command --check-programs is similar to --list-components but works
297 on backend programs and not on components. It runs each program to
298 test whether it is installed and runnable. This also includes a syntax
299 check of all config file options of the program.
300 The command --check-programs lists all available programs, one per
302 line. The format of each line is:
303 name:description:pgmname:avail:okay:cfgfile:line:error:
305 name This field contains a name tag of the program which is identical
308 to the name of the component. The name tag is to be used verba‐
309 tim. It is thus not in any escaped format. This field may be
310 empty to indicate a continuation of error descriptions for the
311 last name. The description and pgmname fields are then also
312 empty.
313 description
316 The string in this field contains a human-readable description
317 of the component. It can be displayed to the user of the GUI
318 for informational purposes. It is percent-escaped and local‐
319 ized.
320 pgmname
323 The string in this field contains the absolute name of the pro‐
324 gram's file. It can be used to unambiguously invoke that pro‐
325 gram. It is percent-escaped.
326 avail The boolean value in this field indicates whether the program is
329 installed and runnable.
330 okay The boolean value in this field indicates whether the program's
333 config file is syntactically okay.
334 cfgfile
337 If an error occurred in the configuration file (as indicated by
338 a false value in the field okay), this field has the name of the
339 failing configuration file. It is percent-escaped.
340 line If an error occurred in the configuration file, this field has
343 the line number of the failing statement in the configuration
344 file. It is an unsigned number.
345 error If an error occurred in the configuration file, this field has
348 the error text of the failing statement in the configuration
349 file. It is percent-escaped and localized.
350 In the following example the dirmngr is not runnable and the configura‐
353 tion file of scdaemon is not okay.
354 $ gpgconf --check-programs
356 gpg:GPG for OpenPGP:/usr/local/bin/gpg2:1:1:
357 gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:1:1:
358 scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:1:0:
359 gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:1:1:
360 dirmngr:Directory Manager:/usr/local/bin/dirmngr:0:0:
361 The command configuration file in the same manner as --check-programs,
364 but only for the component component.
365 Listing options
370 Every component contains one or more options. Options may be gathered
373 into option groups to allow the GUI to give visual hints to the user
374 about which options are related.
375 The command lists all options (and the groups they belong to) in the
377 component component, one per line. component must be the string in the
378 field name in the output of the --list-components command.
379 There is one line for each option and each group. First come all op‐
381 tions that are not in any group. Then comes a line describing a group.
382 Then come all options that belong into each group. Then comes the next
383 group and so on. There does not need to be any group (and in this case
384 the output will stop after the last non-grouped option).
385 The format of each line is:
387 name:flags:level:description:type:alt-type:argname:default:argdef:value
389 name This field contains a name tag for the group or option. The
392 name tag is used to specify the group or option in all communi‐
393 cation with gpgconf. The name tag is to be used verbatim. It
394 is thus not in any escaped format.
395 flags The flags field contains an unsigned number. Its value is the
398 OR-wise combination of the following flag values:
399 group (1)
402 If this flag is set, this is a line describing a group
403 and not an option.
404 The following flag values are only defined for options (that is, if the
406 group flag is not used).
407 optional arg (2)
410 If this flag is set, the argument is optional. This is
411 never set for type 0 (none) options.
412 list (4)
415 If this flag is set, the option can be given multiple
416 times.
417 runtime (8)
420 If this flag is set, the option can be changed at run‐
421 time.
422 default (16)
425 If this flag is set, a default value is available.
426 default desc (32)
429 If this flag is set, a (runtime) default is available.
430 This and the default flag are mutually exclusive.
431 no arg desc (64)
434 If this flag is set, and the optional arg flag is set,
435 then the option has a special meaning if no argument is
436 given.
437 no change (128)
440 If this flag is set, gpgconf ignores requests to change
441 the value. GUI frontends should grey out this option.
442 Note, that manual changes of the configuration files are
443 still possible.
444 level This field is defined for options and for groups. It contains
447 an unsigned number that specifies the expert level under which
448 this group or option should be displayed. The following expert
449 levels are defined for options (they have analogous meaning for
450 groups):
451 basic (0)
454 This option should always be offered to the user.
455 advanced (1)
458 This option may be offered to advanced users.
459 expert (2)
462 This option should only be offered to expert users.
463 invisible (3)
466 This option should normally never be displayed, not even
467 to expert users.
468 internal (4)
471 This option is for internal use only. Ignore it.
472 The level of a group will always be the lowest level of all options it
474 contains.
475 description
478 This field is defined for options and groups. The string in
479 this field contains a human-readable description of the option
480 or group. It can be displayed to the user of the GUI for infor‐
481 mational purposes. It is percent-escaped and localized.
482 type This field is only defined for options. It contains an unsigned
485 number that specifies the type of the option's argument, if any.
486 The following types are defined:
487 Basic types:
489 none (0)
492 No argument allowed.
493 string (1)
496 An unformatted string.
497 int32 (2)
500 A signed number.
501 uint32 (3)
504 An unsigned number.
505 Complex types:
507 pathname (32)
510 A string that describes the pathname of a file. The file
511 does not necessarily need to exist.
512 ldap server (33)
515 A string that describes an LDAP server in the format:
516 hostname:port:username:password:base_dn
518 key fingerprint (34)
521 A string with a 40 digit fingerprint specifying a cer‐
522 tificate.
523 pub key (35)
526 A string that describes a certificate by user ID, key ID
527 or fingerprint.
528 sec key (36)
531 A string that describes a certificate with a key by user
532 ID, key ID or fingerprint.
533 alias list (37)
536 A string that describes an alias list, like the one used
537 with gpg's group option. The list consists of a key, an
538 equal sign and space separated values.
539 More types will be added in the future. Please see the alt-type field
541 for information on how to cope with unknown types.
542 alt-type
545 This field is identical to type, except that only the types 0 to
546 31 are allowed. The GUI is expected to present the user the op‐
547 tion in the format specified by type. But if the argument type
548 type is not supported by the GUI, it can still display the op‐
549 tion in the more generic basic type alt-type. The GUI must sup‐
550 port all the defined basic types to be able to display all op‐
551 tions. More basic types may be added in future versions. If
552 the GUI encounters a basic type it doesn't support, it should
553 report an error and abort the operation.
554 argname
557 This field is only defined for options with an argument type
558 type that is not 0. In this case it may contain a percent-es‐
559 caped and localized string that gives a short name for the argu‐
560 ment. The field may also be empty, though, in which case a
561 short name is not known.
562 default
565 This field is defined only for options for which the default or
566 default desc flag is set. If the default flag is set, its for‐
567 mat is that of an option argument (see: [Format conventions],
568 for details). If the default value is empty, then no default is
569 known. Otherwise, the value specifies the default value for
570 this option. If the default desc flag is set, the field is ei‐
571 ther empty or contains a description of the effect if the option
572 is not given.
573 argdef This field is defined only for options for which the optional
576 arg flag is set. If the no arg desc flag is not set, its format
577 is that of an option argument (see: [Format conventions], for
578 details). If the default value is empty, then no default is
579 known. Otherwise, the value specifies the default argument for
580 this option. If the no arg desc flag is set, the field is ei‐
581 ther empty or contains a description of the effect of this op‐
582 tion if no argument is given.
583 value This field is defined only for options. Its format is that of
586 an option argument. If it is empty, then the option is not ex‐
587 plicitly set in the current configuration, and the default ap‐
588 plies (if any). Otherwise, it contains the current value of the
589 option. Note that this field is also meaningful if the option
590 itself does not take a real argument (in this case, it contains
591 the number of times the option appears).
592 Changing options
594 The command to change the options of the component component to the
597 specified values. component must be the string in the field name in
598 the output of the --list-components command. You have to provide the
599 options that shall be changed in the following format on standard in‐
600 put:
601 name:flags:new-value
603 name This is the name of the option to change. name must be the
606 string in the field name in the output of the --list-options
607 command.
608 flags The flags field contains an unsigned number. Its value is the
611 OR-wise combination of the following flag values:
612 default (16)
615 If this flag is set, the option is deleted and the de‐
616 fault value is used instead (if applicable).
617 new-value
620 The new value for the option. This field is only defined if the
621 default flag is not set. The format is that of an option argu‐
622 ment. If it is empty (or the field is omitted), the default ar‐
623 gument is used (only allowed if the argument is optional for
624 this option). Otherwise, the option will be set to the speci‐
625 fied value.
626 The output of the command is the same as that of --check-options for
628 the modified configuration file.
629 Examples:
631 To set the force option, which is of basic type none (0):
633 $ echo 'force:0:1' | gpgconf --change-options dirmngr
635 To delete the force option:
637 $ echo 'force:16:' | gpgconf --change-options dirmngr
639 The --runtime option can influence when the changes take effect.
641 Listing global options
646 Sometimes it is useful for applications to look at the global options
649 file ‘gpgconf.conf’. The colon separated listing format is record ori‐
650 ented and uses the first field to identify the record type:
651 k This describes a key record to start the definition of a new
654 ruleset for a user/group. The format of a key record is:
655 k:user:group:
657 user This is the user field of the key. It is percent es‐
660 caped. See the definition of the gpgconf.conf format for
661 details.
662 group This is the group field of the key. It is percent es‐
665 caped.
666 r This describes a rule record. All rule records up to the next
669 key record make up a rule set for that key. The format of a
670 rule record is:
671 r:::component:option:flag:value:
673 component
676 This is the component part of a rule. It is a plain
677 string.
678 option This is the option part of a rule. It is a plain string.
681 flag This is the flags part of a rule. There may be only one
684 flag per rule but by using the same component and option,
685 several flags may be assigned to an option. It is a
686 plain string.
687 value This is the optional value for the option. It is a per‐
690 cent escaped string with a single quotation mark to indi‐
691 cate a string. The quotation mark is only required to
692 distinguish between no value specified and an empty
693 string.
694 Unknown record types should be ignored. Note that there is intention‐
697 ally no feature to change the global option file through gpgconf.
698 Get and compare software versions.
703 The GnuPG Project operates a server to query the current versions of
706 software packages related to GnuPG. gpgconf can be used to access this
707 online database. To allow for offline operations, this feature works
708 by having dirmngr download a file from https://versions.gnupg.org,
709 checking the signature of that file and storing the file in the GnuPG
710 home directory. If gpgconf is used and dirmngr is running, it may ask
711 dirmngr to refresh that file before itself uses the file.
712 The command --query-swdb returns information for the given package in a
714 colon delimited format:
715 name This is the name of the package as requested. Note that "gnupg"
719 is a special name which is replaced by the actual package imple‐
720 menting this version of GnuPG. For this name it is also not re‐
721 quired to specify a version because gpgconf takes its own ver‐
722 sion in this case.
723 iversion
726 The currently installed version or an empty string. The value
727 is taken from the command line argument but may be provided by
728 gpg if not given.
729 status The status of the software package according to this table:
732 - No information available. This is either because no cur‐
734 rent version has been specified or due to an error.
735 ? The given name is not known in the online database.
737 u An update of the software is available.
739 c The installed version of the software is current.
741 n The installed version is already newer than the released
743 version.
744 urgency
747 If the value (the empty string should be considered as zero) is
748 greater than zero an important update is available.
749 error This returns an gpg-error error code to distinguish between var‐
752 ious failure modes.
753 filedate
756 This gives the date of the file with the version numbers in
757 standard ISO format (yyyymmddThhmmss). The date has been ex‐
758 tracted by dirmngr from the signature of the file.
759 verified
762 This gives the date in ISO format the file was downloaded. This
763 value can be used to evaluate the freshness of the information.
764 version
767 This returns the version string for the requested software from
768 the file.
769 reldate
772 This returns the release date in ISO format.
773 size This returns the size of the package as decimal number of bytes.
776 hash This returns a hexified SHA-2 hash of the package.
779 More fields may be added in future to the output.
782
786 /etc/gnupg/gpgconf.conf
787 If this file exists, it is processed as a global configuration
788 file.
789 A commented example can be found in the ‘examples’ directory
790 of
791 the distribution.
792 GNUPGHOME/swdb.lst
795 A file with current software versions. dirmngr creates
796 this file on demand from an online resource.
797
800 gpg(1), gpgsm(1), gpg-agent(1), scdaemon(1), dirmngr(1)
801 The full documentation for this tool is maintained as a Texinfo manual.
803 If GnuPG and the info program are properly installed at your site, the
804 command
805 info gnupg
807 should give you access to the complete manual including a menu struc‐
809 ture and an index.
810GnuPG 2.3.3 2021-10-06 GPGCONF(1)