1GPG-CONNECT-AGENT(1) GNU Privacy Guard 2.3 GPG-CONNECT-AGENT(1)
2
3
4
6 gpg-connect-agent - Communicate with a running agent
7
9 gpg-connect-agent [options][commands]
10
11
13 The gpg-connect-agent is a utility to communicate with a running gpg-
14 agent. It is useful to check out the commands gpg-agent provides using
15 the Assuan interface. It might also be useful for scripting simple ap‐
16 plications. Input is expected at stdin and output gets printed to std‐
17 out.
18
19 It is very similar to running gpg-agent in server mode; but here we
20 connect to a running instance.
21
22
23
24
25 The following options may be used:
26
27
28 --dirmngr
29 Connect to a running directory manager (keyserver client) in‐
30 stead of to the gpg-agent. If a dirmngr is not running, start
31 it.
32
33
34 --keyboxd
35 Connect to a running keybox daemon instead of to the gpg-agent.
36 If a keyboxd is not running, start it.
37
38
39 -S
40 --raw-socket name
41 Connect to socket name assuming this is an Assuan style server.
42 Do not run any special initializations or environment checks.
43 This may be used to directly connect to any Assuan style socket
44 server.
45
46
47 -E
48 --exec Take the rest of the command line as a program and it's argu‐
49 ments and execute it as an Assuan server. Here is how you would
50 run gpgsm:
51 gpg-connect-agent --exec gpgsm --server
52 Note that you may not use options on the command line in this case.
53
54
55 -v
56 --verbose
57 Output additional information while running.
58
59
60 -q
61
62 --quiet
63 Try to be as quiet as possible.
64
65
66 --homedir dir
67 Set the name of the home directory to dir. If this option is not
68 used, the home directory defaults to ‘~/.gnupg’. It is only
69 recognized when given on the command line. It also overrides
70 any home directory stated through the environment variable
71 ‘GNUPGHOME’ or (on Windows systems) by means of the Registry en‐
72 try HKCU\Software\GNU\GnuPG:HomeDir.
73
74 On Windows systems it is possible to install GnuPG as a portable
75 application. In this case only this command line option is con‐
76 sidered, all other ways to set a home directory are ignored.
77
78 To install GnuPG as a portable application under Windows, create
79 an empty file named ‘gpgconf.ctl’ in the same directory as the
80 tool ‘gpgconf.exe’. The root of the installation is then that
81 directory; or, if ‘gpgconf.exe’ has been installed directly be‐
82 low a directory named ‘bin’, its parent directory. You also
83 need to make sure that the following directories exist and are
84 writable: ‘ROOT/home’ for the GnuPG home and
85 ‘ROOT/var/cache/gnupg’ for internal cache files.
86
87
88 --chuid uid
89 Change the current user to uid which may either be a number or a
90 name. This can be used from the root account to run gpg-con‐
91 nect-agent for another user. If uid is not the current UID a
92 standard PATH is set and the envvar GNUPGHOME is unset. To
93 override the latter the option --homedir can be used. This op‐
94 tion has only an effect when used on the command line. This op‐
95 tion has currently no effect at all on Windows.
96
97
98 --no-ext-connect
99 When using -S or --exec, gpg-connect-agent connects to the As‐
100 suan server in extended mode to allow descriptor passing. This
101 option makes it use the old mode.
102
103
104 --no-autostart
105 Do not start the gpg-agent or the dirmngr if it has not yet been
106 started.
107
108
109 --no-history
110 In interactive mode the command line history is usually saved
111 and restored to and from a file below the GnuPG home directory.
112 This option inhibits the use of that file.
113
114
115 --agent-program file
116 Specify the agent program to be started if none is running. The
117 default value is determined by running gpgconf with the option
118 --list-dirs. Note that the pipe symbol (|) is used for a re‐
119 gression test suite hack and may thus not be used in the file
120 name.
121
122
123 --dirmngr-program file
124 Specify the directory manager (keyserver client) program to be
125 started if none is running. This has only an effect if used to‐
126 gether with the option --dirmngr.
127
128
129 --keyboxd-program file
130 Specify the keybox daemon program to be started if none is run‐
131 ning. This has only an effect if used together with the option
132 --keyboxd.
133
134
135 -r file
136 --run file
137 Run the commands from file at startup and then continue with the
138 regular input method. Note, that commands given on the command
139 line are executed after this file.
140
141
142 -s
143 --subst
144 Run the command /subst at startup.
145
146
147 --hex Print data lines in a hex format and the ASCII representation of
148 non-control characters.
149
150
151 --decode
152 Decode data lines. That is to remove percent escapes but make
153 sure that a new line always starts with a D and a space.
154
155
156 -u
157 --unbuffered
158 Set stdin and stdout into unbuffered I/O mode. This this some‐
159 times useful for scripting.
160
161
162
164 While reading Assuan commands, gpg-agent also allows a few special com‐
165 mands to control its operation. These control commands all start with
166 a slash (/).
167
168
169
170 /echo args
171 Just print args.
172
173
174 /let name value
175 Set the variable name to value. Variables are only substituted
176 on the input if the /subst has been used. Variables are refer‐
177 enced by prefixing the name with a dollar sign and optionally
178 include the name in curly braces. The rules for a valid name
179 are identically to those of the standard bourne shell. This is
180 not yet enforced but may be in the future. When used with curly
181 braces no leading or trailing white space is allowed.
182
183 If a variable is not found, it is searched in the environment
184 and if found copied to the table of variables.
185
186 Variable functions are available: The name of the function must
187 be followed by at least one space and the at least one argument.
188 The following functions are available:
189
190
191 get Return a value described by the argument. Available ar‐
192 guments are:
193
194
195 cwd The current working directory.
196
197 homedir
198 The gnupg homedir.
199
200 sysconfdir
201 GnuPG's system configuration directory.
202
203 bindir GnuPG's binary directory.
204
205 libdir GnuPG's library directory.
206
207 libexecdir
208 GnuPG's library directory for executable files.
209
210 datadir
211 GnuPG's data directory.
212
213 serverpid
214 The PID of the current server. Command /serverpid
215 must have been given to return a useful value.
216
217
218 unescape args
219 Remove C-style escapes from args. Note that \0 and \x00
220 terminate the returned string implicitly. The string to
221 be converted are the entire arguments right behind the
222 delimiting space of the function name.
223
224
225 unpercent args
226 unpercent+ args
227 Remove percent style escaping from args. Note that %00
228 terminates the string implicitly. The string to be con‐
229 verted are the entire arguments right behind the delimit‐
230 ing space of the function name. unpercent+ also maps plus
231 signs to a spaces.
232
233
234 percent args
235 percent+ args
236 Escape the args using percent style escaping. Tabs,
237 formfeeds, linefeeds, carriage returns and colons are es‐
238 caped. percent+ also maps spaces to plus signs.
239
240
241 errcode arg
242 errsource arg
243 errstring arg
244 Assume arg is an integer and evaluate it using strtol.
245 Return the gpg-error error code, error source or a for‐
246 matted string with the error code and error source.
247
248
249
250 +
251 -
252 *
253 /
254 % Evaluate all arguments as long integers using strtol and
255 apply this operator. A division by zero yields an empty
256 string.
257
258
259 !
260 |
261 & Evaluate all arguments as long integers using strtol and
262 apply the logical operators NOT, OR or AND. The NOT op‐
263 erator works on the last argument only.
264
265
266
267
268
269 /definq name var
270 Use content of the variable var for inquiries with name. name
271 may be an asterisk (*) to match any inquiry.
272
273
274
275 /definqfile name file
276 Use content of file for inquiries with name. name may be an as‐
277 terisk (*) to match any inquiry.
278
279
280 /definqprog name prog
281 Run prog for inquiries matching name and pass the entire line to
282 it as command line arguments.
283
284
285 /datafile name
286 Write all data lines from the server to the file name. The file
287 is opened for writing and created if it does not exists. An ex‐
288 isting file is first truncated to 0. The data written to the
289 file fully decoded. Using a single dash for name writes to std‐
290 out. The file is kept open until a new file is set using this
291 command or this command is used without an argument.
292
293
294 /showdef
295 Print all definitions
296
297
298 /cleardef
299 Delete all definitions
300
301
302 /sendfd file mode
303 Open file in mode (which needs to be a valid fopen mode string)
304 and send the file descriptor to the server. This is usually
305 followed by a command like INPUT FD to set the input source for
306 other commands.
307
308
309 /recvfd
310 Not yet implemented.
311
312
313 /open var file [mode]
314 Open file and assign the file descriptor to var. Warning: This
315 command is experimental and might change in future versions.
316
317
318 /close fd
319 Close the file descriptor fd. Warning: This command is experi‐
320 mental and might change in future versions.
321
322
323 /showopen
324 Show a list of open files.
325
326
327 /serverpid
328 Send the Assuan command GETINFO pid to the server and store the
329 returned PID for internal purposes.
330
331
332 /sleep Sleep for a second.
333
334
335 /hex
336 /nohex Same as the command line option --hex.
337
338
339 /decode
340 /nodecode
341 Same as the command line option --decode.
342
343
344 /subst
345 /nosubst
346 Enable and disable variable substitution. It defaults to dis‐
347 abled unless the command line option --subst has been used. If
348 /subst as been enabled once, leading whitespace is removed from
349 input lines which makes scripts easier to read.
350
351
352 /while condition
353 /end These commands provide a way for executing loops. All lines be‐
354 tween the while and the corresponding end are executed as long
355 as the evaluation of condition yields a non-zero value or is the
356 string true or yes. The evaluation is done by passing condition
357 to the strtol function. Example:
358
359 /subst
360 /let i 3
361 /while $i
362 /echo loop counter is $i
363 /let i ${- $i 1}
364 /end
365
366
367 /if condition
368 /end These commands provide a way for conditional execution. All
369 lines between the if and the corresponding end are executed only
370 if the evaluation of condition yields a non-zero value or is the
371 string true or yes. The evaluation is done by passing condition
372 to the strtol function.
373
374
375 /run file
376 Run commands from file.
377
378
379 /history --clear
380 Clear the command history.
381
382
383 /bye Terminate the connection and the program.
384
385
386 /help Print a list of available control commands.
387
388
390 gpg-agent(1), scdaemon(1)
391
392 The full documentation for this tool is maintained as a Texinfo manual.
393 If GnuPG and the info program are properly installed at your site, the
394 command
395
396 info gnupg
397
398 should give you access to the complete manual including a menu struc‐
399 ture and an index.
400
401
402
403
404
405GnuPG 2.3.8 2022-10-07 GPG-CONNECT-AGENT(1)