NAME

     ssh-agent - authentication agent

SYNOPSIS

     ssh-agent command

     eval `ssh-agent [-k] [-s] [-c]`

DESCRIPTION

     Ssh-agent is a program to hold authentication private  keys.
     The idea is that ssh-agent is started in the beginning of an
     X-session or a login session, and all other windows or  pro-
     grams  are started as children of the ssh-agent program (the
     command normally starts X or is the user  shell).   Programs
     started  under  the agent inherit a connection to the agent,
     and the agent is automatically used for  RSA  authentication
     when logging to other machines using ssh.

     If the ssh-agent is started without any arguments  (no  com-
     mand)  it  will  fork and start agent as background process.
     The agent also prints command that can be evaluated in sh or
     csh  like  shells,  that  will  set  the  SSH_AUTH_SOCK  and
     SSH_AGENT_PID  environment  variables.   The   SSH_AGENT_PID
     environment  variable can be used to kill agent away when it
     is no longer needed (you logout from X-session etc).  If  no
     options are given the ssh-agent uses SHELL environment vari-
     able the detect what kind of shell you  have  (*csh  or  sh-
     style shell). The -c option will force csh-style shell, and
     -s option will force sh-style shell.

     Note that in SysV variants (at least IRIX and  Solaris)  the
     environment  variable  SHELL  might  not  contain the actual
     value of the shell executing the evaluation.  If ALTSHELL is
     set  to  YES  in  /etc/default/login,  the SHELL environment
     variable is set to the login shell of the user.

     The -k option can be used to kill  agent  automatically.  It
     kills  the  agent (it uses the SSH_AGENT_PID to find it) and
     prints  shell  commands  to  stdout  that  will  unset   the
     SSH_AUTH_SOCKET and SSH_AGENT_PID enviroment variables.

     The agent initially does not have any  private  keys.   Keys
     are  added  using  ssh-add. When executed without arguments,
     ssh-add adds the $HOME/.ssh/identity file.  If the  identity
     has  a  passphrase, ssh-add asks for the passphrase (using a
     small X11 application if running under X11, or from the ter-
     minal  if running without X).  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.

     A connection to the agent is inherited by child programs.  A
     unix-domain  socket is created (/tmp/ssh-$USER/agent-socket-
     <pid>), where the %d is  the  process  id  of  the  listener
     (agent  or sshd proxying the agent). 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.  Older  versions  of  ssh  used  inherited  file
     descriptors for contacting the  agent  and  used  the  unix-
     domain sockets in an incompatible way.

     If the command is given as argument to ssh-agent  the  agent
     exits  automatically  when  the command given on the command
     line terminates.  The command  is  executed  even  if  agent
     fails  to  start  it's  key-storing and challenge-processing
     services.

FILES

     $HOME/.ssh/identity
          Contains the RSA authentication identity of  the  user.
          This  file  should  not  be  readable by anyone but the
          user.  It is possible to specify a passphrase when gen-
          erating  the  key;  that  passphrase  will  be  used to
          encrypt the private part of this file.   This  file  is
          not  used  by  ssh-agent,  but is normally added to the
          agent using ssh-add at login time.

     /tmp/ssh-$USER/agent-socket-<pid>
          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 automat-
          ically  removed when the agent exits. The parent direc-
          tory of ssh-$USER must have it's sticky bit set.

AUTHOR

     Tatu Ylonen <ylo@ssh.fi>

SEE ALSO

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