1.\" -*- nroff -*-
2.\"
3.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
4.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
5.\" All rights reserved
6.\"
7.\" 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".
12.\"
13.\" 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.
16.\"
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.
36.\"
| 1.\" -*- nroff -*-
2.\"
3.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
4.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
5.\" All rights reserved
6.\"
7.\" 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".
12.\"
13.\" 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.
16.\"
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.
36.\"
|
| 37.\" $FreeBSD: head/crypto/openssh/ssh.1 128460 2004-04-20 09:46:41Z des $
|
37.\" $OpenBSD: ssh.1,v 1.181 2003/12/16 15:49:51 markus Exp $
| 38.\" $OpenBSD: ssh.1,v 1.181 2003/12/16 15:49:51 markus Exp $
|
38.\" $FreeBSD: head/crypto/openssh/ssh.1 126277 2004-02-26 10:52:33Z des $
| |
39.Dd September 25, 1999
40.Dt SSH 1
41.Os
42.Sh NAME
43.Nm ssh
44.Nd OpenSSH SSH client (remote login program)
45.Sh SYNOPSIS
46.Nm ssh
47.Op Fl 1246AaCfgkNnqsTtVvXxY
48.Op Fl b Ar bind_address
49.Op Fl c Ar cipher_spec
50.Op Fl D Ar port
51.Op Fl e Ar escape_char
52.Op Fl F Ar configfile
53.Op Fl i Ar identity_file
54.Bk -words
55.Oo Fl L Xo
56.Sm off
57.Ar port :
58.Ar host :
59.Ar hostport
60.Sm on
61.Xc
62.Oc
63.Ek
64.Op Fl l Ar login_name
65.Op Fl m Ar mac_spec
66.Op Fl o Ar option
67.Bk -words
68.Op Fl p Ar port
69.Ek
70.Oo Fl R Xo
71.Sm off
72.Ar port :
73.Ar host :
74.Ar hostport
75.Sm on
76.Xc
77.Oc
78.Oo Ar user Ns @ Oc Ns Ar hostname
79.Op Ar command
80.Sh DESCRIPTION
81.Nm
82(SSH client) is a program for logging into a remote machine and for
83executing commands on a remote machine.
84It is intended to replace rlogin and rsh,
85and provide secure encrypted communications between
86two untrusted hosts over an insecure network.
87X11 connections and arbitrary TCP/IP ports
88can also be forwarded over the secure channel.
89.Pp
90.Nm
91connects and logs into the specified
92.Ar hostname
93(with optional
94.Ar user
95name).
96The user must prove
97his/her identity to the remote machine using one of several methods
98depending on the protocol version used.
99.Pp
100If
101.Ar command
102is specified,
103.Ar command
104is executed on the remote host instead of a login shell.
105.Ss SSH protocol version 1
106First, if the machine the user logs in from is listed in
107.Pa /etc/hosts.equiv
108or
109.Pa /etc/ssh/shosts.equiv
110on the remote machine, and the user names are
111the same on both sides, the user is immediately permitted to log in.
112Second, if
113.Pa .rhosts
114or
115.Pa .shosts
116exists 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
119permitted to log in.
120This form of authentication alone is normally not
121allowed by the server because it is not secure.
122.Pp
123The second authentication method is the
124.Em rhosts
125or
126.Em hosts.equiv
127method combined with RSA-based host authentication.
128It means that if the login would be permitted by
129.Pa $HOME/.rhosts ,
130.Pa $HOME/.shosts ,
131.Pa /etc/hosts.equiv ,
132or
133.Pa /etc/ssh/shosts.equiv ,
134and if additionally the server can verify the client's
135host key (see
136.Pa /etc/ssh/ssh_known_hosts
137and
138.Pa $HOME/.ssh/known_hosts
139in the
140.Sx FILES
141section), only then is login permitted.
142This authentication method closes security holes due to IP
143spoofing, DNS spoofing and routing spoofing.
144[Note to the administrator:
145.Pa /etc/hosts.equiv ,
146.Pa $HOME/.rhosts ,
147and the rlogin/rsh protocol in general, are inherently insecure and should be
148disabled if security is desired.]
149.Pp
150As a third authentication method,
151.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.
156RSA is one such system.
157The idea is that each user creates a public/private
158key pair for authentication purposes.
159The server knows the public key, and only the user knows the private key.
160.Pp
161The file
162.Pa $HOME/.ssh/authorized_keys
163lists the public keys that are permitted for logging in.
164When the user logs in, the
165.Nm
166program tells the server which key pair it would like to use for
167authentication.
168The server checks if this key is permitted, and if so,
169sends the user (actually the
170.Nm
171program running on behalf of the user) a challenge, a random number,
172encrypted by the user's public key.
173The 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.
177.Pp
178.Nm
179implements the RSA authentication protocol automatically.
180The user creates his/her RSA key pair by running
181.Xr ssh-keygen 1 .
182This stores the private key in
183.Pa $HOME/.ssh/identity
184and stores the public key in
185.Pa $HOME/.ssh/identity.pub
186in the user's home directory.
187The user should then copy the
188.Pa identity.pub
189to
190.Pa $HOME/.ssh/authorized_keys
191in his/her home directory on the remote machine (the
192.Pa authorized_keys
193file corresponds to the conventional
194.Pa $HOME/.rhosts
195file, and has one key
196per line, though the lines can be very long).
197After this, the user can log in without giving the password.
198RSA authentication is much more secure than
199.Em rhosts
200authentication.
201.Pp
202The most convenient way to use RSA authentication may be with an
203authentication agent.
204See
205.Xr ssh-agent 1
206for more information.
207.Pp
208If other authentication methods fail,
209.Nm
210prompts the user for a password.
211The password is sent to the remote
212host for checking; however, since all communications are encrypted,
213the password cannot be seen by someone listening on the network.
214.Ss SSH protocol version 2
215When a user connects using protocol version 2,
216similar authentication methods are available.
217Using the default values for
218.Cm PreferredAuthentications ,
219the client will try to authenticate first using the hostbased method;
220if this method fails, public key authentication is attempted,
221and finally if this method fails, keyboard-interactive and
222password authentication are tried.
223.Pp
224The public key method is similar to RSA authentication described
225in the previous section and allows the RSA or DSA algorithm to be used:
226The client uses his private key,
227.Pa $HOME/.ssh/id_dsa
228or
229.Pa $HOME/.ssh/id_rsa ,
230to sign the session identifier and sends the result to the server.
231The server checks whether the matching public key is listed in
232.Pa $HOME/.ssh/authorized_keys
233and 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
237If public key authentication fails or is not available, a password
238can be sent encrypted to the remote host to prove the user's identity.
239.Pp
240Additionally,
241.Nm
242supports hostbased or challenge response authentication.
243.Pp
244Protocol 2 provides additional mechanisms for confidentiality
245(the traffic is encrypted using 3DES, Blowfish, CAST128 or Arcfour)
246and integrity (hmac-md5, hmac-sha1).
247Note that protocol 1 lacks a strong mechanism for ensuring the
248integrity of the connection.
249.Ss Login session and remote execution
250When the user's identity has been accepted by the server, the server
251either executes the given command, or logs into the machine and gives
252the user a normal shell on the remote machine.
253All communication with
254the remote command or shell will be automatically encrypted.
255.Pp
256If a pseudo-terminal has been allocated (normal login session), the
257user may use the escape characters noted below.
258.Pp
259If no pseudo-tty has been allocated,
260the session is transparent and can be used to reliably transfer binary data.
261On most systems, setting the escape character to
262.Dq none
263will also make the session transparent even if a tty is used.
264.Pp
265The session terminates when the command or shell on the remote
266machine exits and all X11 and TCP/IP connections have been closed.
267The exit status of the remote program is returned as the exit status of
268.Nm ssh .
269.Ss Escape Characters
270When a pseudo-terminal has been requested,
271.Nm
272supports a number of functions through the use of an escape character.
273.Pp
274A single tilde character can be sent as
275.Ic ~~
276or by following the tilde by a character other than those described below.
277The 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
281configuration directive or on the command line by the
282.Fl e
283option.
284.Pp
285The supported escapes (assuming the default
286.Ql ~ )
287are:
288.Bl -tag -width Ds
289.It Cm ~.
290Disconnect.
291.It Cm ~^Z
292Background
293.Nm ssh .
294.It Cm ~#
295List forwarded connections.
296.It Cm ~&
297Background
298.Nm
299at logout when waiting for forwarded connection / X11 sessions to terminate.
300.It Cm ~?
301Display a list of escape characters.
302.It Cm ~B
303Send a BREAK to the remote system
304(only useful for SSH protocol version 2 and if the peer supports it).
305.It Cm ~C
306Open command line (only useful for adding port forwardings using the
307.Fl L
308and
309.Fl R
310options).
311.It Cm ~R
312Request rekeying of the connection
313(only useful for SSH protocol version 2 and if the peer supports it).
314.El
315.Ss X11 and TCP forwarding
316If the
317.Cm ForwardX11
318variable is set to
319.Dq yes
320(or see the description of the
321.Fl X
322and
323.Fl x
324options described later)
325and the user is using X11 (the
326.Ev DISPLAY
327environment variable is set), the connection to the X11 display is
328automatically forwarded to the remote side in such a way that any X11
329programs started from the shell (or command) will go through the
330encrypted channel, and the connection to the real X server will be made
331from the local machine.
332The user should not manually set
333.Ev DISPLAY .
334Forwarding of X11 connections can be
335configured on the command line or in configuration files.
336Take note that X11 forwarding can represent a security hazard.
337.Pp
338The
339.Ev DISPLAY
340value set by
341.Nm
342will point to the server machine, but with a display number greater than zero.
343This is normal, and happens because
344.Nm
345creates a
346.Dq proxy
347X server on the server machine for forwarding the
348connections over the encrypted channel.
349.Pp
350.Nm
351will also automatically set up Xauthority data on the server machine.
352For this purpose, it will generate a random authorization cookie,
353store it in Xauthority on the server, and verify that any forwarded
354connections carry this cookie and replace it by the real cookie when
355the connection is opened.
356The real authentication cookie is never
357sent to the server machine (and no cookies are sent in the plain).
358.Pp
359If the
360.Cm ForwardAgent
361variable is set to
362.Dq yes
363(or see the description of the
364.Fl A
365and
366.Fl a
367options described later) and
368the user is using an authentication agent, the connection to the agent
369is automatically forwarded to the remote side.
370.Pp
371Forwarding of arbitrary TCP/IP connections over the secure channel can
372be specified either on the command line or in a configuration file.
373One possible application of TCP/IP forwarding is a secure connection to an
374electronic purse; another is going through firewalls.
375.Ss Server authentication
376.Nm
377automatically maintains and checks a database containing
378identifications for all hosts it has ever been used with.
379Host keys are stored in
380.Pa $HOME/.ssh/known_hosts
381in the user's home directory.
382Additionally, the file
383.Pa /etc/ssh/ssh_known_hosts
384is automatically checked for known hosts.
385Any new hosts are automatically added to the user's file.
386If a host's identification ever changes,
387.Nm
388warns about this and disables password authentication to prevent a
389trojan horse from getting the user's password.
390Another purpose of this mechanism is to prevent man-in-the-middle attacks
391which could otherwise be used to circumvent the encryption.
392The
393.Cm StrictHostKeyChecking
394option can be used to prevent logins to machines whose
395host key is not known or has changed.
396.Pp
397The options are as follows:
398.Bl -tag -width Ds
399.It Fl 1
400Forces
401.Nm
402to try protocol version 1 only.
403.It Fl 2
404Forces
405.Nm
406to try protocol version 2 only.
407.It Fl 4
408Forces
409.Nm
410to use IPv4 addresses only.
411.It Fl 6
412Forces
413.Nm
414to use IPv6 addresses only.
415.It Fl A
416Enables forwarding of the authentication agent connection.
417This can also be specified on a per-host basis in a configuration file.
418.Pp
419Agent forwarding should be enabled with caution.
420Users with the ability to bypass file permissions on the remote host
421(for the agent's Unix-domain socket)
422can access the local agent through the forwarded connection.
423An attacker cannot obtain key material from the agent,
424however they can perform operations on the keys that enable them to
425authenticate using the identities loaded into the agent.
426.It Fl a
427Disables forwarding of the authentication agent connection.
428.It Fl b Ar bind_address
429Specify the interface to transmit from on machines with multiple
430interfaces or aliased addresses.
431.It Fl C
432Requests compression of all data (including stdin, stdout, stderr, and
433data for forwarded X11 and TCP/IP connections).
434The compression algorithm is the same used by
435.Xr gzip 1 ,
436and the
437.Dq level
438can be controlled by the
439.Cm CompressionLevel
440option for protocol version 1.
441Compression is desirable on modem lines and other
442slow connections, but will only slow down things on fast networks.
443The default value can be set on a host-by-host basis in the
444configuration files; see the
445.Cm Compression
446option.
447.It Fl c Ar blowfish | 3des | des
448Selects the cipher to use for encrypting the session.
449.Ar 3des
450is used by default.
451It is believed to be secure.
452.Ar 3des
453(triple-des) is an encrypt-decrypt-encrypt triple with three different keys.
454.Ar blowfish
455is a fast block cipher; it appears very secure and is much faster than
456.Ar 3des .
457.Ar des
458is only supported in the
459.Nm
460client for interoperability with legacy protocol 1 implementations
461that do not support the
462.Ar 3des
463cipher.
464Its use is strongly discouraged due to cryptographic weaknesses.
465.It Fl c Ar cipher_spec
466Additionally, for protocol version 2 a comma-separated list of ciphers can
467be specified in order of preference.
468See
469.Cm Ciphers
470for more information.
471.It Fl D Ar port
472Specifies a local
473.Dq dynamic
474application-level port forwarding.
475This works by allocating a socket to listen to
476.Ar port
477on the local side, and whenever a connection is made to this port, the
478connection is forwarded over the secure channel, and the application
479protocol is then used to determine where to connect to from the
480remote machine.
481Currently the SOCKS4 and SOCKS5 protocols are supported, and
482.Nm
483will act as a SOCKS server.
484Only root can forward privileged ports.
485Dynamic port forwardings can also be specified in the configuration file.
486.It Fl e Ar ch | ^ch | none
487Sets the escape character for sessions with a pty (default:
488.Ql ~ ) .
489The escape character is only recognized at the beginning of a line.
490The escape character followed by a dot
491.Pq Ql \&.
492closes the connection;
493followed by control-Z suspends the connection;
494and followed by itself sends the escape character once.
495Setting the character to
496.Dq none
497disables any escapes and makes the session fully transparent.
498.It Fl F Ar configfile
499Specifies an alternative per-user configuration file.
500If a configuration file is given on the command line,
501the system-wide configuration file
502.Pq Pa /etc/ssh/ssh_config
503will be ignored.
504The default for the per-user configuration file is
505.Pa $HOME/.ssh/config .
506.It Fl f
507Requests
508.Nm
509to go to background just before command execution.
510This is useful if
511.Nm
512is going to ask for passwords or passphrases, but the user
513wants it in the background.
514This implies
515.Fl n .
516The recommended way to start X11 programs at a remote site is with
517something like
518.Ic ssh -f host xterm .
519.It Fl g
520Allows remote hosts to connect to local forwarded ports.
521.It Fl I Ar smartcard_device
522Specifies which smartcard device to use.
523The argument is the device
524.Nm
525should use to communicate with a smartcard used for storing the user's
526private RSA key.
527.It Fl i Ar identity_file
528Selects a file from which the identity (private key) for
529RSA or DSA authentication is read.
530The default is
531.Pa $HOME/.ssh/identity
532for protocol version 1, and
533.Pa $HOME/.ssh/id_rsa
534and
535.Pa $HOME/.ssh/id_dsa
536for protocol version 2.
537Identity files may also be specified on
538a per-host basis in the configuration file.
539It is possible to have multiple
540.Fl i
541options (and multiple identities specified in
542configuration files).
543.It Fl k
544Disables forwarding (delegation) of GSSAPI credentials to the server.
545.It Fl L Xo
546.Sm off
547.Ar port : host : hostport
548.Sm on
549.Xc
550Specifies that the given port on the local (client) host is to be
551forwarded to the given host and port on the remote side.
552This works by allocating a socket to listen to
553.Ar port
554on the local side, and whenever a connection is made to this port, the
555connection is forwarded over the secure channel, and a connection is
556made to
557.Ar host
558port
559.Ar hostport
560from the remote machine.
561Port forwardings can also be specified in the configuration file.
562Only root can forward privileged ports.
563IPv6 addresses can be specified with an alternative syntax:
564.Sm off
565.Xo
566.Ar port No / Ar host No /
567.Ar hostport .
568.Xc
569.Sm on
570.It Fl l Ar login_name
571Specifies the user to log in as on the remote machine.
572This also may be specified on a per-host basis in the configuration file.
573.It Fl m Ar mac_spec
574Additionally, for protocol version 2 a comma-separated list of MAC
575(message authentication code) algorithms can
576be specified in order of preference.
577See the
578.Cm MACs
579keyword for more information.
580.It Fl N
581Do not execute a remote command.
582This is useful for just forwarding ports
583(protocol version 2 only).
584.It Fl n
585Redirects stdin from
586.Pa /dev/null
587(actually, prevents reading from stdin).
588This must be used when
589.Nm
590is run in the background.
591A common trick is to use this to run X11 programs on a remote machine.
592For example,
593.Ic ssh -n shadows.cs.hut.fi emacs &
594will start an emacs on shadows.cs.hut.fi, and the X11
595connection will be automatically forwarded over an encrypted channel.
596The
597.Nm
598program will be put in the background.
599(This does not work if
600.Nm
601needs to ask for a password or passphrase; see also the
602.Fl f
603option.)
604.It Fl o Ar option
605Can be used to give options in the format used in the configuration file.
606This is useful for specifying options for which there is no separate
607command-line flag.
608For full details of the options listed below, and their possible values, see
609.Xr ssh_config 5 .
610.Pp
611.Bl -tag -width Ds -offset indent -compact
612.It AddressFamily
613.It BatchMode
614.It BindAddress
615.It ChallengeResponseAuthentication
616.It CheckHostIP
617.It Cipher
618.It Ciphers
619.It ClearAllForwardings
620.It Compression
621.It CompressionLevel
622.It ConnectionAttempts
623.It ConnectionTimeout
624.It DynamicForward
625.It EscapeChar
626.It ForwardAgent
627.It ForwardX11
628.It ForwardX11Trusted
629.It GatewayPorts
630.It GlobalKnownHostsFile
631.It GSSAPIAuthentication
632.It GSSAPIDelegateCredentials
633.It Host
634.It HostbasedAuthentication
635.It HostKeyAlgorithms
636.It HostKeyAlias
637.It HostName
638.It IdentityFile
| 39.Dd September 25, 1999
40.Dt SSH 1
41.Os
42.Sh NAME
43.Nm ssh
44.Nd OpenSSH SSH client (remote login program)
45.Sh SYNOPSIS
46.Nm ssh
47.Op Fl 1246AaCfgkNnqsTtVvXxY
48.Op Fl b Ar bind_address
49.Op Fl c Ar cipher_spec
50.Op Fl D Ar port
51.Op Fl e Ar escape_char
52.Op Fl F Ar configfile
53.Op Fl i Ar identity_file
54.Bk -words
55.Oo Fl L Xo
56.Sm off
57.Ar port :
58.Ar host :
59.Ar hostport
60.Sm on
61.Xc
62.Oc
63.Ek
64.Op Fl l Ar login_name
65.Op Fl m Ar mac_spec
66.Op Fl o Ar option
67.Bk -words
68.Op Fl p Ar port
69.Ek
70.Oo Fl R Xo
71.Sm off
72.Ar port :
73.Ar host :
74.Ar hostport
75.Sm on
76.Xc
77.Oc
78.Oo Ar user Ns @ Oc Ns Ar hostname
79.Op Ar command
80.Sh DESCRIPTION
81.Nm
82(SSH client) is a program for logging into a remote machine and for
83executing commands on a remote machine.
84It is intended to replace rlogin and rsh,
85and provide secure encrypted communications between
86two untrusted hosts over an insecure network.
87X11 connections and arbitrary TCP/IP ports
88can also be forwarded over the secure channel.
89.Pp
90.Nm
91connects and logs into the specified
92.Ar hostname
93(with optional
94.Ar user
95name).
96The user must prove
97his/her identity to the remote machine using one of several methods
98depending on the protocol version used.
99.Pp
100If
101.Ar command
102is specified,
103.Ar command
104is executed on the remote host instead of a login shell.
105.Ss SSH protocol version 1
106First, if the machine the user logs in from is listed in
107.Pa /etc/hosts.equiv
108or
109.Pa /etc/ssh/shosts.equiv
110on the remote machine, and the user names are
111the same on both sides, the user is immediately permitted to log in.
112Second, if
113.Pa .rhosts
114or
115.Pa .shosts
116exists 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
119permitted to log in.
120This form of authentication alone is normally not
121allowed by the server because it is not secure.
122.Pp
123The second authentication method is the
124.Em rhosts
125or
126.Em hosts.equiv
127method combined with RSA-based host authentication.
128It means that if the login would be permitted by
129.Pa $HOME/.rhosts ,
130.Pa $HOME/.shosts ,
131.Pa /etc/hosts.equiv ,
132or
133.Pa /etc/ssh/shosts.equiv ,
134and if additionally the server can verify the client's
135host key (see
136.Pa /etc/ssh/ssh_known_hosts
137and
138.Pa $HOME/.ssh/known_hosts
139in the
140.Sx FILES
141section), only then is login permitted.
142This authentication method closes security holes due to IP
143spoofing, DNS spoofing and routing spoofing.
144[Note to the administrator:
145.Pa /etc/hosts.equiv ,
146.Pa $HOME/.rhosts ,
147and the rlogin/rsh protocol in general, are inherently insecure and should be
148disabled if security is desired.]
149.Pp
150As a third authentication method,
151.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.
156RSA is one such system.
157The idea is that each user creates a public/private
158key pair for authentication purposes.
159The server knows the public key, and only the user knows the private key.
160.Pp
161The file
162.Pa $HOME/.ssh/authorized_keys
163lists the public keys that are permitted for logging in.
164When the user logs in, the
165.Nm
166program tells the server which key pair it would like to use for
167authentication.
168The server checks if this key is permitted, and if so,
169sends the user (actually the
170.Nm
171program running on behalf of the user) a challenge, a random number,
172encrypted by the user's public key.
173The 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.
177.Pp
178.Nm
179implements the RSA authentication protocol automatically.
180The user creates his/her RSA key pair by running
181.Xr ssh-keygen 1 .
182This stores the private key in
183.Pa $HOME/.ssh/identity
184and stores the public key in
185.Pa $HOME/.ssh/identity.pub
186in the user's home directory.
187The user should then copy the
188.Pa identity.pub
189to
190.Pa $HOME/.ssh/authorized_keys
191in his/her home directory on the remote machine (the
192.Pa authorized_keys
193file corresponds to the conventional
194.Pa $HOME/.rhosts
195file, and has one key
196per line, though the lines can be very long).
197After this, the user can log in without giving the password.
198RSA authentication is much more secure than
199.Em rhosts
200authentication.
201.Pp
202The most convenient way to use RSA authentication may be with an
203authentication agent.
204See
205.Xr ssh-agent 1
206for more information.
207.Pp
208If other authentication methods fail,
209.Nm
210prompts the user for a password.
211The password is sent to the remote
212host for checking; however, since all communications are encrypted,
213the password cannot be seen by someone listening on the network.
214.Ss SSH protocol version 2
215When a user connects using protocol version 2,
216similar authentication methods are available.
217Using the default values for
218.Cm PreferredAuthentications ,
219the client will try to authenticate first using the hostbased method;
220if this method fails, public key authentication is attempted,
221and finally if this method fails, keyboard-interactive and
222password authentication are tried.
223.Pp
224The public key method is similar to RSA authentication described
225in the previous section and allows the RSA or DSA algorithm to be used:
226The client uses his private key,
227.Pa $HOME/.ssh/id_dsa
228or
229.Pa $HOME/.ssh/id_rsa ,
230to sign the session identifier and sends the result to the server.
231The server checks whether the matching public key is listed in
232.Pa $HOME/.ssh/authorized_keys
233and 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
237If public key authentication fails or is not available, a password
238can be sent encrypted to the remote host to prove the user's identity.
239.Pp
240Additionally,
241.Nm
242supports hostbased or challenge response authentication.
243.Pp
244Protocol 2 provides additional mechanisms for confidentiality
245(the traffic is encrypted using 3DES, Blowfish, CAST128 or Arcfour)
246and integrity (hmac-md5, hmac-sha1).
247Note that protocol 1 lacks a strong mechanism for ensuring the
248integrity of the connection.
249.Ss Login session and remote execution
250When the user's identity has been accepted by the server, the server
251either executes the given command, or logs into the machine and gives
252the user a normal shell on the remote machine.
253All communication with
254the remote command or shell will be automatically encrypted.
255.Pp
256If a pseudo-terminal has been allocated (normal login session), the
257user may use the escape characters noted below.
258.Pp
259If no pseudo-tty has been allocated,
260the session is transparent and can be used to reliably transfer binary data.
261On most systems, setting the escape character to
262.Dq none
263will also make the session transparent even if a tty is used.
264.Pp
265The session terminates when the command or shell on the remote
266machine exits and all X11 and TCP/IP connections have been closed.
267The exit status of the remote program is returned as the exit status of
268.Nm ssh .
269.Ss Escape Characters
270When a pseudo-terminal has been requested,
271.Nm
272supports a number of functions through the use of an escape character.
273.Pp
274A single tilde character can be sent as
275.Ic ~~
276or by following the tilde by a character other than those described below.
277The 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
281configuration directive or on the command line by the
282.Fl e
283option.
284.Pp
285The supported escapes (assuming the default
286.Ql ~ )
287are:
288.Bl -tag -width Ds
289.It Cm ~.
290Disconnect.
291.It Cm ~^Z
292Background
293.Nm ssh .
294.It Cm ~#
295List forwarded connections.
296.It Cm ~&
297Background
298.Nm
299at logout when waiting for forwarded connection / X11 sessions to terminate.
300.It Cm ~?
301Display a list of escape characters.
302.It Cm ~B
303Send a BREAK to the remote system
304(only useful for SSH protocol version 2 and if the peer supports it).
305.It Cm ~C
306Open command line (only useful for adding port forwardings using the
307.Fl L
308and
309.Fl R
310options).
311.It Cm ~R
312Request rekeying of the connection
313(only useful for SSH protocol version 2 and if the peer supports it).
314.El
315.Ss X11 and TCP forwarding
316If the
317.Cm ForwardX11
318variable is set to
319.Dq yes
320(or see the description of the
321.Fl X
322and
323.Fl x
324options described later)
325and the user is using X11 (the
326.Ev DISPLAY
327environment variable is set), the connection to the X11 display is
328automatically forwarded to the remote side in such a way that any X11
329programs started from the shell (or command) will go through the
330encrypted channel, and the connection to the real X server will be made
331from the local machine.
332The user should not manually set
333.Ev DISPLAY .
334Forwarding of X11 connections can be
335configured on the command line or in configuration files.
336Take note that X11 forwarding can represent a security hazard.
337.Pp
338The
339.Ev DISPLAY
340value set by
341.Nm
342will point to the server machine, but with a display number greater than zero.
343This is normal, and happens because
344.Nm
345creates a
346.Dq proxy
347X server on the server machine for forwarding the
348connections over the encrypted channel.
349.Pp
350.Nm
351will also automatically set up Xauthority data on the server machine.
352For this purpose, it will generate a random authorization cookie,
353store it in Xauthority on the server, and verify that any forwarded
354connections carry this cookie and replace it by the real cookie when
355the connection is opened.
356The real authentication cookie is never
357sent to the server machine (and no cookies are sent in the plain).
358.Pp
359If the
360.Cm ForwardAgent
361variable is set to
362.Dq yes
363(or see the description of the
364.Fl A
365and
366.Fl a
367options described later) and
368the user is using an authentication agent, the connection to the agent
369is automatically forwarded to the remote side.
370.Pp
371Forwarding of arbitrary TCP/IP connections over the secure channel can
372be specified either on the command line or in a configuration file.
373One possible application of TCP/IP forwarding is a secure connection to an
374electronic purse; another is going through firewalls.
375.Ss Server authentication
376.Nm
377automatically maintains and checks a database containing
378identifications for all hosts it has ever been used with.
379Host keys are stored in
380.Pa $HOME/.ssh/known_hosts
381in the user's home directory.
382Additionally, the file
383.Pa /etc/ssh/ssh_known_hosts
384is automatically checked for known hosts.
385Any new hosts are automatically added to the user's file.
386If a host's identification ever changes,
387.Nm
388warns about this and disables password authentication to prevent a
389trojan horse from getting the user's password.
390Another purpose of this mechanism is to prevent man-in-the-middle attacks
391which could otherwise be used to circumvent the encryption.
392The
393.Cm StrictHostKeyChecking
394option can be used to prevent logins to machines whose
395host key is not known or has changed.
396.Pp
397The options are as follows:
398.Bl -tag -width Ds
399.It Fl 1
400Forces
401.Nm
402to try protocol version 1 only.
403.It Fl 2
404Forces
405.Nm
406to try protocol version 2 only.
407.It Fl 4
408Forces
409.Nm
410to use IPv4 addresses only.
411.It Fl 6
412Forces
413.Nm
414to use IPv6 addresses only.
415.It Fl A
416Enables forwarding of the authentication agent connection.
417This can also be specified on a per-host basis in a configuration file.
418.Pp
419Agent forwarding should be enabled with caution.
420Users with the ability to bypass file permissions on the remote host
421(for the agent's Unix-domain socket)
422can access the local agent through the forwarded connection.
423An attacker cannot obtain key material from the agent,
424however they can perform operations on the keys that enable them to
425authenticate using the identities loaded into the agent.
426.It Fl a
427Disables forwarding of the authentication agent connection.
428.It Fl b Ar bind_address
429Specify the interface to transmit from on machines with multiple
430interfaces or aliased addresses.
431.It Fl C
432Requests compression of all data (including stdin, stdout, stderr, and
433data for forwarded X11 and TCP/IP connections).
434The compression algorithm is the same used by
435.Xr gzip 1 ,
436and the
437.Dq level
438can be controlled by the
439.Cm CompressionLevel
440option for protocol version 1.
441Compression is desirable on modem lines and other
442slow connections, but will only slow down things on fast networks.
443The default value can be set on a host-by-host basis in the
444configuration files; see the
445.Cm Compression
446option.
447.It Fl c Ar blowfish | 3des | des
448Selects the cipher to use for encrypting the session.
449.Ar 3des
450is used by default.
451It is believed to be secure.
452.Ar 3des
453(triple-des) is an encrypt-decrypt-encrypt triple with three different keys.
454.Ar blowfish
455is a fast block cipher; it appears very secure and is much faster than
456.Ar 3des .
457.Ar des
458is only supported in the
459.Nm
460client for interoperability with legacy protocol 1 implementations
461that do not support the
462.Ar 3des
463cipher.
464Its use is strongly discouraged due to cryptographic weaknesses.
465.It Fl c Ar cipher_spec
466Additionally, for protocol version 2 a comma-separated list of ciphers can
467be specified in order of preference.
468See
469.Cm Ciphers
470for more information.
471.It Fl D Ar port
472Specifies a local
473.Dq dynamic
474application-level port forwarding.
475This works by allocating a socket to listen to
476.Ar port
477on the local side, and whenever a connection is made to this port, the
478connection is forwarded over the secure channel, and the application
479protocol is then used to determine where to connect to from the
480remote machine.
481Currently the SOCKS4 and SOCKS5 protocols are supported, and
482.Nm
483will act as a SOCKS server.
484Only root can forward privileged ports.
485Dynamic port forwardings can also be specified in the configuration file.
486.It Fl e Ar ch | ^ch | none
487Sets the escape character for sessions with a pty (default:
488.Ql ~ ) .
489The escape character is only recognized at the beginning of a line.
490The escape character followed by a dot
491.Pq Ql \&.
492closes the connection;
493followed by control-Z suspends the connection;
494and followed by itself sends the escape character once.
495Setting the character to
496.Dq none
497disables any escapes and makes the session fully transparent.
498.It Fl F Ar configfile
499Specifies an alternative per-user configuration file.
500If a configuration file is given on the command line,
501the system-wide configuration file
502.Pq Pa /etc/ssh/ssh_config
503will be ignored.
504The default for the per-user configuration file is
505.Pa $HOME/.ssh/config .
506.It Fl f
507Requests
508.Nm
509to go to background just before command execution.
510This is useful if
511.Nm
512is going to ask for passwords or passphrases, but the user
513wants it in the background.
514This implies
515.Fl n .
516The recommended way to start X11 programs at a remote site is with
517something like
518.Ic ssh -f host xterm .
519.It Fl g
520Allows remote hosts to connect to local forwarded ports.
521.It Fl I Ar smartcard_device
522Specifies which smartcard device to use.
523The argument is the device
524.Nm
525should use to communicate with a smartcard used for storing the user's
526private RSA key.
527.It Fl i Ar identity_file
528Selects a file from which the identity (private key) for
529RSA or DSA authentication is read.
530The default is
531.Pa $HOME/.ssh/identity
532for protocol version 1, and
533.Pa $HOME/.ssh/id_rsa
534and
535.Pa $HOME/.ssh/id_dsa
536for protocol version 2.
537Identity files may also be specified on
538a per-host basis in the configuration file.
539It is possible to have multiple
540.Fl i
541options (and multiple identities specified in
542configuration files).
543.It Fl k
544Disables forwarding (delegation) of GSSAPI credentials to the server.
545.It Fl L Xo
546.Sm off
547.Ar port : host : hostport
548.Sm on
549.Xc
550Specifies that the given port on the local (client) host is to be
551forwarded to the given host and port on the remote side.
552This works by allocating a socket to listen to
553.Ar port
554on the local side, and whenever a connection is made to this port, the
555connection is forwarded over the secure channel, and a connection is
556made to
557.Ar host
558port
559.Ar hostport
560from the remote machine.
561Port forwardings can also be specified in the configuration file.
562Only root can forward privileged ports.
563IPv6 addresses can be specified with an alternative syntax:
564.Sm off
565.Xo
566.Ar port No / Ar host No /
567.Ar hostport .
568.Xc
569.Sm on
570.It Fl l Ar login_name
571Specifies the user to log in as on the remote machine.
572This also may be specified on a per-host basis in the configuration file.
573.It Fl m Ar mac_spec
574Additionally, for protocol version 2 a comma-separated list of MAC
575(message authentication code) algorithms can
576be specified in order of preference.
577See the
578.Cm MACs
579keyword for more information.
580.It Fl N
581Do not execute a remote command.
582This is useful for just forwarding ports
583(protocol version 2 only).
584.It Fl n
585Redirects stdin from
586.Pa /dev/null
587(actually, prevents reading from stdin).
588This must be used when
589.Nm
590is run in the background.
591A common trick is to use this to run X11 programs on a remote machine.
592For example,
593.Ic ssh -n shadows.cs.hut.fi emacs &
594will start an emacs on shadows.cs.hut.fi, and the X11
595connection will be automatically forwarded over an encrypted channel.
596The
597.Nm
598program will be put in the background.
599(This does not work if
600.Nm
601needs to ask for a password or passphrase; see also the
602.Fl f
603option.)
604.It Fl o Ar option
605Can be used to give options in the format used in the configuration file.
606This is useful for specifying options for which there is no separate
607command-line flag.
608For full details of the options listed below, and their possible values, see
609.Xr ssh_config 5 .
610.Pp
611.Bl -tag -width Ds -offset indent -compact
612.It AddressFamily
613.It BatchMode
614.It BindAddress
615.It ChallengeResponseAuthentication
616.It CheckHostIP
617.It Cipher
618.It Ciphers
619.It ClearAllForwardings
620.It Compression
621.It CompressionLevel
622.It ConnectionAttempts
623.It ConnectionTimeout
624.It DynamicForward
625.It EscapeChar
626.It ForwardAgent
627.It ForwardX11
628.It ForwardX11Trusted
629.It GatewayPorts
630.It GlobalKnownHostsFile
631.It GSSAPIAuthentication
632.It GSSAPIDelegateCredentials
633.It Host
634.It HostbasedAuthentication
635.It HostKeyAlgorithms
636.It HostKeyAlias
637.It HostName
638.It IdentityFile
|
| 639.It IdentitiesOnly
|
639.It LocalForward
640.It LogLevel
641.It MACs
642.It NoHostAuthenticationForLocalhost
643.It NumberOfPasswordPrompts
644.It PasswordAuthentication
645.It Port
646.It PreferredAuthentications
647.It Protocol
648.It ProxyCommand
649.It PubkeyAuthentication
650.It RemoteForward
651.It RhostsRSAAuthentication
652.It RSAAuthentication
653.It ServerAliveInterval
654.It ServerAliveCountMax
655.It SmartcardDevice
656.It StrictHostKeyChecking
657.It TCPKeepAlive
658.It UsePrivilegedPort
659.It User
660.It UserKnownHostsFile
661.It VerifyHostKeyDNS
662.It XAuthLocation
663.El
664.It Fl p Ar port
665Port to connect to on the remote host.
666This can be specified on a
667per-host basis in the configuration file.
668.It Fl q
669Quiet mode.
670Causes all warning and diagnostic messages to be suppressed.
671.It Fl R Xo
672.Sm off
673.Ar port : host : hostport
674.Sm on
675.Xc
676Specifies that the given port on the remote (server) host is to be
677forwarded to the given host and port on the local side.
678This works by allocating a socket to listen to
679.Ar port
680on the remote side, and whenever a connection is made to this port, the
681connection is forwarded over the secure channel, and a connection is
682made to
683.Ar host
684port
685.Ar hostport
686from the local machine.
687Port forwardings can also be specified in the configuration file.
688Privileged ports can be forwarded only when
689logging in as root on the remote machine.
690IPv6 addresses can be specified with an alternative syntax:
691.Sm off
692.Xo
693.Ar port No / Ar host No /
694.Ar hostport .
695.Xc
696.Sm on
697.It Fl s
698May be used to request invocation of a subsystem on the remote system.
699Subsystems are a feature of the SSH2 protocol which facilitate the use
700of SSH as a secure transport for other applications (eg.\&
701.Xr sftp 1 ) .
702The subsystem is specified as the remote command.
703.It Fl T
704Disable pseudo-tty allocation.
705.It Fl t
706Force pseudo-tty allocation.
707This can be used to execute arbitrary
708screen-based programs on a remote machine, which can be very useful,
709e.g., when implementing menu services.
710Multiple
711.Fl t
712options force tty allocation, even if
713.Nm
714has no local tty.
715.It Fl V
716Display the version number and exit.
717.It Fl v
718Verbose mode.
719Causes
720.Nm
721to print debugging messages about its progress.
722This is helpful in
723debugging connection, authentication, and configuration problems.
724Multiple
725.Fl v
726options increase the verbosity.
727The maximum is 3.
728.It Fl X
729Enables X11 forwarding.
730This can also be specified on a per-host basis in a configuration file.
731.Pp
732X11 forwarding should be enabled with caution.
733Users with the ability to bypass file permissions on the remote host
734(for the user's X authorization database)
735can access the local X11 display through the forwarded connection.
736An attacker may then be able to perform activities such as keystroke monitoring.
737.It Fl x
738Disables X11 forwarding.
739.It Fl Y
740Enables trusted X11 forwarding.
741.El
742.Sh CONFIGURATION FILES
743.Nm
744may additionally obtain configuration data from
745a per-user configuration file and a system-wide configuration file.
746The file format and configuration options are described in
747.Xr ssh_config 5 .
748.Sh ENVIRONMENT
749.Nm
750will normally set the following environment variables:
751.Bl -tag -width LOGNAME
752.It Ev DISPLAY
753The
754.Ev DISPLAY
755variable indicates the location of the X11 server.
756It is automatically set by
757.Nm
758to point to a value of the form
759.Dq hostname:n
760where hostname indicates
761the host where the shell runs, and n is an integer \*(Ge 1.
762.Nm
763uses this special value to forward X11 connections over the secure
764channel.
765The user should normally not set
766.Ev DISPLAY
767explicitly, as that
768will render the X11 connection insecure (and will require the user to
769manually copy any required authorization cookies).
770.It Ev HOME
771Set to the path of the user's home directory.
772.It Ev LOGNAME
773Synonym for
774.Ev USER ;
775set for compatibility with systems that use this variable.
776.It Ev MAIL
777Set to the path of the user's mailbox.
778.It Ev PATH
779Set to the default
780.Ev PATH ,
781as specified when compiling
782.Nm ssh .
783.It Ev SSH_ASKPASS
784If
785.Nm
786needs a passphrase, it will read the passphrase from the current
787terminal if it was run from a terminal.
788If
789.Nm
790does not have a terminal associated with it but
791.Ev DISPLAY
792and
793.Ev SSH_ASKPASS
794are set, it will execute the program specified by
795.Ev SSH_ASKPASS
796and open an X11 window to read the passphrase.
797This is particularly useful when calling
798.Nm
799from a
800.Pa .Xsession
801or related script.
802(Note that on some machines it
803may be necessary to redirect the input from
804.Pa /dev/null
805to make this work.)
806.It Ev SSH_AUTH_SOCK
807Identifies the path of a unix-domain socket used to communicate with the
808agent.
809.It Ev SSH_CONNECTION
810Identifies the client and server ends of the connection.
811The variable contains
812four space-separated values: client ip-address, client port number,
813server ip-address and server port number.
814.It Ev SSH_ORIGINAL_COMMAND
815The variable contains the original command line if a forced command
816is executed.
817It can be used to extract the original arguments.
818.It Ev SSH_TTY
819This is set to the name of the tty (path to the device) associated
820with the current shell or command.
821If the current session has no tty,
822this variable is not set.
823.It Ev TZ
824The timezone variable is set to indicate the present timezone if it
825was set when the daemon was started (i.e., the daemon passes the value
826on to new connections).
827.It Ev USER
828Set to the name of the user logging in.
829.El
830.Pp
831Additionally,
832.Nm
833reads
834.Pa $HOME/.ssh/environment ,
835and adds lines of the format
836.Dq VARNAME=value
837to the environment if the file exists and if users are allowed to
838change their environment.
839For more information, see the
840.Cm PermitUserEnvironment
841option in
842.Xr sshd_config 5 .
843.Sh FILES
844.Bl -tag -width Ds
845.It Pa $HOME/.ssh/known_hosts
846Records host keys for all hosts the user has logged into that are not
847in
848.Pa /etc/ssh/ssh_known_hosts .
849See
850.Xr sshd 8 .
851.It Pa $HOME/.ssh/identity, $HOME/.ssh/id_dsa, $HOME/.ssh/id_rsa
852Contains the authentication identity of the user.
853They are for protocol 1 RSA, protocol 2 DSA, and protocol 2 RSA, respectively.
854These files
855contain sensitive data and should be readable by the user but not
856accessible by others (read/write/execute).
857Note that
858.Nm
859ignores a private key file if it is accessible by others.
860It is possible to specify a passphrase when
861generating the key; the passphrase will be used to encrypt the
862sensitive part of this file using 3DES.
863.It Pa $HOME/.ssh/identity.pub, $HOME/.ssh/id_dsa.pub, $HOME/.ssh/id_rsa.pub
864Contains the public key for authentication (public part of the
865identity file in human-readable form).
866The contents of the
867.Pa $HOME/.ssh/identity.pub
868file should be added to the file
869.Pa $HOME/.ssh/authorized_keys
870on all machines
871where the user wishes to log in using protocol version 1 RSA authentication.
872The contents of the
873.Pa $HOME/.ssh/id_dsa.pub
874and
875.Pa $HOME/.ssh/id_rsa.pub
876file should be added to
877.Pa $HOME/.ssh/authorized_keys
878on all machines
879where the user wishes to log in using protocol version 2 DSA/RSA authentication.
880These files are not
881sensitive and can (but need not) be readable by anyone.
882These files are
883never used automatically and are not necessary; they are only provided for
884the convenience of the user.
885.It Pa $HOME/.ssh/config
886This is the per-user configuration file.
887The file format and configuration options are described in
888.Xr ssh_config 5 .
889.It Pa $HOME/.ssh/authorized_keys
890Lists the public keys (RSA/DSA) that can be used for logging in as this user.
891The format of this file is described in the
892.Xr sshd 8
893manual page.
894In the simplest form the format is the same as the
895.Pa .pub
896identity files.
897This file is not highly sensitive, but the recommended
898permissions are read/write for the user, and not accessible by others.
899.It Pa /etc/ssh/ssh_known_hosts
900Systemwide list of known host keys.
901This file should be prepared by the
902system administrator to contain the public host keys of all machines in the
903organization.
904This file should be world-readable.
905This file contains
906public keys, one per line, in the following format (fields separated
907by spaces): system name, public key and optional comment field.
908When different names are used
909for the same machine, all such names should be listed, separated by
910commas.
911The format is described in the
912.Xr sshd 8
913manual page.
914.Pp
915The canonical system name (as returned by name servers) is used by
916.Xr sshd 8
917to verify the client host when logging in; other names are needed because
918.Nm
919does not convert the user-supplied name to a canonical name before
920checking the key, because someone with access to the name servers
921would then be able to fool host authentication.
922.It Pa /etc/ssh/ssh_config
923Systemwide configuration file.
924The file format and configuration options are described in
925.Xr ssh_config 5 .
926.It Pa /etc/ssh/ssh_host_key, /etc/ssh/ssh_host_dsa_key, /etc/ssh/ssh_host_rsa_key
927These three files contain the private parts of the host keys
928and are used for
929.Cm RhostsRSAAuthentication
930and
931.Cm HostbasedAuthentication .
932If the protocol version 1
933.Cm RhostsRSAAuthentication
934method is used,
935.Nm
936must be setuid root, since the host key is readable only by root.
937For protocol version 2,
938.Nm
939uses
940.Xr ssh-keysign 8
941to access the host keys for
942.Cm HostbasedAuthentication .
943This eliminates the requirement that
944.Nm
945be setuid root when that authentication method is used.
946By default
947.Nm
948is not setuid root.
949.It Pa $HOME/.rhosts
950This file is used in
951.Em rhosts
952authentication to list the
953host/user pairs that are permitted to log in.
954(Note that this file is
955also used by rlogin and rsh, which makes using this file insecure.)
956Each line of the file contains a host name (in the canonical form
957returned by name servers), and then a user name on that host,
958separated by a space.
959On some machines this file may need to be
960world-readable if the user's home directory is on a NFS partition,
961because
962.Xr sshd 8
963reads it as root.
964Additionally, this file must be owned by the user,
965and must not have write permissions for anyone else.
966The recommended
967permission for most machines is read/write for the user, and not
968accessible by others.
969.Pp
970Note that by default
971.Xr sshd 8
972will be installed so that it requires successful RSA host
973authentication before permitting
974.Em rhosts
975authentication.
976If the server machine does not have the client's host key in
977.Pa /etc/ssh/ssh_known_hosts ,
978it can be stored in
979.Pa $HOME/.ssh/known_hosts .
980The easiest way to do this is to
981connect back to the client from the server machine using ssh; this
982will automatically add the host key to
983.Pa $HOME/.ssh/known_hosts .
984.It Pa $HOME/.shosts
985This file is used exactly the same way as
986.Pa .rhosts .
987The purpose for
988having this file is to be able to use rhosts authentication with
989.Nm
990without permitting login with
991.Xr rlogin
992or
993.Xr rsh 1 .
994.It Pa /etc/hosts.equiv
995This file is used during
996.Em rhosts
997authentication.
998It contains
999canonical hosts names, one per line (the full format is described in the
1000.Xr sshd 8
1001manual page).
1002If the client host is found in this file, login is
1003automatically permitted provided client and server user names are the
1004same.
1005Additionally, successful RSA host authentication is normally
1006required.
1007This file should only be writable by root.
1008.It Pa /etc/ssh/shosts.equiv
1009This file is processed exactly as
1010.Pa /etc/hosts.equiv .
1011This file may be useful to permit logins using
1012.Nm
1013but not using rsh/rlogin.
1014.It Pa /etc/ssh/sshrc
1015Commands in this file are executed by
1016.Nm
1017when the user logs in just before the user's shell (or command) is started.
1018See the
1019.Xr sshd 8
1020manual page for more information.
1021.It Pa $HOME/.ssh/rc
1022Commands in this file are executed by
1023.Nm
1024when the user logs in just before the user's shell (or command) is
1025started.
1026See the
1027.Xr sshd 8
1028manual page for more information.
1029.It Pa $HOME/.ssh/environment
1030Contains additional definitions for environment variables, see section
1031.Sx ENVIRONMENT
1032above.
1033.El
1034.Sh DIAGNOSTICS
1035.Nm
1036exits with the exit status of the remote command or with 255
1037if an error occurred.
1038.Sh SEE ALSO
1039.Xr gzip 1 ,
1040.Xr rsh 1 ,
1041.Xr scp 1 ,
1042.Xr sftp 1 ,
1043.Xr ssh-add 1 ,
1044.Xr ssh-agent 1 ,
1045.Xr ssh-keygen 1 ,
1046.Xr telnet 1 ,
1047.Xr hosts.equiv 5 ,
1048.Xr ssh_config 5 ,
1049.Xr ssh-keysign 8 ,
1050.Xr sshd 8
1051.Rs
1052.%A T. Ylonen
1053.%A T. Kivinen
1054.%A M. Saarinen
1055.%A T. Rinne
1056.%A S. Lehtinen
1057.%T "SSH Protocol Architecture"
1058.%N draft-ietf-secsh-architecture-12.txt
1059.%D January 2002
1060.%O work in progress material
1061.Re
1062.Sh AUTHORS
1063OpenSSH is a derivative of the original and free
1064ssh 1.2.12 release by Tatu Ylonen.
1065Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
1066Theo de Raadt and Dug Song
1067removed many bugs, re-added newer features and
1068created OpenSSH.
1069Markus Friedl contributed the support for SSH
1070protocol versions 1.5 and 2.0.
| 640.It LocalForward
641.It LogLevel
642.It MACs
643.It NoHostAuthenticationForLocalhost
644.It NumberOfPasswordPrompts
645.It PasswordAuthentication
646.It Port
647.It PreferredAuthentications
648.It Protocol
649.It ProxyCommand
650.It PubkeyAuthentication
651.It RemoteForward
652.It RhostsRSAAuthentication
653.It RSAAuthentication
654.It ServerAliveInterval
655.It ServerAliveCountMax
656.It SmartcardDevice
657.It StrictHostKeyChecking
658.It TCPKeepAlive
659.It UsePrivilegedPort
660.It User
661.It UserKnownHostsFile
662.It VerifyHostKeyDNS
663.It XAuthLocation
664.El
665.It Fl p Ar port
666Port to connect to on the remote host.
667This can be specified on a
668per-host basis in the configuration file.
669.It Fl q
670Quiet mode.
671Causes all warning and diagnostic messages to be suppressed.
672.It Fl R Xo
673.Sm off
674.Ar port : host : hostport
675.Sm on
676.Xc
677Specifies that the given port on the remote (server) host is to be
678forwarded to the given host and port on the local side.
679This works by allocating a socket to listen to
680.Ar port
681on the remote side, and whenever a connection is made to this port, the
682connection is forwarded over the secure channel, and a connection is
683made to
684.Ar host
685port
686.Ar hostport
687from the local machine.
688Port forwardings can also be specified in the configuration file.
689Privileged ports can be forwarded only when
690logging in as root on the remote machine.
691IPv6 addresses can be specified with an alternative syntax:
692.Sm off
693.Xo
694.Ar port No / Ar host No /
695.Ar hostport .
696.Xc
697.Sm on
698.It Fl s
699May be used to request invocation of a subsystem on the remote system.
700Subsystems are a feature of the SSH2 protocol which facilitate the use
701of SSH as a secure transport for other applications (eg.\&
702.Xr sftp 1 ) .
703The subsystem is specified as the remote command.
704.It Fl T
705Disable pseudo-tty allocation.
706.It Fl t
707Force pseudo-tty allocation.
708This can be used to execute arbitrary
709screen-based programs on a remote machine, which can be very useful,
710e.g., when implementing menu services.
711Multiple
712.Fl t
713options force tty allocation, even if
714.Nm
715has no local tty.
716.It Fl V
717Display the version number and exit.
718.It Fl v
719Verbose mode.
720Causes
721.Nm
722to print debugging messages about its progress.
723This is helpful in
724debugging connection, authentication, and configuration problems.
725Multiple
726.Fl v
727options increase the verbosity.
728The maximum is 3.
729.It Fl X
730Enables X11 forwarding.
731This can also be specified on a per-host basis in a configuration file.
732.Pp
733X11 forwarding should be enabled with caution.
734Users with the ability to bypass file permissions on the remote host
735(for the user's X authorization database)
736can access the local X11 display through the forwarded connection.
737An attacker may then be able to perform activities such as keystroke monitoring.
738.It Fl x
739Disables X11 forwarding.
740.It Fl Y
741Enables trusted X11 forwarding.
742.El
743.Sh CONFIGURATION FILES
744.Nm
745may additionally obtain configuration data from
746a per-user configuration file and a system-wide configuration file.
747The file format and configuration options are described in
748.Xr ssh_config 5 .
749.Sh ENVIRONMENT
750.Nm
751will normally set the following environment variables:
752.Bl -tag -width LOGNAME
753.It Ev DISPLAY
754The
755.Ev DISPLAY
756variable indicates the location of the X11 server.
757It is automatically set by
758.Nm
759to point to a value of the form
760.Dq hostname:n
761where hostname indicates
762the host where the shell runs, and n is an integer \*(Ge 1.
763.Nm
764uses this special value to forward X11 connections over the secure
765channel.
766The user should normally not set
767.Ev DISPLAY
768explicitly, as that
769will render the X11 connection insecure (and will require the user to
770manually copy any required authorization cookies).
771.It Ev HOME
772Set to the path of the user's home directory.
773.It Ev LOGNAME
774Synonym for
775.Ev USER ;
776set for compatibility with systems that use this variable.
777.It Ev MAIL
778Set to the path of the user's mailbox.
779.It Ev PATH
780Set to the default
781.Ev PATH ,
782as specified when compiling
783.Nm ssh .
784.It Ev SSH_ASKPASS
785If
786.Nm
787needs a passphrase, it will read the passphrase from the current
788terminal if it was run from a terminal.
789If
790.Nm
791does not have a terminal associated with it but
792.Ev DISPLAY
793and
794.Ev SSH_ASKPASS
795are set, it will execute the program specified by
796.Ev SSH_ASKPASS
797and open an X11 window to read the passphrase.
798This is particularly useful when calling
799.Nm
800from a
801.Pa .Xsession
802or related script.
803(Note that on some machines it
804may be necessary to redirect the input from
805.Pa /dev/null
806to make this work.)
807.It Ev SSH_AUTH_SOCK
808Identifies the path of a unix-domain socket used to communicate with the
809agent.
810.It Ev SSH_CONNECTION
811Identifies the client and server ends of the connection.
812The variable contains
813four space-separated values: client ip-address, client port number,
814server ip-address and server port number.
815.It Ev SSH_ORIGINAL_COMMAND
816The variable contains the original command line if a forced command
817is executed.
818It can be used to extract the original arguments.
819.It Ev SSH_TTY
820This is set to the name of the tty (path to the device) associated
821with the current shell or command.
822If the current session has no tty,
823this variable is not set.
824.It Ev TZ
825The timezone variable is set to indicate the present timezone if it
826was set when the daemon was started (i.e., the daemon passes the value
827on to new connections).
828.It Ev USER
829Set to the name of the user logging in.
830.El
831.Pp
832Additionally,
833.Nm
834reads
835.Pa $HOME/.ssh/environment ,
836and adds lines of the format
837.Dq VARNAME=value
838to the environment if the file exists and if users are allowed to
839change their environment.
840For more information, see the
841.Cm PermitUserEnvironment
842option in
843.Xr sshd_config 5 .
844.Sh FILES
845.Bl -tag -width Ds
846.It Pa $HOME/.ssh/known_hosts
847Records host keys for all hosts the user has logged into that are not
848in
849.Pa /etc/ssh/ssh_known_hosts .
850See
851.Xr sshd 8 .
852.It Pa $HOME/.ssh/identity, $HOME/.ssh/id_dsa, $HOME/.ssh/id_rsa
853Contains the authentication identity of the user.
854They are for protocol 1 RSA, protocol 2 DSA, and protocol 2 RSA, respectively.
855These files
856contain sensitive data and should be readable by the user but not
857accessible by others (read/write/execute).
858Note that
859.Nm
860ignores a private key file if it is accessible by others.
861It is possible to specify a passphrase when
862generating the key; the passphrase will be used to encrypt the
863sensitive part of this file using 3DES.
864.It Pa $HOME/.ssh/identity.pub, $HOME/.ssh/id_dsa.pub, $HOME/.ssh/id_rsa.pub
865Contains the public key for authentication (public part of the
866identity file in human-readable form).
867The contents of the
868.Pa $HOME/.ssh/identity.pub
869file should be added to the file
870.Pa $HOME/.ssh/authorized_keys
871on all machines
872where the user wishes to log in using protocol version 1 RSA authentication.
873The contents of the
874.Pa $HOME/.ssh/id_dsa.pub
875and
876.Pa $HOME/.ssh/id_rsa.pub
877file should be added to
878.Pa $HOME/.ssh/authorized_keys
879on all machines
880where the user wishes to log in using protocol version 2 DSA/RSA authentication.
881These files are not
882sensitive and can (but need not) be readable by anyone.
883These files are
884never used automatically and are not necessary; they are only provided for
885the convenience of the user.
886.It Pa $HOME/.ssh/config
887This is the per-user configuration file.
888The file format and configuration options are described in
889.Xr ssh_config 5 .
890.It Pa $HOME/.ssh/authorized_keys
891Lists the public keys (RSA/DSA) that can be used for logging in as this user.
892The format of this file is described in the
893.Xr sshd 8
894manual page.
895In the simplest form the format is the same as the
896.Pa .pub
897identity files.
898This file is not highly sensitive, but the recommended
899permissions are read/write for the user, and not accessible by others.
900.It Pa /etc/ssh/ssh_known_hosts
901Systemwide list of known host keys.
902This file should be prepared by the
903system administrator to contain the public host keys of all machines in the
904organization.
905This file should be world-readable.
906This file contains
907public keys, one per line, in the following format (fields separated
908by spaces): system name, public key and optional comment field.
909When different names are used
910for the same machine, all such names should be listed, separated by
911commas.
912The format is described in the
913.Xr sshd 8
914manual page.
915.Pp
916The canonical system name (as returned by name servers) is used by
917.Xr sshd 8
918to verify the client host when logging in; other names are needed because
919.Nm
920does not convert the user-supplied name to a canonical name before
921checking the key, because someone with access to the name servers
922would then be able to fool host authentication.
923.It Pa /etc/ssh/ssh_config
924Systemwide configuration file.
925The file format and configuration options are described in
926.Xr ssh_config 5 .
927.It Pa /etc/ssh/ssh_host_key, /etc/ssh/ssh_host_dsa_key, /etc/ssh/ssh_host_rsa_key
928These three files contain the private parts of the host keys
929and are used for
930.Cm RhostsRSAAuthentication
931and
932.Cm HostbasedAuthentication .
933If the protocol version 1
934.Cm RhostsRSAAuthentication
935method is used,
936.Nm
937must be setuid root, since the host key is readable only by root.
938For protocol version 2,
939.Nm
940uses
941.Xr ssh-keysign 8
942to access the host keys for
943.Cm HostbasedAuthentication .
944This eliminates the requirement that
945.Nm
946be setuid root when that authentication method is used.
947By default
948.Nm
949is not setuid root.
950.It Pa $HOME/.rhosts
951This file is used in
952.Em rhosts
953authentication to list the
954host/user pairs that are permitted to log in.
955(Note that this file is
956also used by rlogin and rsh, which makes using this file insecure.)
957Each line of the file contains a host name (in the canonical form
958returned by name servers), and then a user name on that host,
959separated by a space.
960On some machines this file may need to be
961world-readable if the user's home directory is on a NFS partition,
962because
963.Xr sshd 8
964reads it as root.
965Additionally, this file must be owned by the user,
966and must not have write permissions for anyone else.
967The recommended
968permission for most machines is read/write for the user, and not
969accessible by others.
970.Pp
971Note that by default
972.Xr sshd 8
973will be installed so that it requires successful RSA host
974authentication before permitting
975.Em rhosts
976authentication.
977If the server machine does not have the client's host key in
978.Pa /etc/ssh/ssh_known_hosts ,
979it can be stored in
980.Pa $HOME/.ssh/known_hosts .
981The easiest way to do this is to
982connect back to the client from the server machine using ssh; this
983will automatically add the host key to
984.Pa $HOME/.ssh/known_hosts .
985.It Pa $HOME/.shosts
986This file is used exactly the same way as
987.Pa .rhosts .
988The purpose for
989having this file is to be able to use rhosts authentication with
990.Nm
991without permitting login with
992.Xr rlogin
993or
994.Xr rsh 1 .
995.It Pa /etc/hosts.equiv
996This file is used during
997.Em rhosts
998authentication.
999It contains
1000canonical hosts names, one per line (the full format is described in the
1001.Xr sshd 8
1002manual page).
1003If the client host is found in this file, login is
1004automatically permitted provided client and server user names are the
1005same.
1006Additionally, successful RSA host authentication is normally
1007required.
1008This file should only be writable by root.
1009.It Pa /etc/ssh/shosts.equiv
1010This file is processed exactly as
1011.Pa /etc/hosts.equiv .
1012This file may be useful to permit logins using
1013.Nm
1014but not using rsh/rlogin.
1015.It Pa /etc/ssh/sshrc
1016Commands in this file are executed by
1017.Nm
1018when the user logs in just before the user's shell (or command) is started.
1019See the
1020.Xr sshd 8
1021manual page for more information.
1022.It Pa $HOME/.ssh/rc
1023Commands in this file are executed by
1024.Nm
1025when the user logs in just before the user's shell (or command) is
1026started.
1027See the
1028.Xr sshd 8
1029manual page for more information.
1030.It Pa $HOME/.ssh/environment
1031Contains additional definitions for environment variables, see section
1032.Sx ENVIRONMENT
1033above.
1034.El
1035.Sh DIAGNOSTICS
1036.Nm
1037exits with the exit status of the remote command or with 255
1038if an error occurred.
1039.Sh SEE ALSO
1040.Xr gzip 1 ,
1041.Xr rsh 1 ,
1042.Xr scp 1 ,
1043.Xr sftp 1 ,
1044.Xr ssh-add 1 ,
1045.Xr ssh-agent 1 ,
1046.Xr ssh-keygen 1 ,
1047.Xr telnet 1 ,
1048.Xr hosts.equiv 5 ,
1049.Xr ssh_config 5 ,
1050.Xr ssh-keysign 8 ,
1051.Xr sshd 8
1052.Rs
1053.%A T. Ylonen
1054.%A T. Kivinen
1055.%A M. Saarinen
1056.%A T. Rinne
1057.%A S. Lehtinen
1058.%T "SSH Protocol Architecture"
1059.%N draft-ietf-secsh-architecture-12.txt
1060.%D January 2002
1061.%O work in progress material
1062.Re
1063.Sh AUTHORS
1064OpenSSH is a derivative of the original and free
1065ssh 1.2.12 release by Tatu Ylonen.
1066Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
1067Theo de Raadt and Dug Song
1068removed many bugs, re-added newer features and
1069created OpenSSH.
1070Markus Friedl contributed the support for SSH
1071protocol versions 1.5 and 2.0.
|