539 lines
13 KiB
HTML
539 lines
13 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of GPG-CONNECT-AGENT</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>GPG-CONNECT-AGENT</H1>
|
|
Section: GNU Privacy Guard 2.2 (1)<BR>Updated: 2019-11-23<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
<B>gpg-connect-agent</B>
|
|
|
|
- Communicate with a running agent
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>gpg-connect-agent</B>
|
|
|
|
[<I>options</I>]<I>[commands]</I>
|
|
|
|
<P>
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
The <B>gpg-connect-agent</B> is a utility to communicate with a
|
|
running <B>gpg-agent</B>. It is useful to check out the commands
|
|
<B>gpg-agent</B> provides using the Assuan interface. It might
|
|
also be useful for scripting simple applications. Input is expected
|
|
at stdin and output gets printed to stdout.
|
|
<P>
|
|
It is very similar to running <B>gpg-agent</B> in server mode; but
|
|
here we connect to a running instance.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
The following options may be used:
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT id="1"><B>-v</B>
|
|
|
|
<DD>
|
|
|
|
<B>--verbose</B>
|
|
|
|
Output additional information while running.
|
|
<P>
|
|
<DT id="2"><B>-q</B>
|
|
|
|
<DD>
|
|
<DT id="3"><B>--quiet</B>
|
|
|
|
<DD>
|
|
Try to be as quiet as possible.
|
|
<P>
|
|
<DT id="4"><B>--homedir </B><I>dir</I>
|
|
|
|
<DD>
|
|
Set the name of the home directory to <I>dir</I>. If this option is not
|
|
used, the home directory defaults to '<I>~/.gnupg</I>'. It is only
|
|
recognized when given on the command line. It also overrides any home
|
|
directory stated through the environment variable '<I>GNUPGHOME</I>' or
|
|
(on Windows systems) by means of the Registry entry
|
|
<I>HKCU\Software\GNU\GnuPG:HomeDir</I>.
|
|
<P>
|
|
On Windows systems it is possible to install GnuPG as a portable
|
|
application. In this case only this command line option is
|
|
considered, all other ways to set a home directory are ignored.
|
|
<P>
|
|
To install GnuPG as a portable application under Windows, create an
|
|
empty file named '<I>gpgconf.ctl</I>' in the same directory as the tool
|
|
'<I>gpgconf.exe</I>'. The root of the installation is then that
|
|
directory; or, if '<I>gpgconf.exe</I>' has been installed directly below
|
|
a directory named '<I>bin</I>', its parent directory. You also need to
|
|
make sure that the following directories exist and are writable:
|
|
'<I>ROOT/home</I>' for the GnuPG home and '<I>ROOT/var/cache/gnupg</I>'
|
|
for internal cache files.
|
|
<P>
|
|
<DT id="5"><B>--agent-program </B><I>file</I>
|
|
|
|
<DD>
|
|
Specify the agent program to be started if none is running. The
|
|
default value is determined by running <B>gpgconf</B> with the
|
|
option <B>--list-dirs</B>. Note that the pipe symbol (<B>|</B>) is
|
|
used for a regression test suite hack and may thus not be used in the
|
|
file name.
|
|
<P>
|
|
<DT id="6"><B>--dirmngr-program </B><I>file</I>
|
|
|
|
<DD>
|
|
Specify the directory manager (keyserver client) program to be started
|
|
if none is running. This has only an effect if used together with the
|
|
option <B>--dirmngr</B>.
|
|
<P>
|
|
<DT id="7"><B>--dirmngr</B>
|
|
|
|
<DD>
|
|
Connect to a running directory manager (keyserver client) instead of
|
|
to the gpg-agent. If a dirmngr is not running, start it.
|
|
<P>
|
|
<DT id="8"><B>-S</B>
|
|
|
|
<DD>
|
|
|
|
<B>--raw-socket </B><I>name</I>
|
|
|
|
Connect to socket <I>name</I> assuming this is an Assuan style server.
|
|
Do not run any special initializations or environment checks. This may
|
|
be used to directly connect to any Assuan style socket server.
|
|
<P>
|
|
<DT id="9"><B>-E</B>
|
|
|
|
<DD>
|
|
|
|
<B>--exec</B>
|
|
|
|
Take the rest of the command line as a program and it's arguments and
|
|
execute it as an Assuan server. Here is how you would run <B>gpgsm</B>:
|
|
<DL COMPACT><DT id="10"><DD>
|
|
<PRE>
|
|
gpg-connect-agent --exec gpgsm --server
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
Note that you may not use options on the command line in this case.
|
|
<P>
|
|
<DT id="11"><B>--no-ext-connect</B>
|
|
|
|
<DD>
|
|
When using <B>-S</B> or <B>--exec</B>, <B>gpg-connect-agent</B>
|
|
connects to the Assuan server in extended mode to allow descriptor
|
|
passing. This option makes it use the old mode.
|
|
<P>
|
|
<DT id="12"><B>--no-autostart</B>
|
|
|
|
<DD>
|
|
Do not start the gpg-agent or the dirmngr if it has not yet been
|
|
started.
|
|
<P>
|
|
<DT id="13"><B>-r </B><I>file</I>
|
|
|
|
<DD>
|
|
|
|
<B>--run </B><I>file</I>
|
|
|
|
Run the commands from <I>file</I> at startup and then continue with the
|
|
regular input method. Note, that commands given on the command line are
|
|
executed after this file.
|
|
<P>
|
|
<DT id="14"><B>-s</B>
|
|
|
|
<DD>
|
|
|
|
<B>--subst</B>
|
|
|
|
Run the command <B>/subst</B> at startup.
|
|
<P>
|
|
<DT id="15"><B>--hex</B>
|
|
|
|
<DD>
|
|
Print data lines in a hex format and the ASCII representation of
|
|
non-control characters.
|
|
<P>
|
|
<DT id="16"><B>--decode</B>
|
|
|
|
<DD>
|
|
Decode data lines. That is to remove percent escapes but make sure that
|
|
a new line always starts with a D and a space.
|
|
<P>
|
|
</DL>
|
|
<P>
|
|
|
|
<P>
|
|
<A NAME="lbAE"> </A>
|
|
<H2>CONTROL COMMANDS</H2>
|
|
|
|
<P>
|
|
While reading Assuan commands, gpg-agent also allows a few special
|
|
commands to control its operation. These control commands all start
|
|
with a slash (<B>/</B>).
|
|
<P>
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT id="17"><B>/echo </B><I>args</I>
|
|
|
|
<DD>
|
|
Just print <I>args</I>.
|
|
<P>
|
|
<DT id="18"><B>/let </B><I>name</I> <I>value</I>
|
|
|
|
<DD>
|
|
Set the variable <I>name</I> to <I>value</I>. Variables are only
|
|
substituted on the input if the <B>/subst</B> has been used.
|
|
Variables are referenced by prefixing the name with a dollar sign and
|
|
optionally include the name in curly braces. The rules for a valid name
|
|
are identically to those of the standard bourne shell. This is not yet
|
|
enforced but may be in the future. When used with curly braces no
|
|
leading or trailing white space is allowed.
|
|
<P>
|
|
If a variable is not found, it is searched in the environment and if
|
|
found copied to the table of variables.
|
|
<P>
|
|
Variable functions are available: The name of the function must be
|
|
followed by at least one space and the at least one argument. The
|
|
following functions are available:
|
|
<P>
|
|
<DL COMPACT><DT id="19"><DD>
|
|
<DL COMPACT>
|
|
<DT id="20"><B>get</B>
|
|
|
|
<DD>
|
|
Return a value described by the argument. Available arguments are:
|
|
<P>
|
|
<DL COMPACT><DT id="21"><DD>
|
|
<DL COMPACT>
|
|
<DT id="22"><B>cwd</B>
|
|
|
|
<DD>
|
|
The current working directory.
|
|
<DT id="23"><B>homedir</B>
|
|
|
|
<DD>
|
|
The gnupg homedir.
|
|
<DT id="24"><B>sysconfdir</B>
|
|
|
|
<DD>
|
|
GnuPG's system configuration directory.
|
|
<DT id="25"><B>bindir</B>
|
|
|
|
<DD>
|
|
GnuPG's binary directory.
|
|
<DT id="26"><B>libdir</B>
|
|
|
|
<DD>
|
|
GnuPG's library directory.
|
|
<DT id="27"><B>libexecdir</B>
|
|
|
|
<DD>
|
|
GnuPG's library directory for executable files.
|
|
<DT id="28"><B>datadir</B>
|
|
|
|
<DD>
|
|
GnuPG's data directory.
|
|
<DT id="29"><B>serverpid</B>
|
|
|
|
<DD>
|
|
The PID of the current server. Command <B>/serverpid</B> must
|
|
have been given to return a useful value.
|
|
</DL>
|
|
</DL>
|
|
|
|
<P>
|
|
<DT id="30"><B>unescape </B><I>args</I>
|
|
|
|
<DD>
|
|
Remove C-style escapes from <I>args</I>. Note that <B>\0</B> and
|
|
<B>\x00</B> terminate the returned string implicitly. The string to be
|
|
converted are the entire arguments right behind the delimiting space of
|
|
the function name.
|
|
<P>
|
|
<DT id="31"><B>unpercent </B><I>args</I>
|
|
|
|
<DD>
|
|
|
|
<B>unpercent+ </B><I>args</I>
|
|
|
|
Remove percent style escaping from <I>args</I>. Note that <B>%00</B>
|
|
terminates the string implicitly. The string to be converted are the
|
|
entire arguments right behind the delimiting space of the function
|
|
name. <B>unpercent+</B> also maps plus signs to a spaces.
|
|
<P>
|
|
<DT id="32"><B>percent </B><I>args</I>
|
|
|
|
<DD>
|
|
|
|
<B>percent+ </B><I>args</I>
|
|
|
|
Escape the <I>args</I> using percent style escaping. Tabs, formfeeds,
|
|
linefeeds, carriage returns and colons are escaped. <B>percent+</B> also
|
|
maps spaces to plus signs.
|
|
<P>
|
|
<DT id="33"><B>errcode </B><I>arg</I>
|
|
|
|
<DD>
|
|
|
|
<B>errsource </B><I>arg</I>
|
|
|
|
|
|
<B>errstring </B><I>arg</I>
|
|
|
|
Assume <I>arg</I> is an integer and evaluate it using <B>strtol</B>. Return
|
|
the gpg-error error code, error source or a formatted string with the
|
|
error code and error source.
|
|
<P>
|
|
<P>
|
|
<DT id="34"><B>+</B>
|
|
|
|
<DD>
|
|
|
|
<B>-</B>
|
|
|
|
|
|
<B>*</B>
|
|
|
|
|
|
<B>/</B>
|
|
|
|
|
|
<B>%</B>
|
|
|
|
Evaluate all arguments as long integers using <B>strtol</B> and apply
|
|
this operator. A division by zero yields an empty string.
|
|
<P>
|
|
<DT id="35"><B>!</B>
|
|
|
|
<DD>
|
|
|
|
<B>|</B>
|
|
|
|
|
|
<B>&</B>
|
|
|
|
Evaluate all arguments as long integers using <B>strtol</B> and apply
|
|
the logical operators NOT, OR or AND. The NOT operator works on the
|
|
last argument only.
|
|
<P>
|
|
<P>
|
|
</DL>
|
|
</DL>
|
|
|
|
<P>
|
|
<P>
|
|
<DT id="36"><B>/definq </B><I>name</I> <I>var</I>
|
|
|
|
<DD>
|
|
Use content of the variable <I>var</I> for inquiries with <I>name</I>.
|
|
<I>name</I> may be an asterisk (<B>*</B>) to match any inquiry.
|
|
<P>
|
|
<P>
|
|
<DT id="37"><B>/definqfile </B><I>name</I> <I>file</I>
|
|
|
|
<DD>
|
|
Use content of <I>file</I> for inquiries with <I>name</I>.
|
|
<I>name</I> may be an asterisk (<B>*</B>) to match any inquiry.
|
|
<P>
|
|
<DT id="38"><B>/definqprog </B><I>name</I> <I>prog</I>
|
|
|
|
<DD>
|
|
Run <I>prog</I> for inquiries matching <I>name</I> and pass the
|
|
entire line to it as command line arguments.
|
|
<P>
|
|
<DT id="39"><B>/datafile </B><I>name</I>
|
|
|
|
<DD>
|
|
Write all data lines from the server to the file <I>name</I>. The file
|
|
is opened for writing and created if it does not exists. An existing
|
|
file is first truncated to 0. The data written to the file fully
|
|
decoded. Using a single dash for <I>name</I> writes to stdout. The
|
|
file is kept open until a new file is set using this command or this
|
|
command is used without an argument.
|
|
<P>
|
|
<DT id="40"><B>/showdef</B>
|
|
|
|
<DD>
|
|
Print all definitions
|
|
<P>
|
|
<DT id="41"><B>/cleardef</B>
|
|
|
|
<DD>
|
|
Delete all definitions
|
|
<P>
|
|
<DT id="42"><B>/sendfd </B><I>file</I> <I>mode</I>
|
|
|
|
<DD>
|
|
Open <I>file</I> in <I>mode</I> (which needs to be a valid <B>fopen</B>
|
|
mode string) and send the file descriptor to the server. This is
|
|
usually followed by a command like <B>INPUT FD</B> to set the
|
|
input source for other commands.
|
|
<P>
|
|
<DT id="43"><B>/recvfd</B>
|
|
|
|
<DD>
|
|
Not yet implemented.
|
|
<P>
|
|
<DT id="44"><B>/open </B><I>var</I> <I>file</I> [<I>mode</I>]
|
|
|
|
<DD>
|
|
Open <I>file</I> and assign the file descriptor to <I>var</I>. Warning:
|
|
This command is experimental and might change in future versions.
|
|
<P>
|
|
<DT id="45"><B>/close </B><I>fd</I>
|
|
|
|
<DD>
|
|
Close the file descriptor <I>fd</I>. Warning: This command is
|
|
experimental and might change in future versions.
|
|
<P>
|
|
<DT id="46"><B>/showopen</B>
|
|
|
|
<DD>
|
|
Show a list of open files.
|
|
<P>
|
|
<DT id="47"><B>/serverpid</B>
|
|
|
|
<DD>
|
|
Send the Assuan command <B>GETINFO pid</B> to the server and store
|
|
the returned PID for internal purposes.
|
|
<P>
|
|
<DT id="48"><B>/sleep</B>
|
|
|
|
<DD>
|
|
Sleep for a second.
|
|
<P>
|
|
<DT id="49"><B>/hex</B>
|
|
|
|
<DD>
|
|
|
|
<B>/nohex</B>
|
|
|
|
Same as the command line option <B>--hex</B>.
|
|
<P>
|
|
<DT id="50"><B>/decode</B>
|
|
|
|
<DD>
|
|
|
|
<B>/nodecode</B>
|
|
|
|
Same as the command line option <B>--decode</B>.
|
|
<P>
|
|
<DT id="51"><B>/subst</B>
|
|
|
|
<DD>
|
|
|
|
<B>/nosubst</B>
|
|
|
|
Enable and disable variable substitution. It defaults to disabled
|
|
unless the command line option <B>--subst</B> has been used.
|
|
If /subst as been enabled once, leading whitespace is removed from
|
|
input lines which makes scripts easier to read.
|
|
<P>
|
|
<DT id="52"><B>/while </B><I>condition</I>
|
|
|
|
<DD>
|
|
|
|
<B>/end</B>
|
|
|
|
These commands provide a way for executing loops. All lines between
|
|
the <B>while</B> and the corresponding <B>end</B> are executed as long
|
|
as the evaluation of <I>condition</I> yields a non-zero value or is the
|
|
string <B>true</B> or <B>yes</B>. The evaluation is done by passing
|
|
<I>condition</I> to the <B>strtol</B> function. Example:
|
|
<P>
|
|
<DL COMPACT><DT id="53"><DD>
|
|
<PRE>
|
|
/subst
|
|
/let i 3
|
|
/while $i
|
|
/echo loop counter is $i
|
|
/let i ${- $i 1}
|
|
/end
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
<DT id="54"><B>/if </B><I>condition</I>
|
|
|
|
<DD>
|
|
|
|
<B>/end</B>
|
|
|
|
These commands provide a way for conditional execution. All lines between
|
|
the <B>if</B> and the corresponding <B>end</B> are executed only if
|
|
the evaluation of <I>condition</I> yields a non-zero value or is the
|
|
string <B>true</B> or <B>yes</B>. The evaluation is done by passing
|
|
<I>condition</I> to the <B>strtol</B> function.
|
|
<P>
|
|
<DT id="55"><B>/run </B><I>file</I>
|
|
|
|
<DD>
|
|
Run commands from <I>file</I>.
|
|
<P>
|
|
<DT id="56"><B>/bye</B>
|
|
|
|
<DD>
|
|
Terminate the connection and the program.
|
|
<P>
|
|
<DT id="57"><B>/help</B>
|
|
|
|
<DD>
|
|
Print a list of available control commands.
|
|
<P>
|
|
</DL>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+gpg-agent">gpg-agent</A></B>(1),
|
|
<B><A HREF="/cgi-bin/man/man2html?1+scdaemon">scdaemon</A></B>(1)
|
|
<P>
|
|
The full documentation for this tool is maintained as a Texinfo manual.
|
|
If GnuPG and the info program are properly installed at your site, the
|
|
command
|
|
<P>
|
|
<DL COMPACT><DT id="58"><DD>
|
|
<PRE>
|
|
info gnupg
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
should give you access to the complete manual including a menu structure
|
|
and an index.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="59"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="60"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="61"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="62"><A HREF="#lbAE">CONTROL COMMANDS</A><DD>
|
|
<DT id="63"><A HREF="#lbAF">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:15 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|