1GPG-CONNECT-AGENT(1) GNU Privacy Guard 2.3 GPG-CONNECT-AGENT(1)
2
6 gpg-connect-agent - Communicate with a running agent
7
9 gpg-connect-agent [options][commands]
10
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 It is very similar to running gpg-agent in server mode; but here we
20 connect to a running instance.
21 The following options may be used:
26 --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 --keyboxd
35 Connect to a running keybox daemon instead of to the gpg-agent.
36 If a keyboxd is not running, start it.
37 -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 -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 -v
56 --verbose
57 Output additional information while running.
58 -q
61 --quiet
63 Try to be as quiet as possible.
64 --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 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 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 --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 --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 --no-autostart
105 Do not start the gpg-agent or the dirmngr if it has not yet been
106 started.
107 --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 --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 --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 --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 -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 -s
143 --subst
144 Run the command /subst at startup.
145 --hex Print data lines in a hex format and the ASCII representation of
148 non-control characters.
149 --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 -u
157 --unbuffered
158 Set stdin and stdout into unbuffered I/O mode. This this some‐
159 times useful for scripting.
160
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 /echo args
171 Just print args.
172 /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 If a variable is not found, it is searched in the environment
184 and if found copied to the table of variables.
185 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 get Return a value described by the argument. Available ar‐
192 guments are:
193 cwd The current working directory.
196 homedir
198 The gnupg homedir.
199 sysconfdir
201 GnuPG's system configuration directory.
202 bindir GnuPG's binary directory.
204 libdir GnuPG's library directory.
206 libexecdir
208 GnuPG's library directory for executable files.
209 datadir
211 GnuPG's data directory.
212 serverpid
214 The PID of the current server. Command /serverpid
215 must have been given to return a useful value.
216 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 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 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 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 +
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 !
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 /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 /definqfile name file
276 Use content of file for inquiries with name. name may be an as‐
277 terisk (*) to match any inquiry.
278 /definqprog name prog
281 Run prog for inquiries matching name and pass the entire line to
282 it as command line arguments.
283 /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 /showdef
295 Print all definitions
296 /cleardef
299 Delete all definitions
300 /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 /recvfd
310 Not yet implemented.
311 /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 /close fd
319 Close the file descriptor fd. Warning: This command is experi‐
320 mental and might change in future versions.
321 /showopen
324 Show a list of open files.
325 /serverpid
328 Send the Assuan command GETINFO pid to the server and store the
329 returned PID for internal purposes.
330 /sleep Sleep for a second.
333 /hex
336 /nohex Same as the command line option --hex.
337 /decode
340 /nodecode
341 Same as the command line option --decode.
342 /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 /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 /subst
360 /let i 3
361 /while $i
362 /echo loop counter is $i
363 /let i ${- $i 1}
364 /end
365 /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 /run file
376 Run commands from file.
377 /history --clear
380 Clear the command history.
381 /bye Terminate the connection and the program.
384 /help Print a list of available control commands.
387
390 gpg-agent(1), scdaemon(1)
391 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 info gnupg
397 should give you access to the complete manual including a menu struc‐
399 ture and an index.
400GnuPG 2.4.0 2022-12-16 GPG-CONNECT-AGENT(1)