1 \cfg{man-identity}{pageant}{1}{2015-05-19}{PuTTY tool suite}{PuTTY tool suite}
3 \H{pageant-manpage} Man page for Pageant
5 \S{pageant-manpage-name} NAME
7 \cw{pageant} - PuTTY SSH authentication agent
9 \S{pageant-manpage-synopsis} SYNOPSIS
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
24 \S{pageant-manpage-description} DESCRIPTION
26 \c{pageant} is both an SSH authentication agent, and also a tool for
27 communicating with an already-running agent.
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.
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.
40 The agent protocol used by \c{pageant} is compatible with the PuTTY
41 tools and also with other implementations such as OpenSSH's SSH client
44 To run \c{pageant} as an agent, you must provide an option to tell it
45 what its \e{lifetime} should be. Typically you would probably want
46 Pageant to last for the duration of a login session, in which case you
47 should use either \cw{-X} or \cw{-T}, depending on whether your login
48 session is GUI or purely terminal-based respectively. For example, in
49 your X session startup script you might write
54 which will cause Pageant to start running, monitor the X server to
55 notice when your session terminates (and then it will terminate too),
56 and print on standard output some shell commands to set environment
57 variables that client processes will need to find the running agent.
59 In a terminal-based login, you could do almost exactly the same thing
65 This will cause Pageant to tie its lifetime to that of your
66 controlling terminal: when you log out, and the terminal device ceases
67 to be associated with your session, Pageant will notice that it has no
68 controlling terminal any more, and will terminate automatically.
70 In either of these modes, you can also add one or more private keys as
71 extra command-line arguments, e.g.
73 \c eval $(pageant -T ~/.ssh/key.ppk)
74 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
76 in which case Pageant will prompt for the keys' passphrases (if any)
77 and start the agent with those keys already loaded. Passphrase prompts
78 will use the controlling terminal if one is available, or failing that
79 the GUI if one of those is available. If neither is available, no
80 passphrase prompting can be done.
82 To use Pageant to talk to an existing agent, you can add new keys
83 using \cw{-a}, list the current set of keys' fingerprints and comments
84 with \cw{-l}, extract the full public half of any key using
85 \cw{--public} or \cw{--public-openssh}, delete a key using \cw{-d}, or
86 delete all keys using \cw{-D}.
88 \S{pageant-manpage-lifetime} LIFETIME
90 The following options are called \e{lifetime modes}. They all request
91 Pageant to operate in agent mode; each one specifies a different
92 method for Pageant to start up and know when to shut down.
96 \dd Pageant will open a connection to your X display, and when that
97 connection is lost, it will terminate. This gives it the same lifetime
98 as your GUI login session, so in this mode it is suitable for running
99 from a startup script such as \cw{.xsession}. The actual agent will be
100 a subprocess; the main Pageant process will terminate immediately,
101 after printing environment-variable setting commands on standard
102 output which should be installed in any process wanting to communicate
107 The usual approach would be to run
109 \c eval $(pageant -X)
110 \e bbbbbbbbbbbbbbbbbb
112 in an X session startup script. However, other possibilities exist,
113 such as directing the standard output of \cq{pageant -X} to a file
114 which is then sourced by any new shell.
120 \dd Pageant will tie its lifetime to that of the login session running
121 on its controlling terminal, by noticing when it ceases to have a
122 controlling terminal (which will automatically happen as a side effect
123 of the session leader process terminating). Like \cw{-X}, Pageant will
124 print environment-variable commands on standard output.
126 \dt \cw{--exec} \e{command}
128 \dd Pageant will run the provided command as a subprocess, preloaded
129 with the appropriate environment variables to access the agent it
130 starts up. When the subprocess terminates, Pageant will terminate as
135 All arguments on Pageant's command line after \cw{--exec} will be
136 treated as part of the command to run, even if they look like other
137 valid Pageant options or key files.
143 \dd Pageant will fork off a subprocess to be the agent, and print
144 environment-variable commands on standard output, like \cw{-X} and
145 \cw{-T}. However, in this case, it will make no effort to limit its
146 lifetime in any way; it will simply run permanently, unless manually
147 killed. The environment variable \cw{SSH_AGENT_PID}, set by the
148 commands printed by Pageant, permits the agent process to be found for
153 This option is not recommended, because any method of manually killing
154 the agent carries the risk of the session terminating unexpectedly
155 before it manages to happen.
161 \dd Pageant will run in the foreground, without forking. It will print
162 its environment variable setup commands on standard output, and then it
163 will log all agent activity to standard output as well. This is useful
164 for debugging what Pageant itself is doing, or what another process is
167 \S{pageant-manpage-client} CLIENT OPTIONS
169 The following options tell Pageant to operate in client mode,
170 contacting an existing agent via environment variables that it should
173 \dt \cw{-a} \e{key-files}
175 \dd Load the specified private key file(s), decrypt them if necessary
176 by prompting for their passphrases, and add them to the
177 already-running agent.
181 The private key files must be in PuTTY's \cw{.ppk} file format.
187 \dd List the keys currently in the running agent. Each key's
188 fingerprint and comment string will be shown.
190 \dt \cw{--public} \e{key-identifiers}
192 \dd Print the public half of each specified key, in the RFC 4716
193 standard format (multiple lines, starting with \cq{---- BEGIN SSH2
198 Each \e{key-identifier} can be any of the following:
200 \b The name of a file containing the key, either the whole key (again
201 in \cw{.ppk} format) or just its public half.
203 \b The key's comment string, as shown by \cw{pageant -l}.
205 \b Enough hex digits of the key's fingerprint to be unique among keys
206 currently loaded into the agent.
208 If Pageant can uniquely identify one key by interpreting the
209 \e{key-identifier} in any of these ways, it will assume that key was
210 the one you meant. If it cannot, you will have to specify more detail.
212 If you find that your desired \e{key-identifier} string can be validly
213 interpreted as more than one of the above \e{kinds} of identification,
214 you can disambiguate by prefixing it with \cq{file:}, \cq{comment:} or
215 \cq{fp:} to indicate that it is a filename, comment string or
216 fingerprint prefix respectively.
220 \dt \cw{--public-openssh} \e{key-identifiers}
222 \dd Print the public half of each specified key, in the one-line
223 format used by OpenSSH, suitable for putting in
224 \cw{.ssh/authorized_keys} files.
226 \dt \cw{-d} \e{key-identifiers}
228 \dd Delete each specified key from the agent's memory, so that the
229 agent will no longer serve it to clients unless it is loaded in again
230 using \cw{pageant -a}.
234 \dd Delete all keys from the agent's memory, leaving it completely
237 \S{pageant-manpage-options} OPTIONS
241 \dd Verbose mode. When Pageant runs in agent mode, this option causes
242 it to log all agent activity to its standard error. For example, you
247 \c eval $(pageant -X -v 2>~/.pageant.log)
248 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
250 and expect a list of all signatures requested by agent clients to
251 build up in that log file.
253 The log information is the same as that produced by the \cw{--debug}
254 lifetime option, but \cw{--debug} sends it to standard output (since
255 that is the main point of debugging mode) whereas \cw{-v} in all other
256 lifetime modes sends the same log data to standard error (being a
257 by-product of the program's main purpose). Using \cw{-v} in
258 \cw{--debug} mode has no effect: the log still goes to standard
265 \dd Force Pageant to output its environment setup commands in the
266 style of POSIX / Bourne shells (\cw{-s}) or C shells (\cw{-c})
267 respectively. If neither option is given, Pageant will guess based on
268 whether the environment variable \cw{SHELL} has a value ending in
273 \dd Print a brief summary of command-line options and terminate.
277 \dd Print the version of Pageant.
281 \dd Cause all subsequent arguments to be treated as key file names,
282 even if they look like options.