Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
pageant(1)		       PuTTY tool suite			    pageant(1)

       pageant - PuTTY SSH authentication agent

       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

       pageant is both an SSH authentication agent, and	also a tool for	commu-
       nicating	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 ex-
       tensions, 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 no-
       tice when your session terminates (and then it will terminate too), and
       print  on  standard output some shell commands to set environment vari-
       ables 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	 asso-
       ciated  with  your session, Pageant will	notice that it has no control-
       ling 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  cleart-
       ext  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

       eval $(pageant -T --encrypted ~/.ssh/key.ppk)

       In this case, Pageant will not prompt for a passphrase at startup;  in-
       stead,  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

       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	 suit-
	      able  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 set-
	      ting 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 ex-
	      ist, 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 run-
	      ning 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

       --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  ter-
	      minate 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.

	      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 man-
	      ually 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.

	      Pageant  will  run  in  the foreground, without forking. It will
	      print its	environment variable setup commands on	standard  out-
	      put,  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.

       The following options tell Pageant to operate in	client mode,  contact-
       ing  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  al-
	      ready-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

	      The private key files must be in PuTTY's .ppk file format.

       -l     List the keys currently in the running agent. Each key's finger-
	      print  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:

	      +o	     The name of a file	containing the key, either  the	 whole
		     key (again	in .ppk	format)	or just	its public half.

	      +o	     The key's comment string, as shown	by pageant -l.

	      +o	     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

	      If  you  find  that  your	 desired  key-identifier string	can be
	      validly interpreted as more than one of the above	kinds of iden-
	      tification, you can disambiguate by prefixing it as follows:

		     to	indicate that it is a filename

		     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/autho-
	      rized_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

       -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 result-
	      ing  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  de-
	      fined by the SSH agent protocol.

       --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)	inter-
	      face: it can be passed a prompt to display (as  a	 single	 argu-
	      ment) and, if successful,	prints the passphrase on standard out-
	      put 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.

       -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  out-

       -s, -c Force  Pageant  to  output its environment setup commands	in the
	      style of POSIX / Bourne shells (-s) or  C	 shells	 (-c)  respec-
	      tively.  If neither option is given, Pageant will	guess based on
	      whether the environment variable SHELL has  a  value  ending  in

       --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	 rele-
	      vant  whenever a key file	is specified to	pageant	that needs im-
	      mediate 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.

PuTTY tool suite		  2015-05-19			    pageant(1)


Want to link to this manual page? Use this URL:

home | help