Provided by: putty_0.76-2_amd64 
NAME
pageant - PuTTY SSH authentication agent
SYNOPSIS
pageant ( -X | -T | --permanent | --debug ) [ [ --encrypted ] key-file... ]
pageant [ [ --encrypted ] key-file... ] --exec command [ args... ]
pageant -a [ --encrypted ] key-file...
pageant ( -d | -r | --public | --public-openssh ) key-identifier...
pageant ( -D | -R )
pageant -l [ --fptype format ]
pageant --askpass prompt
DESCRIPTION
pageant is both an SSH authentication agent, and also a tool for communicating with an
already-running agent.
When running as an SSH agent, it listens on a Unix-domain socket for connections from
client processes running under your user id. Clients can load SSH private keys into the
agent, or request signatures on a given message from a key already in the agent. This
permits one-touch authentication by SSH client programs, if Pageant is holding a key that
the server they are connecting to will accept.
pageant can also act as a client program itself, communicating with an already-running
agent to add or remove keys, list the keys, or extract their public half.
The agent protocol used by pageant is compatible with the PuTTY tools and also with other
implementations such as OpenSSH's SSH client and ssh-agent(1). Some pageant features are
implemented with protocol extensions, so will only work if pageant is on both ends.
To run pageant as an agent, you must provide an option to tell it what its lifetime should
be. Typically you would probably want Pageant to last for the duration of a login session,
in which case you should use either -X or -T, depending on whether your login session is
GUI or purely terminal-based respectively. For example, in your X session startup script
you might write
eval $(pageant -X)
which will cause Pageant to start running, monitor the X server to notice when your
session terminates (and then it will terminate too), and print on standard output some
shell commands to set environment variables that client processes will need to find the
running agent.
In a terminal-based login, you could do almost exactly the same thing but with -T:
eval $(pageant -T)
This will cause Pageant to tie its lifetime to that of your controlling terminal: when you
log out, and the terminal device ceases to be associated with your session, Pageant will
notice that it has no controlling terminal any more, and will terminate automatically.
In either of these modes, you can also add one or more private keys as extra command-line
arguments, e.g.
eval $(pageant -T ~/.ssh/key.ppk)
in which case Pageant will immediately prompt for the keys' passphrases (if any) and start
the agent with those keys already loaded in cleartext form. Passphrase prompts will use
the controlling terminal if one is available, or failing that the GUI if one of those is
available. (The prompt method can be overridden with the --gui-prompt or --tty-prompt
options.) If neither is available, no passphrase prompting can be done.
Alternatively, you can start an agent with keys stored in encrypted form:
eval $(pageant -T --encrypted ~/.ssh/key.ppk)
In this case, Pageant will not prompt for a passphrase at startup; instead, it will prompt
the first time a client tries to use the key. (Pageant will need access to a GUI so that
it can pop up a passphrase prompt when required, unless it's running in --debug mode.)
To use Pageant to talk to an existing agent, you can add new keys using -a, list the
current set of keys' fingerprints and comments with -l, extract the full public half of
any key using --public or --public-openssh, delete a specific key or all keys using -d or
-D respectively, or request re-encryption of a specific key or all keys using -r or -R
respectively.
LIFETIME
The following options are called lifetime modes. They all request Pageant to operate in
agent mode; each one specifies a different method for Pageant to start up and know when to
shut down.
-X Pageant will open a connection to your X display, and when that connection is lost,
it will terminate. This gives it the same lifetime as your GUI login session, so in
this mode it is suitable for running from a startup script such as .xsession. The
actual agent will be a subprocess; the main Pageant process will terminate
immediately, after printing environment-variable setting commands on standard
output which should be installed in any process wanting to communicate with the
agent.
The usual approach would be to run
eval $(pageant -X)
in an X session startup script. However, other possibilities exist, such as
directing the standard output of `pageant -X' to a file which is then sourced by
any new shell.
-T Pageant will tie its lifetime to that of the login session running on its
controlling terminal, by noticing when it ceases to have a controlling terminal
(which will automatically happen as a side effect of the session leader process
terminating). Like -X, Pageant will print environment-variable commands on standard
output.
--exec command
Pageant will run the provided command as a subprocess, preloaded with the
appropriate environment variables to access the agent it starts up. When the
subprocess terminates, Pageant will terminate as well.
All arguments on Pageant's command line after --exec will be treated as part of the
command to run, even if they look like other valid Pageant options or key files.
--permanent
Pageant will fork off a subprocess to be the agent, and print environment-variable
commands on standard output, like -X and -T. However, in this case, it will make no
effort to limit its lifetime in any way; it will simply run permanently, unless
manually killed. The environment variable SSH_AGENT_PID, set by the commands
printed by Pageant, permits the agent process to be found for this purpose.
This option is not recommended, because any method of manually killing the agent
carries the risk of the session terminating unexpectedly before it manages to
happen.
--debug
Pageant will run in the foreground, without forking. It will print its environment
variable setup commands on standard output, and then it will log all agent activity
to standard output as well; any passphrase prompts will need to be answered on
standard input. This is useful for debugging what Pageant itself is doing, or what
another process is doing to it.
CLIENT OPTIONS
The following options tell Pageant to operate in client mode, contacting an existing agent
via environment variables that it should already have set.
-a key-files
Load the specified private key file(s) and add them to the already-running agent.
Unless --encrypted is also specified, pageant will decrypt them if necessary by
prompting for their passphrases (with the same choice of user interfaces as in
agent mode).
The private key files must be in PuTTY's .ppk file format.
-l List the keys currently in the running agent. Each key's fingerprint and comment
string will be shown. (Use the -E option to change the fingerprint format.)
Keys that will require a passphrase on their next use are listed as `encrypted'.
Keys that can be returned to this state with -r are listed as `re-encryptable'.
--public key-identifiers
Print the public half of each specified key, in the RFC 4716 standard format
(multiple lines, starting with `---- BEGIN SSH2 PUBLIC KEY ----').
Each key-identifier can be any of the following:
• The name of a file containing the key, either the whole key (again in .ppk
format) or just its public half.
• The key's comment string, as shown by pageant -l.
• Enough of one of the key's fingerprint formats to be unique among keys
currently loaded into the agent.
If Pageant can uniquely identify one key by interpreting the key-identifier in any
of these ways, it will assume that key was the one you meant. If it cannot, you
will have to specify more detail.
If you find that your desired key-identifier string can be validly interpreted as
more than one of the above kinds of identification, you can disambiguate by
prefixing it as follows:
`file:'
to indicate that it is a filename
`comment:'
to indicate that it is a comment string
`fp:' to indicate that it is a fingerprint; any fingerprint format will be matched
`sha256:' or `md5:'
to indicate that it is a fingerprint of a specific format
--public-openssh key-identifiers, -L key-identifiers
Print the public half of each specified key, in the one-line format used by
OpenSSH, suitable for putting in .ssh/authorized_keys files.
-d key-identifiers
Delete each specified key from the agent's memory, so that the agent will no longer
serve it to clients unless it is loaded in again using pageant -a.
-D Delete all keys from the agent's memory, leaving it completely empty.
-r key-identifiers
`Re-encrypt' each specified key in the agent's memory - that is, forget any
cleartext version, so that the user will be prompted for a passphrase again next
time the key is used. (For this to be possible, the key must previously have been
added with the --encrypted option.)
(Holding encrypted keys is a Pageant extension, so this option and -R are unlikely
to work with other agents.)
-R `Re-encrypt' all possible keys in the agent's memory. (This may leave some keys in
cleartext, if they were not previously added with the --encrypted option.)
--test-sign key-identifier
--test-sign-with-flags=flags key-identifier
Sign arbitrary data with the given key. This mode is only likely to be useful when
testing pageant itself.
The data to sign is taken from standard input, signed by the agent with the key
identified by key-identifier, and the resulting signature emitted on standard
output (as a binary blob in the format defined by the SSH specifications).
flags is a number representing a combination of flag bits defined by the SSH agent
protocol.
SSH-ASKPASS REPLACEMENT
--askpass prompt
With this option, pageant acts as an ssh-askpass(1) replacement, rather than
performing any SSH agent functionality. This may be useful if you prefer Pageant's
GUI prompt style, which minimises information leakage about your passphrase length
in its visual feedback, compared to other ssh-askpass(1) implementations.
pageant --askpass implements the standard ssh-askpass(1) interface: it can be
passed a prompt to display (as a single argument) and, if successful, prints the
passphrase on standard output and returns a zero exit status. Typically you would
use the environment variable SSH_ASKPASS to tell other programs to use pageant in
this way.
OPTIONS
-v Verbose mode. When Pageant runs in agent mode, this option causes it to log all
agent activity to its standard error. For example, you might run
eval $(pageant -X -v 2>~/.pageant.log)
and expect a list of all signatures requested by agent clients to build up in that
log file.
The log information is the same as that produced by the --debug lifetime option,
but --debug sends it to standard output (since that is the main point of debugging
mode) whereas -v in all other lifetime modes sends the same log data to standard
error (being a by-product of the program's main purpose). Using -v in --debug mode
has no effect: the log still goes to standard output.
-s, -c Force Pageant to output its environment setup commands in the style of POSIX /
Bourne shells (-s) or C shells (-c) respectively. If neither option is given,
Pageant will guess based on whether the environment variable SHELL has a value
ending in `csh'.
--symlink fixed-path
When operating in agent mode, as well as creating a uniquely named listening
socket, pageant will also create (or update) a symbolic link at fixed-path pointing
to that socket.
This allows access to an agent instance by setting the SSH_AUTH_SOCK environment
variable to fixed-path, rather than having to use the value invented by pageant
when it starts. It's mainly expected to be useful for debugging.
--encrypted, --no-decrypt
When adding keys to the agent (at startup or later), keep them in encrypted form
until the first attempt to use them; the user will be prompted for a passphrase
then. Once decrypted, a key that was added in this way can be `re-encrypted' with
the -r or -R client options.
The --encrypted option makes no difference for key files which do not have a
passphrase.
(Storing keys in encrypted form is a Pageant extension; other agent implementations
are unlikely to support it.)
-E fingerprint-type, --fptype fingerprint-type
Specify the fingerprint format to print. Only applicable when listing fingerprints
with -l. The available formats are sha256 (the default) and md5.
--gui-prompt, --tty-prompt
Force Pageant to prompt for key passphrases with a particular method (GUI or
terminal) rather than trying to guess the most appropriate method as described
above. (These options are relevant whenever a key file is specified to pageant that
needs immediate decryption, and in --askpass mode.)
--help Print a brief summary of command-line options and terminate.
--version, -V
Print the version of Pageant.
-- Cause all subsequent arguments to be treated as key file names, even if they look
like options.