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. Components which support killing are
144 gpg-agent and scdaemon. Components which don't support reload‐
145 ing are ignored. Using "all" for component kills all components
146 running as daemons. Note that as of now reload and kill have
147 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 -n
184 --dry-run
185 Do not actually change anything. This is currently only imple‐
186 mented for --change-options and can be used for testing pur‐
187 poses.
188 -r
191 --runtime
192 Only used together with --change-options. If one of the modi‐
193 fied options can be changed in a running daemon process, signal
194 the running daemon to ask it to reparse its configuration file
195 after changing.
196 This means that the changes will take effect at run-time, as far
198 as this is possible. Otherwise, they will take effect at the
199 next start of the respective backend programs.
200 --status-fd n
203 Write special status strings to the file descriptor n. This
204 program returns the status messages SUCCESS or FAILURE which are
205 helpful when the caller uses a double fork approach and can't
206 easily get the return code of the process.
207
210 The command --list-components will list all components that can be con‐
211 figured with gpgconf. Usually, one component will correspond to one
212 GnuPG-related program and contain the options of that program's config‐
213 uration file that can be modified using gpgconf. However, this is not
214 necessarily the case. A component might also be a group of selected
215 options from several programs, or contain entirely virtual options that
216 have a special effect rather than changing exactly one option in one
217 configuration file.
218 A component is a set of configuration options that semantically belong
220 together. Furthermore, several changes to a component can be made in
221 an atomic way with a single operation. The GUI could for example pro‐
222 vide a menu with one entry for each component, or a window with one
223 tabulator sheet per component.
224 The command --list-components lists all available components, one per
226 line. The format of each line is:
227 name:description:pgmname:
229 name This field contains a name tag of the component. The name tag
232 is used to specify the component in all communication with gpg‐
233 conf. The name tag is to be used verbatim. It is thus not in
234 any escaped format.
235 description
238 The string in this field contains a human-readable description
239 of the component. It can be displayed to the user of the GUI
240 for informational purposes. It is percent-escaped and local‐
241 ized.
242 pgmname
245 The string in this field contains the absolute name of the pro‐
246 gram's file. It can be used to unambiguously invoke that pro‐
247 gram. It is percent-escaped.
248 Example:
250 $ gpgconf --list-components
251 gpg:GPG for OpenPGP:/usr/local/bin/gpg2:
252 gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:
253 scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:
254 gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:
255 dirmngr:Directory Manager:/usr/local/bin/dirmngr:
256 Checking programs
262 The command --check-programs is similar to --list-components but works
265 on backend programs and not on components. It runs each program to
266 test whether it is installed and runnable. This also includes a syntax
267 check of all config file options of the program.
268 The command --check-programs lists all available programs, one per
270 line. The format of each line is:
271 name:description:pgmname:avail:okay:cfgfile:line:error:
273 name This field contains a name tag of the program which is identical
276 to the name of the component. The name tag is to be used verba‐
277 tim. It is thus not in any escaped format. This field may be
278 empty to indicate a continuation of error descriptions for the
279 last name. The description and pgmname fields are then also
280 empty.
281 description
284 The string in this field contains a human-readable description
285 of the component. It can be displayed to the user of the GUI
286 for informational purposes. It is percent-escaped and local‐
287 ized.
288 pgmname
291 The string in this field contains the absolute name of the pro‐
292 gram's file. It can be used to unambiguously invoke that pro‐
293 gram. It is percent-escaped.
294 avail The boolean value in this field indicates whether the program is
297 installed and runnable.
298 okay The boolean value in this field indicates whether the program's
301 config file is syntactically okay.
302 cfgfile
305 If an error occurred in the configuration file (as indicated by
306 a false value in the field okay), this field has the name of the
307 failing configuration file. It is percent-escaped.
308 line If an error occurred in the configuration file, this field has
311 the line number of the failing statement in the configuration
312 file. It is an unsigned number.
313 error If an error occurred in the configuration file, this field has
316 the error text of the failing statement in the configuration
317 file. It is percent-escaped and localized.
318 In the following example the dirmngr is not runnable and the configura‐
321 tion file of scdaemon is not okay.
322 $ gpgconf --check-programs
324 gpg:GPG for OpenPGP:/usr/local/bin/gpg2:1:1:
325 gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:1:1:
326 scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:1:0:
327 gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:1:1:
328 dirmngr:Directory Manager:/usr/local/bin/dirmngr:0:0:
329 The command configuration file in the same manner as --check-programs,
332 but only for the component component.
333 Listing options
338 Every component contains one or more options. Options may be gathered
341 into option groups to allow the GUI to give visual hints to the user
342 about which options are related.
343 The command lists all options (and the groups they belong to) in the
345 component component, one per line. component must be the string in the
346 field name in the output of the --list-components command.
347 There is one line for each option and each group. First come all
349 options that are not in any group. Then comes a line describing a
350 group. Then come all options that belong into each group. Then comes
351 the next group and so on. There does not need to be any group (and in
352 this case the output will stop after the last non-grouped option).
353 The format of each line is:
355 name:flags:level:description:type:alt-type:argname:default:argdef:value
357 name This field contains a name tag for the group or option. The
360 name tag is used to specify the group or option in all communi‐
361 cation with gpgconf. The name tag is to be used verbatim. It
362 is thus not in any escaped format.
363 flags The flags field contains an unsigned number. Its value is the
366 OR-wise combination of the following flag values:
367 group (1)
370 If this flag is set, this is a line describing a group
371 and not an option.
372 The following flag values are only defined for options (that is, if the
374 group flag is not used).
375 optional arg (2)
378 If this flag is set, the argument is optional. This is
379 never set for type 0 (none) options.
380 list (4)
383 If this flag is set, the option can be given multiple
384 times.
385 runtime (8)
388 If this flag is set, the option can be changed at run‐
389 time.
390 default (16)
393 If this flag is set, a default value is available.
394 default desc (32)
397 If this flag is set, a (runtime) default is available.
398 This and the default flag are mutually exclusive.
399 no arg desc (64)
402 If this flag is set, and the optional arg flag is set,
403 then the option has a special meaning if no argument is
404 given.
405 no change (128)
408 If this flag is set, gpgconf ignores requests to change
409 the value. GUI frontends should grey out this option.
410 Note, that manual changes of the configuration files are
411 still possible.
412 level This field is defined for options and for groups. It contains
415 an unsigned number that specifies the expert level under which
416 this group or option should be displayed. The following expert
417 levels are defined for options (they have analogous meaning for
418 groups):
419 basic (0)
422 This option should always be offered to the user.
423 advanced (1)
426 This option may be offered to advanced users.
427 expert (2)
430 This option should only be offered to expert users.
431 invisible (3)
434 This option should normally never be displayed, not even
435 to expert users.
436 internal (4)
439 This option is for internal use only. Ignore it.
440 The level of a group will always be the lowest level of all options it
442 contains.
443 description
446 This field is defined for options and groups. The string in
447 this field contains a human-readable description of the option
448 or group. It can be displayed to the user of the GUI for infor‐
449 mational purposes. It is percent-escaped and localized.
450 type This field is only defined for options. It contains an unsigned
453 number that specifies the type of the option's argument, if any.
454 The following types are defined:
455 Basic types:
457 none (0)
460 No argument allowed.
461 string (1)
464 An unformatted string.
465 int32 (2)
468 A signed number.
469 uint32 (3)
472 An unsigned number.
473 Complex types:
475 pathname (32)
478 A string that describes the pathname of a file. The file
479 does not necessarily need to exist.
480 ldap server (33)
483 A string that describes an LDAP server in the format:
484 hostname:port:username:password:base_dn
486 key fingerprint (34)
489 A string with a 40 digit fingerprint specifying a cer‐
490 tificate.
491 pub key (35)
494 A string that describes a certificate by user ID, key ID
495 or fingerprint.
496 sec key (36)
499 A string that describes a certificate with a key by user
500 ID, key ID or fingerprint.
501 alias list (37)
504 A string that describes an alias list, like the one used
505 with gpg's group option. The list consists of a key, an
506 equal sign and space separated values.
507 More types will be added in the future. Please see the alt-type field
509 for information on how to cope with unknown types.
510 alt-type
513 This field is identical to type, except that only the types 0 to
514 31 are allowed. The GUI is expected to present the user the
515 option in the format specified by type. But if the argument
516 type type is not supported by the GUI, it can still display the
517 option in the more generic basic type alt-type. The GUI must
518 support all the defined basic types to be able to display all
519 options. More basic types may be added in future versions. If
520 the GUI encounters a basic type it doesn't support, it should
521 report an error and abort the operation.
522 argname
525 This field is only defined for options with an argument type
526 type that is not 0. In this case it may contain a percent-
527 escaped and localized string that gives a short name for the
528 argument. The field may also be empty, though, in which case a
529 short name is not known.
530 default
533 This field is defined only for options for which the default or
534 default desc flag is set. If the default flag is set, its for‐
535 mat is that of an option argument (see: [Format conventions],
536 for details). If the default value is empty, then no default is
537 known. Otherwise, the value specifies the default value for
538 this option. If the default desc flag is set, the field is
539 either empty or contains a description of the effect if the
540 option is not given.
541 argdef This field is defined only for options for which the optional
544 arg flag is set. If the no arg desc flag is not set, its format
545 is that of an option argument (see: [Format conventions], for
546 details). If the default value is empty, then no default is
547 known. Otherwise, the value specifies the default argument for
548 this option. If the no arg desc flag is set, the field is
549 either empty or contains a description of the effect of this
550 option if no argument is given.
551 value This field is defined only for options. Its format is that of
554 an option argument. If it is empty, then the option is not
555 explicitly set in the current configuration, and the default
556 applies (if any). Otherwise, it contains the current value of
557 the option. Note that this field is also meaningful if the
558 option itself does not take a real argument (in this case, it
559 contains the number of times the option appears).
560 Changing options
562 The command to change the options of the component component to the
565 specified values. component must be the string in the field name in
566 the output of the --list-components command. You have to provide the
567 options that shall be changed in the following format on standard
568 input:
569 name:flags:new-value
571 name This is the name of the option to change. name must be the
574 string in the field name in the output of the --list-options
575 command.
576 flags The flags field contains an unsigned number. Its value is the
579 OR-wise combination of the following flag values:
580 default (16)
583 If this flag is set, the option is deleted and the
584 default value is used instead (if applicable).
585 new-value
588 The new value for the option. This field is only defined if the
589 default flag is not set. The format is that of an option argu‐
590 ment. If it is empty (or the field is omitted), the default
591 argument is used (only allowed if the argument is optional for
592 this option). Otherwise, the option will be set to the speci‐
593 fied value.
594 The output of the command is the same as that of --check-options for
596 the modified configuration file.
597 Examples:
599 To set the force option, which is of basic type none (0):
601 $ echo 'force:0:1' | gpgconf --change-options dirmngr
603 To delete the force option:
605 $ echo 'force:16:' | gpgconf --change-options dirmngr
607 The --runtime option can influence when the changes take effect.
609 Listing global options
614 Sometimes it is useful for applications to look at the global options
617 file ‘gpgconf.conf’. The colon separated listing format is record ori‐
618 ented and uses the first field to identify the record type:
619 k This describes a key record to start the definition of a new
622 ruleset for a user/group. The format of a key record is:
623 k:user:group:
625 user This is the user field of the key. It is percent
628 escaped. See the definition of the gpgconf.conf format
629 for details.
630 group This is the group field of the key. It is percent
633 escaped.
634 r This describes a rule record. All rule records up to the next
637 key record make up a rule set for that key. The format of a
638 rule record is:
639 r:::component:option:flag:value:
641 component
644 This is the component part of a rule. It is a plain
645 string.
646 option This is the option part of a rule. It is a plain string.
649 flag This is the flags part of a rule. There may be only one
652 flag per rule but by using the same component and option,
653 several flags may be assigned to an option. It is a
654 plain string.
655 value This is the optional value for the option. It is a per‐
658 cent escaped string with a single quotation mark to indi‐
659 cate a string. The quotation mark is only required to
660 distinguish between no value specified and an empty
661 string.
662 Unknown record types should be ignored. Note that there is intention‐
665 ally no feature to change the global option file through gpgconf.
666 Get and compare software versions.
671 The GnuPG Project operates a server to query the current versions of
674 software packages related to GnuPG. gpgconf can be used to access this
675 online database. To allow for offline operations, this feature works
676 by having dirmngr download a file from https://versions.gnupg.org,
677 checking the signature of that file and storing the file in the GnuPG
678 home directory. If gpgconf is used and dirmngr is running, it may ask
679 dirmngr to refresh that file before itself uses the file.
680 The command --query-swdb returns information for the given package in a
682 colon delimited format:
683 name This is the name of the package as requested. Note that "gnupg"
687 is a special name which is replaced by the actual package imple‐
688 menting this version of GnuPG. For this name it is also not
689 required to specify a version because gpgconf takes its own ver‐
690 sion in this case.
691 iversion
694 The currently installed version or an empty string. The value
695 is taken from the command line argument but may be provided by
696 gpg if not given.
697 status The status of the software package according to this table:
700 - No information available. This is either because no cur‐
702 rent version has been specified or due to an error.
703 ? The given name is not known in the online database.
705 u An update of the software is available.
707 c The installed version of the software is current.
709 n The installed version is already newer than the released
711 version.
712 urgency
715 If the value (the empty string should be considered as zero) is
716 greater than zero an important update is available.
717 error This returns an gpg-error error code to distinguish between var‐
720 ious failure modes.
721 filedate
724 This gives the date of the file with the version numbers in
725 standard ISO format (yyyymmddThhmmss). The date has been
726 extracted by dirmngr from the signature of the file.
727 verified
730 This gives the date in ISO format the file was downloaded. This
731 value can be used to evaluate the freshness of the information.
732 version
735 This returns the version string for the requested software from
736 the file.
737 reldate
740 This returns the release date in ISO format.
741 size This returns the size of the package as decimal number of bytes.
744 hash This returns a hexified SHA-2 hash of the package.
747 More fields may be added in future to the output.
750
754 /etc/gnupg/gpgconf.conf
755 If this file exists, it is processed as a global configuration
756 file.
757 A commented example can be found in the ‘examples’ directory
758 of
759 the distribution.
760 GNUPGHOME/swdb.lst
763 A file with current software versions. dirmngr creates
764 this file on demand from an online resource.
765
768 gpg(1), gpgsm(1), gpg-agent(1), scdaemon(1), dirmngr(1)
769 The full documentation for this tool is maintained as a Texinfo manual.
771 If GnuPG and the info program are properly installed at your site, the
772 command
773 info gnupg
775 should give you access to the complete manual including a menu struc‐
777 ture and an index.
778GnuPG 2.2.9 2018-06-12 GPGCONF(1)