1GPG-CONNECT-AGENT(1)         GNU Privacy Guard 2.2        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
16       applications.  Input is expected at stdin and output  gets  printed  to
17       stdout.
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       -v
29       --verbose
30              Output additional information while running.
31
32
33       -q
34
35       --quiet
36              Try to be as quiet as possible.
37
38
39       --homedir dir
40              Set the name of the home directory to dir. If this option is not
41              used,  the  home  directory  defaults to ‘~/.gnupg’.  It is only
42              recognized when given on the command line.   It  also  overrides
43              any  home  directory  stated  through  the  environment variable
44GNUPGHOME’ or (on Windows systems) by  means  of  the  Registry
45              entry HKCU\Software\GNU\GnuPG:HomeDir.
46
47              On Windows systems it is possible to install GnuPG as a portable
48              application.  In this case only this command line option is con‐
49              sidered, all other ways to set a home directory are ignored.
50
51              To install GnuPG as a portable application under Windows, create
52              an empty file named ‘gpgconf.ctl’ in the same directory  as  the
53              tool  ‘gpgconf.exe’.   The root of the installation is then that
54              directory; or, if  ‘gpgconf.exe’  has  been  installed  directly
55              below  a  directory named ‘bin’, its parent directory.  You also
56              need to make sure that the following directories exist  and  are
57              writable:     ‘ROOT/home’     for    the    GnuPG    home    and
58ROOT/var/cache/gnupg’ for internal cache files.
59
60
61       --agent-program file
62              Specify the agent program to be started if none is running.  The
63              default  value  is determined by running gpgconf with the option
64              --list-dirs.  Note that the  pipe  symbol  (|)  is  used  for  a
65              regression  test suite hack and may thus not be used in the file
66              name.
67
68
69       --dirmngr-program file
70              Specify the directory manager (keyserver client) program  to  be
71              started  if  none  is  running.  This has only an effect if used
72              together with the option --dirmngr.
73
74
75       --dirmngr
76              Connect  to  a  running  directory  manager  (keyserver  client)
77              instead of to the gpg-agent.  If a dirmngr is not running, start
78              it.
79
80
81       -S
82       --raw-socket name
83              Connect to socket name assuming this is an Assuan style  server.
84              Do  not  run  any special initializations or environment checks.
85              This may be used to directly connect to any Assuan style  socket
86              server.
87
88
89       -E
90       --exec Take  the  rest  of the command line as a program and it's argu‐
91              ments and execute it as an Assuan server. Here is how you  would
92              run gpgsm:
93          gpg-connect-agent --exec gpgsm --server
94       Note that you may not use options on the command line in this case.
95
96
97       --no-ext-connect
98              When  using  -S  or  --exec,  gpg-connect-agent  connects to the
99              Assuan server in extended  mode  to  allow  descriptor  passing.
100              This option makes it use the old mode.
101
102
103       --no-autostart
104              Do not start the gpg-agent or the dirmngr if it has not yet been
105              started.
106
107
108       -r file
109       --run file
110              Run the commands from file at startup and then continue with the
111              regular  input method.  Note, that commands given on the command
112              line are executed after this file.
113
114
115       -s
116       --subst
117              Run the command /subst at startup.
118
119
120       --hex  Print data lines in a hex format and the ASCII representation of
121              non-control characters.
122
123
124       --decode
125              Decode  data  lines.  That is to remove percent escapes but make
126              sure that a new line always starts with a D and a space.
127
128

CONTROL COMMANDS

