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 ) [ key-file... ]
       pageant [ key-file... ] --exec command [	args...	]
       pageant -a key-file...
       pageant ( -d | --public | --public-openssh ) key-identifier...
       pageant -D
       pageant -l

       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

       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 prompt for the keys'	passphrases  (if  any)
       and  start the agent with those keys already loaded. Passphrase prompts
       will use	the controlling	terminal if one	is available, or failing  that
       the  GUI	 if  one  of  those  is	available. If neither is available, no
       passphrase prompting can	be done.

       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 key using -d, or delete all keys using	-D.

       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. This is useful for debugging what Pageant itself	is do-
	      ing, 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), decrypt them  if	neces-
	      sary by prompting	for their passphrases, and add them to the al-
	      ready-running 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.

       --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 hex	digits of the key's fingerprint	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	with  `file:',
	      `comment:'  or  `fp:' to indicate	that it	is a filename, comment
	      string or	fingerprint prefix respectively.

       --public-openssh	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

       -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

       --help Print a brief summary of command-line options and	terminate.

	      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