pageant (1)

NAME

pageant - PuTTY SSH authentication agent

SYNOPSIS

pageant ( -X | -T | --permanent | --debug ) [ key-file... ]
pageant [ key-file... ] --exec command [ args... ]
pageant -a key-file...
pageant ( -d | --public | --public-openssh ) key-identifier...
pageant -D
pageant -l

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).

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 prompt for the keys' passphrases (if any) and start the agent with those keys already loaded. Passphrase prompts will use the controlling terminal if one is available, or failing that the GUI if one of those is available. If neither is available, no passphrase prompting can be done.

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 key using -d, or delete all keys using -D.

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. 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), decrypt them if necessary by prompting for their passphrases, and add them to the already-running agent.

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.

--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 hex digits of the key's fingerprint 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 with `file:', `comment:' or `fp:' to indicate that it is a filename, comment string or fingerprint prefix respectively.

--public-openssh 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.

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'.

--help

Print a brief summary of command-line options and terminate.

--version

Print the version of Pageant.

--

Cause all subsequent arguments to be treated as key file names, even if they look like options.