130       While reading Assuan commands, gpg-agent also allows a few special com‐
131       mands  to control its operation.  These control commands all start with
132       a slash (/).
133
134
135
136       /echo args
137              Just print args.
138
139
140       /let name value
141              Set the variable name to value.  Variables are only  substituted
142              on  the input if the /subst has been used.  Variables are refer‐
143              enced by prefixing the name with a dollar  sign  and  optionally
144              include  the  name  in curly braces.  The rules for a valid name
145              are identically to those of the standard bourne shell.  This  is
146              not yet enforced but may be in the future.  When used with curly
147              braces no leading or trailing white space is allowed.
148
149              If a variable is not found, it is searched  in  the  environment
150              and if found copied to the table of variables.
151
152              Variable  functions are available: The name of the function must
153              be followed by at least one space and the at least one argument.
154              The following functions are available:
155
156
157              get    Return  a  value  described  by  the argument.  Available
158                     arguments are:
159
160
161                     cwd    The current working directory.
162
163                     homedir
164                            The gnupg homedir.
165
166                     sysconfdir
167                            GnuPG's system configuration directory.
168
169                     bindir GnuPG's binary directory.
170
171                     libdir GnuPG's library directory.
172
173                     libexecdir
174                            GnuPG's library directory for executable files.
175
176                     datadir
177                            GnuPG's data directory.
178
179                     serverpid
180                            The PID of the current server. Command  /serverpid
181                            must have been given to return a useful value.
182
183
184              unescape args
185                     Remove  C-style escapes from args.  Note that \0 and \x00
186                     terminate the returned string implicitly.  The string  to
187                     be  converted  are  the entire arguments right behind the
188                     delimiting space of the function name.
189
190
191              unpercent args
192              unpercent+ args
193                     Remove percent style escaping from args.  Note  that  %00
194                     terminates  the string implicitly.  The string to be con‐
195                     verted are the entire arguments right behind the delimit‐
196                     ing space of the function name. unpercent+ also maps plus
197                     signs to a spaces.
198
199
200              percent args
201              percent+ args
202                     Escape the args  using  percent  style  escaping.   Tabs,
203                     formfeeds,  linefeeds,  carriage  returns  and colons are
204                     escaped. percent+ also maps spaces to plus signs.
205
206
207              errcode arg
208              errsource arg
209              errstring arg
210                     Assume arg is an integer and evaluate  it  using  strtol.
211                     Return  the  gpg-error error code, error source or a for‐
212                     matted string with the error code and error source.
213
214
215
216              +
217              -
218              *
219              /
220              %      Evaluate all arguments as long integers using strtol  and
221                     apply  this operator.  A division by zero yields an empty
222                     string.
223
224
225              !
226              |
227              &      Evaluate all arguments as long integers using strtol  and
228                     apply  the  logical  operators  NOT,  OR or AND.  The NOT
229                     operator works on the last argument only.
230
231
232
233
234
235       /definq name var
236              Use content of the variable var for inquiries with  name.   name
237              may be an asterisk (*) to match any inquiry.
238
239
240
241       /definqfile name file
242              Use  content  of  file  for inquiries with name.  name may be an
243              asterisk (*) to match any inquiry.
244
245
246       /definqprog name prog
247              Run prog for inquiries matching name and pass the entire line to
248              it as command line arguments.
249
250
251       /datafile name
252              Write all data lines from the server to the file name.  The file
253              is opened for writing and created if it  does  not  exists.   An
254              existing  file is first truncated to 0.  The data written to the
255              file fully decoded.  Using a single dash for name writes to std‐
256              out.   The  file is kept open until a new file is set using this
257              command or this command is used without an argument.
258
259
260       /showdef
261              Print all definitions
262
263
264       /cleardef
265              Delete all definitions
266
267
268       /sendfd file mode
269              Open file in mode (which needs to be a valid fopen mode  string)
270              and  send  the  file  descriptor to the server.  This is usually
271              followed by a command like INPUT FD to set the input source  for
272              other commands.
273
274
275       /recvfd
276              Not yet implemented.
277
278
279       /open var file [mode]
280              Open  file and assign the file descriptor to var.  Warning: This
281              command is experimental and might change in future versions.
282
283
284       /close fd
285              Close the file descriptor fd.  Warning: This command is  experi‐
286              mental and might change in future versions.
287
288
289       /showopen
290              Show a list of open files.
291
292
293       /serverpid
294              Send  the Assuan command GETINFO pid to the server and store the
295              returned PID for internal purposes.
296
297
298       /sleep Sleep for a second.
299
300
301       /hex
302       /nohex Same as the command line option --hex.
303
304
305       /decode
306       /nodecode
307              Same as the command line option --decode.
308
309
310       /subst
311       /nosubst
312              Enable and disable variable substitution.  It defaults  to  dis‐
313              abled  unless the command line option --subst has been used.  If
314              /subst as been enabled once, leading whitespace is removed  from
315              input lines which makes scripts easier to read.
316
317
318       /while condition
319       /end   These  commands  provide  a  way for executing loops.  All lines
320              between the while and the corresponding end are executed as long
321              as the evaluation of condition yields a non-zero value or is the
322              string true or yes.  The evaluation is done by passing condition
323              to the strtol function.  Example:
324
325           /subst
326           /let i 3
327           /while $i
328             /echo loop counter is $i
329             /let i ${- $i 1}
330           /end
331
332
333       /if condition
334       /end   These  commands  provide  a  way for conditional execution.  All
335              lines between the if and the corresponding end are executed only
336              if the evaluation of condition yields a non-zero value or is the
337              string true or yes.  The evaluation is done by passing condition
338              to the strtol function.
339
340
341       /run file
342              Run commands from file.
343
344
345       /bye   Terminate the connection and the program.
346
347
348       /help  Print a list of available control commands.
349
350

SEE ALSO

352       gpg-agent(1), scdaemon(1)
353
354       The full documentation for this tool is maintained as a Texinfo manual.
355       If GnuPG and the info program are properly installed at your site,  the
356       command
357
358         info gnupg
359
360       should  give  you access to the complete manual including a menu struc‐
361       ture and an index.
362
363
364
365
366
367GnuPG 2.2.20                      2020-03-18              GPG-CONNECT-AGENT(1)
Impressum