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
17 pageant is both an SSH authentication agent, and also a tool for commu‐
18 nicating with an already-running agent.
19 When running as an SSH agent, it listens on a Unix-domain socket for
21 connections from client processes running under your user id. Clients
22 can load SSH private keys into the agent, or request signatures on a
23 given message from a key already in the agent. This permits one-touch
24 authentication by SSH client programs, if Pageant is holding a key that
25 the server they are connecting to will accept.
26 pageant can also act as a client program itself, communicating with an
28 already-running agent to add or remove keys, list the keys, or extract
29 their public half.
30 The agent protocol used by pageant is compatible with the PuTTY tools
32 and also with other implementations such as OpenSSH's SSH client and
33 ssh-agent(1).
34 To run pageant as an agent, you must provide an option to tell it what
36 its lifetime should be. Typically you would probably want Pageant to
37 last for the duration of a login session, in which case you should use
38 either -X or -T, depending on whether your login session is GUI or
39 purely terminal-based respectively. For example, in your X session
40 startup script you might write
41 eval $(pageant -X)
43 which will cause Pageant to start running, monitor the X server to
45 notice when your session terminates (and then it will terminate too),
46 and print on standard output some shell commands to set environment
47 variables that client processes will need to find the running agent.
48 In a terminal-based login, you could do almost exactly the same thing
50 but with -T:
51 eval $(pageant -T)
53 This will cause Pageant to tie its lifetime to that of your controlling
55 terminal: when you log out, and the terminal device ceases to be asso‐
56 ciated with your session, Pageant will notice that it has no control‐
57 ling terminal any more, and will terminate automatically.
58 In either of these modes, you can also add one or more private keys as
60 extra command-line arguments, e.g.
61 eval $(pageant -T ~/.ssh/key.ppk)
63 in which case Pageant will prompt for the keys' passphrases (if any)
65 and start the agent with those keys already loaded. Passphrase prompts
66 will use the controlling terminal if one is available, or failing that
67 the GUI if one of those is available. If neither is available, no
68 passphrase prompting can be done.
69 To use Pageant to talk to an existing agent, you can add new keys using
71 -a, list the current set of keys' fingerprints and comments with -l,
72 extract the full public half of any key using --public or --public-
73 openssh, delete a key using -d, or delete all keys using -D.
74
76 The following options are called lifetime modes. They all request
77 Pageant to operate in agent mode; each one specifies a different method
78 for Pageant to start up and know when to shut down.
79 -X Pageant will open a connection to your X display, and when that
81 connection is lost, it will terminate. This gives it the same
82 lifetime as your GUI login session, so in this mode it is suit‐
83 able for running from a startup script such as .xsession. The
84 actual agent will be a subprocess; the main Pageant process will
85 terminate immediately, after printing environment-variable set‐
86 ting commands on standard output which should be installed in
87 any process wanting to communicate with the agent.
88 The usual approach would be to run
90 eval $(pageant -X)
92 in an X session startup script. However, other possibilities
94 exist, such as directing the standard output of `pageant -X' to
95 a file which is then sourced by any new shell.
96 -T Pageant will tie its lifetime to that of the login session run‐
98 ning on its controlling terminal, by noticing when it ceases to
99 have a controlling terminal (which will automatically happen as
100 a side effect of the session leader process terminating). Like
101 -X, Pageant will print environment-variable commands on standard
102 output.
103 --exec command
105 Pageant will run the provided command as a subprocess, preloaded
106 with the appropriate environment variables to access the agent
107 it starts up. When the subprocess terminates, Pageant will ter‐
108 minate as well.
109 All arguments on Pageant's command line after --exec will be
111 treated as part of the command to run, even if they look like
112 other valid Pageant options or key files.
113 --permanent
115 Pageant will fork off a subprocess to be the agent, and print
116 environment-variable commands on standard output, like -X and
117 -T. However, in this case, it will make no effort to limit its
118 lifetime in any way; it will simply run permanently, unless man‐
119 ually killed. The environment variable SSH_AGENT_PID, set by the
120 commands printed by Pageant, permits the agent process to be
121 found for this purpose.
122 This option is not recommended, because any method of manually
124 killing the agent carries the risk of the session terminating
125 unexpectedly before it manages to happen.
126 --debug
128 Pageant will run in the foreground, without forking. It will
129 print its environment variable setup commands on standard out‐
130 put, and then it will log all agent activity to standard output
131 as well. This is useful for debugging what Pageant itself is
132 doing, or what another process is doing to it.
133
135 The following options tell Pageant to operate in client mode, contact‐
136 ing an existing agent via environment variables that it should already
137 have set.
138 -a key-files
140 Load the specified private key file(s), decrypt them if neces‐
141 sary by prompting for their passphrases, and add them to the
142 already-running agent.
143 The private key files must be in PuTTY's .ppk file format.
145 -l List the keys currently in the running agent. Each key's finger‐
147 print and comment string will be shown.
148 --public key-identifiers
150 Print the public half of each specified key, in the RFC 4716
151 standard format (multiple lines, starting with `---- BEGIN SSH2
152 PUBLIC KEY ----').
153 Each key-identifier can be any of the following:
155 · The name of a file containing the key, either the whole
157 key (again in .ppk format) or just its public half.
158 · The key's comment string, as shown by pageant -l.
160 · Enough hex digits of the key's fingerprint to be unique
162 among keys currently loaded into the agent.
163 If Pageant can uniquely identify one key by interpreting the
165 key-identifier in any of these ways, it will assume that key was
166 the one you meant. If it cannot, you will have to specify more
167 detail.
168 If you find that your desired key-identifier string can be
170 validly interpreted as more than one of the above kinds of iden‐
171 tification, you can disambiguate by prefixing it with `file:',
172 `comment:' or `fp:' to indicate that it is a filename, comment
173 string or fingerprint prefix respectively.
174 --public-openssh key-identifiers
176 Print the public half of each specified key, in the one-line
177 format used by OpenSSH, suitable for putting in .ssh/autho‐
178 rized_keys files.
179 -d key-identifiers
181 Delete each specified key from the agent's memory, so that the
182 agent will no longer serve it to clients unless it is loaded in
183 again using pageant -a.
184 -D Delete all keys from the agent's memory, leaving it completely
186 empty.
187
189 -v Verbose mode. When Pageant runs in agent mode, this option
190 causes it to log all agent activity to its standard error. For
191 example, you might run
192 eval $(pageant -X -v 2>~/.pageant.log)
194 and expect a list of all signatures requested by agent clients
196 to build up in that log file.
197 The log information is the same as that produced by the --debug
199 lifetime option, but --debug sends it to standard output (since
200 that is the main point of debugging mode) whereas -v in all
201 other lifetime modes sends the same log data to standard error
202 (being a by-product of the program's main purpose). Using -v in
203 --debug mode has no effect: the log still goes to standard out‐
204 put.
205 -s, -c Force Pageant to output its environment setup commands in the
207 style of POSIX / Bourne shells (-s) or C shells (-c) respec‐
208 tively. If neither option is given, Pageant will guess based on
209 whether the environment variable SHELL has a value ending in
210 `csh'.
211 --help Print a brief summary of command-line options and terminate.
213 --version
215 Print the version of Pageant.
216 -- Cause all subsequent arguments to be treated as key file names,
218 even if they look like options.
219PuTTY tool suite 2015‐05‐19 pageant(1)