148
196
program that uses @command{gpgconf} in this way will be called GUI
149
197
throughout this section.
153
* Invoking gpgconf:: List of all commands and options.
154
* Format conventions:: Formatting conventions relevant for all commands.
155
* Listing components:: List all gpgconf components.
156
* Listing options:: List all options of a component.
157
* Changing options:: Changing options of a component.
200
* Invoking gpgconf:: List of all commands and options.
201
* Format conventions:: Formatting conventions relevant for all commands.
202
* Listing components:: List all gpgconf components.
203
* Checking programs:: Check all programs know to gpgconf.
204
* Listing options:: List all options of a component.
205
* Changing options:: Changing options of a component.
206
* Listing global options:: List all global options.
207
* Files used by gpgconf:: What files are used by gpgconf.
161
211
@node Invoking gpgconf
162
212
@subsection Invoking gpgconf
164
214
@mansect commands
165
215
One of the following commands must be given:
168
217
@table @gnupgtabopt
171
219
@item --list-components
172
220
List all components. This is the default command used if none is
223
@item --check-programs
224
List all available backend programs and test whether they are runnable.
175
226
@item --list-options @var{component}
176
227
List all options of the component @var{component}.
178
229
@item --change-options @var{component}
179
230
Change the options of the component @var{component}.
232
@item --apply-defaults
233
Update all configuration files with values taken from the global
234
configuration file (usually @file{/etc/gnupg/gpgconf.conf}).
236
@item --list-config [@var{filename}]
237
List the global configuration file in a colon separated format. If
238
@var{filename} is given, check that file instead.
240
@item --check-config [@var{filename}]
241
Run a syntax check on the global configuration file. If @var{filename}
242
is given, check that file instead.
185
249
The following options may be used:
188
251
@table @gnupgtabopt
190
252
@c FIXME: Not yet supported.
191
253
@c @item -o @var{file}
192
254
@c @itemx --output @var{file}
370
440
of the component. It can be displayed to the user of the GUI for
371
441
informational purposes. It is @emph{percent-escaped} and
372
442
@emph{localized}.
445
The @emph{string} in this field contains the absolute name of the
446
program's file. It can be used to unambiguously invoke that program.
447
It is @emph{percent-escaped}.
377
452
$ gpgconf --list-components
380
scdaemon:Smartcard Daemon
382
dirmngr:Directory Manager
453
gpg:GPG for OpenPGP:/usr/local/bin/gpg2:
454
gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:
455
scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:
456
gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:
457
dirmngr:Directory Manager:/usr/local/bin/dirmngr:
462
@node Checking programs
463
@subsection Checking programs
465
The command @code{--check-programs} is similar to
466
@code{--list-components} but works on backend programs and not on
467
components. It runs each program to test wether it is installed and
468
runnable. This also includes a syntax check of all config file options
471
The command argument @code{--check-programs} lists all available
472
programs, one per line. The format of each line is:
474
@code{@var{name}:@var{description}:@var{pgmname}:@var{avail}:@var{okay}:@var{cfgfile}:@var{line}:@var{error}:}
478
This field contains a name tag of the program which is identical to the
479
name of the component. The name tag is to be used @emph{verbatim}. It
480
is thus not in any escaped format. This field may be empty to indicate
481
a continuation of error descriptions for the last name. The description
482
and pgmname fields are then also empty.
485
The @emph{string} in this field contains a human-readable description
486
of the component. It can be displayed to the user of the GUI for
487
informational purposes. It is @emph{percent-escaped} and
491
The @emph{string} in this field contains the absolute name of the
492
program's file. It can be used to unambiguously invoke that program.
493
It is @emph{percent-escaped}.
496
The @emph{boolean value} in this field indicates whether the program is
497
installed and runnable.
500
The @emph{boolean value} in this field indicates whether the program's
501
config file is syntactically okay.
504
If an error occured in the configuraion file (as indicated by a false
505
value in the field @code{okay}), this field has the name of the failing
506
configuration file. It is @emph{percent-escaped}.
509
If an error occured in the configuration file, this field has the line
510
number of the failing statement in the configuration file.
511
It is an @emph{unsigned number}.
514
If an error occured in the configuration file, this field has the error
515
text of the failing statement in the configuration file. It is
516
@emph{percent-escaped} and @emph{localized}.
521
In the following example the @command{dirmngr} is not runnable and the
522
configuration file of @command{scdaemon} is not okay.
525
$ gpgconf --check-programs
526
gpg:GPG for OpenPGP:/usr/local/bin/gpg2:1:1:
527
gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:1:1:
528
scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:1:0:
529
gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:1:1:
530
dirmngr:Directory Manager:/usr/local/bin/dirmngr:0:0:
538
702
case a short name is not known.
541
This field is defined only for options. Its format is that of an
542
@emph{option argument} (@xref{Format conventions}, for details). If
543
the default value is empty, then no default is known. Otherwise, the
544
value specifies the default value for this option. Note that this
545
field is also meaningful if the option itself does not take a real
705
This field is defined only for options for which the @code{default} or
706
@code{default desc} flag is set. If the @code{default} flag is set,
707
its format is that of an @emph{option argument} (@xref{Format
708
conventions}, for details). If the default value is empty, then no
709
default is known. Otherwise, the value specifies the default value
710
for this option. If the @code{default desc} flag is set, the field is
711
either empty or contains a description of the effect if the option is
549
715
This field is defined only for options for which the @code{optional
550
716
arg} flag is set. If the @code{no arg desc} flag is not set, its
551
717
format is that of an @emph{option argument} (@xref{Format
552
718
conventions}, for details). If the default value is empty, then no
553
default is known. Otherwise, the value specifies the default value
719
default is known. Otherwise, the value specifies the default argument
554
720
for this option. If the @code{no arg desc} flag is set, the field is
555
721
either empty or contains a description of the effect of this option if
556
no argument is given. Note that this field is also meaningful if the
557
option itself does not take a real argument.
722
no argument is given.
560
725
This field is defined only for options. Its format is that of an
619
785
The @code{--runtime} option can influence when the changes take
789
@node Listing global options
790
@subsection Listing global options
792
Sometimes it is useful for applications to look at the global options
793
file @file{gpgconf.conf}.
794
The colon separated listing format is record oriented and uses the first
795
field to identify the record type:
799
This describes a key record to start the definition of a new ruleset for
800
a user/group. The format of a key record is:
802
@code{k:@var{user}:@var{group}:}
806
This is the user field of the key. It is percent escaped. See the
807
definition of the gpgconf.conf format for details.
810
This is the group field of the key. It is percent escaped.
814
This describes a rule record. All rule records up to the next key record
815
make up a rule set for that key. The format of a rule record is:
817
@code{r:::@var{component}:@var{option}:@var{flags}:@var{value}:}
821
This is the component part of a rule. It is a plain string.
824
This is the option part of a rule. It is a plain string.
827
This is the flags part of a rule. There may be only one flag per rule
828
but by using the same component and option, several flags may be
829
assigned to an option. It is a plain string.
832
This is the optional value for the option. It is a percent escaped
833
string with a single quotation mark to indicate a string. The quotation
834
mark is only required to distinguish between no value specified and an
841
Unknown record typs should be ignored. Note that there is intentionally
842
no feature to change the global option file through @command{gpgconf}.
847
@node Files used by gpgconf
848
@subsection Files used by gpgconf
852
@item /etc/gnupg/gpgconf.conf
854
If this file exists, it is processed as a global configuration file.
855
A commented example can be found in the @file{examples} directory of
864
@command{gpg-agent}(1),
865
@command{scdaemon}(1),
868
@include see-also-note.texi
873
@c APPLYGNUPGDEFAULTS
875
@manpage applygnupgdefaults.8
876
@node applygnupgdefaults
877
@section Run gpgconf for all users.
879
.B applygnupgdefaults
880
\- Run gpgconf --apply-defaults for all users.
885
.B applygnupgdefaults
889
This script is a wrapper around @command{gpgconf} to run it with the
890
command @code{--apply-defaults} for all real users with an existing
891
GnuPG home directory. Admins might want to use this script to update he
892
GnuPG configuration files for all users after
893
@file{/etc/gnupg/gpgconf.conf} has been changed. This allows to enforce
894
certain policies for all users. Note, that this is not a bulletproof of
895
forcing a user to use certain options. A user may always directly edit
896
the configuration files and bypass gpgconf.
899
@command{applygnupgdefaults} is invoked by root as:
624
907
@c GPGSM-GENCERT.SH
626
909
@node gpgsm-gencert.sh
627
910
@section Generate an X.509 certificate request
911
@manpage gpgsm-gencert.sh.1
914
\- Generate an X.509 certificate request
629
923
This is a simple tool to interactivly generate a certificate request
630
924
which will be printed to stdout.
633
928
@command{gpgsm-gencert.sh} is invoked as:
635
930
@samp{gpgsm-cencert.sh}
935
@command{gpg-agent}(1),
936
@command{scdaemon}(1)
938
@include see-also-note.texi
771
1105
Do not run any special initializations or environment checks. This may
772
1106
be used to directly connect to any Assuan style socket server.
1111
Take the rest of the command line as a program and it's arguments and
1112
execute it as an assuan server. Here is how you would run @command{gpgsm}:
1114
gpg-connect-agent --exec gpgsm --server
1118
@item --no-ext-connect
1119
@opindex no-ext-connect
1120
When using @option{-S} or @option{--exec}, @command{gpg-connect-agent}
1121
connects to the assuan server in extended mode to allow descriptor
1122
passing. This option makes it use the old mode.
1124
@item --run @var{file}
1126
Run the commands from @var{file} at startup and then continue with the
1127
regular input method.
1132
Run the command @code{/subst} at startup.
1136
Print data lines in a hex format and the ASCII representation of
1137
non-control characters.
1141
Decode data lines. That is to remove percent escapes but make sure that
1142
a new line always starts with a D and a space.
1146
@mansect control commands
1147
@node Controlling gpg-connect-agent
1148
@subsection Control commands.
1150
While reading Assuan commands, gpg-agent also allows a few special
1151
commands to control its operation. These control commands all start
1152
with a slash (@code{/}).
1156
@item /echo @var{args}
1157
Just print @var{args}.
1159
@item /let @var{name} @var{value}
1160
Set the variable @var{name} to @var{value}. Variables are only
1161
substituted on the input if the @command{/subst} has been used.
1162
Variables are referenced by prefixing the name with a dollr sign and
1163
optionally include the name in curly braces. The rules for a valid name
1164
are idnetically to those of the standard bourne shell. This is not yet
1165
enforced but may be in the future. When used with curly braces no
1166
leading or trailing white space is allowed.
1168
If a variable is not found, it is searched in the environment and if
1169
found copied to the table of variables.
1171
Variable functions are available: The name of the function must be
1172
followed by at least one space and the at least one argument. The
1173
following functions are available:
1177
Return a value described by the argument. Available arguments are:
1181
The current working directory.
1185
GnuPG's system configuration directory.
1187
GnuPG's binary directory.
1189
GnuPG's library directory.
1191
GnuPG's library directory for executable files.
1193
GnuPG's data directory.
1195
The PID of the current server. Command @command{/serverpid} must
1196
have been given to return a useful value.
1199
@item unescape @var{args}
1200
Remove C-style escapes from @var{args}. Note that @code{\0} and
1201
@code{\x00} terminate the returned string implicitly. The string to be
1202
converted are the entire arguments right behind the delimiting space of
1205
@item unpercent @var{args}
1206
@itemx unpercent+ @var{args}
1207
Remove percent style ecaping from @var{args}. Note that @code{%00}
1208
terminates the string implicitly. The string to be converted are the
1209
entire arguments right behind the delimiting space of the function
1210
name. @code{unpercent+} also maps plus signs to a spaces.
1212
@item percent @var{args}
1213
@itemx percent+ @var{args}
1214
Escape the @var{args} using percent style ecaping. Tabs, formfeeds,
1215
linefeeds, carriage returns and colons are escaped. @code{percent+} also
1216
maps spaces to plus signs.
1218
@item errcode @var{arg}
1219
@itemx errsource @var{arg}
1220
@itemx errstring @var{arg}
1221
Assume @var{arg} is an integer and evaluate it using @code{strtol}. Return
1222
the gpg-error error code, error source or a formatted string with the
1223
error code and error source.
1231
Evaluate all arguments as long integers using @code{strtol} and apply
1232
this operator. A division by zero yields an empty string.
1237
Evaluate all arguments as long integers using @code{strtol} and apply
1238
the logical oeprators NOT, OR or AND. The NOT operator works on the
1245
@item /definq @var{name} @var{var}
1246
Use content of the variable @var{var} for inquiries with @var{name}.
1247
@var{name} may be an asterisk (@code{*}) to match any inquiry.
1250
@item /definqfile @var{name} @var{file}
1251
Use content of @var{file} for inquiries with @var{name}.
1252
@var{name} may be an asterisk (@code{*}) to match any inquiry.
1254
@item /definqprog @var{name} @var{prog}
1255
Run @var{prog} for inquiries matching @var{name} and pass the
1256
entire line to it as command line arguments.
1259
Print all definitions
1262
Delete all definitions
1264
@item /sendfd @var{file} @var{mode}
1265
Open @var{file} in @var{mode} (which needs to be a valid @code{fopen}
1266
mode string) and send the file descriptor to the server. This is
1267
usually followed by a command like @code{INPUT FD} to set the
1268
input source for other commands.
1271
Not yet implemented.
1273
@item /open @var{var} @var{file} [@var{mode}]
1274
Open @var{file} and assign the file descriptor to @var{var}. Warning:
1275
This command is experimental and might change in future versions.
1277
@item /close @var{fd}
1278
Close the file descriptor @var{fd}. Warning: This command is
1279
experimental and might change in future versions.
1282
Show a listy of open files.
1285
Send the Assuan command @command{GETINFO pid} to the server and store
1286
the returned PID for internal purposes.
1293
Same as the command line option @option{--hex}.
1297
Same as the command line option @option{--decode}.
1301
Enable and disable variable substitution. It defaults to disabled
1302
unless the command line option @option{--subst} has been used.
1303
If /subst as been enabled once, leading whitespace is removed from
1304
input lines which makes scripts easier to read.
1306
@item /while @var{condition}
1308
These commands provide a way for executing loops. All lines between the
1309
@code{while} and the corresponding @code{end} are executed as long as
1310
the evaluation of @var{condition} yields a non-zero value. The
1311
evaluation is done by passing @var{condition} to the @code{strtol}
1318
/echo loop couter is $i
1324
@item /run @var{file}
1325
Run commands from @var{file}.
1328
Terminate the connection and the program
1331
Print a list of available control commands.
1338
@command{gpg-agent}(1),
1339
@command{scdaemon}(1)
1340
@include see-also-note.texi
added
removed
doc/tools.texi
