NAME

       ssh-agent — authentication agent

SYNOPSIS

       ssh-agent [-c | -s] [-d] [-a bind_address] [-t life] [-P pkcs11_whitelist] [command [arg ...]]
       ssh-agent [-c | -s] -k

DESCRIPTION

       ssh-agent  is  a  program  to  hold  private  keys  used  for public key authentication (RSA, DSA, ECDSA,
       ED25519).  The idea is that ssh-agent is started in the beginning of an X-session or a login session, and
       all other windows or programs  are  started  as  clients  to  the  ssh-agent  program.   Through  use  of
       environment  variables the agent can be located and automatically used for authentication when logging in
       to other machines using ssh(1).

       The options are as follows:

       -a bind_address
               Bind   the   agent   to    the    Unix-domain    socket    bind_address.     The    default    is
               $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid>.

       -c      Generate C-shell commands on stdout.  This is the default if SHELL looks like it's a csh style of
               shell.

       -d      Debug mode.  When this option is specified ssh-agent will not fork.

       -k      Kill the current agent (given by the SSH_AGENT_PID environment variable).

       -P      Specify  a  pattern-list of acceptable paths for PKCS#11 shared libraries that may be added using
               the  -s  option  to  ssh-add(1).   The  default  is  to  allow  loading  PKCS#11  libraries  from
               “/usr/lib/*,/usr/local/lib/*”.   PKCS#11  libraries  that  do  not  match  the  whitelist will be
               refused.  See PATTERNS in ssh_config(5) for a description of pattern-list syntax.

       -s      Generate Bourne shell commands on stdout.  This is the default if SHELL does not look like it's a
               csh style of shell.

       -t life
               Set a default value for the maximum lifetime of identities added to the agent.  The lifetime  may
               be  specified  in  seconds or in a time format specified in sshd_config(5).  A lifetime specified
               for an identity with ssh-add(1) overrides this value.  Without this option  the  default  maximum
               lifetime is forever.

       If a commandline is given, this is executed as a subprocess of the agent.  When the command dies, so does
       the agent.

       The  agent  initially  does  not  have any private keys.  Keys are added using ssh-add(1).  When executed
       without  arguments,  ssh-add(1)   adds   the   files   ~/.ssh/id_rsa,   ~/.ssh/id_dsa,   ~/.ssh/id_ecdsa,
       ~/.ssh/id_ed25519  and  ~/.ssh/identity.   If  the  identity  has  a  passphrase, ssh-add(1) asks for the
       passphrase on the terminal if it has one or from a small X11 program if running under X11.  If neither of
       these is the case then the authentication will fail.  It then sends the identity to the  agent.   Several
       identities  can be stored in the agent; the agent can automatically use any of these identities.  ssh-add
       -l displays the identities currently held by the agent.

       The idea is that the agent is run in the user's local PC, laptop, or terminal.  Authentication data  need
       not  be  stored on any other machine, and authentication passphrases never go over the network.  However,
       the connection to the agent is forwarded over SSH remote logins, and the user can thus use the privileges
       given by the identities anywhere in the network in a secure way.

       There are two main ways to get an agent set up: The first is that the agent starts a new subcommand  into
       which some environment variables are exported, eg ssh-agent xterm &.  The second is that the agent prints
       the  needed shell commands (either sh(1) or csh(1) syntax can be generated) which can be evaluated in the
       calling shell, eg eval `ssh-agent -s` for Bourne-type shells such as sh(1) or ksh(1) and eval  `ssh-agent
       -c` for csh(1) and derivatives.

       Later ssh(1) looks at these variables and uses them to establish a connection to the agent.

       The  agent  will  never  send a private key over its request channel.  Instead, operations that require a
       private key will be performed by the agent, and the result will be returned to the requester.  This  way,
       private keys are not exposed to clients using the agent.

       A  Unix-domain  socket  is created and the name of this socket is stored in the SSH_AUTH_SOCK environment
       variable.  The socket is made accessible only to the current user.  This method is easily abused by  root
       or another instance of the same user.

       The SSH_AGENT_PID environment variable holds the agent's process ID.

       The agent exits automatically when the command given on the command line terminates.

       In  Debian, ssh-agent is installed with the set-group-id bit set, to prevent ptrace(2) attacks retrieving
       private key material.  This has the  side-effect  of  causing  the  run-time  linker  to  remove  certain
       environment  variables  which might have security implications for set-id programs, including LD_PRELOAD,
       LD_LIBRARY_PATH, and TMPDIR.  If you need to set any of these environment variables, you will need to  do
       so in the program executed by ssh-agent.

FILES

       ~/.ssh/identity
               Contains the protocol version 1 RSA authentication identity of the user.

       ~/.ssh/id_dsa
               Contains the protocol version 2 DSA authentication identity of the user.

       ~/.ssh/id_ecdsa
               Contains the protocol version 2 ECDSA authentication identity of the user.

       ~/.ssh/id_ed25519
               Contains the protocol version 2 ED25519 authentication identity of the user.

       ~/.ssh/id_rsa
               Contains the protocol version 2 RSA authentication identity of the user.

       $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid>
               Unix-domain  sockets  used  to contain the connection to the authentication agent.  These sockets
               should only be readable by the owner.  The sockets should  get  automatically  removed  when  the
               agent exits.

SEE ALSO

       ssh(1), ssh-add(1), ssh-keygen(1), sshd(8)

AUTHORS

       OpenSSH  is a derivative of the original and free ssh 1.2.12 release by Tatu Ylonen.  Aaron Campbell, Bob
       Beck, Markus Friedl, Niels Provos, Theo de Raadt and Dug Song removed many bugs, re-added newer  features
       and created OpenSSH.  Markus Friedl contributed the support for SSH protocol versions 1.5 and 2.0.

Debian                                          December 7, 2013                                    SSH-AGENT(1)