1pageant(1) PuTTY tool suite pageant(1)
2
6 pageant - PuTTY SSH authentication agent
7
9 pageant ( -X | -T | --permanent | --debug ) [ key-file... ]
10 pageant [ key-file... ] --exec command [ args... ]
11 pageant -a key-file...
12 pageant ( -d | --public | --public-openssh ) key-identifier...
13 pageant -D
14 pageant -l
15 pageant --askpass prompt
16
18 pageant is both an SSH authentication agent, and also a tool for commu‐
19 nicating with an already-running agent.
20 When running as an SSH agent, it listens on a Unix-domain socket for
22 connections from client processes running under your user id. Clients
23 can load SSH private keys into the agent, or request signatures on a
24 given message from a key already in the agent. This permits one-touch
25 authentication by SSH client programs, if Pageant is holding a key that
26 the server they are connecting to will accept.
27 pageant can also act as a client program itself, communicating with an
29 already-running agent to add or remove keys, list the keys, or extract
30 their public half.
31 The agent protocol used by pageant is compatible with the PuTTY tools
33 and also with other implementations such as OpenSSH's SSH client and
34 ssh-agent(1).
35 To run pageant as an agent, you must provide an option to tell it what
37 its lifetime should be. Typically you would probably want Pageant to
38 last for the duration of a login session, in which case you should use
39 either -X or -T, depending on whether your login session is GUI or
40 purely terminal-based respectively. For example, in your X session
41 startup script you might write
42 eval $(pageant -X)
44 which will cause Pageant to start running, monitor the X server to
46 notice when your session terminates (and then it will terminate too),
47 and print on standard output some shell commands to set environment
48 variables that client processes will need to find the running agent.
49 In a terminal-based login, you could do almost exactly the same thing
51 but with -T:
52 eval $(pageant -T)
54 This will cause Pageant to tie its lifetime to that of your controlling
56 terminal: when you log out, and the terminal device ceases to be asso‐
57 ciated with your session, Pageant will notice that it has no control‐
58 ling terminal any more, and will terminate automatically.
59 In either of these modes, you can also add one or more private keys as
61 extra command-line arguments, e.g.
62 eval $(pageant -T ~/.ssh/key.ppk)
64 in which case Pageant will prompt for the keys' passphrases (if any)
66 and start the agent with those keys already loaded. Passphrase prompts
67 will use the controlling terminal if one is available, or failing that
68 the GUI if one of those is available. (The prompt method can be over‐
69 ridden with the --gui-prompt or --tty-prompt options.) If neither is
70 available, no passphrase prompting can be done.
71 To use Pageant to talk to an existing agent, you can add new keys using
73 -a, list the current set of keys' fingerprints and comments with -l,
74 extract the full public half of any key using --public or --public-
75 openssh, delete a key using -d, or delete all keys using -D.
76
78 The following options are called lifetime modes. They all request
79 Pageant to operate in agent mode; each one specifies a different method
80 for Pageant to start up and know when to shut down.
81 -X Pageant will open a connection to your X display, and when that
83 connection is lost, it will terminate. This gives it the same
84 lifetime as your GUI login session, so in this mode it is suit‐
85 able for running from a startup script such as .xsession. The
86 actual agent will be a subprocess; the main Pageant process will
87 terminate immediately, after printing environment-variable set‐
88 ting commands on standard output which should be installed in
89 any process wanting to communicate with the agent.
90 The usual approach would be to run
92 eval $(pageant -X)
94 in an X session startup script. However, other possibilities
96 exist, such as directing the standard output of `pageant -X' to
97 a file which is then sourced by any new shell.
98 -T Pageant will tie its lifetime to that of the login session run‐
100 ning on its controlling terminal, by noticing when it ceases to
101 have a controlling terminal (which will automatically happen as
102 a side effect of the session leader process terminating). Like
103 -X, Pageant will print environment-variable commands on standard
104 output.
105 --exec command
107 Pageant will run the provided command as a subprocess, preloaded
108 with the appropriate environment variables to access the agent
109 it starts up. When the subprocess terminates, Pageant will ter‐
110 minate as well.
111 All arguments on Pageant's command line after --exec will be
113 treated as part of the command to run, even if they look like
114 other valid Pageant options or key files.
115 --permanent
117 Pageant will fork off a subprocess to be the agent, and print
118 environment-variable commands on standard output, like -X and
119 -T. However, in this case, it will make no effort to limit its
120 lifetime in any way; it will simply run permanently, unless man‐
121 ually killed. The environment variable SSH_AGENT_PID, set by the
122 commands printed by Pageant, permits the agent process to be
123 found for this purpose.
124 This option is not recommended, because any method of manually
126 killing the agent carries the risk of the session terminating
127 unexpectedly before it manages to happen.
128 --debug
130 Pageant will run in the foreground, without forking. It will
131 print its environment variable setup commands on standard out‐
132 put, and then it will log all agent activity to standard output
133 as well. This is useful for debugging what Pageant itself is
134 doing, or what another process is doing to it.
135
137 The following options tell Pageant to operate in client mode, contact‐
138 ing an existing agent via environment variables that it should already
139 have set.
140 -a key-files
142 Load the specified private key file(s), decrypt them if neces‐
143 sary by prompting for their passphrases (with the same choice of
144 user interfaces as in agent mode), and add them to the already-
145 running agent.
146 The private key files must be in PuTTY's .ppk file format.
148 -l List the keys currently in the running agent. Each key's finger‐
150 print and comment string will be shown.
151 --public key-identifiers
153 Print the public half of each specified key, in the RFC 4716
154 standard format (multiple lines, starting with `---- BEGIN SSH2
155 PUBLIC KEY ----').
156 Each key-identifier can be any of the following:
158 · The name of a file containing the key, either the whole
160 key (again in .ppk format) or just its public half.
161 · The key's comment string, as shown by pageant -l.
163 · Enough hex digits of the key's fingerprint to be unique
165 among keys currently loaded into the agent.
166 If Pageant can uniquely identify one key by interpreting the
168 key-identifier in any of these ways, it will assume that key was
169 the one you meant. If it cannot, you will have to specify more
170 detail.
171 If you find that your desired key-identifier string can be
173 validly interpreted as more than one of the above kinds of iden‐
174 tification, you can disambiguate by prefixing it with `file:',
175 `comment:' or `fp:' to indicate that it is a filename, comment
176 string or fingerprint prefix respectively.
177 --public-openssh key-identifiers, -L key-identifiers
179 Print the public half of each specified key, in the one-line
180 format used by OpenSSH, suitable for putting in .ssh/autho‐
181 rized_keys files.
182 -d key-identifiers
184 Delete each specified key from the agent's memory, so that the
185 agent will no longer serve it to clients unless it is loaded in
186 again using pageant -a.
187 -D Delete all keys from the agent's memory, leaving it completely
189 empty.
190
192 --askpass prompt
193 With this option, pageant acts as an ssh-askpass(1) replacement,
194 rather than performing any SSH agent functionality. This may be
195 useful if you prefer Pageant's GUI prompt style, which minimises
196 information leakage about your passphrase length in its visual
197 feedback, compared to other ssh-askpass(1) implementations.
198 pageant --askpass implements the standard ssh-askpass(1) inter‐
200 face: it can be passed a prompt to display (as a single argu‐
201 ment) and, if successful, prints the passphrase on standard out‐
202 put and returns a zero exit status. Typically you would use the
203 environment variable SSH_ASKPASS to tell other programs to use
204 pageant in this way.
205
207 -v Verbose mode. When Pageant runs in agent mode, this option
208 causes it to log all agent activity to its standard error. For
209 example, you might run
210 eval $(pageant -X -v 2>~/.pageant.log)
212 and expect a list of all signatures requested by agent clients
214 to build up in that log file.
215 The log information is the same as that produced by the --debug
217 lifetime option, but --debug sends it to standard output (since
218 that is the main point of debugging mode) whereas -v in all
219 other lifetime modes sends the same log data to standard error
220 (being a by-product of the program's main purpose). Using -v in
221 --debug mode has no effect: the log still goes to standard out‐
222 put.
223 -s, -c Force Pageant to output its environment setup commands in the
225 style of POSIX / Bourne shells (-s) or C shells (-c) respec‐
226 tively. If neither option is given, Pageant will guess based on
227 whether the environment variable SHELL has a value ending in
228 `csh'.
229 --gui-prompt, --tty-prompt
231 Force Pageant to prompt for key passphrases with a particular
232 method (GUI or terminal) rather than trying to guess the most
233 appropriate method as described above. (These options are rele‐
234 vant whenever an encrypted key filename is specified to pageant,
235 and in --askpass mode.)
236 --help Print a brief summary of command-line options and terminate.
238 --version, -V
240 Print the version of Pageant.
241 -- Cause all subsequent arguments to be treated as key file names,
243 even if they look like options.
244PuTTY tool suite 2015‐05‐19 pageant(1)