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

       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. (The prompt method
       can be overridden with the --gui-prompt or --tty-prompt options.) 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  (with the same choice of user interfaces as in agent mode), 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, -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.

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

       --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 an encrypted key filename is specified
              to pageant, 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.