1GPG-CONNECT-AGENT(1)         GNU Privacy Guard 2.4        GPG-CONNECT-AGENT(1)
2
3
4

NAME

6       gpg-connect-agent - Communicate with a running agent
7

SYNOPSIS

9       gpg-connect-agent [options][commands]
10
11

DESCRIPTION

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
71GNUPGHOME’ 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
85ROOT/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

CONTROL COMMANDS

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

SEE ALSO

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.4.3                       2023-06-21              GPG-CONNECT-AGENT(1)
Impressum