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
154 default 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
189 entry 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
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 -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 -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 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 --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
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 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 The command --list-components lists all available components, one per
248 line. The format of each line is:
249 name:description:pgmname:
251 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 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 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 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 Checking programs
284 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 The command --check-programs lists all available programs, one per
292 line. The format of each line is:
293 name:description:pgmname:avail:okay:cfgfile:line:error:
295 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 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 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 avail The boolean value in this field indicates whether the program is
319 installed and runnable.
320 okay The boolean value in this field indicates whether the program's
323 config file is syntactically okay.
324 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 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 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 In the following example the dirmngr is not runnable and the configura‐
343 tion file of scdaemon is not okay.
344 $ 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 The command configuration file in the same manner as --check-programs,
354 but only for the component component.
355 Listing options
360 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 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 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 The format of each line is:
377 name:flags:level:description:type:alt-type:argname:default:argdef:value
379 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 flags The flags field contains an unsigned number. Its value is the
388 OR-wise combination of the following flag values:
389 group (1)
392 If this flag is set, this is a line describing a group
393 and not an option.
394 The following flag values are only defined for options (that is, if the
396 group flag is not used).
397 optional arg (2)
400 If this flag is set, the argument is optional. This is
401 never set for type 0 (none) options.
402 list (4)
405 If this flag is set, the option can be given multiple
406 times.
407 runtime (8)
410 If this flag is set, the option can be changed at run‐
411 time.
412 default (16)
415 If this flag is set, a default value is available.
416 default desc (32)
419 If this flag is set, a (runtime) default is available.
420 This and the default flag are mutually exclusive.
421 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 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 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 basic (0)
444 This option should always be offered to the user.
445 advanced (1)
448 This option may be offered to advanced users.
449 expert (2)
452 This option should only be offered to expert users.
453 invisible (3)
456 This option should normally never be displayed, not even
457 to expert users.
458 internal (4)
461 This option is for internal use only. Ignore it.
462 The level of a group will always be the lowest level of all options it
464 contains.
465 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 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 Basic types:
479 none (0)
482 No argument allowed.
483 string (1)
486 An unformatted string.
487 int32 (2)
490 A signed number.
491 uint32 (3)
494 An unsigned number.
495 Complex types:
497 pathname (32)
500 A string that describes the pathname of a file. The file
501 does not necessarily need to exist.
502 ldap server (33)
505 A string that describes an LDAP server in the format:
506 hostname:port:username:password:base_dn
508 key fingerprint (34)
511 A string with a 40 digit fingerprint specifying a cer‐
512 tificate.
513 pub key (35)
516 A string that describes a certificate by user ID, key ID
517 or fingerprint.
518 sec key (36)
521 A string that describes a certificate with a key by user
522 ID, key ID or fingerprint.
523 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 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 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 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 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 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 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 Changing options
584 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 name:flags:new-value
593 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 flags The flags field contains an unsigned number. Its value is the
601 OR-wise combination of the following flag values:
602 default (16)
605 If this flag is set, the option is deleted and the
606 default value is used instead (if applicable).
607 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 The output of the command is the same as that of --check-options for
618 the modified configuration file.
619 Examples:
621 To set the force option, which is of basic type none (0):
623 $ echo 'force:0:1' | gpgconf --change-options dirmngr
625 To delete the force option:
627 $ echo 'force:16:' | gpgconf --change-options dirmngr
629 The --runtime option can influence when the changes take effect.
631 Listing global options
636 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 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 k:user:group:
647 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 group This is the group field of the key. It is percent
655 escaped.
656 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 r:::component:option:flag:value:
663 component
666 This is the component part of a rule. It is a plain
667 string.
668 option This is the option part of a rule. It is a plain string.
671 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 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 Unknown record types should be ignored. Note that there is intention‐
687 ally no feature to change the global option file through gpgconf.
688 Get and compare software versions.
693 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 The command --query-swdb returns information for the given package in a
704 colon delimited format:
705 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 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 status The status of the software package according to this table:
722 - No information available. This is either because no cur‐
724 rent version has been specified or due to an error.
725 ? The given name is not known in the online database.
727 u An update of the software is available.
729 c The installed version of the software is current.
731 n The installed version is already newer than the released
733 version.
734 urgency
737 If the value (the empty string should be considered as zero) is
738 greater than zero an important update is available.
739 error This returns an gpg-error error code to distinguish between var‐
742 ious failure modes.
743 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 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 version
757 This returns the version string for the requested software from
758 the file.
759 reldate
762 This returns the release date in ISO format.
763 size This returns the size of the package as decimal number of bytes.
766 hash This returns a hexified SHA-2 hash of the package.
769 More fields may be added in future to the output.
772
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 GNUPGHOME/swdb.lst
785 A file with current software versions. dirmngr creates
786 this file on demand from an online resource.
787
790 gpg(1), gpgsm(1), gpg-agent(1), scdaemon(1), dirmngr(1)
791 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 info gnupg
797 should give you access to the complete manual including a menu struc‐
799 ture and an index.
800GnuPG 2.2.20 2020-03-18 GPGCONF(1)