blob: 0de3cef4ad5bded3d302f6f051d0e33680d167b8 [file] [log] [blame]
Damien Miller32aa1441999-10-29 09:15:49 +10001.\" -*- nroff -*-
2.\"
3.\" sshd.8.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 Millerb38eff82000-04-01 11:09:21 +100012.\" $Id: sshd.8,v 1.16 2000/04/01 01:09:27 damien Exp $
Damien Miller32aa1441999-10-29 09:15:49 +100013.\"
14.Dd September 25, 1999
15.Dt SSHD 8
16.Os
17.Sh NAME
18.Nm sshd
19.Nd secure shell daemon
20.Sh SYNOPSIS
21.Nm sshd
Damien Miller34132e52000-01-14 15:45:46 +110022.Op Fl diqQ46
Damien Miller32aa1441999-10-29 09:15:49 +100023.Op Fl b Ar bits
24.Op Fl f Ar config_file
25.Op Fl g Ar login_grace_time
26.Op Fl h Ar host_key_file
27.Op Fl k Ar key_gen_time
28.Op Fl p Ar port
Damien Miller95def091999-11-25 00:26:21 +110029.Op Fl V Ar client_protocol_id
Damien Miller32aa1441999-10-29 09:15:49 +100030.Sh DESCRIPTION
31.Nm
32(Secure Shell Daemon) is the daemon program for
33.Xr ssh 1 .
34Together these programs replace rlogin and rsh programs, and
35provide secure encrypted communications between two untrusted hosts
Damien Miller450a7a12000-03-26 13:04:51 +100036over an insecure network.
37The programs are intended to be as easy to
Damien Miller32aa1441999-10-29 09:15:49 +100038install and use as possible.
39.Pp
40.Nm
Damien Miller450a7a12000-03-26 13:04:51 +100041is the daemon that listens for connections from clients.
42It is normally started at boot from
Damien Miller32aa1441999-10-29 09:15:49 +100043.Pa /etc/rc .
44It forks a new
Damien Miller450a7a12000-03-26 13:04:51 +100045daemon for each incoming connection.
46The forked daemons handle
Damien Miller32aa1441999-10-29 09:15:49 +100047key exchange, encryption, authentication, command execution,
48and data exchange.
49.Pp
50.Nm
Damien Miller450a7a12000-03-26 13:04:51 +100051works as follows.
52Each host has a host-specific RSA key
53(normally 1024 bits) used to identify the host.
54Additionally, when
Damien Miller32aa1441999-10-29 09:15:49 +100055the daemon starts, it generates a server RSA key (normally 768 bits).
56This key is normally regenerated every hour if it has been used, and
57is never stored on disk.
58.Pp
59Whenever a client connects the daemon, the daemon sends its host
Damien Miller450a7a12000-03-26 13:04:51 +100060and server public keys to the client.
61The client compares the
Damien Miller32aa1441999-10-29 09:15:49 +100062host key against its own database to verify that it has not changed.
Damien Miller450a7a12000-03-26 13:04:51 +100063The client then generates a 256 bit random number.
64It encrypts this
Damien Miller32aa1441999-10-29 09:15:49 +100065random number using both the host key and the server key, and sends
Damien Miller450a7a12000-03-26 13:04:51 +100066the encrypted number to the server.
67Both sides then start to use this
Damien Miller32aa1441999-10-29 09:15:49 +100068random number as a session key which is used to encrypt all further
Damien Miller450a7a12000-03-26 13:04:51 +100069communications in the session.
70The rest of the session is encrypted
Damien Miller32aa1441999-10-29 09:15:49 +100071using a conventional cipher, currently Blowfish and 3DES, with 3DES
Damien Millerb38eff82000-04-01 11:09:21 +100072being used by default.
Damien Miller450a7a12000-03-26 13:04:51 +100073The client selects the encryption algorithm
Damien Miller32aa1441999-10-29 09:15:49 +100074to use from those offered by the server.
75.Pp
Damien Miller450a7a12000-03-26 13:04:51 +100076Next, the server and the client enter an authentication dialog.
77The client tries to authenticate itself using
Damien Miller32aa1441999-10-29 09:15:49 +100078.Pa .rhosts
79authentication,
80.Pa .rhosts
81authentication combined with RSA host
82authentication, RSA challenge-response authentication, or password
83based authentication.
84.Pp
85Rhosts authentication is normally disabled
86because it is fundamentally insecure, but can be enabled in the server
Damien Miller450a7a12000-03-26 13:04:51 +100087configuration file if desired.
88System security is not improved unless
Damien Miller32aa1441999-10-29 09:15:49 +100089.Xr rshd 8 ,
90.Xr rlogind 8 ,
91.Xr rexecd 8 ,
92and
93.Xr rexd 8
94are disabled (thus completely disabling
95.Xr rlogin 1
96and
97.Xr rsh 1
98into that machine).
99.Pp
100If the client successfully authenticates itself, a dialog for
Damien Miller450a7a12000-03-26 13:04:51 +1000101preparing the session is entered.
102At this time the client may request
Damien Miller32aa1441999-10-29 09:15:49 +1000103things like allocating a pseudo-tty, forwarding X11 connections,
104forwarding TCP/IP connections, or forwarding the authentication agent
105connection over the secure channel.
106.Pp
107Finally, the client either requests a shell or execution of a command.
Damien Miller450a7a12000-03-26 13:04:51 +1000108The sides then enter session mode.
109In this mode, either side may send
Damien Miller32aa1441999-10-29 09:15:49 +1000110data at any time, and such data is forwarded to/from the shell or
111command on the server side, and the user terminal in the client side.
112.Pp
113When the user program terminates and all forwarded X11 and other
114connections have been closed, the server sends command exit status to
115the client, and both sides exit.
116.Pp
117.Nm
118can be configured using command-line options or a configuration
Damien Miller450a7a12000-03-26 13:04:51 +1000119file.
120Command-line options override values specified in the
Damien Miller32aa1441999-10-29 09:15:49 +1000121configuration file.
122.Pp
Damien Miller6162d121999-11-21 13:23:52 +1100123.Nm
124rereads its configuration file when it receives a hangup signal,
125.Dv SIGHUP .
126.Pp
Damien Miller32aa1441999-10-29 09:15:49 +1000127The options are as follows:
128.Bl -tag -width Ds
129.It Fl b Ar bits
130Specifies the number of bits in the server key (default 768).
131.Pp
132.It Fl d
Damien Miller450a7a12000-03-26 13:04:51 +1000133Debug mode.
134The server sends verbose debug output to the system
135log, and does not put itself in the background.
136The server also will not fork and will only process one connection.
137This option is only intended for debugging for the server.
Damien Miller32aa1441999-10-29 09:15:49 +1000138.It Fl f Ar configuration_file
Damien Miller450a7a12000-03-26 13:04:51 +1000139Specifies the name of the configuration file.
140The default is
Damien Miller886c63a2000-01-20 23:13:36 +1100141.Pa /etc/sshd_config .
Damien Miller32aa1441999-10-29 09:15:49 +1000142.Nm
143refuses to start if there is no configuration file.
144.It Fl g Ar login_grace_time
145Gives the grace time for clients to authenticate themselves (default
Damien Miller450a7a12000-03-26 13:04:51 +1000146300 seconds).
147If the client fails to authenticate the user within
148this many seconds, the server disconnects and exits.
149A value of zero indicates no limit.
Damien Miller32aa1441999-10-29 09:15:49 +1000150.It Fl h Ar host_key_file
151Specifies the file from which the host key is read (default
Damien Miller886c63a2000-01-20 23:13:36 +1100152.Pa /etc/ssh_host_key ) .
Damien Miller32aa1441999-10-29 09:15:49 +1000153This option must be given if
154.Nm
155is not run as root (as the normal
156host file is normally not readable by anyone but root).
157.It Fl i
158Specifies that
159.Nm
160is being run from inetd.
161.Nm
162is normally not run
163from inetd because it needs to generate the server key before it can
Damien Miller450a7a12000-03-26 13:04:51 +1000164respond to the client, and this may take tens of seconds.
165Clients would have to wait too long if the key was regenerated every time.
Damien Miller7684ee12000-03-17 23:40:15 +1100166However, with small key sizes (e.g., 512) using
Damien Miller32aa1441999-10-29 09:15:49 +1000167.Nm
168from inetd may
169be feasible.
170.It Fl k Ar key_gen_time
171Specifies how often the server key is regenerated (default 3600
Damien Miller450a7a12000-03-26 13:04:51 +1000172seconds, or one hour).
173The motivation for regenerating the key fairly
Damien Miller32aa1441999-10-29 09:15:49 +1000174often is that the key is not stored anywhere, and after about an hour,
175it becomes impossible to recover the key for decrypting intercepted
176communications even if the machine is cracked into or physically
Damien Miller450a7a12000-03-26 13:04:51 +1000177seized.
178A value of zero indicates that the key will never be regenerated.
Damien Miller32aa1441999-10-29 09:15:49 +1000179.It Fl p Ar port
180Specifies the port on which the server listens for connections
181(default 22).
182.It Fl q
Damien Miller450a7a12000-03-26 13:04:51 +1000183Quiet mode.
184Nothing is sent to the system log.
185Normally the beginning,
Damien Miller32aa1441999-10-29 09:15:49 +1000186authentication, and termination of each connection is logged.
187.It Fl Q
188Do not print an error message if RSA support is missing.
Damien Miller95def091999-11-25 00:26:21 +1100189.It Fl V Ar client_protocol_id
190SSH2 compatibility mode.
191When this options is specified
192.Nm
193assumes the client has sent the given version string
194and skips the
195Protocol Version Identification Exchange.
Damien Miller34132e52000-01-14 15:45:46 +1100196.It Fl 4
197Forces
198.Nm
199to use IPv4 addresses only.
200.It Fl 6
201Forces
202.Nm
203to use IPv6 addresses only.
Damien Miller32aa1441999-10-29 09:15:49 +1000204.El
205.Sh CONFIGURATION FILE
206.Nm
207reads configuration data from
Damien Miller886c63a2000-01-20 23:13:36 +1100208.Pa /etc/sshd_config
Damien Miller32aa1441999-10-29 09:15:49 +1000209(or the file specified with
210.Fl f
Damien Miller450a7a12000-03-26 13:04:51 +1000211on the command line).
212The file contains keyword-value pairs, one per line.
213Lines starting with
Damien Miller32aa1441999-10-29 09:15:49 +1000214.Ql #
215and empty lines are interpreted as comments.
216.Pp
217The following keywords are possible.
218.Bl -tag -width Ds
219.It Cm AFSTokenPassing
Damien Miller450a7a12000-03-26 13:04:51 +1000220Specifies whether an AFS token may be forwarded to the server.
221Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000222.Dq yes .
223.It Cm AllowGroups
224This keyword can be followed by a number of group names, separated
Damien Miller450a7a12000-03-26 13:04:51 +1000225by spaces.
226If specified, login is allowed only for users whose primary
Damien Miller32aa1441999-10-29 09:15:49 +1000227group matches one of the patterns.
228.Ql \&*
229and
230.Ql ?
231can be used as
Damien Miller450a7a12000-03-26 13:04:51 +1000232wildcards in the patterns.
233Only group names are valid, a numerical group ID isn't recognized.
234By default login is allowed regardless of the primary group.
Damien Miller32aa1441999-10-29 09:15:49 +1000235.Pp
236.It Cm AllowUsers
237This keyword can be followed by a number of user names, separated
Damien Miller450a7a12000-03-26 13:04:51 +1000238by spaces.
239If specified, login is allowed only for users names that
Damien Miller32aa1441999-10-29 09:15:49 +1000240match one of the patterns.
241.Ql \&*
242and
243.Ql ?
244can be used as
Damien Miller450a7a12000-03-26 13:04:51 +1000245wildcards in the patterns.
246Only user names are valid, a numerical user ID isn't recognized.
247By default login is allowed regardless of the user name.
Damien Miller32aa1441999-10-29 09:15:49 +1000248.Pp
249.It Cm CheckMail
250Specifies whether
251.Nm
252should check for new mail for interactive logins.
253The default is
254.Dq no .
255.It Cm DenyGroups
256This keyword can be followed by a number of group names, separated
Damien Miller450a7a12000-03-26 13:04:51 +1000257by spaces.
258Users whose primary group matches one of the patterns
Damien Miller32aa1441999-10-29 09:15:49 +1000259aren't allowed to log in.
260.Ql \&*
261and
262.Ql ?
263can be used as
Damien Miller450a7a12000-03-26 13:04:51 +1000264wildcards in the patterns.
265Only group names are valid, a numerical group ID isn't recognized.
266By default login is allowed regardless of the primary group.
Damien Miller32aa1441999-10-29 09:15:49 +1000267.Pp
268.It Cm DenyUsers
269This keyword can be followed by a number of user names, separated
Damien Miller450a7a12000-03-26 13:04:51 +1000270by spaces.
271Login is disallowed for user names that match one of the patterns.
Damien Miller32aa1441999-10-29 09:15:49 +1000272.Ql \&*
273and
274.Ql ?
Damien Miller450a7a12000-03-26 13:04:51 +1000275can be used as wildcards in the patterns.
276Only user names are valid, a numerical user ID isn't recognized.
277By default login is allowed regardless of the user name.
Damien Miller32aa1441999-10-29 09:15:49 +1000278.It Cm HostKey
279Specifies the file containing the private host key (default
Damien Miller886c63a2000-01-20 23:13:36 +1100280.Pa /etc/ssh_host_key ) .
Damien Miller32aa1441999-10-29 09:15:49 +1000281Note that
282.Nm
283does not start if this file is group/world-accessible.
284.It Cm IgnoreRhosts
Damien Miller98c7ad62000-03-09 21:27:49 +1100285Specifies that
286.Pa .rhosts
287and
288.Pa .shosts
289files will not be used in authentication.
Damien Miller32aa1441999-10-29 09:15:49 +1000290.Pa /etc/hosts.equiv
291and
Damien Miller886c63a2000-01-20 23:13:36 +1100292.Pa /etc/shosts.equiv
Damien Miller450a7a12000-03-26 13:04:51 +1000293are still used.
294The default is
Damien Miller98c7ad62000-03-09 21:27:49 +1100295.Dq yes .
Damien Miller32265091999-11-12 11:33:04 +1100296.It Cm IgnoreUserKnownHosts
297Specifies whether
298.Nm
299should ignore the user's
300.Pa $HOME/.ssh/known_hosts
301during
302.Cm RhostsRSAAuthentication .
303The default is
304.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000305.It Cm KeepAlive
306Specifies whether the system should send keepalive messages to the
Damien Miller450a7a12000-03-26 13:04:51 +1000307other side.
308If they are sent, death of the connection or crash of one
309of the machines will be properly noticed.
310However, this means that
Damien Miller32aa1441999-10-29 09:15:49 +1000311connections will die if the route is down temporarily, and some people
Damien Miller450a7a12000-03-26 13:04:51 +1000312find it annoying.
313On the other hand, if keepalives are not send,
Damien Miller32aa1441999-10-29 09:15:49 +1000314sessions may hang indefinitely on the server, leaving
315.Dq ghost
316users and consuming server resources.
317.Pp
318The default is
319.Dq yes
320(to send keepalives), and the server will notice
Damien Miller450a7a12000-03-26 13:04:51 +1000321if the network goes down or the client host reboots.
322This avoids infinitely hanging sessions.
Damien Miller32aa1441999-10-29 09:15:49 +1000323.Pp
324To disable keepalives, the value should be set to
325.Dq no
326in both the server and the client configuration files.
327.It Cm KerberosAuthentication
Damien Miller450a7a12000-03-26 13:04:51 +1000328Specifies whether Kerberos authentication is allowed.
329This can be in the form of a Kerberos ticket, or if
Damien Miller32aa1441999-10-29 09:15:49 +1000330.Cm PasswordAuthentication
331is yes, the password provided by the user will be validated through
Damien Miller450a7a12000-03-26 13:04:51 +1000332the Kerberos KDC.
333Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000334.Dq yes .
335.It Cm KerberosOrLocalPasswd
336If set then if password authentication through Kerberos fails then
337the password will be validated via any additional local mechanism
338such as
339.Pa /etc/passwd
Damien Miller450a7a12000-03-26 13:04:51 +1000340or SecurID.
341Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000342.Dq yes .
343.It Cm KerberosTgtPassing
344Specifies whether a Kerberos TGT may be forwarded to the server.
345Default is
346.Dq no ,
347as this only works when the Kerberos KDC is actually an AFS kaserver.
348.It Cm KerberosTicketCleanup
349Specifies whether to automatically destroy the user's ticket cache
Damien Miller450a7a12000-03-26 13:04:51 +1000350file on logout.
351Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000352.Dq yes .
353.It Cm KeyRegenerationInterval
354The server key is automatically regenerated after this many seconds
Damien Miller450a7a12000-03-26 13:04:51 +1000355(if it has been used).
356The purpose of regeneration is to prevent
Damien Miller32aa1441999-10-29 09:15:49 +1000357decrypting captured sessions by later breaking into the machine and
Damien Miller450a7a12000-03-26 13:04:51 +1000358stealing the keys.
359The key is never stored anywhere.
360If the value is 0, the key is never regenerated.
361The default is 3600 (seconds).
Damien Miller32aa1441999-10-29 09:15:49 +1000362.It Cm ListenAddress
363Specifies what local address
364.Nm
365should listen on.
366The default is to listen to all local addresses.
Damien Miller34132e52000-01-14 15:45:46 +1100367Multiple options of this type are permitted.
368Additionally, the
369.Cm Ports
370options must precede this option.
Damien Miller32aa1441999-10-29 09:15:49 +1000371.It Cm LoginGraceTime
372The server disconnects after this time if the user has not
Damien Miller450a7a12000-03-26 13:04:51 +1000373successfully logged in.
374If the value is 0, there is no time limit.
Damien Miller32aa1441999-10-29 09:15:49 +1000375The default is 600 (seconds).
Damien Miller5ce662a1999-11-11 17:57:39 +1100376.It Cm LogLevel
377Gives the verbosity level that is used when logging messages from
378.Nm sshd .
379The possible values are:
Damien Miller95def091999-11-25 00:26:21 +1100380QUIET, FATAL, ERROR, INFO, VERBOSE and DEBUG.
Damien Miller5ce662a1999-11-11 17:57:39 +1100381The default is INFO.
382Logging with level DEBUG violates the privacy of users
383and is not recommended.
Damien Miller32aa1441999-10-29 09:15:49 +1000384.It Cm PasswordAuthentication
385Specifies whether password authentication is allowed.
386The default is
387.Dq yes .
388.It Cm PermitEmptyPasswords
389When password authentication is allowed, it specifies whether the
Damien Miller450a7a12000-03-26 13:04:51 +1000390server allows login to accounts with empty password strings.
391The default is
Damien Miller98c7ad62000-03-09 21:27:49 +1100392.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000393.It Cm PermitRootLogin
394Specifies whether the root can log in using
395.Xr ssh 1 .
396The argument must be
397.Dq yes ,
398.Dq without-password
399or
400.Dq no .
401The default is
402.Dq yes .
403If this options is set to
404.Dq without-password
405only password authentication is disabled for root.
406.Pp
407Root login with RSA authentication when the
408.Ar command
409option has been
410specified will be allowed regardless of the value of this setting
411(which may be useful for taking remote backups even if root login is
412normally not allowed).
413.It Cm Port
414Specifies the port number that
415.Nm
Damien Miller450a7a12000-03-26 13:04:51 +1000416listens on.
417The default is 22.
Damien Miller34132e52000-01-14 15:45:46 +1100418Multiple options of this type are permitted.
Damien Miller32aa1441999-10-29 09:15:49 +1000419.It Cm PrintMotd
420Specifies whether
421.Nm
422should print
423.Pa /etc/motd
Damien Miller450a7a12000-03-26 13:04:51 +1000424when a user logs in interactively.
425(On some systems it is also printed by the shell,
Damien Miller32aa1441999-10-29 09:15:49 +1000426.Pa /etc/profile ,
Damien Miller450a7a12000-03-26 13:04:51 +1000427or equivalent.)
428The default is
Damien Miller32aa1441999-10-29 09:15:49 +1000429.Dq yes .
Damien Miller32aa1441999-10-29 09:15:49 +1000430.It Cm RandomSeed
Damien Miller450a7a12000-03-26 13:04:51 +1000431Obsolete.
432Random number generation uses other techniques.
Damien Miller32aa1441999-10-29 09:15:49 +1000433.It Cm RhostsAuthentication
434Specifies whether authentication using rhosts or /etc/hosts.equiv
Damien Miller450a7a12000-03-26 13:04:51 +1000435files is sufficient.
436Normally, this method should not be permitted because it is insecure.
Damien Miller32aa1441999-10-29 09:15:49 +1000437.Cm RhostsRSAAuthentication
438should be used
439instead, because it performs RSA-based host authentication in addition
440to normal rhosts or /etc/hosts.equiv authentication.
441The default is
442.Dq no .
443.It Cm RhostsRSAAuthentication
444Specifies whether rhosts or /etc/hosts.equiv authentication together
Damien Miller450a7a12000-03-26 13:04:51 +1000445with successful RSA host authentication is allowed.
446The default is
Damien Miller98c7ad62000-03-09 21:27:49 +1100447.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000448.It Cm RSAAuthentication
Damien Miller450a7a12000-03-26 13:04:51 +1000449Specifies whether pure RSA authentication is allowed.
450The default is
Damien Miller32aa1441999-10-29 09:15:49 +1000451.Dq yes .
452.It Cm ServerKeyBits
Damien Miller450a7a12000-03-26 13:04:51 +1000453Defines the number of bits in the server key.
454The minimum value is 512, and the default is 768.
Damien Miller32aa1441999-10-29 09:15:49 +1000455.It Cm SkeyAuthentication
456Specifies whether
457.Xr skey 1
Damien Miller450a7a12000-03-26 13:04:51 +1000458authentication is allowed.
459The default is
Damien Miller32aa1441999-10-29 09:15:49 +1000460.Dq yes .
461Note that s/key authentication is enabled only if
462.Cm PasswordAuthentication
463is allowed, too.
464.It Cm StrictModes
465Specifies whether
466.Nm
467should check file modes and ownership of the
Damien Miller450a7a12000-03-26 13:04:51 +1000468user's files and home directory before accepting login.
469This is normally desirable because novices sometimes accidentally leave their
470directory or files world-writable.
471The default is
Damien Miller32aa1441999-10-29 09:15:49 +1000472.Dq yes .
473.It Cm SyslogFacility
474Gives the facility code that is used when logging messages from
475.Nm sshd .
476The possible values are: DAEMON, USER, AUTH, LOCAL0, LOCAL1, LOCAL2,
Damien Miller450a7a12000-03-26 13:04:51 +1000477LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7.
478The default is AUTH.
Damien Miller32aa1441999-10-29 09:15:49 +1000479.It Cm UseLogin
480Specifies whether
481.Xr login 1
Damien Miller450a7a12000-03-26 13:04:51 +1000482is used.
483The default is
Damien Miller32aa1441999-10-29 09:15:49 +1000484.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000485.It Cm X11DisplayOffset
486Specifies the first display number available for
487.Nm sshd Ns 's
Damien Miller450a7a12000-03-26 13:04:51 +1000488X11 forwarding.
489This prevents
Damien Miller32aa1441999-10-29 09:15:49 +1000490.Nm
491from interfering with real X11 servers.
Damien Miller98c7ad62000-03-09 21:27:49 +1100492The default is 10.
Damien Miller396691a2000-01-20 22:44:08 +1100493.It Cm X11Forwarding
Damien Miller450a7a12000-03-26 13:04:51 +1000494Specifies whether X11 forwarding is permitted.
495The default is
Damien Miller98c7ad62000-03-09 21:27:49 +1100496.Dq no .
Damien Miller396691a2000-01-20 22:44:08 +1100497Note that disabling X11 forwarding does not improve security in any
498way, as users can always install their own forwarders.
Damien Miller32aa1441999-10-29 09:15:49 +1000499.El
500.Sh LOGIN PROCESS
501When a user successfully logs in,
502.Nm
503does the following:
504.Bl -enum -offset indent
505.It
506If the login is on a tty, and no command has been specified,
507prints last login time and
508.Pa /etc/motd
509(unless prevented in the configuration file or by
510.Pa $HOME/.hushlogin ;
511see the
512.Sx FILES
513section).
514.It
515If the login is on a tty, records login time.
516.It
517Checks
518.Pa /etc/nologin ;
519if it exists, prints contents and quits
520(unless root).
521.It
522Changes to run with normal user privileges.
523.It
524Sets up basic environment.
525.It
526Reads
527.Pa $HOME/.ssh/environment
528if it exists.
529.It
530Changes to user's home directory.
531.It
532If
533.Pa $HOME/.ssh/rc
534exists, runs it; else if
Damien Miller886c63a2000-01-20 23:13:36 +1100535.Pa /etc/sshrc
Damien Miller32aa1441999-10-29 09:15:49 +1000536exists, runs
Damien Miller450a7a12000-03-26 13:04:51 +1000537it; otherwise runs xauth.
538The
Damien Miller32aa1441999-10-29 09:15:49 +1000539.Dq rc
540files are given the X11
541authentication protocol and cookie in standard input.
542.It
543Runs user's shell or command.
544.El
545.Sh AUTHORIZED_KEYS FILE FORMAT
546The
547.Pa $HOME/.ssh/authorized_keys
548file lists the RSA keys that are
Damien Miller450a7a12000-03-26 13:04:51 +1000549permitted for RSA authentication.
550Each line of the file contains one
Damien Miller32aa1441999-10-29 09:15:49 +1000551key (empty lines and lines starting with a
552.Ql #
553are ignored as
Damien Miller450a7a12000-03-26 13:04:51 +1000554comments).
555Each line consists of the following fields, separated by
556spaces: options, bits, exponent, modulus, comment.
557The options field
Damien Miller32aa1441999-10-29 09:15:49 +1000558is optional; its presence is determined by whether the line starts
559with a number or not (the option field never starts with a number).
560The bits, exponent, modulus and comment fields give the RSA key; the
561comment field is not used for anything (but may be convenient for the
562user to identify the key).
563.Pp
564Note that lines in this file are usually several hundred bytes long
Damien Miller450a7a12000-03-26 13:04:51 +1000565(because of the size of the RSA key modulus).
566You don't want to type them in; instead, copy the
Damien Miller32aa1441999-10-29 09:15:49 +1000567.Pa identity.pub
568file and edit it.
569.Pp
570The options (if present) consists of comma-separated option
Damien Miller450a7a12000-03-26 13:04:51 +1000571specifications.
572No spaces are permitted, except within double quotes.
Damien Miller32aa1441999-10-29 09:15:49 +1000573The following option specifications are supported:
574.Bl -tag -width Ds
575.It Cm from="pattern-list"
576Specifies that in addition to RSA authentication, the canonical name
577of the remote host must be present in the comma-separated list of
Damien Miller450a7a12000-03-26 13:04:51 +1000578patterns
579.Pf ( Ql *
580and
581.Ql ?
582serve as wildcards).
583The list may also contain
584patterns negated by prefixing them with
585.Ql ! ;
586if the canonical host name matches a negated pattern, the key is not accepted.
587The purpose
Damien Miller32aa1441999-10-29 09:15:49 +1000588of this option is to optionally increase security: RSA authentication
589by itself does not trust the network or name servers or anything (but
590the key); however, if somebody somehow steals the key, the key
Damien Miller450a7a12000-03-26 13:04:51 +1000591permits an intruder to log in from anywhere in the world.
592This additional option makes using a stolen key more difficult (name
Damien Miller32aa1441999-10-29 09:15:49 +1000593servers and/or routers would have to be compromised in addition to
594just the key).
595.It Cm command="command"
596Specifies that the command is executed whenever this key is used for
Damien Miller450a7a12000-03-26 13:04:51 +1000597authentication.
598The command supplied by the user (if any) is ignored.
Damien Miller32aa1441999-10-29 09:15:49 +1000599The command is run on a pty if the connection requests a pty;
Damien Miller450a7a12000-03-26 13:04:51 +1000600otherwise it is run without a tty.
601A quote may be included in the command by quoting it with a backslash.
602This option might be useful
603to restrict certain RSA keys to perform just a specific operation.
604An example might be a key that permits remote backups but nothing else.
605Notice that the client may specify TCP/IP and/or X11
Damien Miller32aa1441999-10-29 09:15:49 +1000606forwardings unless they are explicitly prohibited.
607.It Cm environment="NAME=value"
608Specifies that the string is to be added to the environment when
Damien Miller450a7a12000-03-26 13:04:51 +1000609logging in using this key.
610Environment variables set this way
611override other default environment values.
612Multiple options of this type are permitted.
Damien Miller32aa1441999-10-29 09:15:49 +1000613.It Cm no-port-forwarding
614Forbids TCP/IP forwarding when this key is used for authentication.
Damien Miller450a7a12000-03-26 13:04:51 +1000615Any port forward requests by the client will return an error.
616This might be used, e.g., in connection with the
Damien Miller32aa1441999-10-29 09:15:49 +1000617.Cm command
618option.
619.It Cm no-X11-forwarding
620Forbids X11 forwarding when this key is used for authentication.
621Any X11 forward requests by the client will return an error.
622.It Cm no-agent-forwarding
623Forbids authentication agent forwarding when this key is used for
624authentication.
625.It Cm no-pty
626Prevents tty allocation (a request to allocate a pty will fail).
627.El
628.Ss Examples
6291024 33 12121.\|.\|.\|312314325 ylo@foo.bar
630.Pp
631from="*.niksula.hut.fi,!pc.niksula.hut.fi" 1024 35 23.\|.\|.\|2334 ylo@niksula
632.Pp
633command="dump /home",no-pty,no-port-forwarding 1024 33 23.\|.\|.\|2323 backup.hut.fi
634.Sh SSH_KNOWN_HOSTS FILE FORMAT
635The
Damien Miller886c63a2000-01-20 23:13:36 +1100636.Pa /etc/ssh_known_hosts
Damien Miller32aa1441999-10-29 09:15:49 +1000637and
638.Pa $HOME/.ssh/known_hosts
Damien Miller450a7a12000-03-26 13:04:51 +1000639files contain host public keys for all known hosts.
640The global file should
641be prepared by the administrator (optional), and the per-user file is
Damien Miller32aa1441999-10-29 09:15:49 +1000642maintained automatically: whenever the user connects an unknown host
Damien Miller450a7a12000-03-26 13:04:51 +1000643its key is added to the per-user file.
Damien Miller32aa1441999-10-29 09:15:49 +1000644.Pp
645Each line in these files contains the following fields: hostnames,
Damien Miller450a7a12000-03-26 13:04:51 +1000646bits, exponent, modulus, comment.
647The fields are separated by spaces.
Damien Miller32aa1441999-10-29 09:15:49 +1000648.Pp
649Hostnames is a comma-separated list of patterns ('*' and '?' act as
650wildcards); each pattern in turn is matched against the canonical host
651name (when authenticating a client) or against the user-supplied
Damien Miller450a7a12000-03-26 13:04:51 +1000652name (when authenticating a server).
653A pattern may also be preceded by
Damien Miller32aa1441999-10-29 09:15:49 +1000654.Ql !
655to indicate negation: if the host name matches a negated
656pattern, it is not accepted (by that line) even if it matched another
657pattern on the line.
658.Pp
659Bits, exponent, and modulus are taken directly from the host key; they
660can be obtained, e.g., from
Damien Miller886c63a2000-01-20 23:13:36 +1100661.Pa /etc/ssh_host_key.pub .
Damien Miller32aa1441999-10-29 09:15:49 +1000662The optional comment field continues to the end of the line, and is not used.
663.Pp
664Lines starting with
665.Ql #
666and empty lines are ignored as comments.
667.Pp
668When performing host authentication, authentication is accepted if any
Damien Miller450a7a12000-03-26 13:04:51 +1000669matching line has the proper key.
670It is thus permissible (but not
Damien Miller32aa1441999-10-29 09:15:49 +1000671recommended) to have several lines or different host keys for the same
Damien Miller450a7a12000-03-26 13:04:51 +1000672names.
673This will inevitably happen when short forms of host names
674from different domains are put in the file.
675It is possible
Damien Miller32aa1441999-10-29 09:15:49 +1000676that the files contain conflicting information; authentication is
677accepted if valid information can be found from either file.
678.Pp
679Note that the lines in these files are typically hundreds of characters
680long, and you definitely don't want to type in the host keys by hand.
681Rather, generate them by a script
682or by taking
Damien Miller886c63a2000-01-20 23:13:36 +1100683.Pa /etc/ssh_host_key.pub
Damien Miller32aa1441999-10-29 09:15:49 +1000684and adding the host names at the front.
685.Ss Examples
686closenet,closenet.hut.fi,.\|.\|.\|,130.233.208.41 1024 37 159.\|.\|.93 closenet.hut.fi
687.Sh FILES
688.Bl -tag -width Ds
Damien Miller886c63a2000-01-20 23:13:36 +1100689.It Pa /etc/sshd_config
Damien Miller32aa1441999-10-29 09:15:49 +1000690Contains configuration data for
691.Nm sshd .
692This file should be writable by root only, but it is recommended
693(though not necessary) that it be world-readable.
Damien Miller886c63a2000-01-20 23:13:36 +1100694.It Pa /etc/ssh_host_key
Damien Miller32aa1441999-10-29 09:15:49 +1000695Contains the private part of the host key.
696This file should only be owned by root, readable only by root, and not
697accessible to others.
698Note that
699.Nm
700does not start if this file is group/world-accessible.
Damien Miller886c63a2000-01-20 23:13:36 +1100701.It Pa /etc/ssh_host_key.pub
Damien Miller32aa1441999-10-29 09:15:49 +1000702Contains the public part of the host key.
703This file should be world-readable but writable only by
Damien Miller450a7a12000-03-26 13:04:51 +1000704root.
705Its contents should match the private part.
706This file is not
Damien Miller32aa1441999-10-29 09:15:49 +1000707really used for anything; it is only provided for the convenience of
708the user so its contents can be copied to known hosts files.
709These two files are created using
710.Xr ssh-keygen 1 .
Damien Miller886c63a2000-01-20 23:13:36 +1100711.It Pa /var/run/sshd.pid
Damien Miller32aa1441999-10-29 09:15:49 +1000712Contains the process ID of the
713.Nm
714listening for connections (if there are several daemons running
715concurrently for different ports, this contains the pid of the one
Damien Miller450a7a12000-03-26 13:04:51 +1000716started last).
717The contents of this file are not sensitive; it can be world-readable.
Damien Miller32aa1441999-10-29 09:15:49 +1000718.It Pa $HOME/.ssh/authorized_keys
719Lists the RSA keys that can be used to log into the user's account.
720This file must be readable by root (which may on some machines imply
721it being world-readable if the user's home directory resides on an NFS
Damien Miller450a7a12000-03-26 13:04:51 +1000722volume).
723It is recommended that it not be accessible by others.
724The format of this file is described above.
Damien Miller886c63a2000-01-20 23:13:36 +1100725.It Pa "/etc/ssh_known_hosts" and "$HOME/.ssh/known_hosts"
Damien Miller5ce662a1999-11-11 17:57:39 +1100726These files are consulted when using rhosts with RSA host
Damien Miller450a7a12000-03-26 13:04:51 +1000727authentication to check the public key of the host.
728The key must be listed in one of these files to be accepted.
Damien Miller33e511e1999-11-11 11:43:13 +1100729The client uses the same files
Damien Miller450a7a12000-03-26 13:04:51 +1000730to verify that the remote host is the one we intended to connect.
731These files should be writable only by root/the owner.
Damien Miller886c63a2000-01-20 23:13:36 +1100732.Pa /etc/ssh_known_hosts
Damien Miller32aa1441999-10-29 09:15:49 +1000733should be world-readable, and
734.Pa $HOME/.ssh/known_hosts
735can but need not be world-readable.
736.It Pa /etc/nologin
737If this file exists,
738.Nm
Damien Miller450a7a12000-03-26 13:04:51 +1000739refuses to let anyone except root log in.
740The contents of the file
Damien Miller32aa1441999-10-29 09:15:49 +1000741are displayed to anyone trying to log in, and non-root connections are
Damien Miller450a7a12000-03-26 13:04:51 +1000742refused.
743The file should be world-readable.
Damien Miller32aa1441999-10-29 09:15:49 +1000744.It Pa /etc/hosts.allow, /etc/hosts.deny
745If compiled with
746.Sy LIBWRAP
747support, tcp-wrappers access controls may be defined here as described in
748.Xr hosts_access 5 .
749.It Pa $HOME/.rhosts
750This file contains host-username pairs, separated by a space, one per
Damien Miller450a7a12000-03-26 13:04:51 +1000751line.
752The given user on the corresponding host is permitted to log in
753without password.
754The same file is used by rlogind and rshd.
Damien Miller32aa1441999-10-29 09:15:49 +1000755The file must
756be writable only by the user; it is recommended that it not be
757accessible by others.
758.Pp
Damien Miller450a7a12000-03-26 13:04:51 +1000759If is also possible to use netgroups in the file.
760Either host or user
Damien Miller32aa1441999-10-29 09:15:49 +1000761name may be of the form +@groupname to specify all hosts or all users
762in the group.
763.It Pa $HOME/.shosts
764For ssh,
765this file is exactly the same as for
766.Pa .rhosts .
767However, this file is
768not used by rlogin and rshd, so using this permits access using SSH only.
769.Pa /etc/hosts.equiv
770This file is used during
771.Pa .rhosts
Damien Miller450a7a12000-03-26 13:04:51 +1000772authentication.
773In the simplest form, this file contains host names, one per line.
774Users on
Damien Miller32aa1441999-10-29 09:15:49 +1000775those hosts are permitted to log in without a password, provided they
Damien Miller450a7a12000-03-26 13:04:51 +1000776have the same user name on both machines.
777The host name may also be
Damien Miller32aa1441999-10-29 09:15:49 +1000778followed by a user name; such users are permitted to log in as
779.Em any
Damien Miller450a7a12000-03-26 13:04:51 +1000780user on this machine (except root).
781Additionally, the syntax
Damien Miller32aa1441999-10-29 09:15:49 +1000782.Dq +@group
Damien Miller450a7a12000-03-26 13:04:51 +1000783can be used to specify netgroups.
784Negated entries start with
Damien Miller32aa1441999-10-29 09:15:49 +1000785.Ql \&- .
786.Pp
787If the client host/user is successfully matched in this file, login is
788automatically permitted provided the client and server user names are the
Damien Miller450a7a12000-03-26 13:04:51 +1000789same.
790Additionally, successful RSA host authentication is normally required.
791This file must be writable only by root; it is recommended
Damien Miller32aa1441999-10-29 09:15:49 +1000792that it be world-readable.
793.Pp
794.Sy "Warning: It is almost never a good idea to use user names in"
795.Pa hosts.equiv .
796Beware that it really means that the named user(s) can log in as
797.Em anybody ,
798which includes bin, daemon, adm, and other accounts that own critical
Damien Miller450a7a12000-03-26 13:04:51 +1000799binaries and directories.
800Using a user name practically grants the user root access.
801The only valid use for user names that I can think
Damien Miller32aa1441999-10-29 09:15:49 +1000802of is in negative entries.
803.Pp
804Note that this warning also applies to rsh/rlogin.
Damien Miller886c63a2000-01-20 23:13:36 +1100805.It Pa /etc/shosts.equiv
Damien Miller32aa1441999-10-29 09:15:49 +1000806This is processed exactly as
807.Pa /etc/hosts.equiv .
808However, this file may be useful in environments that want to run both
809rsh/rlogin and ssh.
810.It Pa $HOME/.ssh/environment
Damien Miller450a7a12000-03-26 13:04:51 +1000811This file is read into the environment at login (if it exists).
812It can only contain empty lines, comment lines (that start with
Damien Miller32aa1441999-10-29 09:15:49 +1000813.Ql # ) ,
Damien Miller450a7a12000-03-26 13:04:51 +1000814and assignment lines of the form name=value.
815The file should be writable
Damien Miller32aa1441999-10-29 09:15:49 +1000816only by the user; it need not be readable by anyone else.
817.It Pa $HOME/.ssh/rc
818If this file exists, it is run with /bin/sh after reading the
Damien Miller450a7a12000-03-26 13:04:51 +1000819environment files but before starting the user's shell or command.
820If X11 spoofing is in use, this will receive the "proto cookie" pair in
Damien Miller32aa1441999-10-29 09:15:49 +1000821standard input (and
822.Ev DISPLAY
Damien Miller450a7a12000-03-26 13:04:51 +1000823in environment).
824This must call
Damien Miller32aa1441999-10-29 09:15:49 +1000825.Xr xauth 1
826in that case.
827.Pp
828The primary purpose of this file is to run any initialization routines
829which may be needed before the user's home directory becomes
830accessible; AFS is a particular example of such an environment.
831.Pp
832This file will probably contain some initialization code followed by
833something similar to: "if read proto cookie; then echo add $DISPLAY
834$proto $cookie | xauth -q -; fi".
835.Pp
836If this file does not exist,
Damien Miller886c63a2000-01-20 23:13:36 +1100837.Pa /etc/sshrc
Damien Miller32aa1441999-10-29 09:15:49 +1000838is run, and if that
839does not exist either, xauth is used to store the cookie.
840.Pp
841This file should be writable only by the user, and need not be
842readable by anyone else.
Damien Miller886c63a2000-01-20 23:13:36 +1100843.It Pa /etc/sshrc
Damien Miller32aa1441999-10-29 09:15:49 +1000844Like
845.Pa $HOME/.ssh/rc .
846This can be used to specify
Damien Miller450a7a12000-03-26 13:04:51 +1000847machine-specific login-time initializations globally.
848This file should be writable only by root, and should be world-readable.
Damien Miller32aa1441999-10-29 09:15:49 +1000849.Sh AUTHOR
Damien Miller32aa1441999-10-29 09:15:49 +1000850OpenSSH
Damien Miller98c7ad62000-03-09 21:27:49 +1100851is a derivative of the original (free) ssh 1.2.12 release by Tatu Ylonen,
Damien Miller450a7a12000-03-26 13:04:51 +1000852but with bugs removed and newer features re-added.
853Rapidly after the
Damien Miller98c7ad62000-03-09 21:27:49 +11008541.2.12 release, newer versions of the original ssh bore successively
855more restrictive licenses, and thus demand for a free version was born.
856This version of OpenSSH
Damien Miller32aa1441999-10-29 09:15:49 +1000857.Bl -bullet
858.It
Damien Miller14537852000-01-22 19:57:40 +1100859has all components of a restrictive nature (i.e., patents, see
Damien Miller32aa1441999-10-29 09:15:49 +1000860.Xr ssl 8 )
861directly removed from the source code; any licensed or patented components
862are chosen from
863external libraries.
864.It
Damien Miller98c7ad62000-03-09 21:27:49 +1100865has been updated to support ssh protocol 1.5, making it compatible with
866all other ssh protocol 1 clients and servers.
Damien Miller32aa1441999-10-29 09:15:49 +1000867.It
868contains added support for
869.Xr kerberos 8
870authentication and ticket passing.
871.It
872supports one-time password authentication with
873.Xr skey 1 .
874.El
875.Pp
876The libraries described in
877.Xr ssl 8
878are required for proper operation.
879.Sh SEE ALSO
Damien Miller32aa1441999-10-29 09:15:49 +1000880.Xr scp 1 ,
881.Xr ssh 1 ,
882.Xr ssh-add 1 ,
883.Xr ssh-agent 1 ,
884.Xr ssh-keygen 1 ,
Damien Millerb38eff82000-04-01 11:09:21 +1000885.Xr ssl 8 ,
886.Xr rlogin 1 ,
887.Xr rsh 1