Provided by: putty_0.76-2_amd64 bug

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.