blob: 5cdeee2dab2dfbfa984fb3109b2df26ef4ee6f45 [file] [log] [blame]
Damien Miller32aa1441999-10-29 09:15:49 +10001.\" -*- nroff -*-
2.\"
Damien Miller32aa1441999-10-29 09:15:49 +10003.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
Damien Miller32aa1441999-10-29 09:15:49 +10004.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
5.\" All rights reserved
6.\"
Damien Millere4340be2000-09-16 13:29:08 +11007.\" As far as I am concerned, the code I have written for this software
8.\" can be used freely for any purpose. Any derived versions of this
9.\" software must be clearly marked as such, and if the derived work is
10.\" incompatible with the protocol description in the RFC file, it must be
11.\" called by a name other than "ssh" or "Secure Shell".
Damien Miller32aa1441999-10-29 09:15:49 +100012.\"
Ben Lindstrom92a2e382001-03-05 06:59:27 +000013.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
14.\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
15.\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
Damien Millere4340be2000-09-16 13:29:08 +110016.\"
17.\" Redistribution and use in source and binary forms, with or without
18.\" modification, are permitted provided that the following conditions
19.\" are met:
20.\" 1. Redistributions of source code must retain the above copyright
21.\" notice, this list of conditions and the following disclaimer.
22.\" 2. Redistributions in binary form must reproduce the above copyright
23.\" notice, this list of conditions and the following disclaimer in the
24.\" documentation and/or other materials provided with the distribution.
25.\"
26.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
27.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
28.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
29.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
30.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
31.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
32.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
33.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
35.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Damien Miller32aa1441999-10-29 09:15:49 +100036.\"
Damien Millerb8ea2482004-06-18 22:21:55 +100037.\" $OpenBSD: ssh.1,v 1.192 2004/06/18 10:55:43 markus Exp $
Damien Miller32aa1441999-10-29 09:15:49 +100038.Dd September 25, 1999
39.Dt SSH 1
40.Os
41.Sh NAME
42.Nm ssh
Ben Lindstromd58eb5f2001-03-07 06:07:22 +000043.Nd OpenSSH SSH client (remote login program)
Damien Miller32aa1441999-10-29 09:15:49 +100044.Sh SYNOPSIS
45.Nm ssh
Darren Tuckerba5c5922004-06-18 16:22:39 +100046.Op Fl 1246AaCfgkMNnqsTtVvXxY
Ben Lindstrome0f88042001-04-30 13:06:24 +000047.Op Fl b Ar bind_address
Damien Miller30c3d422000-05-09 11:02:59 +100048.Op Fl c Ar cipher_spec
Darren Tucker61776952003-10-02 16:19:47 +100049.Op Fl D Ar port
Damien Miller32aa1441999-10-29 09:15:49 +100050.Op Fl e Ar escape_char
Ben Lindstrom14f31ab2001-09-12 17:48:04 +000051.Op Fl F Ar configfile
Darren Tucker61776952003-10-02 16:19:47 +100052.Op Fl i Ar identity_file
53.Bk -words
Damien Miller32aa1441999-10-29 09:15:49 +100054.Oo Fl L Xo
55.Sm off
Damien Miller32aa1441999-10-29 09:15:49 +100056.Ar port :
Damien Miller396691a2000-01-20 22:44:08 +110057.Ar host :
Damien Miller32aa1441999-10-29 09:15:49 +100058.Ar hostport
59.Sm on
60.Xc
61.Oc
Damien Miller495dca32003-04-01 21:42:14 +100062.Ek
Darren Tucker61776952003-10-02 16:19:47 +100063.Op Fl l Ar login_name
64.Op Fl m Ar mac_spec
65.Op Fl o Ar option
Damien Miller495dca32003-04-01 21:42:14 +100066.Bk -words
Darren Tucker61776952003-10-02 16:19:47 +100067.Op Fl p Ar port
68.Ek
Damien Miller32aa1441999-10-29 09:15:49 +100069.Oo Fl R Xo
70.Sm off
Damien Miller32aa1441999-10-29 09:15:49 +100071.Ar port :
Damien Miller396691a2000-01-20 22:44:08 +110072.Ar host :
Damien Miller32aa1441999-10-29 09:15:49 +100073.Ar hostport
74.Sm on
75.Xc
76.Oc
Damien Millerb8ea2482004-06-18 22:21:55 +100077.Op Fl S Ar ctl
Darren Tucker61776952003-10-02 16:19:47 +100078.Oo Ar user Ns @ Oc Ns Ar hostname
Damien Miller32aa1441999-10-29 09:15:49 +100079.Op Ar command
Damien Miller22c77262000-04-13 12:26:34 +100080.Sh DESCRIPTION
Damien Miller32aa1441999-10-29 09:15:49 +100081.Nm
Ben Lindstromd58eb5f2001-03-07 06:07:22 +000082(SSH client) is a program for logging into a remote machine and for
Damien Miller7684ee12000-03-17 23:40:15 +110083executing commands on a remote machine.
Darren Tucker61776952003-10-02 16:19:47 +100084It is intended to replace rlogin and rsh,
85and provide secure encrypted communications between
Damien Miller7684ee12000-03-17 23:40:15 +110086two untrusted hosts over an insecure network.
Darren Tucker61776952003-10-02 16:19:47 +100087X11 connections and arbitrary TCP/IP ports
88can also be forwarded over the secure channel.
Damien Miller32aa1441999-10-29 09:15:49 +100089.Pp
90.Nm
Damien Miller22c77262000-04-13 12:26:34 +100091connects and logs into the specified
Darren Tucker61776952003-10-02 16:19:47 +100092.Ar hostname
93(with optional
94.Ar user
95name).
Damien Miller32aa1441999-10-29 09:15:49 +100096The user must prove
Damien Millere247cc42000-05-07 12:03:14 +100097his/her identity to the remote machine using one of several methods
Darren Tucker61776952003-10-02 16:19:47 +100098depending on the protocol version used.
Damien Millere247cc42000-05-07 12:03:14 +100099.Pp
Darren Tucker61776952003-10-02 16:19:47 +1000100If
101.Ar command
102is specified,
103.Ar command
104is executed on the remote host instead of a login shell.
Damien Millere247cc42000-05-07 12:03:14 +1000105.Ss SSH protocol version 1
Damien Miller32aa1441999-10-29 09:15:49 +1000106First, if the machine the user logs in from is listed in
107.Pa /etc/hosts.equiv
108or
Damien Miller886c63a2000-01-20 23:13:36 +1100109.Pa /etc/shosts.equiv
Damien Miller32aa1441999-10-29 09:15:49 +1000110on the remote machine, and the user names are
111the same on both sides, the user is immediately permitted to log in.
Damien Miller22c77262000-04-13 12:26:34 +1000112Second, if
Darren Tucker61776952003-10-02 16:19:47 +1000113.Pa .rhosts
Damien Miller32aa1441999-10-29 09:15:49 +1000114or
Darren Tucker61776952003-10-02 16:19:47 +1000115.Pa .shosts
Damien Miller32aa1441999-10-29 09:15:49 +1000116exists in the user's home directory on the
117remote machine and contains a line containing the name of the client
118machine and the name of the user on that machine, the user is
Damien Miller7684ee12000-03-17 23:40:15 +1100119permitted to log in.
120This form of authentication alone is normally not
Damien Miller32aa1441999-10-29 09:15:49 +1000121allowed by the server because it is not secure.
122.Pp
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000123The second authentication method is the
Darren Tucker61776952003-10-02 16:19:47 +1000124.Em rhosts
Damien Miller32aa1441999-10-29 09:15:49 +1000125or
Darren Tucker61776952003-10-02 16:19:47 +1000126.Em hosts.equiv
Damien Miller7684ee12000-03-17 23:40:15 +1100127method combined with RSA-based host authentication.
128It means that if the login would be permitted by
Damien Millere247cc42000-05-07 12:03:14 +1000129.Pa $HOME/.rhosts ,
130.Pa $HOME/.shosts ,
Damien Miller32aa1441999-10-29 09:15:49 +1000131.Pa /etc/hosts.equiv ,
132or
Damien Miller886c63a2000-01-20 23:13:36 +1100133.Pa /etc/shosts.equiv ,
Damien Miller32aa1441999-10-29 09:15:49 +1000134and if additionally the server can verify the client's
Damien Miller22c77262000-04-13 12:26:34 +1000135host key (see
Damien Miller05eda432002-02-10 18:32:28 +1100136.Pa /etc/ssh/ssh_known_hosts
Damien Miller33e511e1999-11-11 11:43:13 +1100137and
138.Pa $HOME/.ssh/known_hosts
Damien Miller32aa1441999-10-29 09:15:49 +1000139in the
140.Sx FILES
Darren Tucker61776952003-10-02 16:19:47 +1000141section), only then is login permitted.
Damien Miller7684ee12000-03-17 23:40:15 +1100142This authentication method closes security holes due to IP
143spoofing, DNS spoofing and routing spoofing.
144[Note to the administrator:
Damien Miller32aa1441999-10-29 09:15:49 +1000145.Pa /etc/hosts.equiv ,
Damien Millere247cc42000-05-07 12:03:14 +1000146.Pa $HOME/.rhosts ,
Damien Miller32aa1441999-10-29 09:15:49 +1000147and the rlogin/rsh protocol in general, are inherently insecure and should be
148disabled if security is desired.]
149.Pp
Damien Miller22c77262000-04-13 12:26:34 +1000150As a third authentication method,
Damien Miller32aa1441999-10-29 09:15:49 +1000151.Nm
152supports RSA based authentication.
153The scheme is based on public-key cryptography: there are cryptosystems
154where encryption and decryption are done using separate keys, and it
155is not possible to derive the decryption key from the encryption key.
Damien Miller7684ee12000-03-17 23:40:15 +1100156RSA is one such system.
Damien Miller22c77262000-04-13 12:26:34 +1000157The idea is that each user creates a public/private
Damien Miller7684ee12000-03-17 23:40:15 +1100158key pair for authentication purposes.
159The server knows the public key, and only the user knows the private key.
Darren Tucker61776952003-10-02 16:19:47 +1000160.Pp
Damien Miller22c77262000-04-13 12:26:34 +1000161The file
Damien Miller32aa1441999-10-29 09:15:49 +1000162.Pa $HOME/.ssh/authorized_keys
Darren Tucker61776952003-10-02 16:19:47 +1000163lists the public keys that are permitted for logging in.
Damien Miller7684ee12000-03-17 23:40:15 +1100164When the user logs in, the
Damien Miller32aa1441999-10-29 09:15:49 +1000165.Nm
166program tells the server which key pair it would like to use for
Damien Miller7684ee12000-03-17 23:40:15 +1100167authentication.
Darren Tucker61776952003-10-02 16:19:47 +1000168The server checks if this key is permitted, and if so,
169sends the user (actually the
Damien Miller32aa1441999-10-29 09:15:49 +1000170.Nm
171program running on behalf of the user) a challenge, a random number,
Damien Miller7684ee12000-03-17 23:40:15 +1100172encrypted by the user's public key.
Darren Tucker61776952003-10-02 16:19:47 +1000173The challenge can only be decrypted using the proper private key.
174The user's client then decrypts the challenge using the private key,
175proving that he/she knows the private key
176but without disclosing it to the server.
Damien Miller32aa1441999-10-29 09:15:49 +1000177.Pp
178.Nm
Damien Miller7684ee12000-03-17 23:40:15 +1100179implements the RSA authentication protocol automatically.
180The user creates his/her RSA key pair by running
Damien Miller32aa1441999-10-29 09:15:49 +1000181.Xr ssh-keygen 1 .
Damien Miller22c77262000-04-13 12:26:34 +1000182This stores the private key in
Damien Millere247cc42000-05-07 12:03:14 +1000183.Pa $HOME/.ssh/identity
Darren Tucker61776952003-10-02 16:19:47 +1000184and stores the public key in
Damien Millere247cc42000-05-07 12:03:14 +1000185.Pa $HOME/.ssh/identity.pub
Damien Miller7684ee12000-03-17 23:40:15 +1100186in the user's home directory.
187The user should then copy the
Damien Miller32aa1441999-10-29 09:15:49 +1000188.Pa identity.pub
Damien Miller22c77262000-04-13 12:26:34 +1000189to
Damien Millere247cc42000-05-07 12:03:14 +1000190.Pa $HOME/.ssh/authorized_keys
Damien Miller22c77262000-04-13 12:26:34 +1000191in his/her home directory on the remote machine (the
Damien Miller32aa1441999-10-29 09:15:49 +1000192.Pa authorized_keys
Damien Miller22c77262000-04-13 12:26:34 +1000193file corresponds to the conventional
Damien Millere247cc42000-05-07 12:03:14 +1000194.Pa $HOME/.rhosts
Damien Miller32aa1441999-10-29 09:15:49 +1000195file, and has one key
Damien Miller7684ee12000-03-17 23:40:15 +1100196per line, though the lines can be very long).
197After this, the user can log in without giving the password.
Darren Tucker61776952003-10-02 16:19:47 +1000198RSA authentication is much more secure than
199.Em rhosts
200authentication.
Damien Miller32aa1441999-10-29 09:15:49 +1000201.Pp
202The most convenient way to use RSA authentication may be with an
Damien Miller7684ee12000-03-17 23:40:15 +1100203authentication agent.
204See
Damien Miller32aa1441999-10-29 09:15:49 +1000205.Xr ssh-agent 1
206for more information.
207.Pp
Damien Miller22c77262000-04-13 12:26:34 +1000208If other authentication methods fail,
Damien Miller32aa1441999-10-29 09:15:49 +1000209.Nm
Damien Miller7684ee12000-03-17 23:40:15 +1100210prompts the user for a password.
211The password is sent to the remote
Damien Miller32aa1441999-10-29 09:15:49 +1000212host for checking; however, since all communications are encrypted,
213the password cannot be seen by someone listening on the network.
Damien Millere247cc42000-05-07 12:03:14 +1000214.Ss SSH protocol version 2
Darren Tucker61776952003-10-02 16:19:47 +1000215When a user connects using protocol version 2,
Damien Miller07a2d422002-02-05 12:16:15 +1100216similar authentication methods are available.
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000217Using the default values for
218.Cm PreferredAuthentications ,
Ben Lindstroma9086a12001-08-06 20:58:51 +0000219the client will try to authenticate first using the hostbased method;
Darren Tucker61776952003-10-02 16:19:47 +1000220if this method fails, public key authentication is attempted,
221and finally if this method fails, keyboard-interactive and
Ben Lindstroma9086a12001-08-06 20:58:51 +0000222password authentication are tried.
Damien Millere247cc42000-05-07 12:03:14 +1000223.Pp
224The public key method is similar to RSA authentication described
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000225in the previous section and allows the RSA or DSA algorithm to be used:
Ben Lindstrom18a82ac2001-04-11 15:59:35 +0000226The client uses his private key,
Damien Millere247cc42000-05-07 12:03:14 +1000227.Pa $HOME/.ssh/id_dsa
Ben Lindstrom18a82ac2001-04-11 15:59:35 +0000228or
229.Pa $HOME/.ssh/id_rsa ,
Damien Millere247cc42000-05-07 12:03:14 +1000230to sign the session identifier and sends the result to the server.
231The server checks whether the matching public key is listed in
Ben Lindstromf96704d2001-06-25 04:17:12 +0000232.Pa $HOME/.ssh/authorized_keys
Damien Millere247cc42000-05-07 12:03:14 +1000233and grants access if both the key is found and the signature is correct.
234The session identifier is derived from a shared Diffie-Hellman value
235and is only known to the client and the server.
236.Pp
Darren Tucker61776952003-10-02 16:19:47 +1000237If public key authentication fails or is not available, a password
238can be sent encrypted to the remote host to prove the user's identity.
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000239.Pp
240Additionally,
241.Nm
242supports hostbased or challenge response authentication.
Damien Millere247cc42000-05-07 12:03:14 +1000243.Pp
244Protocol 2 provides additional mechanisms for confidentiality
Damien Miller05202ff2004-06-15 10:30:39 +1000245(the traffic is encrypted using AES, 3DES, Blowfish, CAST128 or Arcfour)
246and integrity (hmac-md5, hmac-sha1, hmac-ripemd160).
Damien Millere247cc42000-05-07 12:03:14 +1000247Note that protocol 1 lacks a strong mechanism for ensuring the
248integrity of the connection.
Damien Millere247cc42000-05-07 12:03:14 +1000249.Ss Login session and remote execution
Damien Miller32aa1441999-10-29 09:15:49 +1000250When the user's identity has been accepted by the server, the server
251either executes the given command, or logs into the machine and gives
Damien Miller7684ee12000-03-17 23:40:15 +1100252the user a normal shell on the remote machine.
253All communication with
Damien Miller32aa1441999-10-29 09:15:49 +1000254the remote command or shell will be automatically encrypted.
255.Pp
256If a pseudo-terminal has been allocated (normal login session), the
Ben Lindstrom9ffdcb52001-04-20 12:50:51 +0000257user may use the escape characters noted below.
Damien Miller32aa1441999-10-29 09:15:49 +1000258.Pp
Darren Tucker61776952003-10-02 16:19:47 +1000259If no pseudo-tty has been allocated,
260the session is transparent and can be used to reliably transfer binary data.
Damien Miller7684ee12000-03-17 23:40:15 +1100261On most systems, setting the escape character to
Damien Miller32aa1441999-10-29 09:15:49 +1000262.Dq none
263will also make the session transparent even if a tty is used.
264.Pp
Ben Lindstroma6885612000-12-09 03:45:32 +0000265The session terminates when the command or shell on the remote
Ben Lindstromebd888d2001-03-05 05:49:29 +0000266machine exits and all X11 and TCP/IP connections have been closed.
Darren Tucker61776952003-10-02 16:19:47 +1000267The exit status of the remote program is returned as the exit status of
Damien Miller32aa1441999-10-29 09:15:49 +1000268.Nm ssh .
Ben Lindstrom9ffdcb52001-04-20 12:50:51 +0000269.Ss Escape Characters
Darren Tucker61776952003-10-02 16:19:47 +1000270When a pseudo-terminal has been requested,
271.Nm
272supports a number of functions through the use of an escape character.
Ben Lindstrom9ffdcb52001-04-20 12:50:51 +0000273.Pp
274A single tilde character can be sent as
275.Ic ~~
Ben Lindstrom66007692001-07-22 20:41:59 +0000276or by following the tilde by a character other than those described below.
Ben Lindstrom9ffdcb52001-04-20 12:50:51 +0000277The escape character must always follow a newline to be interpreted as
278special.
279The escape character can be changed in configuration files using the
280.Cm EscapeChar
Ben Lindstrom24643222001-06-25 05:08:11 +0000281configuration directive or on the command line by the
Ben Lindstrom9ffdcb52001-04-20 12:50:51 +0000282.Fl e
283option.
284.Pp
285The supported escapes (assuming the default
286.Ql ~ )
287are:
288.Bl -tag -width Ds
289.It Cm ~.
Darren Tucker61776952003-10-02 16:19:47 +1000290Disconnect.
Ben Lindstrom9ffdcb52001-04-20 12:50:51 +0000291.It Cm ~^Z
Darren Tucker61776952003-10-02 16:19:47 +1000292Background
293.Nm ssh .
Ben Lindstrom9ffdcb52001-04-20 12:50:51 +0000294.It Cm ~#
Darren Tucker61776952003-10-02 16:19:47 +1000295List forwarded connections.
Ben Lindstrom9ffdcb52001-04-20 12:50:51 +0000296.It Cm ~&
Darren Tucker61776952003-10-02 16:19:47 +1000297Background
298.Nm
299at logout when waiting for forwarded connection / X11 sessions to terminate.
Ben Lindstrom9ffdcb52001-04-20 12:50:51 +0000300.It Cm ~?
Darren Tucker61776952003-10-02 16:19:47 +1000301Display a list of escape characters.
Damien Miller54c45982003-05-15 10:20:13 +1000302.It Cm ~B
Darren Tucker61776952003-10-02 16:19:47 +1000303Send a BREAK to the remote system
304(only useful for SSH protocol version 2 and if the peer supports it).
Ben Lindstrom5589f4b2002-03-22 03:24:32 +0000305.It Cm ~C
Darren Tuckere7066df2004-05-24 10:18:05 +1000306Open command line.
307Currently this allows the addition of port forwardings using the
Ben Lindstrom5589f4b2002-03-22 03:24:32 +0000308.Fl L
309and
310.Fl R
Darren Tuckere7066df2004-05-24 10:18:05 +1000311options (see below).
Darren Tuckere534e122004-05-24 10:35:14 +1000312It also allows the cancellation of existing remote port-forwardings
Darren Tuckere7066df2004-05-24 10:18:05 +1000313using
314.Fl KR Ar hostport .
Darren Tucker1973c882004-05-24 10:34:36 +1000315Basic help is available, using the
316.Fl h
Darren Tuckere7066df2004-05-24 10:18:05 +1000317option.
Ben Lindstrom9ffdcb52001-04-20 12:50:51 +0000318.It Cm ~R
Darren Tucker61776952003-10-02 16:19:47 +1000319Request rekeying of the connection
320(only useful for SSH protocol version 2 and if the peer supports it).
Ben Lindstrom9ffdcb52001-04-20 12:50:51 +0000321.El
Damien Millere247cc42000-05-07 12:03:14 +1000322.Ss X11 and TCP forwarding
Ben Lindstrom71215072001-05-17 03:16:18 +0000323If the
324.Cm ForwardX11
325variable is set to
326.Dq yes
Darren Tucker61776952003-10-02 16:19:47 +1000327(or see the description of the
Ben Lindstrom71215072001-05-17 03:16:18 +0000328.Fl X
329and
330.Fl x
331options described later)
332and the user is using X11 (the
Damien Miller32aa1441999-10-29 09:15:49 +1000333.Ev DISPLAY
334environment variable is set), the connection to the X11 display is
335automatically forwarded to the remote side in such a way that any X11
336programs started from the shell (or command) will go through the
337encrypted channel, and the connection to the real X server will be made
Damien Miller7684ee12000-03-17 23:40:15 +1100338from the local machine.
339The user should not manually set
Damien Miller32aa1441999-10-29 09:15:49 +1000340.Ev DISPLAY .
341Forwarding of X11 connections can be
342configured on the command line or in configuration files.
343.Pp
344The
Damien Miller22c77262000-04-13 12:26:34 +1000345.Ev DISPLAY
Damien Miller32aa1441999-10-29 09:15:49 +1000346value set by
347.Nm
Darren Tucker61776952003-10-02 16:19:47 +1000348will point to the server machine, but with a display number greater than zero.
Damien Miller7684ee12000-03-17 23:40:15 +1100349This is normal, and happens because
Damien Miller32aa1441999-10-29 09:15:49 +1000350.Nm
351creates a
352.Dq proxy
353X server on the server machine for forwarding the
354connections over the encrypted channel.
355.Pp
356.Nm
357will also automatically set up Xauthority data on the server machine.
358For this purpose, it will generate a random authorization cookie,
359store it in Xauthority on the server, and verify that any forwarded
360connections carry this cookie and replace it by the real cookie when
Damien Miller7684ee12000-03-17 23:40:15 +1100361the connection is opened.
362The real authentication cookie is never
Damien Miller32aa1441999-10-29 09:15:49 +1000363sent to the server machine (and no cookies are sent in the plain).
364.Pp
Ben Lindstrom3541f182002-08-20 19:03:20 +0000365If the
366.Cm ForwardAgent
367variable is set to
368.Dq yes
Darren Tucker61776952003-10-02 16:19:47 +1000369(or see the description of the
Ben Lindstrom3541f182002-08-20 19:03:20 +0000370.Fl A
371and
372.Fl a
Damien Miller495dca32003-04-01 21:42:14 +1000373options described later) and
Ben Lindstrom3541f182002-08-20 19:03:20 +0000374the user is using an authentication agent, the connection to the agent
375is automatically forwarded to the remote side.
Damien Miller32aa1441999-10-29 09:15:49 +1000376.Pp
377Forwarding of arbitrary TCP/IP connections over the secure channel can
Ben Lindstrom979c9812001-07-22 20:45:39 +0000378be specified either on the command line or in a configuration file.
Damien Miller7684ee12000-03-17 23:40:15 +1100379One possible application of TCP/IP forwarding is a secure connection to an
Ben Lindstromebd888d2001-03-05 05:49:29 +0000380electronic purse; another is going through firewalls.
Damien Millere247cc42000-05-07 12:03:14 +1000381.Ss Server authentication
Damien Miller32aa1441999-10-29 09:15:49 +1000382.Nm
Damien Millere247cc42000-05-07 12:03:14 +1000383automatically maintains and checks a database containing
Damien Miller7684ee12000-03-17 23:40:15 +1100384identifications for all hosts it has ever been used with.
Ben Lindstromd6481ea2001-06-25 04:37:41 +0000385Host keys are stored in
Damien Millere247cc42000-05-07 12:03:14 +1000386.Pa $HOME/.ssh/known_hosts
Damien Miller7684ee12000-03-17 23:40:15 +1100387in the user's home directory.
Ben Lindstromd6481ea2001-06-25 04:37:41 +0000388Additionally, the file
Damien Miller05eda432002-02-10 18:32:28 +1100389.Pa /etc/ssh/ssh_known_hosts
Ben Lindstromd6481ea2001-06-25 04:37:41 +0000390is automatically checked for known hosts.
Damien Miller7684ee12000-03-17 23:40:15 +1100391Any new hosts are automatically added to the user's file.
Darren Tucker61776952003-10-02 16:19:47 +1000392If a host's identification ever changes,
Damien Miller32aa1441999-10-29 09:15:49 +1000393.Nm
394warns about this and disables password authentication to prevent a
Damien Miller7684ee12000-03-17 23:40:15 +1100395trojan horse from getting the user's password.
Darren Tucker61776952003-10-02 16:19:47 +1000396Another purpose of this mechanism is to prevent man-in-the-middle attacks
397which could otherwise be used to circumvent the encryption.
Damien Miller7684ee12000-03-17 23:40:15 +1100398The
Damien Miller32aa1441999-10-29 09:15:49 +1000399.Cm StrictHostKeyChecking
Ben Lindstrom9f049032002-06-21 00:59:05 +0000400option can be used to prevent logins to machines whose
Damien Miller32aa1441999-10-29 09:15:49 +1000401host key is not known or has changed.
Damien Miller0bc1bd82000-11-13 22:57:25 +1100402.Pp
403The options are as follows:
Damien Miller32aa1441999-10-29 09:15:49 +1000404.Bl -tag -width Ds
Darren Tucker61776952003-10-02 16:19:47 +1000405.It Fl 1
406Forces
407.Nm
408to try protocol version 1 only.
409.It Fl 2
410Forces
411.Nm
412to try protocol version 2 only.
413.It Fl 4
414Forces
415.Nm
416to use IPv4 addresses only.
417.It Fl 6
418Forces
419.Nm
420to use IPv6 addresses only.
Damien Millerb1715dc2000-05-30 13:44:51 +1000421.It Fl A
422Enables forwarding of the authentication agent connection.
423This can also be specified on a per-host basis in a configuration file.
Damien Millerb5fdfaa2002-09-12 09:52:03 +1000424.Pp
Damien Miller495dca32003-04-01 21:42:14 +1000425Agent forwarding should be enabled with caution.
426Users with the ability to bypass file permissions on the remote host
427(for the agent's Unix-domain socket)
428can access the local agent through the forwarded connection.
429An attacker cannot obtain key material from the agent,
Damien Millerb5fdfaa2002-09-12 09:52:03 +1000430however they can perform operations on the keys that enable them to
431authenticate using the identities loaded into the agent.
Darren Tucker61776952003-10-02 16:19:47 +1000432.It Fl a
433Disables forwarding of the authentication agent connection.
Ben Lindstrome0f88042001-04-30 13:06:24 +0000434.It Fl b Ar bind_address
435Specify the interface to transmit from on machines with multiple
436interfaces or aliased addresses.
Darren Tucker61776952003-10-02 16:19:47 +1000437.It Fl C
438Requests compression of all data (including stdin, stdout, stderr, and
439data for forwarded X11 and TCP/IP connections).
440The compression algorithm is the same used by
441.Xr gzip 1 ,
442and the
443.Dq level
444can be controlled by the
445.Cm CompressionLevel
446option for protocol version 1.
447Compression is desirable on modem lines and other
448slow connections, but will only slow down things on fast networks.
449The default value can be set on a host-by-host basis in the
450configuration files; see the
451.Cm Compression
452option.
Damien Miller05202ff2004-06-15 10:30:39 +1000453.It Fl c Ar cipher_spec
454Selects the cipher specification for encrypting the session.
455.Pp
456Protocol version 1 allows specification of a single cipher.
457The suported values are
458.Dq 3des ,
459.Dq blowfish
460and
461.Dq des .
Damien Miller32aa1441999-10-29 09:15:49 +1000462.Ar 3des
463(triple-des) is an encrypt-decrypt-encrypt triple with three different keys.
Damien Miller05202ff2004-06-15 10:30:39 +1000464It is believed to be secure.
Damien Miller32aa1441999-10-29 09:15:49 +1000465.Ar blowfish
Darren Tucker61776952003-10-02 16:19:47 +1000466is a fast block cipher; it appears very secure and is much faster than
Damien Miller7684ee12000-03-17 23:40:15 +1100467.Ar 3des .
Ben Lindstromffa1dd62001-09-12 16:52:28 +0000468.Ar des
469is only supported in the
470.Nm
471client for interoperability with legacy protocol 1 implementations
472that do not support the
473.Ar 3des
Damien Miller495dca32003-04-01 21:42:14 +1000474cipher.
475Its use is strongly discouraged due to cryptographic weaknesses.
Damien Miller05202ff2004-06-15 10:30:39 +1000476The default is
477.Dq 3des .
478.Pp
479For protocol version 2
480.Ar cipher_spec
481is a comma-separated list of ciphers
482listed in order of preference.
483The supported ciphers are
484.Dq 3des-cbc ,
485.Dq aes128-cbc ,
486.Dq aes192-cbc ,
487.Dq aes256-cbc ,
488.Dq aes128-ctr ,
489.Dq aes192-ctr ,
490.Dq aes256-ctr ,
491.Dq arcfour ,
492.Dq blowfish-cbc ,
493and
494.Dq cast128-cbc .
495The default is
496.Bd -literal
497 ``aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour,
498 aes192-cbc,aes256-cbc''
499.Ed
Darren Tucker61776952003-10-02 16:19:47 +1000500.It Fl D Ar port
501Specifies a local
502.Dq dynamic
503application-level port forwarding.
504This works by allocating a socket to listen to
505.Ar port
506on the local side, and whenever a connection is made to this port, the
507connection is forwarded over the secure channel, and the application
508protocol is then used to determine where to connect to from the
509remote machine.
510Currently the SOCKS4 and SOCKS5 protocols are supported, and
511.Nm
512will act as a SOCKS server.
513Only root can forward privileged ports.
514Dynamic port forwardings can also be specified in the configuration file.
515.It Fl e Ar ch | ^ch | none
Damien Miller32aa1441999-10-29 09:15:49 +1000516Sets the escape character for sessions with a pty (default:
517.Ql ~ ) .
Damien Miller7684ee12000-03-17 23:40:15 +1100518The escape character is only recognized at the beginning of a line.
519The escape character followed by a dot
Damien Miller32aa1441999-10-29 09:15:49 +1000520.Pq Ql \&.
Darren Tucker61776952003-10-02 16:19:47 +1000521closes the connection;
522followed by control-Z suspends the connection;
523and followed by itself sends the escape character once.
Damien Miller7684ee12000-03-17 23:40:15 +1100524Setting the character to
Damien Miller32aa1441999-10-29 09:15:49 +1000525.Dq none
526disables any escapes and makes the session fully transparent.
Darren Tucker61776952003-10-02 16:19:47 +1000527.It Fl F Ar configfile
528Specifies an alternative per-user configuration file.
529If a configuration file is given on the command line,
530the system-wide configuration file
531.Pq Pa /etc/ssh/ssh_config
532will be ignored.
533The default for the per-user configuration file is
534.Pa $HOME/.ssh/config .
Damien Miller32aa1441999-10-29 09:15:49 +1000535.It Fl f
536Requests
537.Nm
Damien Miller7684ee12000-03-17 23:40:15 +1100538to go to background just before command execution.
539This is useful if
Damien Miller32aa1441999-10-29 09:15:49 +1000540.Nm
541is going to ask for passwords or passphrases, but the user
Damien Miller7684ee12000-03-17 23:40:15 +1100542wants it in the background.
Damien Miller22c77262000-04-13 12:26:34 +1000543This implies
Damien Miller32aa1441999-10-29 09:15:49 +1000544.Fl n .
545The recommended way to start X11 programs at a remote site is with
546something like
547.Ic ssh -f host xterm .
Damien Miller396691a2000-01-20 22:44:08 +1100548.It Fl g
549Allows remote hosts to connect to local forwarded ports.
Darren Tucker61776952003-10-02 16:19:47 +1000550.It Fl I Ar smartcard_device
551Specifies which smartcard device to use.
552The argument is the device
553.Nm
554should use to communicate with a smartcard used for storing the user's
555private RSA key.
Damien Miller32aa1441999-10-29 09:15:49 +1000556.It Fl i Ar identity_file
Damien Millerfae23862002-01-22 23:32:26 +1100557Selects a file from which the identity (private key) for
Damien Miller0bc1bd82000-11-13 22:57:25 +1100558RSA or DSA authentication is read.
Damien Millerfae23862002-01-22 23:32:26 +1100559The default is
Damien Millere247cc42000-05-07 12:03:14 +1000560.Pa $HOME/.ssh/identity
Damien Millerfae23862002-01-22 23:32:26 +1100561for protocol version 1, and
562.Pa $HOME/.ssh/id_rsa
563and
564.Pa $HOME/.ssh/id_dsa
565for protocol version 2.
Damien Miller7684ee12000-03-17 23:40:15 +1100566Identity files may also be specified on
567a per-host basis in the configuration file.
568It is possible to have multiple
Damien Miller32aa1441999-10-29 09:15:49 +1000569.Fl i
570options (and multiple identities specified in
571configuration files).
Damien Miller32aa1441999-10-29 09:15:49 +1000572.It Fl k
Damien Millere0113cc2003-11-24 13:10:09 +1100573Disables forwarding (delegation) of GSSAPI credentials to the server.
Darren Tucker61776952003-10-02 16:19:47 +1000574.It Fl L Xo
575.Sm off
576.Ar port : host : hostport
577.Sm on
578.Xc
579Specifies that the given port on the local (client) host is to be
580forwarded to the given host and port on the remote side.
581This works by allocating a socket to listen to
582.Ar port
583on the local side, and whenever a connection is made to this port, the
584connection is forwarded over the secure channel, and a connection is
585made to
586.Ar host
587port
588.Ar hostport
589from the remote machine.
590Port forwardings can also be specified in the configuration file.
591Only root can forward privileged ports.
592IPv6 addresses can be specified with an alternative syntax:
593.Sm off
594.Xo
595.Ar port No / Ar host No /
596.Ar hostport .
597.Xc
598.Sm on
Damien Miller32aa1441999-10-29 09:15:49 +1000599.It Fl l Ar login_name
Damien Miller7684ee12000-03-17 23:40:15 +1100600Specifies the user to log in as on the remote machine.
601This also may be specified on a per-host basis in the configuration file.
Ben Lindstrom06b33aa2001-02-15 03:01:59 +0000602.It Fl m Ar mac_spec
603Additionally, for protocol version 2 a comma-separated list of MAC
604(message authentication code) algorithms can
605be specified in order of preference.
606See the
607.Cm MACs
608keyword for more information.
Damien Miller0e220db2004-06-15 10:34:08 +1000609.It Fl M
610Places the
611.Nm
612client into
613.Dq master
614mode for connection sharing.
615Refer to the description of
616.Cm ControlMaster
617in
618.Xr ssh_config 5
619for details.
Darren Tucker61776952003-10-02 16:19:47 +1000620.It Fl N
621Do not execute a remote command.
622This is useful for just forwarding ports
623(protocol version 2 only).
Damien Miller32aa1441999-10-29 09:15:49 +1000624.It Fl n
625Redirects stdin from
626.Pa /dev/null
627(actually, prevents reading from stdin).
628This must be used when
629.Nm
Damien Miller7684ee12000-03-17 23:40:15 +1100630is run in the background.
631A common trick is to use this to run X11 programs on a remote machine.
632For example,
Damien Miller32aa1441999-10-29 09:15:49 +1000633.Ic ssh -n shadows.cs.hut.fi emacs &
634will start an emacs on shadows.cs.hut.fi, and the X11
635connection will be automatically forwarded over an encrypted channel.
636The
637.Nm
638program will be put in the background.
639(This does not work if
640.Nm
641needs to ask for a password or passphrase; see also the
642.Fl f
643option.)
644.It Fl o Ar option
Ben Lindstrom14c62eb2001-08-15 23:25:46 +0000645Can be used to give options in the format used in the configuration file.
Damien Miller32aa1441999-10-29 09:15:49 +1000646This is useful for specifying options for which there is no separate
Damien Miller7684ee12000-03-17 23:40:15 +1100647command-line flag.
Darren Tucker61776952003-10-02 16:19:47 +1000648For full details of the options listed below, and their possible values, see
649.Xr ssh_config 5 .
650.Pp
651.Bl -tag -width Ds -offset indent -compact
652.It AddressFamily
653.It BatchMode
654.It BindAddress
655.It ChallengeResponseAuthentication
656.It CheckHostIP
657.It Cipher
658.It Ciphers
659.It ClearAllForwardings
660.It Compression
661.It CompressionLevel
662.It ConnectionAttempts
Darren Tuckeredae0ec2004-05-02 22:15:52 +1000663.It ConnectTimeout
Damien Miller0e220db2004-06-15 10:34:08 +1000664.It ControlMaster
665.It ControlPath
Darren Tucker61776952003-10-02 16:19:47 +1000666.It DynamicForward
Darren Tucker61776952003-10-02 16:19:47 +1000667.It EscapeChar
668.It ForwardAgent
669.It ForwardX11
Darren Tucker0a118da2003-10-15 15:54:32 +1000670.It ForwardX11Trusted
Darren Tucker61776952003-10-02 16:19:47 +1000671.It GatewayPorts
672.It GlobalKnownHostsFile
673.It GSSAPIAuthentication
674.It GSSAPIDelegateCredentials
675.It Host
676.It HostbasedAuthentication
677.It HostKeyAlgorithms
678.It HostKeyAlias
679.It HostName
680.It IdentityFile
Damien Millerbd394c32004-03-08 23:12:36 +1100681.It IdentitiesOnly
Darren Tucker61776952003-10-02 16:19:47 +1000682.It LocalForward
683.It LogLevel
684.It MACs
685.It NoHostAuthenticationForLocalhost
686.It NumberOfPasswordPrompts
687.It PasswordAuthentication
688.It Port
689.It PreferredAuthentications
690.It Protocol
691.It ProxyCommand
692.It PubkeyAuthentication
693.It RemoteForward
694.It RhostsRSAAuthentication
695.It RSAAuthentication
Darren Tucker7a6c0662004-05-02 22:14:03 +1000696.It SendEnv
Damien Miller509b0102003-12-17 16:33:10 +1100697.It ServerAliveInterval
698.It ServerAliveCountMax
Darren Tucker61776952003-10-02 16:19:47 +1000699.It SmartcardDevice
700.It StrictHostKeyChecking
Damien Miller12c150e2003-12-17 16:31:10 +1100701.It TCPKeepAlive
Darren Tucker61776952003-10-02 16:19:47 +1000702.It UsePrivilegedPort
703.It User
704.It UserKnownHostsFile
705.It VerifyHostKeyDNS
706.It XAuthLocation
707.El
Damien Miller32aa1441999-10-29 09:15:49 +1000708.It Fl p Ar port
Damien Miller7684ee12000-03-17 23:40:15 +1100709Port to connect to on the remote host.
710This can be specified on a
Damien Miller32aa1441999-10-29 09:15:49 +1000711per-host basis in the configuration file.
Damien Miller32aa1441999-10-29 09:15:49 +1000712.It Fl q
Damien Miller7684ee12000-03-17 23:40:15 +1100713Quiet mode.
714Causes all warning and diagnostic messages to be suppressed.
Darren Tucker61776952003-10-02 16:19:47 +1000715.It Fl R Xo
716.Sm off
717.Ar port : host : hostport
718.Sm on
719.Xc
Damien Miller32aa1441999-10-29 09:15:49 +1000720Specifies that the given port on the remote (server) host is to be
Damien Miller7684ee12000-03-17 23:40:15 +1100721forwarded to the given host and port on the local side.
722This works by allocating a socket to listen to
Damien Miller32aa1441999-10-29 09:15:49 +1000723.Ar port
724on the remote side, and whenever a connection is made to this port, the
725connection is forwarded over the secure channel, and a connection is
726made to
Damien Miller34132e52000-01-14 15:45:46 +1100727.Ar host
728port
729.Ar hostport
Damien Miller7684ee12000-03-17 23:40:15 +1100730from the local machine.
731Port forwardings can also be specified in the configuration file.
732Privileged ports can be forwarded only when
Damien Miller32aa1441999-10-29 09:15:49 +1000733logging in as root on the remote machine.
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000734IPv6 addresses can be specified with an alternative syntax:
Darren Tucker61776952003-10-02 16:19:47 +1000735.Sm off
736.Xo
737.Ar port No / Ar host No /
738.Ar hostport .
739.Xc
740.Sm on
Damien Millerb8ea2482004-06-18 22:21:55 +1000741.It Fl S Ar ctl
Darren Tuckerba5c5922004-06-18 16:22:39 +1000742Specifies the location of a control socket for for connection sharing.
Damien Miller0e220db2004-06-15 10:34:08 +1000743Refer to the description of
Darren Tuckerba5c5922004-06-18 16:22:39 +1000744.Cm ControlPath
745and
Damien Miller0e220db2004-06-15 10:34:08 +1000746.Cm ControlMaster
747in
748.Xr ssh_config 5
749for details.
Darren Tucker61776952003-10-02 16:19:47 +1000750.It Fl s
751May be used to request invocation of a subsystem on the remote system.
752Subsystems are a feature of the SSH2 protocol which facilitate the use
753of SSH as a secure transport for other applications (eg.\&
754.Xr sftp 1 ) .
755The subsystem is specified as the remote command.
756.It Fl T
757Disable pseudo-tty allocation.
758.It Fl t
759Force pseudo-tty allocation.
760This can be used to execute arbitrary
761screen-based programs on a remote machine, which can be very useful,
762e.g., when implementing menu services.
763Multiple
764.Fl t
765options force tty allocation, even if
Ben Lindstrom19ceb172001-09-12 17:54:24 +0000766.Nm
Darren Tucker61776952003-10-02 16:19:47 +1000767has no local tty.
768.It Fl V
769Display the version number and exit.
770.It Fl v
771Verbose mode.
772Causes
Ben Lindstrom5ab6ae12001-02-10 22:08:03 +0000773.Nm
Darren Tucker61776952003-10-02 16:19:47 +1000774to print debugging messages about its progress.
775This is helpful in
776debugging connection, authentication, and configuration problems.
777Multiple
778.Fl v
779options increase the verbosity.
780The maximum is 3.
781.It Fl X
782Enables X11 forwarding.
783This can also be specified on a per-host basis in a configuration file.
784.Pp
785X11 forwarding should be enabled with caution.
786Users with the ability to bypass file permissions on the remote host
787(for the user's X authorization database)
788can access the local X11 display through the forwarded connection.
789An attacker may then be able to perform activities such as keystroke monitoring.
790.It Fl x
791Disables X11 forwarding.
Darren Tucker0a118da2003-10-15 15:54:32 +1000792.It Fl Y
793Enables trusted X11 forwarding.
Damien Miller32aa1441999-10-29 09:15:49 +1000794.El
795.Sh CONFIGURATION FILES
796.Nm
Ben Lindstrom9f049032002-06-21 00:59:05 +0000797may additionally obtain configuration data from
798a per-user configuration file and a system-wide configuration file.
799The file format and configuration options are described in
800.Xr ssh_config 5 .
Damien Miller32aa1441999-10-29 09:15:49 +1000801.Sh ENVIRONMENT
802.Nm
803will normally set the following environment variables:
Darren Tucker61776952003-10-02 16:19:47 +1000804.Bl -tag -width LOGNAME
Damien Miller32aa1441999-10-29 09:15:49 +1000805.It Ev DISPLAY
806The
807.Ev DISPLAY
Damien Miller7684ee12000-03-17 23:40:15 +1100808variable indicates the location of the X11 server.
Damien Miller22c77262000-04-13 12:26:34 +1000809It is automatically set by
Damien Miller32aa1441999-10-29 09:15:49 +1000810.Nm
811to point to a value of the form
812.Dq hostname:n
813where hostname indicates
Darren Tucker61776952003-10-02 16:19:47 +1000814the host where the shell runs, and n is an integer \*(Ge 1.
Damien Miller7684ee12000-03-17 23:40:15 +1100815.Nm
816uses this special value to forward X11 connections over the secure
817channel.
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000818The user should normally not set
819.Ev DISPLAY
820explicitly, as that
Damien Miller32aa1441999-10-29 09:15:49 +1000821will render the X11 connection insecure (and will require the user to
822manually copy any required authorization cookies).
823.It Ev HOME
824Set to the path of the user's home directory.
825.It Ev LOGNAME
826Synonym for
827.Ev USER ;
828set for compatibility with systems that use this variable.
829.It Ev MAIL
Ben Lindstrome59433d2001-09-12 16:41:37 +0000830Set to the path of the user's mailbox.
Damien Miller7684ee12000-03-17 23:40:15 +1100831.It Ev PATH
Damien Miller32aa1441999-10-29 09:15:49 +1000832Set to the default
833.Ev PATH ,
834as specified when compiling
835.Nm ssh .
Ben Lindstrom5bf5d672001-07-04 04:31:38 +0000836.It Ev SSH_ASKPASS
837If
838.Nm
839needs a passphrase, it will read the passphrase from the current
840terminal if it was run from a terminal.
841If
842.Nm
843does not have a terminal associated with it but
844.Ev DISPLAY
845and
846.Ev SSH_ASKPASS
847are set, it will execute the program specified by
848.Ev SSH_ASKPASS
849and open an X11 window to read the passphrase.
850This is particularly useful when calling
851.Nm
852from a
853.Pa .Xsession
854or related script.
855(Note that on some machines it
856may be necessary to redirect the input from
857.Pa /dev/null
858to make this work.)
Damien Miller32aa1441999-10-29 09:15:49 +1000859.It Ev SSH_AUTH_SOCK
Ben Lindstrome59433d2001-09-12 16:41:37 +0000860Identifies the path of a unix-domain socket used to communicate with the
Damien Miller32aa1441999-10-29 09:15:49 +1000861agent.
Damien Millerf37e2462002-09-19 11:47:55 +1000862.It Ev SSH_CONNECTION
863Identifies the client and server ends of the connection.
Damien Miller7684ee12000-03-17 23:40:15 +1100864The variable contains
Damien Millerf37e2462002-09-19 11:47:55 +1000865four space-separated values: client ip-address, client port number,
866server ip-address and server port number.
Ben Lindstrom4dccfa52000-12-28 16:40:05 +0000867.It Ev SSH_ORIGINAL_COMMAND
868The variable contains the original command line if a forced command
869is executed.
870It can be used to extract the original arguments.
Damien Miller32aa1441999-10-29 09:15:49 +1000871.It Ev SSH_TTY
872This is set to the name of the tty (path to the device) associated
Damien Miller7684ee12000-03-17 23:40:15 +1100873with the current shell or command.
874If the current session has no tty,
Damien Miller32aa1441999-10-29 09:15:49 +1000875this variable is not set.
876.It Ev TZ
877The timezone variable is set to indicate the present timezone if it
Damien Miller942da032000-08-18 13:59:06 +1000878was set when the daemon was started (i.e., the daemon passes the value
Damien Miller32aa1441999-10-29 09:15:49 +1000879on to new connections).
880.It Ev USER
881Set to the name of the user logging in.
882.El
883.Pp
Damien Miller22c77262000-04-13 12:26:34 +1000884Additionally,
Damien Miller32aa1441999-10-29 09:15:49 +1000885.Nm
Damien Miller22c77262000-04-13 12:26:34 +1000886reads
887.Pa $HOME/.ssh/environment ,
Damien Miller32aa1441999-10-29 09:15:49 +1000888and adds lines of the format
889.Dq VARNAME=value
Ben Lindstromdc7adf22002-08-20 18:38:02 +0000890to the environment if the file exists and if users are allowed to
891change their environment.
Darren Tucker61776952003-10-02 16:19:47 +1000892For more information, see the
Ben Lindstromdc7adf22002-08-20 18:38:02 +0000893.Cm PermitUserEnvironment
Ben Lindstrombd9bf382002-08-20 18:54:20 +0000894option in
Ben Lindstromdc7adf22002-08-20 18:38:02 +0000895.Xr sshd_config 5 .
Damien Miller32aa1441999-10-29 09:15:49 +1000896.Sh FILES
Damien Miller98c7ad62000-03-09 21:27:49 +1100897.Bl -tag -width Ds
Ben Lindstromd6481ea2001-06-25 04:37:41 +0000898.It Pa $HOME/.ssh/known_hosts
Ben Lindstrome59433d2001-09-12 16:41:37 +0000899Records host keys for all hosts the user has logged into that are not
Damien Miller32aa1441999-10-29 09:15:49 +1000900in
Damien Miller05eda432002-02-10 18:32:28 +1100901.Pa /etc/ssh/ssh_known_hosts .
Damien Miller32aa1441999-10-29 09:15:49 +1000902See
903.Xr sshd 8 .
Ben Lindstrom18a82ac2001-04-11 15:59:35 +0000904.It Pa $HOME/.ssh/identity, $HOME/.ssh/id_dsa, $HOME/.ssh/id_rsa
905Contains the authentication identity of the user.
906They are for protocol 1 RSA, protocol 2 DSA, and protocol 2 RSA, respectively.
Damien Millere247cc42000-05-07 12:03:14 +1000907These files
908contain sensitive data and should be readable by the user but not
Damien Miller32aa1441999-10-29 09:15:49 +1000909accessible by others (read/write/execute).
910Note that
911.Nm
Damien Millere247cc42000-05-07 12:03:14 +1000912ignores a private key file if it is accessible by others.
Damien Miller32aa1441999-10-29 09:15:49 +1000913It is possible to specify a passphrase when
914generating the key; the passphrase will be used to encrypt the
915sensitive part of this file using 3DES.
Ben Lindstrom18a82ac2001-04-11 15:59:35 +0000916.It Pa $HOME/.ssh/identity.pub, $HOME/.ssh/id_dsa.pub, $HOME/.ssh/id_rsa.pub
Damien Miller32aa1441999-10-29 09:15:49 +1000917Contains the public key for authentication (public part of the
Damien Miller7684ee12000-03-17 23:40:15 +1100918identity file in human-readable form).
Damien Millere247cc42000-05-07 12:03:14 +1000919The contents of the
920.Pa $HOME/.ssh/identity.pub
Darren Tucker61776952003-10-02 16:19:47 +1000921file should be added to the file
Damien Miller32aa1441999-10-29 09:15:49 +1000922.Pa $HOME/.ssh/authorized_keys
923on all machines
Ben Lindstrom594e2032001-09-12 18:35:30 +0000924where the user wishes to log in using protocol version 1 RSA authentication.
Damien Millere247cc42000-05-07 12:03:14 +1000925The contents of the
926.Pa $HOME/.ssh/id_dsa.pub
Ben Lindstrom18a82ac2001-04-11 15:59:35 +0000927and
928.Pa $HOME/.ssh/id_rsa.pub
Damien Millere247cc42000-05-07 12:03:14 +1000929file should be added to
Ben Lindstromf96704d2001-06-25 04:17:12 +0000930.Pa $HOME/.ssh/authorized_keys
Damien Millere247cc42000-05-07 12:03:14 +1000931on all machines
Ben Lindstrom594e2032001-09-12 18:35:30 +0000932where the user wishes to log in using protocol version 2 DSA/RSA authentication.
Damien Millere247cc42000-05-07 12:03:14 +1000933These files are not
Damien Miller7684ee12000-03-17 23:40:15 +1100934sensitive and can (but need not) be readable by anyone.
Damien Millere247cc42000-05-07 12:03:14 +1000935These files are
Kevin Steves3c034ae2001-02-05 13:47:11 +0000936never used automatically and are not necessary; they are only provided for
Damien Miller32aa1441999-10-29 09:15:49 +1000937the convenience of the user.
938.It Pa $HOME/.ssh/config
Damien Miller7684ee12000-03-17 23:40:15 +1100939This is the per-user configuration file.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000940The file format and configuration options are described in
941.Xr ssh_config 5 .
Damien Millerc970cb92004-04-20 20:12:53 +1000942Because of the potential for abuse, this file must have strict permissions:
943read/write for the user, and not accessible by others.
Damien Miller32aa1441999-10-29 09:15:49 +1000944.It Pa $HOME/.ssh/authorized_keys
Ben Lindstromf96704d2001-06-25 04:17:12 +0000945Lists the public keys (RSA/DSA) that can be used for logging in as this user.
Damien Miller7684ee12000-03-17 23:40:15 +1100946The format of this file is described in the
Damien Miller32aa1441999-10-29 09:15:49 +1000947.Xr sshd 8
Damien Miller7684ee12000-03-17 23:40:15 +1100948manual page.
Darren Tucker61776952003-10-02 16:19:47 +1000949In the simplest form the format is the same as the
950.Pa .pub
Ben Lindstromd6481ea2001-06-25 04:37:41 +0000951identity files.
Damien Millere247cc42000-05-07 12:03:14 +1000952This file is not highly sensitive, but the recommended
953permissions are read/write for the user, and not accessible by others.
Damien Miller05eda432002-02-10 18:32:28 +1100954.It Pa /etc/ssh/ssh_known_hosts
Damien Miller7684ee12000-03-17 23:40:15 +1100955Systemwide list of known host keys.
Ben Lindstromd6481ea2001-06-25 04:37:41 +0000956This file should be prepared by the
Damien Miller32aa1441999-10-29 09:15:49 +1000957system administrator to contain the public host keys of all machines in the
Damien Miller7684ee12000-03-17 23:40:15 +1100958organization.
959This file should be world-readable.
960This file contains
Damien Miller32aa1441999-10-29 09:15:49 +1000961public keys, one per line, in the following format (fields separated
Ben Lindstromd6481ea2001-06-25 04:37:41 +0000962by spaces): system name, public key and optional comment field.
Damien Miller7684ee12000-03-17 23:40:15 +1100963When different names are used
Damien Miller32aa1441999-10-29 09:15:49 +1000964for the same machine, all such names should be listed, separated by
Damien Miller7684ee12000-03-17 23:40:15 +1100965commas.
Darren Tucker61776952003-10-02 16:19:47 +1000966The format is described in the
Damien Miller32aa1441999-10-29 09:15:49 +1000967.Xr sshd 8
968manual page.
969.Pp
970The canonical system name (as returned by name servers) is used by
971.Xr sshd 8
972to verify the client host when logging in; other names are needed because
973.Nm
974does not convert the user-supplied name to a canonical name before
975checking the key, because someone with access to the name servers
976would then be able to fool host authentication.
Damien Miller05eda432002-02-10 18:32:28 +1100977.It Pa /etc/ssh/ssh_config
Damien Miller7684ee12000-03-17 23:40:15 +1100978Systemwide configuration file.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000979The file format and configuration options are described in
980.Xr ssh_config 5 .
Damien Miller05eda432002-02-10 18:32:28 +1100981.It Pa /etc/ssh/ssh_host_key, /etc/ssh/ssh_host_dsa_key, /etc/ssh/ssh_host_rsa_key
Damien Miller705499b2001-11-12 11:05:38 +1100982These three files contain the private parts of the host keys
983and are used for
984.Cm RhostsRSAAuthentication
985and
986.Cm HostbasedAuthentication .
Ben Lindstrom5cac4232002-06-11 15:45:02 +0000987If the protocol version 1
988.Cm RhostsRSAAuthentication
Ben Lindstromcb72e4f2002-06-21 00:41:51 +0000989method is used,
Damien Miller705499b2001-11-12 11:05:38 +1100990.Nm
Ben Lindstrom5cac4232002-06-11 15:45:02 +0000991must be setuid root, since the host key is readable only by root.
992For protocol version 2,
993.Nm
994uses
995.Xr ssh-keysign 8
996to access the host keys for
997.Cm HostbasedAuthentication .
998This eliminates the requirement that
999.Nm
1000be setuid root when that authentication method is used.
1001By default
1002.Nm
1003is not setuid root.
Damien Miller32aa1441999-10-29 09:15:49 +10001004.It Pa $HOME/.rhosts
1005This file is used in
Darren Tucker61776952003-10-02 16:19:47 +10001006.Em rhosts
Damien Miller32aa1441999-10-29 09:15:49 +10001007authentication to list the
Damien Miller7684ee12000-03-17 23:40:15 +11001008host/user pairs that are permitted to log in.
1009(Note that this file is
Damien Miller32aa1441999-10-29 09:15:49 +10001010also used by rlogin and rsh, which makes using this file insecure.)
1011Each line of the file contains a host name (in the canonical form
1012returned by name servers), and then a user name on that host,
Damien Miller7684ee12000-03-17 23:40:15 +11001013separated by a space.
Ben Lindstromebd888d2001-03-05 05:49:29 +00001014On some machines this file may need to be
Damien Miller32aa1441999-10-29 09:15:49 +10001015world-readable if the user's home directory is on a NFS partition,
1016because
1017.Xr sshd 8
Damien Miller7684ee12000-03-17 23:40:15 +11001018reads it as root.
1019Additionally, this file must be owned by the user,
1020and must not have write permissions for anyone else.
1021The recommended
Damien Miller32aa1441999-10-29 09:15:49 +10001022permission for most machines is read/write for the user, and not
1023accessible by others.
1024.Pp
1025Note that by default
1026.Xr sshd 8
1027will be installed so that it requires successful RSA host
Darren Tucker61776952003-10-02 16:19:47 +10001028authentication before permitting
1029.Em rhosts
1030authentication.
Ben Lindstrom594e2032001-09-12 18:35:30 +00001031If the server machine does not have the client's host key in
Damien Miller05eda432002-02-10 18:32:28 +11001032.Pa /etc/ssh/ssh_known_hosts ,
Ben Lindstrom594e2032001-09-12 18:35:30 +00001033it can be stored in
Damien Miller32aa1441999-10-29 09:15:49 +10001034.Pa $HOME/.ssh/known_hosts .
1035The easiest way to do this is to
1036connect back to the client from the server machine using ssh; this
Damien Millere247cc42000-05-07 12:03:14 +10001037will automatically add the host key to
Damien Miller32aa1441999-10-29 09:15:49 +10001038.Pa $HOME/.ssh/known_hosts .
1039.It Pa $HOME/.shosts
1040This file is used exactly the same way as
Darren Tucker61776952003-10-02 16:19:47 +10001041.Pa .rhosts .
Damien Miller32aa1441999-10-29 09:15:49 +10001042The purpose for
1043having this file is to be able to use rhosts authentication with
1044.Nm
1045without permitting login with
Darren Tucker61776952003-10-02 16:19:47 +10001046.Xr rlogin
Damien Miller32aa1441999-10-29 09:15:49 +10001047or
1048.Xr rsh 1 .
1049.It Pa /etc/hosts.equiv
1050This file is used during
Darren Tucker61776952003-10-02 16:19:47 +10001051.Em rhosts
Damien Millerf1ce5052003-06-11 22:04:39 +10001052authentication.
Damien Miller7684ee12000-03-17 23:40:15 +11001053It contains
Darren Tucker61776952003-10-02 16:19:47 +10001054canonical hosts names, one per line (the full format is described in the
Damien Miller32aa1441999-10-29 09:15:49 +10001055.Xr sshd 8
Damien Miller7684ee12000-03-17 23:40:15 +11001056manual page).
1057If the client host is found in this file, login is
Damien Miller32aa1441999-10-29 09:15:49 +10001058automatically permitted provided client and server user names are the
Damien Miller7684ee12000-03-17 23:40:15 +11001059same.
1060Additionally, successful RSA host authentication is normally
1061required.
1062This file should only be writable by root.
Damien Miller886c63a2000-01-20 23:13:36 +11001063.It Pa /etc/shosts.equiv
Damien Miller22c77262000-04-13 12:26:34 +10001064This file is processed exactly as
Damien Miller32aa1441999-10-29 09:15:49 +10001065.Pa /etc/hosts.equiv .
1066This file may be useful to permit logins using
1067.Nm
1068but not using rsh/rlogin.
Damien Miller05eda432002-02-10 18:32:28 +11001069.It Pa /etc/ssh/sshrc
Damien Miller32aa1441999-10-29 09:15:49 +10001070Commands in this file are executed by
1071.Nm
1072when the user logs in just before the user's shell (or command) is started.
1073See the
1074.Xr sshd 8
1075manual page for more information.
1076.It Pa $HOME/.ssh/rc
1077Commands in this file are executed by
1078.Nm
1079when the user logs in just before the user's shell (or command) is
1080started.
Damien Miller22c77262000-04-13 12:26:34 +10001081See the
Damien Miller32aa1441999-10-29 09:15:49 +10001082.Xr sshd 8
1083manual page for more information.
Damien Miller4f0fa561999-12-26 14:24:41 +11001084.It Pa $HOME/.ssh/environment
1085Contains additional definitions for environment variables, see section
1086.Sx ENVIRONMENT
1087above.
Damien Miller7b28dc52000-09-05 13:34:53 +11001088.El
Damien Miller07a2d422002-02-05 12:16:15 +11001089.Sh DIAGNOSTICS
1090.Nm
1091exits with the exit status of the remote command or with 255
1092if an error occurred.
Damien Miller32aa1441999-10-29 09:15:49 +10001093.Sh SEE ALSO
Darren Tucker61776952003-10-02 16:19:47 +10001094.Xr gzip 1 ,
Damien Miller32aa1441999-10-29 09:15:49 +10001095.Xr rsh 1 ,
1096.Xr scp 1 ,
Damien Miller33804262001-02-04 23:20:18 +11001097.Xr sftp 1 ,
Damien Miller32aa1441999-10-29 09:15:49 +10001098.Xr ssh-add 1 ,
1099.Xr ssh-agent 1 ,
1100.Xr ssh-keygen 1 ,
1101.Xr telnet 1 ,
Darren Tucker61776952003-10-02 16:19:47 +10001102.Xr hosts.equiv 5 ,
Ben Lindstrombf69e3b2002-06-23 00:31:24 +00001103.Xr ssh_config 5 ,
Ben Lindstromc001cd32002-06-23 00:32:11 +00001104.Xr ssh-keysign 8 ,
Ben Lindstrom5ab6ae12001-02-10 22:08:03 +00001105.Xr sshd 8
Ben Lindstrom160ec622001-04-22 17:17:46 +00001106.Rs
1107.%A T. Ylonen
1108.%A T. Kivinen
1109.%A M. Saarinen
1110.%A T. Rinne
1111.%A S. Lehtinen
1112.%T "SSH Protocol Architecture"
Ben Lindstromf1813842002-03-27 17:18:31 +00001113.%N draft-ietf-secsh-architecture-12.txt
1114.%D January 2002
Ben Lindstrom160ec622001-04-22 17:17:46 +00001115.%O work in progress material
1116.Re
Damien Millerf1ce5052003-06-11 22:04:39 +10001117.Sh AUTHORS
1118OpenSSH is a derivative of the original and free
1119ssh 1.2.12 release by Tatu Ylonen.
1120Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
1121Theo de Raadt and Dug Song
1122removed many bugs, re-added newer features and
1123created OpenSSH.
1124Markus Friedl contributed the support for SSH
1125protocol versions 1.5 and 2.0.