1GPGCONF(1) GNU Privacy Guard 2.4 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’). Note:
87 This is a legacy mechanism. Please use global configuration
88 files instead.
89 --list-dirs [names]
92 -L Lists the directories used by gpgconf. One directory is listed
93 per line, and each line consists of a colon-separated list where
94 the first field names the directory type (for example
95 sysconfdir) and the second field contains the percent-escaped
96 directory. Although they are not directories, the socket file
97 names used by gpg-agent and dirmngr are printed as well. Note
98 that the socket file names and the homedir lines are the default
99 names and they may be overridden by command line switches. If
100 names are given only the directories or file names specified by
101 the list names are printed without any escaping.
102 --list-config [filename]
105 List the global configuration file in a colon separated format.
106 If filename is given, check that file instead.
107 --check-config [filename]
110 Run a syntax check on the global configuration file. If file‐
111 name is given, check that file instead.
112 --query-swdb package_name [version_string]
116 Returns the current version for package_name and if ver‐
117 sion_string is given also an indicator on whether an update is
118 available. The actual file with the software version is auto‐
119 matically downloaded and checked by dirmngr. dirmngr uses a
120 thresholds to avoid download the file too often and it does this
121 by default only if it can be done via Tor. To force an update
122 of that file this command can be used:
123 gpg-connect-agent --dirmngr 'loadswdb --force' /bye
125 --reload [component]
128 -R Reload all or the given component. This is basically the same as
129 sending a SIGHUP to the component. Components which don't sup‐
130 port reloading are ignored. Without component or by using "all"
131 for component all components which are daemons are reloaded.
132 --launch [component]
135 If the component is not already running, start it. component
136 must be a daemon. This is in general not required because the
137 system starts these daemons as needed. However, external soft‐
138 ware making direct use of gpg-agent or dirmngr may use this com‐
139 mand to ensure that they are started. Using "all" for component
140 launches all components which are daemons.
141 --kill [component]
144 -K Kill the given component that runs as a daemon, including gpg-
145 agent, dirmngr, and scdaemon. A component which does not run as
146 a daemon will be ignored. Using "all" for component kills all
147 components running as daemons. Note that as of now reload and
148 kill have the same effect for scdaemon.
149 --create-socketdir
152 Create a directory for sockets below /run/user or /var/run/user.
153 This is command is only required if a non default home directory
154 is used and the /run based sockets shall be used. For the de‐
155 fault home directory GnUPG creates a directory on the fly.
156 --remove-socketdir
159 Remove a directory created with command --create-socketdir.
160
163 The following options may be used:
164 -o file
168 --output file
169 Write output to file. Default is to write to stdout.
170 -v
173 --verbose
174 Outputs additional information while running. Specifically,
175 this extends numerical field values by human-readable descrip‐
176 tions.
177 -q
180 --quiet
181 Try to be as quiet as possible.
182 --homedir dir
185 Set the name of the home directory to dir. If this option is not
186 used, the home directory defaults to ‘~/.gnupg’. It is only
187 recognized when given on the command line. It also overrides
188 any home directory stated through the environment variable
189 ‘GNUPGHOME’ or (on Windows systems) by means of the Registry en‐
190 try HKCU\Software\GNU\GnuPG:HomeDir.
191 On Windows systems it is possible to install GnuPG as a portable
193 application. In this case only this command line option is con‐
194 sidered, all other ways to set a home directory are ignored.
195 To install GnuPG as a portable application under Windows, create
197 an empty file named ‘gpgconf.ctl’ in the same directory as the
198 tool ‘gpgconf.exe’. The root of the installation is then that
199 directory; or, if ‘gpgconf.exe’ has been installed directly be‐
200 low a directory named ‘bin’, its parent directory. You also
201 need to make sure that the following directories exist and are
202 writable: ‘ROOT/home’ for the GnuPG home and
203 ‘ROOT/var/cache/gnupg’ for internal cache files.
204 --chuid uid
207 Change the current user to uid which may either be a number or a
208 name. This can be used from the root account to get information
209 on the GnuPG environment of the specified user or to start or
210 kill daemons. If uid is not the current UID a standard PATH is
211 set and the envvar GNUPGHOME is unset. To override the latter
212 the option --homedir can be used. This option has currently no
213 effect on Windows.
214 -n
217 --dry-run
218 Do not actually change anything. This is currently only imple‐
219 mented for --change-options and can be used for testing pur‐
220 poses.
221 -r
224 --runtime
225 Only used together with --change-options. If one of the modi‐
226 fied options can be changed in a running daemon process, signal
227 the running daemon to ask it to reparse its configuration file
228 after changing.
229 This means that the changes will take effect at run-time, as far
231 as this is possible. Otherwise, they will take effect at the
232 next start of the respective backend programs.
233 --status-fd n
236 Write special status strings to the file descriptor n. This
237 program returns the status messages SUCCESS or FAILURE which are
238 helpful when the caller uses a double fork approach and can't
239 easily get the return code of the process.
240
243 The command --list-components will list all components that can be con‐
244 figured with gpgconf. Usually, one component will correspond to one
245 GnuPG-related program and contain the options of that program's config‐
246 uration file that can be modified using gpgconf. However, this is not
247 necessarily the case. A component might also be a group of selected
248 options from several programs, or contain entirely virtual options that
249 have a special effect rather than changing exactly one option in one
250 configuration file.
251 A component is a set of configuration options that semantically belong
253 together. Furthermore, several changes to a component can be made in
254 an atomic way with a single operation. The GUI could for example pro‐
255 vide a menu with one entry for each component, or a window with one
256 tabulator sheet per component.
257 The command --list-components lists all available components, one per
259 line. The format of each line is:
260 name:description:pgmname:
262 name This field contains a name tag of the component. The name tag
265 is used to specify the component in all communication with gpg‐
266 conf. The name tag is to be used verbatim. It is thus not in
267 any escaped format.
268 description
271 The string in this field contains a human-readable description
272 of the component. It can be displayed to the user of the GUI
273 for informational purposes. It is percent-escaped and local‐
274 ized.
275 pgmname
278 The string in this field contains the absolute name of the pro‐
279 gram's file. It can be used to unambiguously invoke that pro‐
280 gram. It is percent-escaped.
281 Example:
283 $ gpgconf --list-components
284 gpg:GPG for OpenPGP:/usr/local/bin/gpg2:
285 gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:
286 scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:
287 gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:
288 dirmngr:Directory Manager:/usr/local/bin/dirmngr:
289 Checking programs
295 The command --check-programs is similar to --list-components but works
298 on backend programs and not on components. It runs each program to
299 test whether it is installed and runnable. This also includes a syntax
300 check of all config file options of the program.
301 The command --check-programs lists all available programs, one per
303 line. The format of each line is:
304 name:description:pgmname:avail:okay:cfgfile:line:error:
306 name This field contains a name tag of the program which is identical
309 to the name of the component. The name tag is to be used verba‐
310 tim. It is thus not in any escaped format. This field may be
311 empty to indicate a continuation of error descriptions for the
312 last name. The description and pgmname fields are then also
313 empty.
314 description
317 The string in this field contains a human-readable description
318 of the component. It can be displayed to the user of the GUI
319 for informational purposes. It is percent-escaped and local‐
320 ized.
321 pgmname
324 The string in this field contains the absolute name of the pro‐
325 gram's file. It can be used to unambiguously invoke that pro‐
326 gram. It is percent-escaped.
327 avail The boolean value in this field indicates whether the program is
330 installed and runnable.
331 okay The boolean value in this field indicates whether the program's
334 config file is syntactically okay.
335 cfgfile
338 If an error occurred in the configuration file (as indicated by
339 a false value in the field okay), this field has the name of the
340 failing configuration file. It is percent-escaped.
341 line If an error occurred in the configuration file, this field has
344 the line number of the failing statement in the configuration
345 file. It is an unsigned number.
346 error If an error occurred in the configuration file, this field has
349 the error text of the failing statement in the configuration
350 file. It is percent-escaped and localized.
351 In the following example the dirmngr is not runnable and the configura‐
354 tion file of scdaemon is not okay.
355 $ gpgconf --check-programs
357 gpg:GPG for OpenPGP:/usr/local/bin/gpg2:1:1:
358 gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:1:1:
359 scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:1:0:
360 gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:1:1:
361 dirmngr:Directory Manager:/usr/local/bin/dirmngr:0:0:
362 The command configuration file in the same manner as --check-programs,
365 but only for the component component.
366 Listing options
371 Every component contains one or more options. Options may be gathered
374 into option groups to allow the GUI to give visual hints to the user
375 about which options are related.
376 The command lists all options (and the groups they belong to) in the
378 component component, one per line. component must be the string in the
379 field name in the output of the --list-components command.
380 There is one line for each option and each group. First come all op‐
382 tions that are not in any group. Then comes a line describing a group.
383 Then come all options that belong into each group. Then comes the next
384 group and so on. There does not need to be any group (and in this case
385 the output will stop after the last non-grouped option).
386 The format of each line is:
388 name:flags:level:description:type:alt-type:argname:default:argdef:value
390 name This field contains a name tag for the group or option. The
393 name tag is used to specify the group or option in all communi‐
394 cation with gpgconf. The name tag is to be used verbatim. It
395 is thus not in any escaped format.
396 flags The flags field contains an unsigned number. Its value is the
399 OR-wise combination of the following flag values:
400 group (1)
403 If this flag is set, this is a line describing a group
404 and not an option.
405 The following flag values are only defined for options (that is, if the
407 group flag is not used).
408 optional arg (2)
411 If this flag is set, the argument is optional. This is
412 never set for type 0 (none) options.
413 list (4)
416 If this flag is set, the option can be given multiple
417 times.
418 runtime (8)
421 If this flag is set, the option can be changed at run‐
422 time.
423 default (16)
426 If this flag is set, a default value is available.
427 default desc (32)
430 If this flag is set, a (runtime) default is available.
431 This and the default flag are mutually exclusive.
432 no arg desc (64)
435 If this flag is set, and the optional arg flag is set,
436 then the option has a special meaning if no argument is
437 given.
438 no change (128)
441 If this flag is set, gpgconf ignores requests to change
442 the value. GUI frontends should grey out this option.
443 Note, that manual changes of the configuration files are
444 still possible.
445 level This field is defined for options and for groups. It contains
448 an unsigned number that specifies the expert level under which
449 this group or option should be displayed. The following expert
450 levels are defined for options (they have analogous meaning for
451 groups):
452 basic (0)
455 This option should always be offered to the user.
456 advanced (1)
459 This option may be offered to advanced users.
460 expert (2)
463 This option should only be offered to expert users.
464 invisible (3)
467 This option should normally never be displayed, not even
468 to expert users.
469 internal (4)
472 This option is for internal use only. Ignore it.
473 The level of a group will always be the lowest level of all options it
475 contains.
476 description
479 This field is defined for options and groups. The string in
480 this field contains a human-readable description of the option
481 or group. It can be displayed to the user of the GUI for infor‐
482 mational purposes. It is percent-escaped and localized.
483 type This field is only defined for options. It contains an unsigned
486 number that specifies the type of the option's argument, if any.
487 The following types are defined:
488 Basic types:
490 none (0)
493 No argument allowed.
494 string (1)
497 An unformatted string.
498 int32 (2)
501 A signed number.
502 uint32 (3)
505 An unsigned number.
506 Complex types:
508 pathname (32)
511 A string that describes the pathname of a file. The file
512 does not necessarily need to exist.
513 ldap server (33)
516 A string that describes an LDAP server in the format:
517 hostname:port:username:password:base_dn
519 key fingerprint (34)
522 A string with a 40 digit fingerprint specifying a cer‐
523 tificate.
524 pub key (35)
527 A string that describes a certificate by user ID, key ID
528 or fingerprint.
529 sec key (36)
532 A string that describes a certificate with a key by user
533 ID, key ID or fingerprint.
534 alias list (37)
537 A string that describes an alias list, like the one used
538 with gpg's group option. The list consists of a key, an
539 equal sign and space separated values.
540 More types will be added in the future. Please see the alt-type field
542 for information on how to cope with unknown types.
543 alt-type
546 This field is identical to type, except that only the types 0 to
547 31 are allowed. The GUI is expected to present the user the op‐
548 tion in the format specified by type. But if the argument type
549 type is not supported by the GUI, it can still display the op‐
550 tion in the more generic basic type alt-type. The GUI must sup‐
551 port all the defined basic types to be able to display all op‐
552 tions. More basic types may be added in future versions. If
553 the GUI encounters a basic type it doesn't support, it should
554 report an error and abort the operation.
555 argname
558 This field is only defined for options with an argument type
559 type that is not 0. In this case it may contain a percent-es‐
560 caped and localized string that gives a short name for the argu‐
561 ment. The field may also be empty, though, in which case a
562 short name is not known.
563 default
566 This field is defined only for options for which the default or
567 default desc flag is set. If the default flag is set, its for‐
568 mat is that of an option argument (see: [Format conventions],
569 for details). If the default value is empty, then no default is
570 known. Otherwise, the value specifies the default value for
571 this option. If the default desc flag is set, the field is ei‐
572 ther empty or contains a description of the effect if the option
573 is not given.
574 argdef This field is defined only for options for which the optional
577 arg flag is set. If the no arg desc flag is not set, its format
578 is that of an option argument (see: [Format conventions], for
579 details). If the default value is empty, then no default is
580 known. Otherwise, the value specifies the default argument for
581 this option. If the no arg desc flag is set, the field is ei‐
582 ther empty or contains a description of the effect of this op‐
583 tion if no argument is given.
584 value This field is defined only for options. Its format is that of
587 an option argument. If it is empty, then the option is not ex‐
588 plicitly set in the current configuration, and the default ap‐
589 plies (if any). Otherwise, it contains the current value of the
590 option. Note that this field is also meaningful if the option
591 itself does not take a real argument (in this case, it contains
592 the number of times the option appears).
593 Changing options
595 The command to change the options of the component component to the
598 specified values. component must be the string in the field name in
599 the output of the --list-components command. You have to provide the
600 options that shall be changed in the following format on standard in‐
601 put:
602 name:flags:new-value
604 name This is the name of the option to change. name must be the
607 string in the field name in the output of the --list-options
608 command.
609 flags The flags field contains an unsigned number. Its value is the
612 OR-wise combination of the following flag values:
613 default (16)
616 If this flag is set, the option is deleted and the de‐
617 fault value is used instead (if applicable).
618 new-value
621 The new value for the option. This field is only defined if the
622 default flag is not set. The format is that of an option argu‐
623 ment. If it is empty (or the field is omitted), the default ar‐
624 gument is used (only allowed if the argument is optional for
625 this option). Otherwise, the option will be set to the speci‐
626 fied value.
627 The output of the command is the same as that of --check-options for
629 the modified configuration file.
630 Examples:
632 To set the force option, which is of basic type none (0):
634 $ echo 'force:0:1' | gpgconf --change-options dirmngr
636 To delete the force option:
638 $ echo 'force:16:' | gpgconf --change-options dirmngr
640 The --runtime option can influence when the changes take effect.
642 Listing global options
647 Some legacy applications look at the global configuration file for the
650 gpgconf tool itself; this is the file ‘gpgconf.conf’. Modern applica‐
651 tions should not use it but use per component global configuration
652 files which are more flexible than the ‘gpgconf.conf’. Using both
653 files is not suggested.
654 The colon separated listing format is record oriented and uses the
656 first field to identify the record type:
657 k This describes a key record to start the definition of a new
660 ruleset for a user/group. The format of a key record is:
661 k:user:group:
663 user This is the user field of the key. It is percent es‐
666 caped. See the definition of the gpgconf.conf format for
667 details.
668 group This is the group field of the key. It is percent es‐
671 caped.
672 r This describes a rule record. All rule records up to the next
675 key record make up a rule set for that key. The format of a
676 rule record is:
677 r:::component:option:flag:value:
679 component
682 This is the component part of a rule. It is a plain
683 string.
684 option This is the option part of a rule. It is a plain string.
687 flag This is the flags part of a rule. There may be only one
690 flag per rule but by using the same component and option,
691 several flags may be assigned to an option. It is a
692 plain string.
693 value This is the optional value for the option. It is a per‐
696 cent escaped string with a single quotation mark to indi‐
697 cate a string. The quotation mark is only required to
698 distinguish between no value specified and an empty
699 string.
700 Unknown record types should be ignored. Note that there is intention‐
703 ally no feature to change the global option file through gpgconf.
704 Get and compare software versions.
709 The GnuPG Project operates a server to query the current versions of
712 software packages related to GnuPG. gpgconf can be used to access this
713 online database. To allow for offline operations, this feature works
714 by having dirmngr download a file from https://versions.gnupg.org,
715 checking the signature of that file and storing the file in the GnuPG
716 home directory. If gpgconf is used and dirmngr is running, it may ask
717 dirmngr to refresh that file before itself uses the file.
718 The command --query-swdb returns information for the given package in a
720 colon delimited format:
721 name This is the name of the package as requested. Note that "gnupg"
725 is a special name which is replaced by the actual package imple‐
726 menting this version of GnuPG. For this name it is also not re‐
727 quired to specify a version because gpgconf takes its own ver‐
728 sion in this case.
729 iversion
732 The currently installed version or an empty string. The value
733 is taken from the command line argument but may be provided by
734 gpg if not given.
735 status The status of the software package according to this table:
738 - No information available. This is either because no cur‐
740 rent version has been specified or due to an error.
741 ? The given name is not known in the online database.
743 u An update of the software is available.
745 c The installed version of the software is current.
747 n The installed version is already newer than the released
749 version.
750 urgency
753 If the value (the empty string should be considered as zero) is
754 greater than zero an important update is available.
755 error This returns an gpg-error error code to distinguish between var‐
758 ious failure modes.
759 filedate
762 This gives the date of the file with the version numbers in
763 standard ISO format (yyyymmddThhmmss). The date has been ex‐
764 tracted by dirmngr from the signature of the file.
765 verified
768 This gives the date in ISO format the file was downloaded. This
769 value can be used to evaluate the freshness of the information.
770 version
773 This returns the version string for the requested software from
774 the file.
775 reldate
778 This returns the release date in ISO format.
779 size This returns the size of the package as decimal number of bytes.
782 hash This returns a hexified SHA-2 hash of the package.
785 More fields may be added in future to the output.
788
792 /etc/gnupg/gpgconf.conf
793 If this file exists, it is processed as a global configuration
794 file.
795 This is a legacy mechanism which should not be used tigether
796 with
797 the modern global per component configuration files. A com‐
798 mented
799 example can be found in the ‘examples’ directory of the
800 distribution.
801 GNUPGHOME/swdb.lst
804 A file with current software versions. dirmngr creates
805 this file on demand from an online resource.
806
809 gpg(1), gpgsm(1), gpg-agent(1), scdaemon(1), dirmngr(1)
810 The full documentation for this tool is maintained as a Texinfo manual.
812 If GnuPG and the info program are properly installed at your site, the
813 command
814 info gnupg
816 should give you access to the complete manual including a menu struc‐
818 ture and an index.
819GnuPG 2.4.3 2023-06-21 GPGCONF(1)