blob: 66a47569248d7ec7ed2acb4cf260a8ddef33a76a [file] [log] [blame]
Damien Millere247cc42000-05-07 12:03:14 +10001.\" $OpenBSD: ssh-agent.1,v 1.12 2000/05/03 18:04:39 markus Exp $
Damien Miller32aa1441999-10-29 09:15:49 +10002.\"
3.\" -*- nroff -*-
4.\"
5.\" ssh-agent.1
6.\"
7.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
Damien Miller10f6f6b1999-11-17 17:29:08 +11008.\"
Damien Miller32aa1441999-10-29 09:15:49 +10009.\" 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
Damien Miller22c77262000-04-13 12:26:34 +100021.Nm ssh-agent
Damien Miller32aa1441999-10-29 09:15:49 +100022.Op Fl c Li | Fl s
23.Op Fl k
24.Oo
25.Ar command
26.Op Ar args ...
27.Oc
Damien Miller22c77262000-04-13 12:26:34 +100028.Sh DESCRIPTION
Damien Miller32aa1441999-10-29 09:15:49 +100029.Nm
Damien Millere247cc42000-05-07 12:03:14 +100030is a program to hold private keys used for RSA authentication.
Damien Miller450a7a12000-03-26 13:04:51 +100031The idea is that
Damien Miller32aa1441999-10-29 09:15:49 +100032.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
Damien Miller450a7a12000-03-26 13:04:51 +100035program.
36Through use of environment variables the agent can be located
Damien Miller32aa1441999-10-29 09:15:49 +100037and 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
Damien Miller450a7a12000-03-26 13:04:51 +100064The agent initially does not have any private keys.
65Keys are added using
Damien Miller32aa1441999-10-29 09:15:49 +100066.Xr ssh-add 1 .
Damien Miller22c77262000-04-13 12:26:34 +100067When executed without arguments,
Damien Miller32aa1441999-10-29 09:15:49 +100068.Xr ssh-add 1
Damien Miller22c77262000-04-13 12:26:34 +100069adds the
Damien Miller32aa1441999-10-29 09:15:49 +100070.Pa $HOME/.ssh/identity
Damien Miller450a7a12000-03-26 13:04:51 +100071file.
Damien Miller22c77262000-04-13 12:26:34 +100072If the identity has a passphrase,
Damien Miller32aa1441999-10-29 09:15:49 +100073.Xr ssh-add 1
74asks for the passphrase (using a small X11 application if running
Damien Miller450a7a12000-03-26 13:04:51 +100075under X11, or from the terminal if running without X).
76It then sends the identity to the agent.
77Several identities can be stored in the
Damien Miller32aa1441999-10-29 09:15:49 +100078agent; 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
Damien Miller450a7a12000-03-26 13:04:51 +100083terminal.
84Authentication data need not be stored on any other
Damien Miller32aa1441999-10-29 09:15:49 +100085machine, 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
Damien Miller450a7a12000-03-26 13:04:51 +100090There are two main ways to get an agent setup:
91Either you let the agent
Damien Miller32aa1441999-10-29 09:15:49 +100092start 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
Damien Miller450a7a12000-03-26 13:04:51 +1000107variable.
108The socket is made accessible only to the current user.
Damien Miller32aa1441999-10-29 09:15:49 +1000109This 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.
Damien Miller32aa1441999-10-29 09:15:49 +1000118.Sh FILES
119.Bl -tag -width Ds
120.It Pa $HOME/.ssh/identity
Damien Miller450a7a12000-03-26 13:04:51 +1000121Contains the RSA authentication identity of the user.
122This file should not be readable by anyone but the user.
123It is possible to
Damien Miller32aa1441999-10-29 09:15:49 +1000124specify a passphrase when generating the key; that passphrase will be
Damien Miller450a7a12000-03-26 13:04:51 +1000125used to encrypt the private part of this file.
126This file is not used by
Damien Miller32aa1441999-10-29 09:15:49 +1000127.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
Damien Miller450a7a12000-03-26 13:04:51 +1000133authentication agent.
134These sockets should only be readable by the owner.
135The sockets should get automatically removed when the agent exits.
Damien Miller32aa1441999-10-29 09:15:49 +1000136.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
Damien Miller450a7a12000-03-26 13:04:51 +1000141removed and newer features re-added.
142Rapidly after the 1.2.12 release,
143newer versions bore successively more restrictive licenses.
144This version of OpenSSH
Damien Miller32aa1441999-10-29 09:15:49 +1000145.Bl -bullet
146.It
Damien Millercfabe862000-04-20 23:27:27 +1000147has all components of a restrictive nature (i.e., patents)
Damien Miller32aa1441999-10-29 09:15:49 +1000148directly removed from the source code; any licensed or patented components
149are chosen from
150external libraries.
151.It
152has been updated to support ssh protocol 1.5.
153.It
Damien Miller22c77262000-04-13 12:26:34 +1000154contains added support for
Damien Miller32aa1441999-10-29 09:15:49 +1000155.Xr kerberos 8
156authentication and ticket passing.
157.It
158supports one-time password authentication with
159.Xr skey 1 .
160.El
161.Pp
Damien Miller32aa1441999-10-29 09:15:49 +1000162.Sh SEE ALSO
163.Xr ssh 1 ,
164.Xr ssh-add 1 ,
165.Xr ssh-keygen 1 ,
166.Xr sshd 8 ,