| .\" $OpenBSD: ssh-agent.1,v 1.7 1999/10/28 08:43:10 markus Exp $ |
| .\" |
| .\" -*- nroff -*- |
| .\" |
| .\" ssh-agent.1 |
| .\" |
| .\" Author: Tatu Ylonen <ylo@cs.hut.fi> |
| pp.\" |
| .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland |
| .\" All rights reserved |
| .\" |
| .\" Created: Sat Apr 23 20:10:43 1995 ylo |
| .\" |
| .Dd September 25, 1999 |
| .Dt SSH-AGENT 1 |
| .Os |
| .Sh NAME |
| .Nm ssh-agent |
| .Nd authentication agent |
| .Sh SYNOPSIS |
| .Nm ssh-agent |
| .Op Fl c Li | Fl s |
| .Op Fl k |
| .Oo |
| .Ar command |
| .Op Ar args ... |
| .Oc |
| .Sh DESCRIPTION |
| .Nm |
| is a program to hold authentication private keys. The |
| idea is that |
| .Nm |
| 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 RSA authentication when logging in to other |
| machines using |
| .Xr ssh 1 . |
| .Pp |
| The options are as follows: |
| .Bl -tag -width Ds |
| .It Fl c |
| Generate C-shell commands on |
| .Dv stdout . |
| This is the default if |
| .Ev SHELL |
| looks like it's a csh style of shell. |
| .It Fl s |
| Generate Bourne shell commands on |
| .Dv stdout . |
| This is the default if |
| .Ev SHELL |
| does not look like it's a csh style of shell. |
| .It Fl k |
| Kill the current agent (given by the |
| .Ev SSH_AGENT_PID |
| environment variable). |
| .El |
| .Pp |
| If a commandline is given, this is executed as a subprocess of the agent. |
| When the command dies, so does the agent. |
| .Pp |
| The agent initially does not have any private keys. Keys are added |
| using |
| .Xr ssh-add 1 . |
| When executed without arguments, |
| .Xr ssh-add 1 |
| adds the |
| .Pa $HOME/.ssh/identity |
| file. If the identity has a passphrase, |
| .Xr ssh-add 1 |
| asks for the passphrase (using a small X11 application if running |
| under X11, or from the terminal 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. |
| .Ic ssh-add -l |
| displays the identities currently held by the agent. |
| .Pp |
| 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. |
| .Pp |
| There are two main ways to get an agent setup: Either you let the agent |
| start a new subcommand into which some environment variables are exported, or |
| you let the agent print the needed shell commands (either |
| .Xr sh 1 |
| or |
| .Xr csh 1 |
| syntax can be generated) which can be evalled in the calling shell. |
| Later |
| .Xr ssh 1 |
| look at these variables and use them to establish a connection to the agent. |
| .Pp |
| A unix-domain socket is created |
| .Pq Pa /tmp/ssh-XXXXXXXX/agent.<pid> , |
| and the name of this socket is stored in the |
| .Ev 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. |
| .Pp |
| The |
| .Ev SSH_AGENT_PID |
| environment variable holds the agent's PID. |
| .Pp |
| The agent exits automatically when the command given on the command |
| line terminates. |
| .Pp |
| Here's a trick that will allow you to start this up from your .bash_profile (just put it in as the first thing that happens): |
| .Sp |
| .Vb 1 |
| |
| \& [ ! "$SSH_AGENT_PID" ] && exec ssh-agent -- bash --login |
| \& ssh-add |
| .Ve |
| .Sh FILES |
| .Bl -tag -width Ds |
| .It Pa $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 generating the key; that passphrase will be |
| used to encrypt the private part of this file. This file |
| is not used by |
| .Nm |
| but is normally added to the agent using |
| .Xr ssh-add 1 |
| at login time. |
| .It Pa /tmp/ssh-XXXX/agent.<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 automatically removed when the agent |
| exits. |
| .Sh AUTHOR |
| Tatu Ylonen <ylo@cs.hut.fi> |
| .Pp |
| OpenSSH |
| is a derivative of the original (free) ssh 1.2.12 release, but with bugs |
| removed and newer features re-added. Rapidly after the 1.2.12 release, |
| newer versions bore successively more restrictive licenses. This version |
| of OpenSSH |
| .Bl -bullet |
| .It |
| has all components of a restrictive nature (ie. patents, see |
| .Xr ssl 8 ) |
| directly removed from the source code; any licensed or patented components |
| are chosen from |
| external libraries. |
| .It |
| has been updated to support ssh protocol 1.5. |
| .It |
| contains added support for |
| .Xr kerberos 8 |
| authentication and ticket passing. |
| .It |
| supports one-time password authentication with |
| .Xr skey 1 . |
| .El |
| .Pp |
| The libraries described in |
| .Xr ssl 8 |
| are required for proper operation. |
| .Sh SEE ALSO |
| .Xr ssh 1 , |
| .Xr ssh-add 1 , |
| .Xr ssh-keygen 1 , |
| .Xr sshd 8 , |
| .Xr ssl 8 |