ssh-agent(1) - NetBSD Manual Pages

SSH-AGENT(1)                NetBSD Reference Manual               SSH-AGENT(1)


NAME

     ssh-agent - authentication agent for the Secure Shell


SYNOPSIS

     ssh-agent [-c | -s] [-k] [command [args ...]]


DESCRIPTION

     ssh-agent is a program to hold private keys used for public key (RSA or
     DSA) authentication.  It is intended to be started at the beginning of an
     X Window System or login session.  ssh-agent works by setting certain
     variables in the user's environment.  Through the use of these environ-
     ment variables, the agent can be located and automatically used for RSA
     authentication when logging in to other hosts using ssh(1).

     A user generally one identity per ``workstation'', e.g. laptop or desktop
     computer, handheld device, etc.  Use of ssh-agent on these workstations
     prevents having to store authentication information on remote hosts, and
     prevents having to transmit Passphrases over the network.

     The options are as follows:

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

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

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

     If a command line is given, it is executed as a sub-process of the agent.
     When the command dies, so does the agent.  If a command line is not giv-
     en, the agent will not automatically exit, and must be explicitly killed
     with the -k option when the session ends.

     The agent initially does not have any private keys.  Keys must added us-
     ing ssh-add(1).

     There are two main ways to set up the agent:

     +   Invoke ssh-agent with a command line.  The command will be started
         with the appropriate environment variables set to use the agent.

     +   Invoke ssh-agent without a command line, which causes ssh-agent to
         print shell commands which will set up the enviroment if evaluated by
         the shell.  ssh-agent will attempt to detect if you are running a
         csh(1) or sh(1) style shell, and generate the appropriate syntax.
         The syntax can be forced with the -c and -s flags.

     When the agent is started, a Unix-domain socket is created and the name
     of this socket stored in the SSH_AUTH_SOCK environment variable.  The
     socket is made accessible only to the current user.  This method is easi-
     ly abused by root or another instance of the same user.


EXAMPLES

     The following shows using the command line facility of ssh-agent to asso-
     ciate an agent with an X session started by xinit(1):

           #!/bin/sh -
           #
           # $HOME/.xinitrc
           #

           if [ -r $HOME/.ssh/identity ]; then
                   EXEC="exec ssh-agent"
           else
                   EXEC="exec"
           fi

           # .xsession will perform the ssh-add to add the keys.
           $EXEC $HOME/.xsession

     The following shows using ssh-agent and ssh-add(1) in an X session start-
     up script:

           #!/bin/sh -
           #
           # $HOME/.xsession
           #

           if [ -f $HOME/.Xdefaults ]; then
                   xrdb -merge $HOME/.Xdefaults
           fi

           xsetroot -solid black

           if [ -r $HOME/.ssh/identity ]; then
                   eval `ssh-agent`
                   ssh-add < /dev/null     # ensure stdin is not a tty
                   if [ $? != 0 ]; then
                           # Failed to provide a Passphrase, bail out!
                           exit 1
                   fi
           fi

           # Start the window manager.
           twm

           # Kill the agent we started above.
           if [ -n "$SSH_AGENT_PID" ]; then
                   ssh-agent -k
           fi


FILES

     /tmp/ssh-XXXXXXXX/agent.<pid>
             Unix-domain sockets used to communicate with the authentication
             agent.  These sockets should only be readable by the owner.  The
             sockets should get automatically removed when the agent exits.


AUTHOR

     Tatu Ylonen <ylo@cs.hut.fi>, Markus Friedl


SEE ALSO

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

NetBSD 1.5                      August 6, 2000                               2