1GPG-CONNECT-AGENT(1) GNU Privacy Guard 2.2 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
157 While reading Assuan commands, gpg-agent also allows a few special com‐
158 mands to control its operation. These control commands all start with
159 a slash (/).
160 /echo args
164 Just print args.
165 /let name value
168 Set the variable name to value. Variables are only substituted
169 on the input if the /subst has been used. Variables are refer‐
170 enced by prefixing the name with a dollar sign and optionally
171 include the name in curly braces. The rules for a valid name
172 are identically to those of the standard bourne shell. This is
173 not yet enforced but may be in the future. When used with curly
174 braces no leading or trailing white space is allowed.
175 If a variable is not found, it is searched in the environment
177 and if found copied to the table of variables.
178 Variable functions are available: The name of the function must
180 be followed by at least one space and the at least one argument.
181 The following functions are available:
182 get Return a value described by the argument. Available ar‐
185 guments are:
186 cwd The current working directory.
189 homedir
191 The gnupg homedir.
192 sysconfdir
194 GnuPG's system configuration directory.
195 bindir GnuPG's binary directory.
197 libdir GnuPG's library directory.
199 libexecdir
201 GnuPG's library directory for executable files.
202 datadir
204 GnuPG's data directory.
205 serverpid
207 The PID of the current server. Command /serverpid
208 must have been given to return a useful value.
209 unescape args
212 Remove C-style escapes from args. Note that \0 and \x00
213 terminate the returned string implicitly. The string to
214 be converted are the entire arguments right behind the
215 delimiting space of the function name.
216 unpercent args
219 unpercent+ args
220 Remove percent style escaping from args. Note that %00
221 terminates the string implicitly. The string to be con‐
222 verted are the entire arguments right behind the delimit‐
223 ing space of the function name. unpercent+ also maps plus
224 signs to a spaces.
225 percent args
228 percent+ args
229 Escape the args using percent style escaping. Tabs,
230 formfeeds, linefeeds, carriage returns and colons are es‐
231 caped. percent+ also maps spaces to plus signs.
232 errcode arg
235 errsource arg
236 errstring arg
237 Assume arg is an integer and evaluate it using strtol.
238 Return the gpg-error error code, error source or a for‐
239 matted string with the error code and error source.
240 +
244 -
245 *
246 /
247 % Evaluate all arguments as long integers using strtol and
248 apply this operator. A division by zero yields an empty
249 string.
250 !
253 |
254 & Evaluate all arguments as long integers using strtol and
255 apply the logical operators NOT, OR or AND. The NOT op‐
256 erator works on the last argument only.
257 /definq name var
263 Use content of the variable var for inquiries with name. name
264 may be an asterisk (*) to match any inquiry.
265 /definqfile name file
269 Use content of file for inquiries with name. name may be an as‐
270 terisk (*) to match any inquiry.
271 /definqprog name prog
274 Run prog for inquiries matching name and pass the entire line to
275 it as command line arguments.
276 /datafile name
279 Write all data lines from the server to the file name. The file
280 is opened for writing and created if it does not exists. An ex‐
281 isting file is first truncated to 0. The data written to the
282 file fully decoded. Using a single dash for name writes to std‐
283 out. The file is kept open until a new file is set using this
284 command or this command is used without an argument.
285 /showdef
288 Print all definitions
289 /cleardef
292 Delete all definitions
293 /sendfd file mode
296 Open file in mode (which needs to be a valid fopen mode string)
297 and send the file descriptor to the server. This is usually
298 followed by a command like INPUT FD to set the input source for
299 other commands.
300 /recvfd
303 Not yet implemented.
304 /open var file [mode]
307 Open file and assign the file descriptor to var. Warning: This
308 command is experimental and might change in future versions.
309 /close fd
312 Close the file descriptor fd. Warning: This command is experi‐
313 mental and might change in future versions.
314 /showopen
317 Show a list of open files.
318 /serverpid
321 Send the Assuan command GETINFO pid to the server and store the
322 returned PID for internal purposes.
323 /sleep Sleep for a second.
326 /hex
329 /nohex Same as the command line option --hex.
330 /decode
333 /nodecode
334 Same as the command line option --decode.
335 /subst
338 /nosubst
339 Enable and disable variable substitution. It defaults to dis‐
340 abled unless the command line option --subst has been used. If
341 /subst as been enabled once, leading whitespace is removed from
342 input lines which makes scripts easier to read.
343 /while condition
346 /end These commands provide a way for executing loops. All lines be‐
347 tween the while and the corresponding end are executed as long
348 as the evaluation of condition yields a non-zero value or is the
349 string true or yes. The evaluation is done by passing condition
350 to the strtol function. Example:
351 /subst
353 /let i 3
354 /while $i
355 /echo loop counter is $i
356 /let i ${- $i 1}
357 /end
358 /if condition
361 /end These commands provide a way for conditional execution. All
362 lines between the if and the corresponding end are executed only
363 if the evaluation of condition yields a non-zero value or is the
364 string true or yes. The evaluation is done by passing condition
365 to the strtol function.
366 /run file
369 Run commands from file.
370 /history --clear
373 Clear the command history.
374 /bye Terminate the connection and the program.
377 /help Print a list of available control commands.
380
383 gpg-agent(1), scdaemon(1)
384 The full documentation for this tool is maintained as a Texinfo manual.
386 If GnuPG and the info program are properly installed at your site, the
387 command
388 info gnupg
390 should give you access to the complete manual including a menu struc‐
392 ture and an index.
393GnuPG 2.3.3 2021-10-06 GPG-CONNECT-AGENT(1)