doc/man-pag.but

   1 \cfg{man-identity}{pageant}{1}{2015-05-19}{PuTTY tool suite}{PuTTY tool suite}
   2
   3 \H{pageant-manpage} Man page for Pageant
   4
   5 \S{pageant-manpage-name} NAME
   6
   7 \cw{pageant} - SSH authentication agent for the PuTTY tools
   8
   9 \S{pageant-manpage-synopsis} SYNOPSIS
  10
  11 \c pageant ( -X | -T | --permanent | --debug ) [ key-file... ]
  12 \e bbbbbbb   bb   bb   bbbbbbbbbbb   bbbbbbb     iiiiiiii
  13 \c pageant [ key-file... ] --exec command [ args... ]
  14 \e bbbbbbb   iiiiiiii      bbbbbb iiiiiii   iiii
  15 \c pageant -a key-file...
  16 \e bbbbbbb bb iiiiiiii
  17 \c pageant ( -d | --public | --public-openssh ) key-identifier...
  18 \e bbbbbbb   bb   bbbbbbbb   bbbbbbbbbbbbbbbb   iiiiiiiiiiiiii
  19 \c pageant -D
  20 \e bbbbbbb bb
  21 \c pageant -l
  22 \e bbbbbbb bb
  23
  24 \S{pageant-manpage-description} DESCRIPTION
  25
  26 \c{pageant} is both an SSH authentication agent, and also a tool for
  27 communicating with an already-running agent.
  28
  29 When running as an SSH agent, it listens on a Unix-domain socket for
  30 connections from client processes running under your user id. Clients
  31 can load SSH private keys into the agent, or request signatures on a
  32 given message from a key already in the agent. This permits one-touch
  33 authentication by SSH client programs, if Pageant is holding a key
  34 that the server they are connecting to will accept.
  35
  36 \c{pageant} can also act as a client program itself, communicating
  37 with an already-running agent to add or remove keys, list the keys, or
  38 extract their public half.
  39
  40 To run \c{pageant} as an agent, you must provide an option to tell it
  41 what its \e{lifetime} should be. Typically you would probably want
  42 Pageant to last for the duration of a login session, in which case you
  43 should use either \cw{-X} or \cw{-T}, depending on whether your login
  44 session is GUI or purely terminal-based respectively. For example, in
  45 your X session startup script you might write
  46
  47 \c eval $(pageant -X)
  48 \e bbbbbbbbbbbbbbbbbb
  49
  50 which will cause Pageant to start running, monitor the X server to
  51 notice when your session terminates (and then it will terminate too),
  52 and print on standard output some shell commands to set environment
  53 variables that client processes will need to find the running agent.
  54
  55 In a terminal-based login, you could do almost exactly the same thing
  56 but with \cw{-T}:
  57
  58 \c eval $(pageant -T)
  59 \e bbbbbbbbbbbbbbbbbb
  60
  61 This will cause Pageant to tie its lifetime to that of your
  62 controlling terminal: when you log out, and the terminal device ceases
  63 to be associated with your session, Pageant will notice that it has no
  64 controlling terminal any more, and will terminate automatically.
  65
  66 In either of these modes, you can also add one or more private keys as
  67 extra command-line arguments, e.g.
  68
  69 \c eval $(pageant -T ~/.ssh/key.ppk)
  70 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
  71
  72 in which case Pageant will prompt for the keys' passphrases (if any)
  73 and start the agent with those keys already loaded. Passphrase prompts
  74 will use the controlling terminal if one is available, or failing that
  75 the GUI if one of those is available. If neither is available, no
  76 passphrase prompting can be done.
  77
  78 To use Pageant to talk to an existing agent, you can add new keys
  79 using \cw{-a}, list the current set of keys' fingerprints and comments
  80 with \cw{-l}, extract the full public half of any key using
  81 \cw{--public} or \cw{--public-openssh}, delete a key using \cw{-d}, or
  82 delete all keys using \cw{-D}.
  83
  84 \S{pageant-manpage-lifetime} LIFETIME
  85
  86 The following options are called \e{lifetime modes}. They all request
  87 Pageant to operate in agent mode; each one specifies a different
  88 method for Pageant to start up and know when to shut down.
  89
  90 \dt \cw{-X}
  91
  92 \dd Pageant will open a connection to your X display, and when that
  93 connection is lost, it will terminate. This gives it the same lifetime
  94 as your GUI login session, so in this mode it is suitable for running
  95 from a startup script such as \cw{.xsession}. The actual agent will be
  96 a subprocess; the main Pageant process will terminate immediately,
  97 after printing environment-variable setting commands on standard
  98 output which should be installed in any process wanting to communicate
  99 with the agent.
 100
 101 \lcont{
 102
 103 The usual approach would be to run
 104
 105 \c eval $(pageant -X)
 106 \e bbbbbbbbbbbbbbbbbb
 107
 108 in an X session startup script. However, other possibilities exist,
 109 such as directing the standard output of \cq{pageant -X} to a file
 110 which is then sourced by any new shell.
 111
 112 }
 113
 114 \dt \cw{-T}
 115
 116 \dd Pageant will tie its lifetime to that of the login session running
 117 on its controlling terminal, by noticing when it ceases to have a
 118 controlling terminal (which will automatically happen as a side effect
 119 of the session leader process terminating). Like \cw{-X}, Pageant will
 120 print environment-variable commands on standard output.
 121
 122 \dt \cw{--exec} \e{command}
 123
 124 \dd Pageant will run the provided command as a subprocess, preloaded
 125 with the appropriate environment variables to access the agent it
 126 starts up. When the subprocess terminates, Pageant will terminate as
 127 well.
 128
 129 \lcont{
 130
 131 All arguments on Pageant's command line after \cw{--exec} will be
 132 treated as part of the command to run, even if they look like other
 133 valid Pageant options or key files.
 134
 135 }
 136
 137 \dt \cw{--permanent}
 138
 139 \dd Pageant will fork off a subprocess to be the agent, and print
 140 environment-variable commands on standard output, like \cw{-X} and
 141 \cw{-T}. However, in this case, it will make no effort to limit its
 142 lifetime in any way; it will simply run permanently, unless manually
 143 killed. The environment variable \cw{SSH_AGENT_PID}, set by the
 144 commands printed by Pageant, permits the agent process to be found for
 145 this purpose.
 146
 147 \lcont{
 148
 149 This option is not recommended, because any method of manually killing
 150 the agent carries the risk of the session terminating unexpectedly
 151 before it manages to happen.
 152
 153 }
 154
 155 \dt \cw{--debug}
 156
 157 \dd Pageant will run in the foreground, without forking. It will print
 158 its environment variable setup commands on standard output, and then it
 159 will log all agent activity to standard output as well. This is useful
 160 for debugging what Pageant itself is doing, or what another process is
 161 doing to it.
 162
 163 \S{pageant-manpage-client} CLIENT OPTIONS
 164
 165 The following options tell Pageant to operate in client mode,
 166 contacting an existing agent via environment variables that it should
 167 already have set.
 168
 169 \dt \cw{-a} \e{key-files}
 170
 171 \dd Load the specified private key file(s), decrypt them if necessary
 172 by prompting for their passphrases, and add them to the
 173 already-running agent.
 174
 175 \lcont{
 176
 177 The private key files must be in PuTTY's \cw{.ppk} file format.
 178
 179 }
 180
 181 \dt \cw{-l}
 182
 183 \dd List the keys currently in the running agent. Each key's
 184 fingerprint and comment string will be shown.
 185
 186 \dt \cw{--public} \e{key-identifiers}
 187
 188 \dd Print the public half of each specified key, in the RFC 4716
 189 standard format (multiple lines, starting with \cq{---- BEGIN SSH2
 190 PUBLIC KEY ----}).
 191
 192 \lcont{
 193
 194 Each \e{key-identifier} can be any of the following:
 195
 196 \b The name of a file containing the key, either the whole key (again
 197 in \cw{.ppk} format) or just its public half.
 198
 199 \b The key's comment string, as shown by \cw{pageant -l}.
 200
 201 \b Enough hex digits of the key's fingerprint to be unique among keys
 202 currently loaded into the agent.
 203
 204 If Pageant can uniquely identify one key by interpreting the
 205 \e{key-identifier} in any of these ways, it will assume that key was
 206 the one you meant. If it cannot, you will have to specify more detail.
 207
 208 If you find that your desired \e{key-identifier} string can be validly
 209 interpreted as more than one of the above \e{kinds} of identification,
 210 you can disambiguate by prefixing it with \cq{file:}, \cq{comment:} or
 211 \cq{fp:} to indicate that it is a filename, comment string or
 212 fingerprint prefix respectively.
 213
 214 }
 215
 216 \dt \cw{--public-openssh} \e{key-identifiers}
 217
 218 \dd Print the public half of each specified key, in the one-line
 219 format used by OpenSSH, suitable for putting in
 220 \cw{.ssh/authorized_keys} files.
 221
 222 \dt \cw{-d} \e{key-identifiers}
 223
 224 \dd Delete each specified key from the agent's memory, so that the
 225 agent will no longer serve it to clients unless it is loaded in again
 226 using \cw{pageant -a}.
 227
 228 \dt \cw{-D}
 229
 230 \dd Delete all keys from the agent's memory, leaving it completely
 231 empty.
 232
 233 \S{pageant-manpage-options} OPTIONS
 234
 235 \dt \cw{-v}
 236
 237 \dd Verbose mode. When Pageant runs in agent mode, this option causes
 238 it to log all agent activity to its standard error. For example, you
 239 might run
 240
 241 \lcont{
 242
 243 \c eval $(pageant -X -v 2>~/.pageant.log)
 244 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
 245
 246 and expect a list of all signatures requested by agent clients to
 247 build up in that log file.
 248
 249 The log information is the same as that produced by the \cw{--debug}
 250 lifetime option, but \cw{--debug} sends it to standard output (since
 251 that is the main point of debugging mode) whereas \cw{-v} in all other
 252 lifetime modes sends the same log data to standard error (being a
 253 by-product of the program's main purpose). Using \cw{-v} in
 254 \cw{--debug} mode has no effect: the log still goes to standard
 255 output.
 256
 257 }
 258
 259 \dt \cw{--help}
 260
 261 \dd Print a brief summary of command-line options and terminate.
 262
 263 \dt \cw{--version}
 264
 265 \dd Print the version of Pageant.
 266
 267 \dt \cw{--}
 268
 269 \dd Cause all subsequent arguments to be treated as key file names,
 270 even if they look like options.