blob: fb50444821a1976b2e96e89571603bbfee6273fc [file] [log] [blame]
Damien Miller32aa1441999-10-29 09:15:49 +10001.\" -*- nroff -*-
2.\"
3.\" ssh.1.in
4.\"
5.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
6.\"
7.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
8.\" All rights reserved
9.\"
10.\" Created: Sat Apr 22 21:55:14 1995 ylo
11.\"
Damien Milleraae6c611999-12-06 11:47:28 +110012.\" $Id: ssh.1,v 1.11 1999/12/06 00:47:29 damien Exp $
Damien Miller32aa1441999-10-29 09:15:49 +100013.\"
14.Dd September 25, 1999
15.Dt SSH 1
16.Os
17.Sh NAME
18.Nm ssh
19.Nd OpenSSH secure shell client (remote login program)
20.Sh SYNOPSIS
21.Nm ssh
22.Op Fl l Ar login_name
23.Op Ar hostname | user@hostname
24.Op Ar command
25.Pp
26.Nm ssh
27.Op Fl afgknqtvxCPX
28.Op Fl c Ar blowfish | 3des
29.Op Fl e Ar escape_char
30.Op Fl i Ar identity_file
31.Op Fl l Ar login_name
32.Op Fl o Ar option
33.Op Fl p Ar port
34.Oo Fl L Xo
35.Sm off
36.Ar host :
37.Ar port :
38.Ar hostport
39.Sm on
40.Xc
41.Oc
42.Oo Fl R Xo
43.Sm off
44.Ar host :
45.Ar port :
46.Ar hostport
47.Sm on
48.Xc
49.Oc
50.Op Ar hostname | user@hostname
51.Op Ar command
52.Sh DESCRIPTION
53.Nm
54(Secure Shell) is a program for logging into a remote machine and for
55executing commands on a remote machine. It is intended to replace
56rlogin and rsh, and provide secure encrypted communications between
57two untrusted hosts over an insecure network. X11 connections and
58arbitrary TCP/IP ports can also be forwarded over the secure channel.
59.Pp
60.Nm
61connects and logs into the specified
62.Ar hostname .
63The user must prove
64his/her identity to the remote machine using one of several methods.
65.Pp
66First, if the machine the user logs in from is listed in
67.Pa /etc/hosts.equiv
68or
Damien Millerf1d9a301999-10-29 09:17:36 +100069.Pa /etc/ssh/shosts.equiv
Damien Miller32aa1441999-10-29 09:15:49 +100070on the remote machine, and the user names are
71the same on both sides, the user is immediately permitted to log in.
72Second, if
73.Pa \&.rhosts
74or
75.Pa \&.shosts
76exists in the user's home directory on the
77remote machine and contains a line containing the name of the client
78machine and the name of the user on that machine, the user is
79permitted to log in. This form of authentication alone is normally not
80allowed by the server because it is not secure.
81.Pp
82The second (and primary) authentication method is the
83.Pa rhosts
84or
85.Pa hosts.equiv
86method combined with RSA-based host authentication. It
87means that if the login would be permitted by
88.Pa \&.rhosts ,
89.Pa \&.shosts ,
90.Pa /etc/hosts.equiv ,
91or
Damien Millerf1d9a301999-10-29 09:17:36 +100092.Pa /etc/ssh/shosts.equiv ,
Damien Miller32aa1441999-10-29 09:15:49 +100093and if additionally the server can verify the client's
94host key (see
Damien Millerf1d9a301999-10-29 09:17:36 +100095.Pa /etc/ssh/ssh_known_hosts
Damien Miller33e511e1999-11-11 11:43:13 +110096and
97.Pa $HOME/.ssh/known_hosts
Damien Miller32aa1441999-10-29 09:15:49 +100098in the
99.Sx FILES
100section), only then login is
101permitted. This authentication method closes security holes due to IP
102spoofing, DNS spoofing and routing spoofing. [Note to the
103administrator:
104.Pa /etc/hosts.equiv ,
105.Pa \&.rhosts ,
106and the rlogin/rsh protocol in general, are inherently insecure and should be
107disabled if security is desired.]
108.Pp
109As a third authentication method,
110.Nm
111supports RSA based authentication.
112The scheme is based on public-key cryptography: there are cryptosystems
113where encryption and decryption are done using separate keys, and it
114is not possible to derive the decryption key from the encryption key.
115RSA is one such system. The idea is that each user creates a public/private
116key pair for authentication purposes. The
117server knows the public key, and only the user knows the private key.
118The file
119.Pa $HOME/.ssh/authorized_keys
120lists the public keys that are permitted for logging
121in. When the user logs in, the
122.Nm
123program tells the server which key pair it would like to use for
124authentication. The server checks if this key is permitted, and if
125so, sends the user (actually the
126.Nm
127program running on behalf of the user) a challenge, a random number,
128encrypted by the user's public key. The challenge can only be
129decrypted using the proper private key. The user's client then decrypts the
130challenge using the private key, proving that he/she knows the private
131key but without disclosing it to the server.
132.Pp
133.Nm
134implements the RSA authentication protocol automatically. The user
135creates his/her RSA key pair by running
136.Xr ssh-keygen 1 .
137This stores the private key in
138.Pa \&.ssh/identity
139and the public key in
140.Pa \&.ssh/identity.pub
141in the user's home directory. The user should then
142copy the
143.Pa identity.pub
144to
145.Pa \&.ssh/authorized_keys
146in his/her home directory on the remote machine (the
147.Pa authorized_keys
148file corresponds to the conventional
149.Pa \&.rhosts
150file, and has one key
151per line, though the lines can be very long). After this, the user
152can log in without giving the password. RSA authentication is much
153more secure than rhosts authentication.
154.Pp
155The most convenient way to use RSA authentication may be with an
156authentication agent. See
157.Xr ssh-agent 1
158for more information.
159.Pp
160If other authentication methods fail,
161.Nm
162prompts the user for a password. The password is sent to the remote
163host for checking; however, since all communications are encrypted,
164the password cannot be seen by someone listening on the network.
165.Pp
166When the user's identity has been accepted by the server, the server
167either executes the given command, or logs into the machine and gives
168the user a normal shell on the remote machine. All communication with
169the remote command or shell will be automatically encrypted.
170.Pp
171If a pseudo-terminal has been allocated (normal login session), the
172user can disconnect with
173.Ic ~. ,
174and suspend
175.Nm
176with
177.Ic ~^Z .
178All forwarded connections can be listed with
179.Ic ~#
180and if
181the session blocks waiting for forwarded X11 or TCP/IP
182connections to terminate, it can be backgrounded with
183.Ic ~&
184(this should not be used while the user shell is active, as it can cause the
185shell to hang). All available escapes can be listed with
186.Ic ~? .
187.Pp
188A single tilde character can be sent as
189.Ic ~~
190(or by following the tilde by a character other than those described above).
191The escape character must always follow a newline to be interpreted as
192special. The escape character can be changed in configuration files
193or on the command line.
194.Pp
195If no pseudo tty has been allocated, the
196session is transparent and can be used to reliably transfer binary
197data. On most systems, setting the escape character to
198.Dq none
199will also make the session transparent even if a tty is used.
200.Pp
201The session terminates when the command or shell in on the remote
202machine exists and all X11 and TCP/IP connections have been closed.
203The exit status of the remote program is returned as the exit status
204of
205.Nm ssh .
206.Pp
207If the user is using X11 (the
208.Ev DISPLAY
209environment variable is set), the connection to the X11 display is
210automatically forwarded to the remote side in such a way that any X11
211programs started from the shell (or command) will go through the
212encrypted channel, and the connection to the real X server will be made
213from the local machine. The user should not manually set
214.Ev DISPLAY .
215Forwarding of X11 connections can be
216configured on the command line or in configuration files.
217.Pp
218The
219.Ev DISPLAY
220value set by
221.Nm
222will point to the server machine, but with a display number greater
223than zero. This is normal, and happens because
224.Nm
225creates a
226.Dq proxy
227X server on the server machine for forwarding the
228connections over the encrypted channel.
229.Pp
230.Nm
231will also automatically set up Xauthority data on the server machine.
232For this purpose, it will generate a random authorization cookie,
233store it in Xauthority on the server, and verify that any forwarded
234connections carry this cookie and replace it by the real cookie when
235the connection is opened. The real authentication cookie is never
236sent to the server machine (and no cookies are sent in the plain).
237.Pp
238If the user is using an authentication agent, the connection to the agent
239is automatically forwarded to the remote side unless disabled on
240command line or in a configuration file.
241.Pp
242Forwarding of arbitrary TCP/IP connections over the secure channel can
243be specified either on command line or in a configuration file. One
244possible application of TCP/IP forwarding is a secure connection to an
245electronic purse; another is going trough firewalls.
246.Pp
247.Nm
248automatically maintains and checks a database containing RSA-based
249identifications for all hosts it has ever been used with. The
250database is stored in
251.Pa \&.ssh/known_hosts
252in the user's home directory. Additionally, the file
Damien Millerf1d9a301999-10-29 09:17:36 +1000253.Pa /etc/ssh/ssh_known_hosts
Damien Miller32aa1441999-10-29 09:15:49 +1000254is automatically checked for known hosts. Any new hosts are
255automatically added to the user's file. If a host's identification
256ever changes,
257.Nm
258warns about this and disables password authentication to prevent a
259trojan horse from getting the user's password. Another purpose of
260this mechanism is to prevent man-in-the-middle attacks which could
261otherwise be used to circumvent the encryption. The
262.Cm StrictHostKeyChecking
263option (see below) can be used to prevent logins to machines whose
264host key is not known or has changed.
265.Sh OPTIONS
266.Bl -tag -width Ds
267.It Fl a
268Disables forwarding of the authentication agent connection. This may
269also be specified on a per-host basis in the configuration file.
270.It Fl c Ar blowfish|3des
271Selects the cipher to use for encrypting the session.
272.Ar 3des
273is used by default. It is believed to be secure.
274.Ar 3des
275(triple-des) is an encrypt-decrypt-encrypt triple with three different keys.
276It is presumably more secure than the
277.Ar des
278cipher which is no longer supported in ssh.
279.Ar blowfish
280is a fast block cipher, it appears very secure and is much faster than
281.Ar 3des .
282.It Fl e Ar ch|^ch|none
283Sets the escape character for sessions with a pty (default:
284.Ql ~ ) .
285The escape character is only recognized at the beginning of a line. The
286escape character followed by a dot
287.Pq Ql \&.
288closes the connection, followed
289by control-Z suspends the connection, and followed by itself sends the
290escape character once. Setting the character to
291.Dq none
292disables any escapes and makes the session fully transparent.
293.It Fl f
294Requests
295.Nm
Damien Miller5428f641999-11-25 11:54:57 +1100296to go to background just before command execution. This is useful
Damien Miller32aa1441999-10-29 09:15:49 +1000297if
298.Nm
299is going to ask for passwords or passphrases, but the user
300wants it in the background. This implies
301.Fl n .
302The recommended way to start X11 programs at a remote site is with
303something like
304.Ic ssh -f host xterm .
305.It Fl i Ar identity_file
306Selects the file from which the identity (private key) for
307RSA authentication is read. Default is
308.Pa \&.ssh/identity
309in the user's home directory. Identity files may also be specified on
310a per-host basis in the configuration file. It is possible to have
311multiple
312.Fl i
313options (and multiple identities specified in
314configuration files).
315.It Fl g
316Allows remote hosts to connect to local forwarded ports.
317.It Fl k
318Disables forwarding of Kerberos tickets and AFS tokens. This may
319also be specified on a per-host basis in the configuration file.
320.It Fl l Ar login_name
321Specifies the user to log in as on the remote machine. This may also
322be specified on a per-host basis in the configuration file.
323.It Fl n
324Redirects stdin from
325.Pa /dev/null
326(actually, prevents reading from stdin).
327This must be used when
328.Nm
329is run in the background. A common trick is to use this to run X11
330programs in a remote machine. For example,
331.Ic ssh -n shadows.cs.hut.fi emacs &
332will start an emacs on shadows.cs.hut.fi, and the X11
333connection will be automatically forwarded over an encrypted channel.
334The
335.Nm
336program will be put in the background.
337(This does not work if
338.Nm
339needs to ask for a password or passphrase; see also the
340.Fl f
341option.)
342.It Fl o Ar option
343Can be used to give options in the format used in the config file.
344This is useful for specifying options for which there is no separate
345command-line flag. The option has the same format as a line in the
346configuration file.
347.It Fl p Ar port
348Port to connect to on the remote host. This can be specified on a
349per-host basis in the configuration file.
350.It Fl P
351Use a non-privileged port for outgoing connections.
352This can be used if your firewall does
353not permit connections from privileged ports.
354Note that this option turns of
355.Cm RhostsAuthentication
356and
357.Cm RhostsRSAAuthentication .
358.It Fl q
359Quiet mode. Causes all warning and diagnostic messages to be
360suppressed. Only fatal errors are displayed.
361.It Fl t
362Force pseudo-tty allocation. This can be used to execute arbitary
363screen-based programs on a remote machine, which can be very useful
364e.g. when implementing menu services.
365.It Fl v
366Verbose mode. Causes
367.Nm
368to print debugging messages about its progress. This is helpful in
369debugging connection, authentication, and configuration problems.
370The verbose mode is also used to display
371.Xr skey 1
372challenges, if the user entered "s/key" as password.
373.It Fl x
374Disables X11 forwarding. This can also be specified on a per-host
375basis in a configuration file.
376.It Fl X
377Enables X11 forwarding.
378.It Fl C
379Requests compression of all data (including stdin, stdout, stderr, and
380data for forwarded X11 and TCP/IP connections). The compression
381algorithm is the same used by gzip, and the
382.Dq level
383can be controlled by the
384.Cm CompressionLevel
385option (see below). Compression is desirable on modem lines and other
386slow connections, but will only slow down things on fast networks.
387The default value can be set on a host-by-host basis in the
388configuration files; see the
389.Cm Compress
390option below.
391.It Fl L Ar port:host:hostport
392Specifies that the given port on the local (client) host is to be
393forwarded to the given host and port on the remote side. This works
394by allocating a socket to listen to
395.Ar port
396on the local side, and whenever a connection is made to this port, the
397connection is forwarded over the secure channel, and a connection is
398made to
399.Ar host:hostport
400from the remote machine. Port forwardings can also be specified in the
401configuration file. Only root can forward privileged ports.
402.It Fl R Ar port:host:hostport
403Specifies that the given port on the remote (server) host is to be
404forwarded to the given host and port on the local side. This works
405by allocating a socket to listen to
406.Ar port
407on the remote side, and whenever a connection is made to this port, the
408connection is forwarded over the secure channel, and a connection is
409made to
410.Ar host:hostport
411from the local machine. Port forwardings can also be specified in the
412configuration file. Privileged ports can be forwarded only when
413logging in as root on the remote machine.
414.El
415.Sh CONFIGURATION FILES
416.Nm
417obtains configuration data from the following sources (in this order):
418command line options, user's configuration file
419.Pq Pa $HOME/.ssh/config ,
420and system-wide configuration file
Damien Millerf1d9a301999-10-29 09:17:36 +1000421.Pq Pa /etc/ssh/ssh_config .
Damien Miller32aa1441999-10-29 09:15:49 +1000422For each parameter, the first obtained value
423will be used. The configuration files contain sections bracketed by
424"Host" specifications, and that section is only applied for hosts that
425match one of the patterns given in the specification. The matched
426host name is the one given on the command line.
427.Pp
428Since the first obtained value for each parameter is used, more
429host-specific declarations should be given near the beginning of the
430file, and general defaults at the end.
431.Pp
432The configuration file has the following format:
433.Pp
434Empty lines and lines starting with
435.Ql #
436are comments.
437.Pp
438Otherwise a line is of the format
439.Dq keyword arguments .
440The possible
441keywords and their meanings are as follows (note that the
442configuration files are case-sensitive):
443.Bl -tag -width Ds
444.It Cm Host
445Restricts the following declarations (up to the next
446.Cm Host
447keyword) to be only for those hosts that match one of the patterns
448given after the keyword.
449.Ql \&*
450and
451.Ql ?
452can be used as wildcards in the
453patterns. A single
454.Ql \&*
455as a pattern can be used to provide global
456defaults for all hosts. The host is the
457.Ar hostname
458argument given on the command line (i.e., the name is not converted to
459a canonicalized host name before matching).
460.It Cm AFSTokenPassing
461Specifies whether to pass AFS tokens to remote host. The argument to
462this keyword must be
463.Dq yes
464or
465.Dq no .
466.It Cm BatchMode
467If set to
468.Dq yes ,
469passphrase/password querying will be disabled. This
470option is useful in scripts and other batch jobs where you have no
471user to supply the password. The argument must be
472.Dq yes
473or
474.Dq no .
475.It Cm Cipher
476Specifies the cipher to use for encrypting the session. Currently,
477.Dq blowfish ,
478and
479.Dq 3des
480are supported. The default is
481.Dq 3des .
482.It Cm Compression
483Specifies whether to use compression. The argument must be
484.Dq yes
485or
486.Dq no .
487.It Cm CompressionLevel
488Specifies the compression level to use if compression is enable. The
489argument must be an integer from 1 (fast) to 9 (slow, best). The
490default level is 6, which is good for most applications. The meaning
491of the values is the same as in GNU GZIP.
492.It Cm ConnectionAttempts
493Specifies the number of tries (one per second) to make before falling
494back to rsh or exiting. The argument must be an integer. This may be
495useful in scripts if the connection sometimes fails.
496.It Cm EscapeChar
497Sets the escape character (default:
498.Ql ~ ) .
499The escape character can also
500be set on the command line. The argument should be a single
501character,
502.Ql ^
503followed by a letter, or
504.Dq none
505to disable the escape
506character entirely (making the connection transparent for binary
507data).
508.It Cm FallBackToRsh
509Specifies that if connecting via
510.Nm
511fails due to a connection refused error (there is no
512.Xr sshd 8
513listening on the remote host),
514.Xr rsh 1
515should automatically be used instead (after a suitable warning about
516the session being unencrypted). The argument must be
517.Dq yes
518or
519.Dq no .
520.It Cm ForwardAgent
521Specifies whether the connection to the authentication agent (if any)
522will be forwarded to the remote machine. The argument must be
523.Dq yes
524or
525.Dq no .
526.It Cm ForwardX11
527Specifies whether X11 connections will be automatically redirected
528over the secure channel and
529.Ev DISPLAY
530set. The argument must be
531.Dq yes
532or
533.Dq no .
534.It Cm GatewayPorts
535Specifies whether remote hosts are allowed to connect to local
536forwarded ports.
537The argument must be
538.Dq yes
539or
540.Dq no .
541The default is
542.Dq no .
543.It Cm GlobalKnownHostsFile
544Specifies a file to use instead of
Damien Millerf1d9a301999-10-29 09:17:36 +1000545.Pa /etc/ssh/ssh_known_hosts .
Damien Miller32aa1441999-10-29 09:15:49 +1000546.It Cm HostName
547Specifies the real host name to log into. This can be used to specify
548nicnames or abbreviations for hosts. Default is the name given on the
549command line. Numeric IP addresses are also permitted (both on the
550command line and in
551.Cm HostName
552specifications).
553.It Cm IdentityFile
554Specifies the file from which the user's RSA authentication identity
555is read (default
556.Pa .ssh/identity
557in the user's home directory).
558Additionally, any identities represented by the authentication agent
559will be used for authentication. The file name may use the tilde
560syntax to refer to a user's home directory. It is possible to have
561multiple identity files specified in configuration files; all these
562identities will be tried in sequence.
563.It Cm KeepAlive
564Specifies whether the system should send keepalive messages to the
565other side. If they are sent, death of the connection or crash of one
566of the machines will be properly noticed. However, this means that
567connections will die if the route is down temporarily, and some people
568find it annoying.
569.Pp
570The default is
571.Dq yes
572(to send keepalives), and the client will notice
573if the network goes down or the remote host dies. This is important
574in scripts, and many users want it too.
575.Pp
576To disable keepalives, the value should be set to
577.Dq no
578in both the server and the client configuration files.
579.It Cm KerberosAuthentication
580Specifies whether Kerberos authentication will be used. The argument to
581this keyword must be
582.Dq yes
583or
584.Dq no .
585.It Cm KerberosTgtPassing
586Specifies whether a Kerberos TGT will be forwarded to the server. This
587will only work if the Kerberos server is actually an AFS kaserver. The
588argument to this keyword must be
589.Dq yes
590or
591.Dq no .
592.It Cm LocalForward
593Specifies that a TCP/IP port on the local machine be forwarded over
594the secure channel to given host:port from the remote machine. The
595first argument must be a port number, and the second must be
596host:port. Multiple forwardings may be specified, and additional
597forwardings can be given on the command line. Only the root can
598forward privileged ports.
599.It Cm PasswordAuthentication
600Specifies whether to use password authentication. The argument to
601this keyword must be
602.Dq yes
603or
604.Dq no .
Damien Miller5ce662a1999-11-11 17:57:39 +1100605.It Cm LogLevel
606Gives the verbosity level that is used when logging messages from
607.Nm ssh .
608The possible values are:
609QUIET, FATAL, ERROR, INFO, CHAT and DEBUG.
610The default is INFO.
Damien Miller32aa1441999-10-29 09:15:49 +1000611.It Cm NumberOfPasswordPrompts
612Specifies the number of password prompts before giving up. The
613argument to this keyword must be an integer. Default is 3.
614.It Cm Port
615Specifies the port number to connect on the remote host. Default is
61622.
617.It Cm ProxyCommand
618Specifies the command to use to connect to the server. The command
619string extends to the end of the line, and is executed with /bin/sh.
620In the command string, %h will be substituted by the host name to
621connect and %p by the port. The command can be basically anything,
622and should read from its stdin and write to its stdout. It should
623eventually connect an
624.Xr sshd 8
625server running on some machine, or execute
626.Ic sshd -i
627somewhere. Host key management will be done using the
628HostName of the host being connected (defaulting to the name typed by
629the user).
Damien Milleraae6c611999-12-06 11:47:28 +1100630Note that
631.Cm CheckHostIP
632is not available for connects with a proxy command.
Damien Miller32aa1441999-10-29 09:15:49 +1000633.Pp
634.It Cm RemoteForward
635Specifies that a TCP/IP port on the remote machine be forwarded over
636the secure channel to given host:port from the local machine. The
637first argument must be a port number, and the second must be
638host:port. Multiple forwardings may be specified, and additional
639forwardings can be given on the command line. Only the root can
640forward privileged ports.
641.It Cm RhostsAuthentication
642Specifies whether to try rhosts based authentication. Note that this
643declaration only affects the client side and has no effect whatsoever
644on security. Disabling rhosts authentication may reduce
645authentication time on slow connections when rhosts authentication is
646not used. Most servers do not permit RhostsAuthentication because it
647is not secure (see RhostsRSAAuthentication). The argument to this
648keyword must be
649.Dq yes
650or
651.Dq no .
652.It Cm RhostsRSAAuthentication
653Specifies whether to try rhosts based authentication with RSA host
654authentication. This is the primary authentication method for most
655sites. The argument must be
656.Dq yes
657or
658.Dq no .
659.It Cm RSAAuthentication
660Specifies whether to try RSA authentication. The argument to this
661keyword must be
662.Dq yes
663or
664.Dq no .
665RSA authentication will only be
666attempted if the identity file exists, or an authentication agent is
667running.
Damien Miller95def091999-11-25 00:26:21 +1100668.It Cm SkeyAuthentication
669Specifies whether to use
670.Xr skey 1
671authentication. The argument to
672this keyword must be
673.Dq yes
674or
675.Dq no .
676The default is
677.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000678.It Cm CheckHostIP
679If this flag is set to
680.Dq yes ,
681ssh will additionally check the host ip address in the
682.Pa known_hosts
683file. This allows ssh to detect if a host key changed due to DNS spoofing.
684If the option is set to
685.Dq no ,
686the check will not be executed.
687.It Cm StrictHostKeyChecking
688If this flag is set to
689.Dq yes ,
690.Nm
691ssh will never automatically add host keys to the
692.Pa $HOME/.ssh/known_hosts
693file, and refuses to connect hosts whose host key has changed. This
694provides maximum protection against trojan horse attacks. However, it
695can be somewhat annoying if you don't have good
Damien Millerf1d9a301999-10-29 09:17:36 +1000696.Pa /etc/ssh/ssh_known_hosts
Damien Miller32aa1441999-10-29 09:15:49 +1000697files installed and frequently
698connect new hosts. Basically this option forces the user to manually
699add any new hosts. Normally this option is disabled, and new hosts
700will automatically be added to the known host files. The host keys of
701known hosts will be verified automatically in either case. The
702argument must be
703.Dq yes
704or
705.Dq no .
706.It Cm User
707Specifies the user to log in as. This can be useful if you have a
708different user name in different machines. This saves the trouble of
709having to remember to give the user name on the command line.
710.It Cm UserKnownHostsFile
711Specifies a file to use instead of
712.Pa $HOME/.ssh/known_hosts .
713.It Cm UsePrivilegedPort
714Specifies whether to use a privileged port for outgoing connections.
715The argument must be
716.Dq yes
717or
718.Dq no .
719The default is
720.Dq yes .
721Note that setting this option to
722.Dq no
723turns of
724.Cm RhostsAuthentication
725and
726.Cm RhostsRSAAuthentication .
727.It Cm UseRsh
728Specifies that rlogin/rsh should be used for this host. It is
729possible that the host does not at all support the
730.Nm
731protocol. This causes
732.Nm
733to immediately exec
734.Xr rsh 1 .
735All other options (except
736.Cm HostName )
737are ignored if this has been specified. The argument must be
738.Dq yes
739or
740.Dq no .
741.Sh ENVIRONMENT
742.Nm
743will normally set the following environment variables:
744.Bl -tag -width Ds
745.It Ev DISPLAY
746The
747.Ev DISPLAY
748variable indicates the location of the X11 server. It is
749automatically set by
750.Nm
751to point to a value of the form
752.Dq hostname:n
753where hostname indicates
754the host where the shell runs, and n is an integer >= 1. Ssh uses
755this special value to forward X11 connections over the secure
756channel. The user should normally not set DISPLAY explicitly, as that
757will render the X11 connection insecure (and will require the user to
758manually copy any required authorization cookies).
759.It Ev HOME
760Set to the path of the user's home directory.
761.It Ev LOGNAME
762Synonym for
763.Ev USER ;
764set for compatibility with systems that use this variable.
765.It Ev MAIL
766Set to point the user's mailbox.
767.It Ev PATH
768Set to the default
769.Ev PATH ,
770as specified when compiling
771.Nm ssh .
772.It Ev SSH_AUTH_SOCK
773indicates the path of a unix-domain socket used to communicate with the
774agent.
775.It Ev SSH_CLIENT
776Identifies the client end of the connection. The variable contains
777three space-separated values: client ip-address, client port number,
778and server port number.
779.It Ev SSH_TTY
780This is set to the name of the tty (path to the device) associated
781with the current shell or command. If the current session has no tty,
782this variable is not set.
783.It Ev TZ
784The timezone variable is set to indicate the present timezone if it
785was set when the daemon was started (e.i., the daemon passes the value
786on to new connections).
787.It Ev USER
788Set to the name of the user logging in.
789.El
790.Pp
791Additionally,
792.Nm
793reads
794.Pa $HOME/.ssh/environment ,
795and adds lines of the format
796.Dq VARNAME=value
797to the environment.
798.Sh FILES
799.Bl -tag -width $HOME/.ssh/known_hosts
800.It Pa $HOME/.ssh/known_hosts
801Records host keys for all hosts the user has logged into (that are not
802in
Damien Millerf1d9a301999-10-29 09:17:36 +1000803.Pa /etc/ssh/ssh_known_hosts ) .
Damien Miller32aa1441999-10-29 09:15:49 +1000804See
805.Xr sshd 8 .
806.It Pa $HOME/.ssh/random_seed
807Used for seeding the random number generator. This file contains
808sensitive data and should read/write for the user and not accessible
809for others. This file is created the first time the program is run
810and updated automatically. The user should never need to read or
811modify this file.
812.It Pa $HOME/.ssh/identity
813Contains the RSA authentication identity of the user. This file
814contains sensitive data and should be readable by the user but not
815accessible by others (read/write/execute).
816Note that
817.Nm
818ignores this file if it is accessible by others.
819It is possible to specify a passphrase when
820generating the key; the passphrase will be used to encrypt the
821sensitive part of this file using 3DES.
822.It Pa $HOME/.ssh/identity.pub
823Contains the public key for authentication (public part of the
824identity file in human-readable form). The contents of this file
825should be added to
826.Pa $HOME/.ssh/authorized_keys
827on all machines
828where you wish to log in using RSA authentication. This file is not
829sensitive and can (but need not) be readable by anyone. This file is
830never used automatically and is not necessary; it is only provided for
831the convenience of the user.
832.It Pa $HOME/.ssh/config
833This is the per-user configuration file. The format of this file is
834described above. This file is used by the
835.Nm
836client. This file does not usually contain any sensitive information,
837but the recommended permissions are read/write for the user, and not
838accessible by others.
839.It Pa $HOME/.ssh/authorized_keys
840Lists the RSA keys that can be used for logging in as this user. The
841format of this file is described in the
842.Xr sshd 8
843manual page. In the simplest form the format is the same as the .pub
844identity files (that is, each line contains the number of bits in
845modulus, public exponent, modulus, and comment fields, separated by
846spaces). This file is not highly sensitive, but the recommended
847permissions are read/write for the user, and not accessible by others.
Damien Millerf1d9a301999-10-29 09:17:36 +1000848.It Pa /etc/ssh/ssh_known_hosts
Damien Miller32aa1441999-10-29 09:15:49 +1000849Systemwide list of known host keys. This file should be prepared by the
850system administrator to contain the public host keys of all machines in the
851organization. This file should be world-readable. This file contains
852public keys, one per line, in the following format (fields separated
853by spaces): system name, number of bits in modulus, public exponent,
854modulus, and optional comment field. When different names are used
855for the same machine, all such names should be listed, separated by
856commas. The format is described on the
857.Xr sshd 8
858manual page.
859.Pp
860The canonical system name (as returned by name servers) is used by
861.Xr sshd 8
862to verify the client host when logging in; other names are needed because
863.Nm
864does not convert the user-supplied name to a canonical name before
865checking the key, because someone with access to the name servers
866would then be able to fool host authentication.
Damien Millerf1d9a301999-10-29 09:17:36 +1000867.It Pa /etc/ssh/ssh_config
Damien Miller32aa1441999-10-29 09:15:49 +1000868Systemwide configuration file. This file provides defaults for those
869values that are not specified in the user's configuration file, and
870for those users who do not have a configuration file. This file must
871be world-readable.
872.It Pa $HOME/.rhosts
873This file is used in
874.Pa \&.rhosts
875authentication to list the
876host/user pairs that are permitted to log in. (Note that this file is
877also used by rlogin and rsh, which makes using this file insecure.)
878Each line of the file contains a host name (in the canonical form
879returned by name servers), and then a user name on that host,
880separated by a space. One some machines this file may need to be
881world-readable if the user's home directory is on a NFS partition,
882because
883.Xr sshd 8
884reads it as root. Additionally, this file must be owned by the user,
885and must not have write permissions for anyone else. The recommended
886permission for most machines is read/write for the user, and not
887accessible by others.
888.Pp
889Note that by default
890.Xr sshd 8
891will be installed so that it requires successful RSA host
892authentication before permitting \s+2.\s0rhosts authentication. If your
893server machine does not have the client's host key in
Damien Millerf1d9a301999-10-29 09:17:36 +1000894.Pa /etc/ssh/ssh_known_hosts ,
Damien Miller32aa1441999-10-29 09:15:49 +1000895you can store it in
896.Pa $HOME/.ssh/known_hosts .
897The easiest way to do this is to
898connect back to the client from the server machine using ssh; this
899will automatically add the host key inxi
900.Pa $HOME/.ssh/known_hosts .
901.It Pa $HOME/.shosts
902This file is used exactly the same way as
903.Pa \&.rhosts .
904The purpose for
905having this file is to be able to use rhosts authentication with
906.Nm
907without permitting login with
908.Xr rlogin 1
909or
910.Xr rsh 1 .
911.It Pa /etc/hosts.equiv
912This file is used during
913.Pa \&.rhosts authentication. It contains
914canonical hosts names, one per line (the full format is described on
915the
916.Xr sshd 8
917manual page). If the client host is found in this file, login is
918automatically permitted provided client and server user names are the
919same. Additionally, successful RSA host authentication is normally
920required. This file should only be writable by root.
Damien Millerf1d9a301999-10-29 09:17:36 +1000921.It Pa /etc/ssh/shosts.equiv
Damien Miller32aa1441999-10-29 09:15:49 +1000922This file is processed exactly as
923.Pa /etc/hosts.equiv .
924This file may be useful to permit logins using
925.Nm
926but not using rsh/rlogin.
Damien Millerf1d9a301999-10-29 09:17:36 +1000927.It Pa /etc/ssh/sshrc
Damien Miller32aa1441999-10-29 09:15:49 +1000928Commands in this file are executed by
929.Nm
930when the user logs in just before the user's shell (or command) is started.
931See the
932.Xr sshd 8
933manual page for more information.
934.It Pa $HOME/.ssh/rc
935Commands in this file are executed by
936.Nm
937when the user logs in just before the user's shell (or command) is
938started.
939See the
940.Xr sshd 8
941manual page for more information.
942.It Pa libcrypto.so.X.1
943A version of this library which includes support for the RSA algorithm
944is required for proper operation.
945.Sh AUTHOR
946Tatu Ylonen <ylo@cs.hut.fi>
947.Pp
948Issues can be found from the SSH WWW home page:
949.Pp
950.Dl http://www.cs.hut.fi/ssh
951.Pp
952OpenSSH
953is a derivative of the original (free) ssh 1.2.12 release, but with bugs
954removed and newer features re-added. Rapidly after the 1.2.12 release,
955newer versions bore successively more restrictive licenses. This version
956of OpenSSH
957.Bl -bullet
958.It
959has all components of a restrictive nature (ie. patents, see
960.Xr ssl 8 )
961directly removed from the source code; any licensed or patented components
962are chosen from
963external libraries.
964.It
965has been updated to support ssh protocol 1.5.
966.It
967contains added support for
968.Xr kerberos 8
969authentication and ticket passing.
970.It
971supports one-time password authentication with
972.Xr skey 1 .
973.El
974.Pp
975The libraries described in
976.Xr ssl 8
977are required for proper operation.
Damien Miller10f6f6b1999-11-17 17:29:08 +1100978.Pp
Damien Miller6ee95641999-11-18 11:35:13 +1100979OpenSSH has been created by Aaron Campbell, Bob Beck, Markus Friedl,
Damien Miller10f6f6b1999-11-17 17:29:08 +1100980Niels Provos, Theo de Raadt, and Dug Song.
Damien Miller32aa1441999-10-29 09:15:49 +1000981.Sh SEE ALSO
982.Xr rlogin 1 ,
983.Xr rsh 1 ,
984.Xr scp 1 ,
985.Xr ssh-add 1 ,
986.Xr ssh-agent 1 ,
987.Xr ssh-keygen 1 ,
988.Xr telnet 1 ,
989.Xr sshd 8 ,
990.Xr ssl 8