1.\" $OpenBSD: ssh-agent.1,v 1.10 2000/03/23 21:10:10 aaron Exp $ 2.\" 3.\" -*- nroff -*- 4.\" 5.\" ssh-agent.1 6.\" 7.\" Author: Tatu Ylonen <ylo@cs.hut.fi> 8.\" 9.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland 10.\" All rights reserved 11.\" 12.\" Created: Sat Apr 23 20:10:43 1995 ylo 13.\" 14.Dd September 25, 1999 15.Dt SSH-AGENT 1 16.Os 17.Sh NAME 18.Nm ssh-agent 19.Nd authentication agent 20.Sh SYNOPSIS 21.Nm ssh-agent 22.Op Fl c Li | Fl s 23.Op Fl k 24.Oo 25.Ar command 26.Op Ar args ... 27.Oc 28.Sh DESCRIPTION 29.Nm 30is a program to hold authentication private keys. 31The idea is that 32.Nm 33is started in the beginning of an X-session or a login session, and 34all other windows or programs are started as clients to the ssh-agent 35program. 36Through use of environment variables the agent can be located 37and automatically used for RSA authentication when logging in to other 38machines using 39.Xr ssh 1 . 40.Pp 41The options are as follows: 42.Bl -tag -width Ds 43.It Fl c 44Generate C-shell commands on 45.Dv stdout . 46This is the default if 47.Ev SHELL 48looks like it's a csh style of shell. 49.It Fl s 50Generate Bourne shell commands on 51.Dv stdout . 52This is the default if 53.Ev SHELL 54does not look like it's a csh style of shell. 55.It Fl k 56Kill the current agent (given by the 57.Ev SSH_AGENT_PID 58environment variable). 59.El 60.Pp 61If a commandline is given, this is executed as a subprocess of the agent. 62When the command dies, so does the agent. 63.Pp 64The agent initially does not have any private keys. 65Keys are added using 66.Xr ssh-add 1 . 67When executed without arguments, 68.Xr ssh-add 1 69adds the 70.Pa $HOME/.ssh/identity 71file. 72If the identity has a passphrase, 73.Xr ssh-add 1 74asks for the passphrase (using a small X11 application if running 75under X11, or from the terminal if running without X). 76It then sends the identity to the agent. 77Several identities can be stored in the 78agent; the agent can automatically use any of these identities. 79.Ic ssh-add -l 80displays the identities currently held by the agent. 81.Pp 82The idea is that the agent is run in the user's local PC, laptop, or 83terminal. 84Authentication data need not be stored on any other 85machine, and authentication passphrases never go over the network. 86However, the connection to the agent is forwarded over SSH 87remote logins, and the user can thus use the privileges given by the 88identities anywhere in the network in a secure way. 89.Pp 90There are two main ways to get an agent setup: 91Either you let the agent 92start a new subcommand into which some environment variables are exported, or 93you let the agent print the needed shell commands (either 94.Xr sh 1 95or 96.Xr csh 1 97syntax can be generated) which can be evalled in the calling shell. 98Later 99.Xr ssh 1 100look at these variables and use them to establish a connection to the agent. 101.Pp 102A unix-domain socket is created 103.Pq Pa /tmp/ssh-XXXXXXXX/agent.<pid> , 104and the name of this socket is stored in the 105.Ev SSH_AUTH_SOCK 106environment 107variable. 108The socket is made accessible only to the current user. 109This method is easily abused by root or another instance of the same 110user. 111.Pp 112The 113.Ev SSH_AGENT_PID 114environment variable holds the agent's PID. 115.Pp 116The agent exits automatically when the command given on the command 117line terminates. 118.Sh FILES 119.Bl -tag -width Ds 120.It Pa $HOME/.ssh/identity 121Contains the RSA authentication identity of the user. 122This file should not be readable by anyone but the user. 123It is possible to 124specify a passphrase when generating the key; that passphrase will be 125used to encrypt the private part of this file. 126This file is not used by 127.Nm 128but is normally added to the agent using 129.Xr ssh-add 1 130at login time. 131.It Pa /tmp/ssh-XXXX/agent.<pid> , 132Unix-domain sockets used to contain the connection to the 133authentication agent. 134These sockets should only be readable by the owner. 135The sockets should get automatically removed when the agent exits. 136.Sh AUTHOR 137Tatu Ylonen <ylo@cs.hut.fi> 138.Pp 139OpenSSH 140is a derivative of the original (free) ssh 1.2.12 release, but with bugs 141removed and newer features re-added. 142Rapidly after the 1.2.12 release, 143newer versions bore successively more restrictive licenses. 144This version of OpenSSH 145.Bl -bullet 146.It 147has all components of a restrictive nature (i.e., patents, see 148.Xr ssl 8 ) 149directly removed from the source code; any licensed or patented components 150are chosen from 151external libraries. 152.It 153has been updated to support ssh protocol 1.5. 154.It 155contains added support for 156.Xr kerberos 8 157authentication and ticket passing. 158.It 159supports one-time password authentication with 160.Xr skey 1 . 161.El 162.Pp 163The libraries described in 164.Xr ssl 8 165are required for proper operation. 166.Sh SEE ALSO 167.Xr ssh 1 , 168.Xr ssh-add 1 , 169.Xr ssh-keygen 1 , 170.Xr sshd 8 , 171.Xr ssl 8 172