blob: 63ca7df22978f4c0d4b643b1a900ddf9f7270ab3 [file] [log] [blame]
Damien Miller32aa1441999-10-29 09:15:49 +10001.\" -*- nroff -*-
2.\"
Damien Miller32aa1441999-10-29 09:15:49 +10003.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
Damien Miller32aa1441999-10-29 09:15:49 +10004.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
5.\" All rights reserved
6.\"
Damien Millere4340be2000-09-16 13:29:08 +11007.\" As far as I am concerned, the code I have written for this software
8.\" can be used freely for any purpose. Any derived versions of this
9.\" software must be clearly marked as such, and if the derived work is
10.\" incompatible with the protocol description in the RFC file, it must be
11.\" called by a name other than "ssh" or "Secure Shell".
Damien Miller32aa1441999-10-29 09:15:49 +100012.\"
Ben Lindstrom92a2e382001-03-05 06:59:27 +000013.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
14.\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
15.\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
Damien Millere4340be2000-09-16 13:29:08 +110016.\"
17.\" Redistribution and use in source and binary forms, with or without
18.\" modification, are permitted provided that the following conditions
19.\" are met:
20.\" 1. Redistributions of source code must retain the above copyright
21.\" notice, this list of conditions and the following disclaimer.
22.\" 2. Redistributions in binary form must reproduce the above copyright
23.\" notice, this list of conditions and the following disclaimer in the
24.\" documentation and/or other materials provided with the distribution.
25.\"
26.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
27.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
28.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
29.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
30.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
31.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
32.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
33.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
35.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Damien Miller32aa1441999-10-29 09:15:49 +100036.\"
Ben Lindstroma11e2702002-04-05 22:18:48 +000037.\" $OpenBSD: sshd.8,v 1.176 2002/04/05 20:56:21 stevesk Exp $
Damien Miller32aa1441999-10-29 09:15:49 +100038.Dd September 25, 1999
39.Dt SSHD 8
40.Os
41.Sh NAME
42.Nm sshd
Ben Lindstromc65e6a02001-04-23 13:02:16 +000043.Nd OpenSSH SSH daemon
Damien Miller32aa1441999-10-29 09:15:49 +100044.Sh SYNOPSIS
45.Nm sshd
Ben Lindstromdfd18502001-09-20 01:06:08 +000046.Op Fl deiqtD46
Damien Miller32aa1441999-10-29 09:15:49 +100047.Op Fl b Ar bits
48.Op Fl f Ar config_file
49.Op Fl g Ar login_grace_time
50.Op Fl h Ar host_key_file
51.Op Fl k Ar key_gen_time
Ben Lindstromade03f62001-12-06 18:22:17 +000052.Op Fl o Ar option
Damien Miller32aa1441999-10-29 09:15:49 +100053.Op Fl p Ar port
Damien Miller942da032000-08-18 13:59:06 +100054.Op Fl u Ar len
Damien Miller22c77262000-04-13 12:26:34 +100055.Sh DESCRIPTION
Damien Miller32aa1441999-10-29 09:15:49 +100056.Nm
Ben Lindstromd58eb5f2001-03-07 06:07:22 +000057(SSH Daemon) is the daemon program for
Damien Miller32aa1441999-10-29 09:15:49 +100058.Xr ssh 1 .
Damien Miller35dabd02000-05-01 21:10:33 +100059Together these programs replace rlogin and rsh, and
Damien Miller32aa1441999-10-29 09:15:49 +100060provide secure encrypted communications between two untrusted hosts
Damien Miller450a7a12000-03-26 13:04:51 +100061over an insecure network.
62The programs are intended to be as easy to
Damien Miller32aa1441999-10-29 09:15:49 +100063install and use as possible.
64.Pp
65.Nm
Damien Miller450a7a12000-03-26 13:04:51 +100066is the daemon that listens for connections from clients.
Damien Miller22c77262000-04-13 12:26:34 +100067It is normally started at boot from
Damien Miller32aa1441999-10-29 09:15:49 +100068.Pa /etc/rc .
69It forks a new
Damien Miller450a7a12000-03-26 13:04:51 +100070daemon for each incoming connection.
71The forked daemons handle
Damien Miller32aa1441999-10-29 09:15:49 +100072key exchange, encryption, authentication, command execution,
73and data exchange.
Damien Millere247cc42000-05-07 12:03:14 +100074This implementation of
75.Nm
76supports both SSH protocol version 1 and 2 simultaneously.
Damien Miller32aa1441999-10-29 09:15:49 +100077.Nm
Damien Miller450a7a12000-03-26 13:04:51 +100078works as follows.
Damien Millere247cc42000-05-07 12:03:14 +100079.Pp
80.Ss SSH protocol version 1
81.Pp
Damien Miller450a7a12000-03-26 13:04:51 +100082Each host has a host-specific RSA key
83(normally 1024 bits) used to identify the host.
84Additionally, when
Damien Miller32aa1441999-10-29 09:15:49 +100085the daemon starts, it generates a server RSA key (normally 768 bits).
86This key is normally regenerated every hour if it has been used, and
87is never stored on disk.
88.Pp
Damien Miller35dabd02000-05-01 21:10:33 +100089Whenever a client connects the daemon responds with its public
90host and server keys.
Damien Miller450a7a12000-03-26 13:04:51 +100091The client compares the
Damien Millere247cc42000-05-07 12:03:14 +100092RSA host key against its own database to verify that it has not changed.
Damien Miller450a7a12000-03-26 13:04:51 +100093The client then generates a 256 bit random number.
94It encrypts this
Damien Miller32aa1441999-10-29 09:15:49 +100095random number using both the host key and the server key, and sends
Damien Miller450a7a12000-03-26 13:04:51 +100096the encrypted number to the server.
Damien Miller35dabd02000-05-01 21:10:33 +100097Both sides then use this
Damien Miller32aa1441999-10-29 09:15:49 +100098random number as a session key which is used to encrypt all further
Damien Miller450a7a12000-03-26 13:04:51 +100099communications in the session.
100The rest of the session is encrypted
Damien Miller35dabd02000-05-01 21:10:33 +1000101using a conventional cipher, currently Blowfish or 3DES, with 3DES
Damien Millerb38eff82000-04-01 11:09:21 +1000102being used by default.
Damien Miller450a7a12000-03-26 13:04:51 +1000103The client selects the encryption algorithm
Damien Miller32aa1441999-10-29 09:15:49 +1000104to use from those offered by the server.
105.Pp
Damien Miller450a7a12000-03-26 13:04:51 +1000106Next, the server and the client enter an authentication dialog.
107The client tries to authenticate itself using
Damien Miller32aa1441999-10-29 09:15:49 +1000108.Pa .rhosts
109authentication,
110.Pa .rhosts
111authentication combined with RSA host
112authentication, RSA challenge-response authentication, or password
113based authentication.
114.Pp
115Rhosts authentication is normally disabled
116because it is fundamentally insecure, but can be enabled in the server
Damien Miller450a7a12000-03-26 13:04:51 +1000117configuration file if desired.
118System security is not improved unless
Damien Miller32aa1441999-10-29 09:15:49 +1000119.Xr rshd 8 ,
120.Xr rlogind 8 ,
Damien Miller32aa1441999-10-29 09:15:49 +1000121and
Ben Lindstrom044274b2001-09-12 16:46:08 +0000122.Xr rexecd 8
Damien Miller32aa1441999-10-29 09:15:49 +1000123are disabled (thus completely disabling
124.Xr rlogin 1
125and
126.Xr rsh 1
Damien Miller35dabd02000-05-01 21:10:33 +1000127into the machine).
Damien Miller32aa1441999-10-29 09:15:49 +1000128.Pp
Damien Millere247cc42000-05-07 12:03:14 +1000129.Ss SSH protocol version 2
130.Pp
Damien Miller942da032000-08-18 13:59:06 +1000131Version 2 works similarly:
Ben Lindstrom07d24dc2001-08-06 21:18:57 +0000132Each host has a host-specific key (RSA or DSA) used to identify the host.
Damien Millere247cc42000-05-07 12:03:14 +1000133However, when the daemon starts, it does not generate a server key.
134Forward security is provided through a Diffie-Hellman key agreement.
135This key agreement results in a shared session key.
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000136.Pp
Ben Lindstromfd2e05b2001-03-05 07:48:45 +0000137The rest of the session is encrypted using a symmetric cipher, currently
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000138128 bit AES, Blowfish, 3DES, CAST128, Arcfour, 192 bit AES, or 256 bit AES.
Damien Millere247cc42000-05-07 12:03:14 +1000139The client selects the encryption algorithm
140to use from those offered by the server.
141Additionally, session integrity is provided
Damien Miller30c3d422000-05-09 11:02:59 +1000142through a cryptographic message authentication code
Damien Millere247cc42000-05-07 12:03:14 +1000143(hmac-sha1 or hmac-md5).
144.Pp
145Protocol version 2 provides a public key based
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000146user (PubkeyAuthentication) or
147client host (HostbasedAuthentication) authentication method,
148conventional password authentication and challenge response based methods.
Damien Millere247cc42000-05-07 12:03:14 +1000149.Pp
150.Ss Command execution and data forwarding
151.Pp
Damien Miller32aa1441999-10-29 09:15:49 +1000152If the client successfully authenticates itself, a dialog for
Damien Miller450a7a12000-03-26 13:04:51 +1000153preparing the session is entered.
154At this time the client may request
Damien Miller32aa1441999-10-29 09:15:49 +1000155things like allocating a pseudo-tty, forwarding X11 connections,
156forwarding TCP/IP connections, or forwarding the authentication agent
157connection over the secure channel.
158.Pp
159Finally, the client either requests a shell or execution of a command.
Damien Miller450a7a12000-03-26 13:04:51 +1000160The sides then enter session mode.
161In this mode, either side may send
Damien Miller32aa1441999-10-29 09:15:49 +1000162data at any time, and such data is forwarded to/from the shell or
163command on the server side, and the user terminal in the client side.
164.Pp
165When the user program terminates and all forwarded X11 and other
166connections have been closed, the server sends command exit status to
167the client, and both sides exit.
168.Pp
169.Nm
170can be configured using command-line options or a configuration
Damien Miller450a7a12000-03-26 13:04:51 +1000171file.
172Command-line options override values specified in the
Damien Miller32aa1441999-10-29 09:15:49 +1000173configuration file.
174.Pp
Damien Miller6162d121999-11-21 13:23:52 +1100175.Nm
176rereads its configuration file when it receives a hangup signal,
Ben Lindstrom49a098d2001-03-05 06:55:18 +0000177.Dv SIGHUP ,
Ben Lindstromd2bf0d62001-06-25 04:10:54 +0000178by executing itself with the name it was started as, i.e.,
Ben Lindstrom49a098d2001-03-05 06:55:18 +0000179.Pa /usr/sbin/sshd .
Damien Miller6162d121999-11-21 13:23:52 +1100180.Pp
Damien Miller32aa1441999-10-29 09:15:49 +1000181The options are as follows:
182.Bl -tag -width Ds
183.It Fl b Ar bits
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000184Specifies the number of bits in the ephemeral protocol version 1
185server key (default 768).
Damien Miller32aa1441999-10-29 09:15:49 +1000186.It Fl d
Damien Miller450a7a12000-03-26 13:04:51 +1000187Debug mode.
188The server sends verbose debug output to the system
189log, and does not put itself in the background.
190The server also will not fork and will only process one connection.
191This option is only intended for debugging for the server.
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000192Multiple -d options increase the debugging level.
Damien Miller874d77b2000-10-14 16:23:11 +1100193Maximum is 3.
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000194.It Fl e
195When this option is specified,
196.Nm
197will send the output to the standard error instead of the system log.
Damien Miller32aa1441999-10-29 09:15:49 +1000198.It Fl f Ar configuration_file
Damien Miller450a7a12000-03-26 13:04:51 +1000199Specifies the name of the configuration file.
200The default is
Damien Miller05eda432002-02-10 18:32:28 +1100201.Pa /etc/ssh/sshd_config .
Damien Miller32aa1441999-10-29 09:15:49 +1000202.Nm
203refuses to start if there is no configuration file.
204.It Fl g Ar login_grace_time
205Gives the grace time for clients to authenticate themselves (default
Kevin Steves9ce907c2001-01-07 11:53:40 +0000206600 seconds).
Damien Miller450a7a12000-03-26 13:04:51 +1000207If the client fails to authenticate the user within
208this many seconds, the server disconnects and exits.
209A value of zero indicates no limit.
Damien Miller32aa1441999-10-29 09:15:49 +1000210.It Fl h Ar host_key_file
Damien Miller7fc23732002-01-22 23:19:11 +1100211Specifies a file from which a host key is read.
Damien Miller32aa1441999-10-29 09:15:49 +1000212This option must be given if
213.Nm
214is not run as root (as the normal
Damien Miller7fc23732002-01-22 23:19:11 +1100215host key files are normally not readable by anyone but root).
216The default is
Damien Miller05eda432002-02-10 18:32:28 +1100217.Pa /etc/ssh/ssh_host_key
Damien Miller7fc23732002-01-22 23:19:11 +1100218for protocol version 1, and
Damien Miller05eda432002-02-10 18:32:28 +1100219.Pa /etc/ssh/ssh_host_rsa_key
Damien Miller7fc23732002-01-22 23:19:11 +1100220and
Damien Miller05eda432002-02-10 18:32:28 +1100221.Pa /etc/ssh/ssh_host_dsa_key
Damien Miller7fc23732002-01-22 23:19:11 +1100222for protocol version 2.
Ben Lindstrom4dccfa52000-12-28 16:40:05 +0000223It is possible to have multiple host key files for
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000224the different protocol versions and host key algorithms.
Damien Miller32aa1441999-10-29 09:15:49 +1000225.It Fl i
226Specifies that
227.Nm
Damien Miller22c77262000-04-13 12:26:34 +1000228is being run from inetd.
Damien Miller32aa1441999-10-29 09:15:49 +1000229.Nm
230is normally not run
231from inetd because it needs to generate the server key before it can
Damien Miller450a7a12000-03-26 13:04:51 +1000232respond to the client, and this may take tens of seconds.
233Clients would have to wait too long if the key was regenerated every time.
Damien Miller7684ee12000-03-17 23:40:15 +1100234However, with small key sizes (e.g., 512) using
Damien Miller32aa1441999-10-29 09:15:49 +1000235.Nm
236from inetd may
237be feasible.
238.It Fl k Ar key_gen_time
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000239Specifies how often the ephemeral protocol version 1 server key is
240regenerated (default 3600 seconds, or one hour).
Damien Miller450a7a12000-03-26 13:04:51 +1000241The motivation for regenerating the key fairly
Damien Miller32aa1441999-10-29 09:15:49 +1000242often is that the key is not stored anywhere, and after about an hour,
243it becomes impossible to recover the key for decrypting intercepted
244communications even if the machine is cracked into or physically
Damien Miller450a7a12000-03-26 13:04:51 +1000245seized.
246A value of zero indicates that the key will never be regenerated.
Ben Lindstromade03f62001-12-06 18:22:17 +0000247.It Fl o Ar option
248Can be used to give options in the format used in the configuration file.
249This is useful for specifying options for which there is no separate
250command-line flag.
Damien Miller32aa1441999-10-29 09:15:49 +1000251.It Fl p Ar port
252Specifies the port on which the server listens for connections
253(default 22).
Damien Miller7d1ded42002-01-22 23:09:41 +1100254Multiple port options are permitted.
255Ports specified in the configuration file are ignored when a
256command-line port is specified.
Damien Miller32aa1441999-10-29 09:15:49 +1000257.It Fl q
Damien Miller450a7a12000-03-26 13:04:51 +1000258Quiet mode.
259Nothing is sent to the system log.
260Normally the beginning,
Damien Miller32aa1441999-10-29 09:15:49 +1000261authentication, and termination of each connection is logged.
Ben Lindstrom794325a2001-08-06 21:09:07 +0000262.It Fl t
263Test mode.
264Only check the validity of the configuration file and sanity of the keys.
Damien Miller9f0f5c62001-12-21 14:45:46 +1100265This is useful for updating
Ben Lindstrom794325a2001-08-06 21:09:07 +0000266.Nm
267reliably as configuration options may change.
Damien Miller942da032000-08-18 13:59:06 +1000268.It Fl u Ar len
269This option is used to specify the size of the field
270in the
271.Li utmp
272structure that holds the remote host name.
273If the resolved host name is longer than
274.Ar len ,
275the dotted decimal value will be used instead.
276This allows hosts with very long host names that
277overflow this field to still be uniquely identified.
278Specifying
279.Fl u0
280indicates that only dotted decimal addresses
281should be put into the
282.Pa utmp
283file.
Ben Lindstrom6f672c02001-09-12 17:51:55 +0000284.Fl u0
285is also be used to prevent
286.Nm
287from making DNS requests unless the authentication
288mechanism or configuration requires it.
289Authentication mechanisms that may require DNS include
290.Cm RhostsAuthentication ,
291.Cm RhostsRSAAuthentication ,
292.Cm HostbasedAuthentication
293and using a
294.Cm from="pattern-list"
295option in a key file.
Ben Lindstromea03db92002-03-05 01:38:57 +0000296Configuration options that require DNS include using a
297USER@HOST pattern in
298.Cm AllowUsers
299or
300.Cm DenyUsers .
Ben Lindstrom4dccfa52000-12-28 16:40:05 +0000301.It Fl D
302When this option is specified
303.Nm
304will not detach and does not become a daemon.
305This allows easy monitoring of
306.Nm sshd .
Damien Miller34132e52000-01-14 15:45:46 +1100307.It Fl 4
308Forces
309.Nm
310to use IPv4 addresses only.
311.It Fl 6
312Forces
313.Nm
314to use IPv6 addresses only.
Damien Miller32aa1441999-10-29 09:15:49 +1000315.El
316.Sh CONFIGURATION FILE
317.Nm
Damien Miller22c77262000-04-13 12:26:34 +1000318reads configuration data from
Damien Miller05eda432002-02-10 18:32:28 +1100319.Pa /etc/ssh/sshd_config
Damien Miller32aa1441999-10-29 09:15:49 +1000320(or the file specified with
321.Fl f
Damien Miller450a7a12000-03-26 13:04:51 +1000322on the command line).
Ben Lindstrom1c0fd092001-09-12 16:36:17 +0000323The file contains keyword-argument pairs, one per line.
Damien Miller450a7a12000-03-26 13:04:51 +1000324Lines starting with
Damien Miller32aa1441999-10-29 09:15:49 +1000325.Ql #
326and empty lines are interpreted as comments.
327.Pp
Ben Lindstrom1c0fd092001-09-12 16:36:17 +0000328The possible
329keywords and their meanings are as follows (note that
330keywords are case-insensitive and arguments are case-sensitive):
Damien Miller32aa1441999-10-29 09:15:49 +1000331.Bl -tag -width Ds
332.It Cm AFSTokenPassing
Damien Miller450a7a12000-03-26 13:04:51 +1000333Specifies whether an AFS token may be forwarded to the server.
334Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000335.Dq yes .
336.It Cm AllowGroups
Damien Millerdf64a682002-01-22 23:33:45 +1100337This keyword can be followed by a list of group name patterns, separated
Damien Miller450a7a12000-03-26 13:04:51 +1000338by spaces.
339If specified, login is allowed only for users whose primary
Kevin Steves7b61cfa2001-01-14 19:11:00 +0000340group or supplementary group list matches one of the patterns.
Damien Miller32aa1441999-10-29 09:15:49 +1000341.Ql \&*
342and
343.Ql ?
344can be used as
Damien Miller450a7a12000-03-26 13:04:51 +1000345wildcards in the patterns.
Ben Lindstrom594e2032001-09-12 18:35:30 +0000346Only group names are valid; a numerical group ID is not recognized.
Damien Millerdf64a682002-01-22 23:33:45 +1100347By default, login is allowed for all groups.
Damien Miller32aa1441999-10-29 09:15:49 +1000348.Pp
Damien Miller50a41ed2000-10-16 12:14:42 +1100349.It Cm AllowTcpForwarding
350Specifies whether TCP forwarding is permitted.
351The default is
352.Dq yes .
353Note that disabling TCP forwarding does not improve security unless
354users are also denied shell access, as they can always install their
355own forwarders.
356.Pp
Damien Miller32aa1441999-10-29 09:15:49 +1000357.It Cm AllowUsers
Damien Millerdf64a682002-01-22 23:33:45 +1100358This keyword can be followed by a list of user name patterns, separated
Damien Miller450a7a12000-03-26 13:04:51 +1000359by spaces.
360If specified, login is allowed only for users names that
Damien Miller32aa1441999-10-29 09:15:49 +1000361match one of the patterns.
362.Ql \&*
363and
364.Ql ?
365can be used as
Damien Miller450a7a12000-03-26 13:04:51 +1000366wildcards in the patterns.
Ben Lindstrom594e2032001-09-12 18:35:30 +0000367Only user names are valid; a numerical user ID is not recognized.
Damien Millerdf64a682002-01-22 23:33:45 +1100368By default, login is allowed for all users.
Ben Lindstrom60260022001-07-04 04:56:44 +0000369If the pattern takes the form USER@HOST then USER and HOST
Ben Lindstrom594e2032001-09-12 18:35:30 +0000370are separately checked, restricting logins to particular
Ben Lindstrom60260022001-07-04 04:56:44 +0000371users from particular hosts.
Damien Miller32aa1441999-10-29 09:15:49 +1000372.Pp
Ben Lindstrombfb3a0e2001-06-05 20:25:05 +0000373.It Cm AuthorizedKeysFile
Ben Lindstrom07d24dc2001-08-06 21:18:57 +0000374Specifies the file that contains the public keys that can be used
375for user authentication.
Ben Lindstrombfb3a0e2001-06-05 20:25:05 +0000376.Cm AuthorizedKeysFile
377may contain tokens of the form %T which are substituted during connection
Ben Lindstrome59433d2001-09-12 16:41:37 +0000378set-up. The following tokens are defined: %% is replaced by a literal '%',
Ben Lindstrombfb3a0e2001-06-05 20:25:05 +0000379%h is replaced by the home directory of the user being authenticated and
380%u is replaced by the username of that user.
381After expansion,
382.Cm AuthorizedKeysFile
Ben Lindstrom34a99682001-06-12 00:23:12 +0000383is taken to be an absolute path or one relative to the user's home
Ben Lindstrombfb3a0e2001-06-05 20:25:05 +0000384directory.
385The default is
Damien Miller70972eb2002-01-22 23:19:55 +1100386.Dq .ssh/authorized_keys .
Ben Lindstrom48bd7c12001-01-09 00:35:42 +0000387.It Cm Banner
388In some jurisdictions, sending a warning message before authentication
389may be relevant for getting legal protection.
390The contents of the specified file are sent to the remote user before
391authentication is allowed.
392This option is only available for protocol version 2.
Ben Lindstrom85520a62002-03-22 02:44:40 +0000393By default, no banner is displayed.
Ben Lindstrom48bd7c12001-01-09 00:35:42 +0000394.Pp
Ben Lindstromff8b4942001-03-06 01:00:03 +0000395.It Cm ChallengeResponseAuthentication
Ben Lindstromc8e29ce2001-08-06 20:55:28 +0000396Specifies whether challenge response authentication is allowed.
397All authentication styles from
398.Xr login.conf 5
399are supported.
Ben Lindstromff8b4942001-03-06 01:00:03 +0000400The default is
401.Dq yes .
Ben Lindstrom608d1d12001-06-05 19:33:22 +0000402.It Cm Ciphers
403Specifies the ciphers allowed for protocol version 2.
404Multiple ciphers must be comma-separated.
405The default is
Damien Miller9c3f9502002-01-22 23:33:15 +1100406.Pp
407.Bd -literal
408 ``aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour,
409 aes192-cbc,aes256-cbc''
410.Ed
Ben Lindstrom5744dc42001-04-13 23:28:01 +0000411.It Cm ClientAliveInterval
412Sets a timeout interval in seconds after which if no data has been received
Ben Lindstrom24643222001-06-25 05:08:11 +0000413from the client,
Ben Lindstrom5744dc42001-04-13 23:28:01 +0000414.Nm
415will send a message through the encrypted
Ben Lindstroma8f39722001-04-16 02:03:49 +0000416channel to request a response from the client.
417The default
Ben Lindstrom5744dc42001-04-13 23:28:01 +0000418is 0, indicating that these messages will not be sent to the client.
Ben Lindstroma8f39722001-04-16 02:03:49 +0000419This option applies to protocol version 2 only.
Ben Lindstrom5744dc42001-04-13 23:28:01 +0000420.It Cm ClientAliveCountMax
421Sets the number of client alive messages (see above) which may be
422sent without
423.Nm
424receiving any messages back from the client. If this threshold is
Ben Lindstrom24643222001-06-25 05:08:11 +0000425reached while client alive messages are being sent,
Ben Lindstrom5744dc42001-04-13 23:28:01 +0000426.Nm
427will disconnect the client, terminating the session. It is important
Ben Lindstrom24643222001-06-25 05:08:11 +0000428to note that the use of client alive messages is very different from
Damien Miller60d8aaf2001-11-12 11:04:05 +1100429.Cm KeepAlive
Ben Lindstroma8f39722001-04-16 02:03:49 +0000430(below). The client alive messages are sent through the
Ben Lindstrom5744dc42001-04-13 23:28:01 +0000431encrypted channel and therefore will not be spoofable. The TCP keepalive
Ben Lindstroma8f39722001-04-16 02:03:49 +0000432option enabled by
Damien Miller60d8aaf2001-11-12 11:04:05 +1100433.Cm KeepAlive
Ben Lindstrom594e2032001-09-12 18:35:30 +0000434is spoofable. The client alive mechanism is valuable when the client or
435server depend on knowing when a connection has become inactive.
Ben Lindstroma8f39722001-04-16 02:03:49 +0000436.Pp
Ben Lindstrom594e2032001-09-12 18:35:30 +0000437The default value is 3. If
Ben Lindstroma8f39722001-04-16 02:03:49 +0000438.Cm ClientAliveInterval
Ben Lindstrom594e2032001-09-12 18:35:30 +0000439(above) is set to 15, and
Ben Lindstrom406b4f02001-09-20 23:09:16 +0000440.Cm ClientAliveCountMax
441is left at the default, unresponsive ssh clients
Ben Lindstrom24643222001-06-25 05:08:11 +0000442will be disconnected after approximately 45 seconds.
Damien Miller32aa1441999-10-29 09:15:49 +1000443.It Cm DenyGroups
Damien Millerdf64a682002-01-22 23:33:45 +1100444This keyword can be followed by a list of group name patterns, separated
Damien Miller450a7a12000-03-26 13:04:51 +1000445by spaces.
Damien Millerdf64a682002-01-22 23:33:45 +1100446Login is disallowed for users whose primary group or supplementary
447group list matches one of the patterns.
Damien Miller32aa1441999-10-29 09:15:49 +1000448.Ql \&*
449and
450.Ql ?
451can be used as
Damien Miller450a7a12000-03-26 13:04:51 +1000452wildcards in the patterns.
Ben Lindstrom594e2032001-09-12 18:35:30 +0000453Only group names are valid; a numerical group ID is not recognized.
Damien Millerdf64a682002-01-22 23:33:45 +1100454By default, login is allowed for all groups.
Damien Miller32aa1441999-10-29 09:15:49 +1000455.Pp
456.It Cm DenyUsers
Damien Millerdf64a682002-01-22 23:33:45 +1100457This keyword can be followed by a list of user name patterns, separated
Damien Miller450a7a12000-03-26 13:04:51 +1000458by spaces.
459Login is disallowed for user names that match one of the patterns.
Damien Miller32aa1441999-10-29 09:15:49 +1000460.Ql \&*
461and
462.Ql ?
Damien Miller450a7a12000-03-26 13:04:51 +1000463can be used as wildcards in the patterns.
Ben Lindstrom594e2032001-09-12 18:35:30 +0000464Only user names are valid; a numerical user ID is not recognized.
Damien Millerdf64a682002-01-22 23:33:45 +1100465By default, login is allowed for all users.
Ben Lindstrom778bf552002-03-05 01:37:12 +0000466If the pattern takes the form USER@HOST then USER and HOST
467are separately checked, restricting logins to particular
468users from particular hosts.
Damien Millere247cc42000-05-07 12:03:14 +1000469.It Cm GatewayPorts
470Specifies whether remote hosts are allowed to connect to ports
471forwarded for the client.
Ben Lindstrom60d82be2001-09-12 17:58:15 +0000472By default,
473.Nm
474binds remote port forwardings to the loopback addresss. This
475prevents other remote hosts from connecting to forwarded ports.
476.Cm GatewayPorts
477can be used to specify that
478.Nm
479should bind remote port forwardings to the wildcard address,
480thus allowing remote hosts to connect to forwarded ports.
Damien Millere247cc42000-05-07 12:03:14 +1000481The argument must be
482.Dq yes
483or
484.Dq no .
485The default is
486.Dq no .
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000487.It Cm HostbasedAuthentication
488Specifies whether rhosts or /etc/hosts.equiv authentication together
489with successful public key client host authentication is allowed
490(hostbased authentication).
491This option is similar to
492.Cm RhostsRSAAuthentication
493and applies to protocol version 2 only.
494The default is
495.Dq no .
Damien Millere247cc42000-05-07 12:03:14 +1000496.It Cm HostKey
Damien Miller7fc23732002-01-22 23:19:11 +1100497Specifies a file containing a private host key
498used by SSH.
499The default is
Damien Miller05eda432002-02-10 18:32:28 +1100500.Pa /etc/ssh/ssh_host_key
Damien Miller7fc23732002-01-22 23:19:11 +1100501for protocol version 1, and
Damien Miller05eda432002-02-10 18:32:28 +1100502.Pa /etc/ssh/ssh_host_rsa_key
Damien Miller7fc23732002-01-22 23:19:11 +1100503and
Damien Miller05eda432002-02-10 18:32:28 +1100504.Pa /etc/ssh/ssh_host_dsa_key
Damien Miller7fc23732002-01-22 23:19:11 +1100505for protocol version 2.
Damien Millere247cc42000-05-07 12:03:14 +1000506Note that
507.Nm
Ben Lindstrom226cfa02001-01-22 05:34:40 +0000508will refuse to use a file if it is group/world-accessible.
Damien Miller0bc1bd82000-11-13 22:57:25 +1100509It is possible to have multiple host key files.
510.Dq rsa1
511keys are used for version 1 and
512.Dq dsa
513or
514.Dq rsa
515are used for version 2 of the SSH protocol.
Damien Miller32aa1441999-10-29 09:15:49 +1000516.It Cm IgnoreRhosts
Damien Miller98c7ad62000-03-09 21:27:49 +1100517Specifies that
518.Pa .rhosts
Damien Miller22c77262000-04-13 12:26:34 +1000519and
Damien Miller98c7ad62000-03-09 21:27:49 +1100520.Pa .shosts
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000521files will not be used in
522.Cm RhostsAuthentication ,
523.Cm RhostsRSAAuthentication
524or
525.Cm HostbasedAuthentication .
526.Pp
Damien Miller32aa1441999-10-29 09:15:49 +1000527.Pa /etc/hosts.equiv
528and
Damien Miller22c77262000-04-13 12:26:34 +1000529.Pa /etc/shosts.equiv
Damien Miller450a7a12000-03-26 13:04:51 +1000530are still used.
Damien Miller22c77262000-04-13 12:26:34 +1000531The default is
Damien Miller98c7ad62000-03-09 21:27:49 +1100532.Dq yes .
Damien Miller32265091999-11-12 11:33:04 +1100533.It Cm IgnoreUserKnownHosts
534Specifies whether
535.Nm
536should ignore the user's
537.Pa $HOME/.ssh/known_hosts
538during
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000539.Cm RhostsRSAAuthentication
540or
541.Cm HostbasedAuthentication .
Damien Miller32265091999-11-12 11:33:04 +1100542The default is
543.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000544.It Cm KeepAlive
Damien Miller9749c0c2002-02-05 12:23:58 +1100545Specifies whether the system should send TCP keepalive messages to the
Damien Miller450a7a12000-03-26 13:04:51 +1000546other side.
547If they are sent, death of the connection or crash of one
548of the machines will be properly noticed.
549However, this means that
Damien Miller32aa1441999-10-29 09:15:49 +1000550connections will die if the route is down temporarily, and some people
Damien Miller450a7a12000-03-26 13:04:51 +1000551find it annoying.
Damien Miller30c3d422000-05-09 11:02:59 +1000552On the other hand, if keepalives are not sent,
Damien Miller32aa1441999-10-29 09:15:49 +1000553sessions may hang indefinitely on the server, leaving
554.Dq ghost
555users and consuming server resources.
556.Pp
557The default is
558.Dq yes
559(to send keepalives), and the server will notice
Damien Miller9749c0c2002-02-05 12:23:58 +1100560if the network goes down or the client host crashes.
Damien Miller450a7a12000-03-26 13:04:51 +1000561This avoids infinitely hanging sessions.
Damien Miller32aa1441999-10-29 09:15:49 +1000562.Pp
563To disable keepalives, the value should be set to
Damien Miller9749c0c2002-02-05 12:23:58 +1100564.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000565.It Cm KerberosAuthentication
Damien Miller450a7a12000-03-26 13:04:51 +1000566Specifies whether Kerberos authentication is allowed.
567This can be in the form of a Kerberos ticket, or if
Damien Miller32aa1441999-10-29 09:15:49 +1000568.Cm PasswordAuthentication
569is yes, the password provided by the user will be validated through
Damien Miller874d77b2000-10-14 16:23:11 +1100570the Kerberos KDC.
571To use this option, the server needs a
Damien Miller942da032000-08-18 13:59:06 +1000572Kerberos servtab which allows the verification of the KDC's identity.
Damien Miller450a7a12000-03-26 13:04:51 +1000573Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000574.Dq yes .
575.It Cm KerberosOrLocalPasswd
576If set then if password authentication through Kerberos fails then
577the password will be validated via any additional local mechanism
578such as
Damien Miller62cee002000-09-23 17:15:56 +1100579.Pa /etc/passwd .
Damien Miller450a7a12000-03-26 13:04:51 +1000580Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000581.Dq yes .
582.It Cm KerberosTgtPassing
583Specifies whether a Kerberos TGT may be forwarded to the server.
Damien Miller22c77262000-04-13 12:26:34 +1000584Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000585.Dq no ,
586as this only works when the Kerberos KDC is actually an AFS kaserver.
587.It Cm KerberosTicketCleanup
588Specifies whether to automatically destroy the user's ticket cache
Damien Miller450a7a12000-03-26 13:04:51 +1000589file on logout.
590Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000591.Dq yes .
592.It Cm KeyRegenerationInterval
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000593In protocol version 1, the ephemeral server key is automatically regenerated
594after this many seconds (if it has been used).
Damien Miller450a7a12000-03-26 13:04:51 +1000595The purpose of regeneration is to prevent
Damien Miller32aa1441999-10-29 09:15:49 +1000596decrypting captured sessions by later breaking into the machine and
Damien Miller450a7a12000-03-26 13:04:51 +1000597stealing the keys.
598The key is never stored anywhere.
599If the value is 0, the key is never regenerated.
600The default is 3600 (seconds).
Damien Miller32aa1441999-10-29 09:15:49 +1000601.It Cm ListenAddress
Ben Lindstrom49e57a82001-04-08 18:02:43 +0000602Specifies the local addresses
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000603.Nm
Damien Miller32aa1441999-10-29 09:15:49 +1000604should listen on.
Ben Lindstrom49e57a82001-04-08 18:02:43 +0000605The following forms may be used:
606.Pp
607.Bl -item -offset indent -compact
608.It
609.Cm ListenAddress
Ben Lindstrom1a598a42001-04-10 02:48:50 +0000610.Sm off
611.Ar host No | Ar IPv4_addr No | Ar IPv6_addr
612.Sm on
Ben Lindstrom49e57a82001-04-08 18:02:43 +0000613.It
614.Cm ListenAddress
Ben Lindstrom1a598a42001-04-10 02:48:50 +0000615.Sm off
616.Ar host No | Ar IPv4_addr No : Ar port
617.Sm on
Ben Lindstrom49e57a82001-04-08 18:02:43 +0000618.It
619.Cm ListenAddress
Ben Lindstrom1a598a42001-04-10 02:48:50 +0000620.Sm off
621.Oo
622.Ar host No | Ar IPv6_addr Oc : Ar port
623.Sm on
Ben Lindstrom49e57a82001-04-08 18:02:43 +0000624.El
625.Pp
626If
Ben Lindstrom1a598a42001-04-10 02:48:50 +0000627.Ar port
Ben Lindstrom49e57a82001-04-08 18:02:43 +0000628is not specified,
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000629.Nm
Ben Lindstrom49e57a82001-04-08 18:02:43 +0000630will listen on the address and all prior
631.Cm Port
632options specified. The default is to listen on all local
633addresses. Multiple
634.Cm ListenAddress
635options are permitted. Additionally, any
636.Cm Port
637options must precede this option for non port qualified addresses.
Damien Miller32aa1441999-10-29 09:15:49 +1000638.It Cm LoginGraceTime
639The server disconnects after this time if the user has not
Damien Miller450a7a12000-03-26 13:04:51 +1000640successfully logged in.
641If the value is 0, there is no time limit.
Damien Miller32aa1441999-10-29 09:15:49 +1000642The default is 600 (seconds).
Damien Miller5ce662a1999-11-11 17:57:39 +1100643.It Cm LogLevel
644Gives the verbosity level that is used when logging messages from
645.Nm sshd .
646The possible values are:
Damien Millerdc9e0672002-01-22 23:17:51 +1100647QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2 and DEBUG3.
648The default is INFO. DEBUG and DEBUG1 are equivalent. DEBUG2
649and DEBUG3 each specify higher levels of debugging output.
650Logging with a DEBUG level violates the privacy of users
Damien Miller5ce662a1999-11-11 17:57:39 +1100651and is not recommended.
Ben Lindstrom06b33aa2001-02-15 03:01:59 +0000652.It Cm MACs
653Specifies the available MAC (message authentication code) algorithms.
654The MAC algorithm is used in protocol version 2
655for data integrity protection.
656Multiple algorithms must be comma-separated.
657The default is
Ben Lindstrombd0e2de2001-06-05 19:52:52 +0000658.Dq hmac-md5,hmac-sha1,hmac-ripemd160,hmac-sha1-96,hmac-md5-96 .
Damien Miller37023962000-07-11 17:31:38 +1000659.It Cm MaxStartups
660Specifies the maximum number of concurrent unauthenticated connections to the
661.Nm
662daemon.
663Additional connections will be dropped until authentication succeeds or the
664.Cm LoginGraceTime
665expires for a connection.
666The default is 10.
Damien Miller942da032000-08-18 13:59:06 +1000667.Pp
668Alternatively, random early drop can be enabled by specifying
669the three colon separated values
670.Dq start:rate:full
Damien Miller874d77b2000-10-14 16:23:11 +1100671(e.g., "10:30:60").
Damien Miller942da032000-08-18 13:59:06 +1000672.Nm
Ben Lindstroma7333502001-01-29 08:44:03 +0000673will refuse connection attempts with a probability of
Damien Miller942da032000-08-18 13:59:06 +1000674.Dq rate/100
675(30%)
676if there are currently
677.Dq start
678(10)
679unauthenticated connections.
Ben Lindstroma7333502001-01-29 08:44:03 +0000680The probability increases linearly and all connection attempts
Damien Miller942da032000-08-18 13:59:06 +1000681are refused if the number of unauthenticated connections reaches
682.Dq full
683(60).
Damien Millerf8154422001-04-25 22:44:14 +1000684.It Cm PAMAuthenticationViaKbdInt
685Specifies whether PAM challenge response authentication is allowed. This
686allows the use of most PAM challenge response authentication modules, but
687it will allow password authentication regardless of whether
688.Cm PasswordAuthentication
689is disabled.
690The default is
691.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000692.It Cm PasswordAuthentication
693Specifies whether password authentication is allowed.
694The default is
695.Dq yes .
696.It Cm PermitEmptyPasswords
697When password authentication is allowed, it specifies whether the
Damien Miller450a7a12000-03-26 13:04:51 +1000698server allows login to accounts with empty password strings.
699The default is
Damien Miller98c7ad62000-03-09 21:27:49 +1100700.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000701.It Cm PermitRootLogin
Ben Lindstrom323c98f2001-03-05 07:40:40 +0000702Specifies whether root can login using
Damien Miller32aa1441999-10-29 09:15:49 +1000703.Xr ssh 1 .
704The argument must be
705.Dq yes ,
Ben Lindstromd8a90212001-02-15 03:08:27 +0000706.Dq without-password ,
707.Dq forced-commands-only
Damien Miller32aa1441999-10-29 09:15:49 +1000708or
709.Dq no .
710The default is
711.Dq yes .
Damien Miller32aa1441999-10-29 09:15:49 +1000712.Pp
Ben Lindstromd8a90212001-02-15 03:08:27 +0000713If this option is set to
714.Dq without-password
715password authentication is disabled for root.
716.Pp
717If this option is set to
718.Dq forced-commands-only
719root login with public key authentication will be allowed,
720but only if the
Damien Miller32aa1441999-10-29 09:15:49 +1000721.Ar command
Ben Lindstromd8a90212001-02-15 03:08:27 +0000722option has been specified
Damien Miller32aa1441999-10-29 09:15:49 +1000723(which may be useful for taking remote backups even if root login is
Ben Lindstromd8a90212001-02-15 03:08:27 +0000724normally not allowed). All other authentication methods are disabled
725for root.
Ben Lindstrom323c98f2001-03-05 07:40:40 +0000726.Pp
727If this option is set to
728.Dq no
729root is not allowed to login.
Damien Miller6f83b8e2000-05-02 09:23:45 +1000730.It Cm PidFile
731Specifies the file that contains the process identifier of the
732.Nm
733daemon.
734The default is
735.Pa /var/run/sshd.pid .
Damien Miller32aa1441999-10-29 09:15:49 +1000736.It Cm Port
737Specifies the port number that
738.Nm
Damien Miller450a7a12000-03-26 13:04:51 +1000739listens on.
740The default is 22.
Damien Miller34132e52000-01-14 15:45:46 +1100741Multiple options of this type are permitted.
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000742See also
743.Cm ListenAddress .
Ben Lindstrom7bfff362001-03-26 05:45:53 +0000744.It Cm PrintLastLog
745Specifies whether
746.Nm
747should print the date and time when the user last logged in.
748The default is
749.Dq yes .
Damien Miller32aa1441999-10-29 09:15:49 +1000750.It Cm PrintMotd
751Specifies whether
752.Nm
Damien Miller22c77262000-04-13 12:26:34 +1000753should print
Damien Miller32aa1441999-10-29 09:15:49 +1000754.Pa /etc/motd
Damien Miller450a7a12000-03-26 13:04:51 +1000755when a user logs in interactively.
756(On some systems it is also printed by the shell,
Damien Miller32aa1441999-10-29 09:15:49 +1000757.Pa /etc/profile ,
Damien Miller450a7a12000-03-26 13:04:51 +1000758or equivalent.)
759The default is
Damien Miller32aa1441999-10-29 09:15:49 +1000760.Dq yes .
Damien Miller22c77262000-04-13 12:26:34 +1000761.It Cm Protocol
762Specifies the protocol versions
763.Nm
764should support.
765The possible values are
766.Dq 1
767and
768.Dq 2 .
769Multiple versions must be comma-separated.
770The default is
Ben Lindstrombdc2beb2001-04-16 02:11:52 +0000771.Dq 2,1 .
Ben Lindstromff8b4942001-03-06 01:00:03 +0000772.It Cm PubkeyAuthentication
773Specifies whether public key authentication is allowed.
774The default is
775.Dq yes .
776Note that this option applies to protocol version 2 only.
Damien Miller32aa1441999-10-29 09:15:49 +1000777.It Cm RhostsAuthentication
778Specifies whether authentication using rhosts or /etc/hosts.equiv
Damien Miller450a7a12000-03-26 13:04:51 +1000779files is sufficient.
780Normally, this method should not be permitted because it is insecure.
Damien Miller32aa1441999-10-29 09:15:49 +1000781.Cm RhostsRSAAuthentication
782should be used
783instead, because it performs RSA-based host authentication in addition
784to normal rhosts or /etc/hosts.equiv authentication.
785The default is
786.Dq no .
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000787This option applies to protocol version 1 only.
Damien Miller32aa1441999-10-29 09:15:49 +1000788.It Cm RhostsRSAAuthentication
789Specifies whether rhosts or /etc/hosts.equiv authentication together
Damien Miller450a7a12000-03-26 13:04:51 +1000790with successful RSA host authentication is allowed.
791The default is
Damien Miller98c7ad62000-03-09 21:27:49 +1100792.Dq no .
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000793This option applies to protocol version 1 only.
Damien Miller32aa1441999-10-29 09:15:49 +1000794.It Cm RSAAuthentication
Damien Miller450a7a12000-03-26 13:04:51 +1000795Specifies whether pure RSA authentication is allowed.
796The default is
Damien Miller32aa1441999-10-29 09:15:49 +1000797.Dq yes .
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000798This option applies to protocol version 1 only.
Damien Miller32aa1441999-10-29 09:15:49 +1000799.It Cm ServerKeyBits
Ben Lindstromc65e6a02001-04-23 13:02:16 +0000800Defines the number of bits in the ephemeral protocol version 1 server key.
Damien Miller450a7a12000-03-26 13:04:51 +1000801The minimum value is 512, and the default is 768.
Damien Miller32aa1441999-10-29 09:15:49 +1000802.It Cm StrictModes
803Specifies whether
804.Nm
805should check file modes and ownership of the
Damien Miller450a7a12000-03-26 13:04:51 +1000806user's files and home directory before accepting login.
807This is normally desirable because novices sometimes accidentally leave their
808directory or files world-writable.
809The default is
Damien Miller32aa1441999-10-29 09:15:49 +1000810.Dq yes .
Damien Millerf6d9e222000-06-18 14:50:44 +1000811.It Cm Subsystem
Damien Miller874d77b2000-10-14 16:23:11 +1100812Configures an external subsystem (e.g., file transfer daemon).
813Arguments should be a subsystem name and a command to execute upon subsystem
814request.
Damien Miller7b28dc52000-09-05 13:34:53 +1100815The command
816.Xr sftp-server 8
817implements the
818.Dq sftp
819file transfer subsystem.
Damien Millerf6d9e222000-06-18 14:50:44 +1000820By default no subsystems are defined.
821Note that this option applies to protocol version 2 only.
Damien Miller32aa1441999-10-29 09:15:49 +1000822.It Cm SyslogFacility
823Gives the facility code that is used when logging messages from
824.Nm sshd .
825The possible values are: DAEMON, USER, AUTH, LOCAL0, LOCAL1, LOCAL2,
Damien Miller450a7a12000-03-26 13:04:51 +1000826LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7.
827The default is AUTH.
Damien Miller32aa1441999-10-29 09:15:49 +1000828.It Cm UseLogin
829Specifies whether
830.Xr login 1
Damien Millerd3a18572000-06-07 19:55:44 +1000831is used for interactive login sessions.
Ben Lindstrom699776e2001-06-21 03:14:49 +0000832The default is
833.Dq no .
Damien Millerd3a18572000-06-07 19:55:44 +1000834Note that
835.Xr login 1
Damien Miller942da032000-08-18 13:59:06 +1000836is never used for remote command execution.
Ben Lindstrom24643222001-06-25 05:08:11 +0000837Note also, that if this is enabled,
838.Cm X11Forwarding
Ben Lindstrom699776e2001-06-21 03:14:49 +0000839will be disabled because
840.Xr login 1
841does not know how to handle
Ben Lindstrom24643222001-06-25 05:08:11 +0000842.Xr xauth 1
Ben Lindstrom191c8e52002-03-22 02:37:50 +0000843cookies. If
844.Cm UsePrivilegeSeparation
845is specified, it will be disabled after authentication.
846.It Cm UsePrivilegeSeparation
847Specifies whether
848.Nm
849separated privileges by creating an unprivileged child process
850to deal with incoming network traffic. After successful authentication,
851another process will be created that has the privilege of the authenticated
852user. The goal of privilege separation is to prevent privilege
853escalation by containing any corruption within the unprivileged processes.
854The default is
855.Dq no .
Damien Millerc5d86352002-02-05 12:13:41 +1100856.It Cm VerifyReverseMapping
857Specifies whether
858.Nm
859should try to verify the remote host name and check that
860the resolved host name for the remote IP address maps back to the
861very same IP address.
862The default is
863.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000864.It Cm X11DisplayOffset
865Specifies the first display number available for
866.Nm sshd Ns 's
Damien Miller450a7a12000-03-26 13:04:51 +1000867X11 forwarding.
868This prevents
Damien Miller32aa1441999-10-29 09:15:49 +1000869.Nm
870from interfering with real X11 servers.
Damien Miller98c7ad62000-03-09 21:27:49 +1100871The default is 10.
Damien Miller396691a2000-01-20 22:44:08 +1100872.It Cm X11Forwarding
Damien Miller450a7a12000-03-26 13:04:51 +1000873Specifies whether X11 forwarding is permitted.
874The default is
Damien Miller98c7ad62000-03-09 21:27:49 +1100875.Dq no .
Damien Miller396691a2000-01-20 22:44:08 +1100876Note that disabling X11 forwarding does not improve security in any
877way, as users can always install their own forwarders.
Ben Lindstrom24643222001-06-25 05:08:11 +0000878X11 forwarding is automatically disabled if
879.Cm UseLogin
880is enabled.
Damien Miller95c249f2002-02-05 12:11:34 +1100881.It Cm X11UseLocalhost
882Specifies whether
883.Nm
884should bind the X11 forwarding server to the loopback address or to
885the wildcard address. By default,
886.Nm
887binds the forwarding server to the loopback address and sets the
888hostname part of the
889.Ev DISPLAY
890environment variable to
891.Dq localhost .
892This prevents remote hosts from connecting to the fake display.
893However, some older X11 clients may not function with this
894configuration.
895.Cm X11UseLocalhost
896may be set to
897.Dq no
898to specify that the forwarding server should be bound to the wildcard
899address.
900The argument must be
901.Dq yes
902or
903.Dq no .
904The default is
905.Dq yes .
Damien Millerd3a18572000-06-07 19:55:44 +1000906.It Cm XAuthLocation
907Specifies the location of the
908.Xr xauth 1
909program.
910The default is
911.Pa /usr/X11R6/bin/xauth .
Damien Miller32aa1441999-10-29 09:15:49 +1000912.El
Ben Lindstrom1bda4c82001-06-05 19:59:08 +0000913.Ss Time Formats
914.Pp
915.Nm
916command-line arguments and configuration file options that specify time
917may be expressed using a sequence of the form:
918.Sm off
919.Ar time Oo Ar qualifier Oc ,
920.Sm on
921where
922.Ar time
923is a positive integer value and
924.Ar qualifier
925is one of the following:
926.Pp
927.Bl -tag -width Ds -compact -offset indent
928.It Cm <none>
929seconds
930.It Cm s | Cm S
931seconds
932.It Cm m | Cm M
933minutes
934.It Cm h | Cm H
935hours
936.It Cm d | Cm D
937days
938.It Cm w | Cm W
939weeks
940.El
941.Pp
942Each member of the sequence is added together to calculate
943the total time value.
944.Pp
945Time format examples:
946.Pp
947.Bl -tag -width Ds -compact -offset indent
948.It 600
949600 seconds (10 minutes)
950.It 10m
95110 minutes
952.It 1h30m
9531 hour 30 minutes (90 minutes)
954.El
Damien Miller32aa1441999-10-29 09:15:49 +1000955.Sh LOGIN PROCESS
956When a user successfully logs in,
957.Nm
958does the following:
959.Bl -enum -offset indent
960.It
961If the login is on a tty, and no command has been specified,
Damien Miller22c77262000-04-13 12:26:34 +1000962prints last login time and
Damien Miller32aa1441999-10-29 09:15:49 +1000963.Pa /etc/motd
964(unless prevented in the configuration file or by
965.Pa $HOME/.hushlogin ;
966see the
Damien Miller22c77262000-04-13 12:26:34 +1000967.Sx FILES
Damien Miller32aa1441999-10-29 09:15:49 +1000968section).
969.It
970If the login is on a tty, records login time.
971.It
972Checks
973.Pa /etc/nologin ;
974if it exists, prints contents and quits
975(unless root).
976.It
977Changes to run with normal user privileges.
978.It
979Sets up basic environment.
980.It
981Reads
982.Pa $HOME/.ssh/environment
983if it exists.
984.It
985Changes to user's home directory.
986.It
987If
988.Pa $HOME/.ssh/rc
989exists, runs it; else if
Damien Millerafcc2252002-02-10 18:32:55 +1100990.Pa /etc/ssh/sshrc
Damien Miller32aa1441999-10-29 09:15:49 +1000991exists, runs
Damien Miller450a7a12000-03-26 13:04:51 +1000992it; otherwise runs xauth.
993The
Damien Miller32aa1441999-10-29 09:15:49 +1000994.Dq rc
995files are given the X11
996authentication protocol and cookie in standard input.
997.It
998Runs user's shell or command.
999.El
1000.Sh AUTHORIZED_KEYS FILE FORMAT
Damien Miller32aa1441999-10-29 09:15:49 +10001001.Pa $HOME/.ssh/authorized_keys
Ben Lindstromf96704d2001-06-25 04:17:12 +00001002is the default file that lists the public keys that are
1003permitted for RSA authentication in protocol version 1
1004and for public key authentication (PubkeyAuthentication)
Ben Lindstromc65e6a02001-04-23 13:02:16 +00001005in protocol version 2.
Ben Lindstromf96704d2001-06-25 04:17:12 +00001006.Cm AuthorizedKeysFile
Ben Lindstrombfb3a0e2001-06-05 20:25:05 +00001007may be used to specify an alternative file.
Ben Lindstrom4dccfa52000-12-28 16:40:05 +00001008.Pp
Damien Miller450a7a12000-03-26 13:04:51 +10001009Each line of the file contains one
Damien Miller32aa1441999-10-29 09:15:49 +10001010key (empty lines and lines starting with a
1011.Ql #
1012are ignored as
Damien Miller450a7a12000-03-26 13:04:51 +10001013comments).
Ben Lindstrom4dccfa52000-12-28 16:40:05 +00001014Each RSA public key consists of the following fields, separated by
Damien Miller450a7a12000-03-26 13:04:51 +10001015spaces: options, bits, exponent, modulus, comment.
Ben Lindstrom4dccfa52000-12-28 16:40:05 +00001016Each protocol version 2 public key consists of:
1017options, keytype, base64 encoded key, comment.
1018The options fields
1019are optional; its presence is determined by whether the line starts
Damien Miller32aa1441999-10-29 09:15:49 +10001020with a number or not (the option field never starts with a number).
Ben Lindstrom4dccfa52000-12-28 16:40:05 +00001021The bits, exponent, modulus and comment fields give the RSA key for
1022protocol version 1; the
Damien Miller32aa1441999-10-29 09:15:49 +10001023comment field is not used for anything (but may be convenient for the
1024user to identify the key).
Ben Lindstrom4dccfa52000-12-28 16:40:05 +00001025For protocol version 2 the keytype is
1026.Dq ssh-dss
1027or
1028.Dq ssh-rsa .
Damien Miller32aa1441999-10-29 09:15:49 +10001029.Pp
1030Note that lines in this file are usually several hundred bytes long
Damien Miller450a7a12000-03-26 13:04:51 +10001031(because of the size of the RSA key modulus).
1032You don't want to type them in; instead, copy the
Ben Lindstrom18a82ac2001-04-11 15:59:35 +00001033.Pa identity.pub ,
Ben Lindstrom4dccfa52000-12-28 16:40:05 +00001034.Pa id_dsa.pub
Ben Lindstrom18a82ac2001-04-11 15:59:35 +00001035or the
1036.Pa id_rsa.pub
Damien Miller32aa1441999-10-29 09:15:49 +10001037file and edit it.
1038.Pp
Ben Lindstrom0d0be022002-04-02 20:39:29 +00001039.Nm
1040enforces a minimum RSA key modulus size for protocol 1
1041and protocol 2 keys of 768 bits.
1042.Pp
Damien Miller942da032000-08-18 13:59:06 +10001043The options (if present) consist of comma-separated option
Damien Miller450a7a12000-03-26 13:04:51 +10001044specifications.
1045No spaces are permitted, except within double quotes.
Ben Lindstrom1c0fd092001-09-12 16:36:17 +00001046The following option specifications are supported (note
1047that option keywords are case-insensitive):
Damien Miller32aa1441999-10-29 09:15:49 +10001048.Bl -tag -width Ds
1049.It Cm from="pattern-list"
1050Specifies that in addition to RSA authentication, the canonical name
1051of the remote host must be present in the comma-separated list of
Damien Miller450a7a12000-03-26 13:04:51 +10001052patterns
1053.Pf ( Ql *
1054and
1055.Ql ?
1056serve as wildcards).
1057The list may also contain
1058patterns negated by prefixing them with
1059.Ql ! ;
1060if the canonical host name matches a negated pattern, the key is not accepted.
1061The purpose
Damien Miller32aa1441999-10-29 09:15:49 +10001062of this option is to optionally increase security: RSA authentication
1063by itself does not trust the network or name servers or anything (but
1064the key); however, if somebody somehow steals the key, the key
Damien Miller450a7a12000-03-26 13:04:51 +10001065permits an intruder to log in from anywhere in the world.
1066This additional option makes using a stolen key more difficult (name
Damien Miller32aa1441999-10-29 09:15:49 +10001067servers and/or routers would have to be compromised in addition to
1068just the key).
1069.It Cm command="command"
1070Specifies that the command is executed whenever this key is used for
Damien Miller450a7a12000-03-26 13:04:51 +10001071authentication.
1072The command supplied by the user (if any) is ignored.
Ben Lindstrom23124ea2001-09-14 23:14:25 +00001073The command is run on a pty if the client requests a pty;
Damien Miller450a7a12000-03-26 13:04:51 +10001074otherwise it is run without a tty.
Ben Lindstrom594e2032001-09-12 18:35:30 +00001075If a 8-bit clean channel is required,
1076one must not request a pty or should specify
Damien Miller33804262001-02-04 23:20:18 +11001077.Cm no-pty .
Damien Miller450a7a12000-03-26 13:04:51 +10001078A quote may be included in the command by quoting it with a backslash.
1079This option might be useful
1080to restrict certain RSA keys to perform just a specific operation.
1081An example might be a key that permits remote backups but nothing else.
Damien Miller30c3d422000-05-09 11:02:59 +10001082Note that the client may specify TCP/IP and/or X11
1083forwarding unless they are explicitly prohibited.
Ben Lindstrom20daef72001-09-20 00:54:01 +00001084Note that this option applies to shell, command or subsystem execution.
Damien Miller32aa1441999-10-29 09:15:49 +10001085.It Cm environment="NAME=value"
1086Specifies that the string is to be added to the environment when
Damien Miller450a7a12000-03-26 13:04:51 +10001087logging in using this key.
1088Environment variables set this way
1089override other default environment values.
1090Multiple options of this type are permitted.
Ben Lindstrom38b951c2001-12-06 17:47:47 +00001091This option is automatically disabled if
1092.Cm UseLogin
1093is enabled.
Damien Miller32aa1441999-10-29 09:15:49 +10001094.It Cm no-port-forwarding
1095Forbids TCP/IP forwarding when this key is used for authentication.
Damien Miller450a7a12000-03-26 13:04:51 +10001096Any port forward requests by the client will return an error.
1097This might be used, e.g., in connection with the
Damien Miller32aa1441999-10-29 09:15:49 +10001098.Cm command
1099option.
1100.It Cm no-X11-forwarding
1101Forbids X11 forwarding when this key is used for authentication.
1102Any X11 forward requests by the client will return an error.
1103.It Cm no-agent-forwarding
1104Forbids authentication agent forwarding when this key is used for
1105authentication.
1106.It Cm no-pty
1107Prevents tty allocation (a request to allocate a pty will fail).
Damien Millera243fde2001-03-19 23:16:08 +11001108.It Cm permitopen="host:port"
Ben Lindstrom24643222001-06-25 05:08:11 +00001109Limit local
Damien Millera243fde2001-03-19 23:16:08 +11001110.Li ``ssh -L''
Ben Lindstrom4b3564e2001-04-10 02:41:56 +00001111port forwarding such that it may only connect to the specified host and
Ben Lindstromd71ba572001-09-12 18:03:31 +00001112port.
1113IPv6 addresses can be specified with an alternative syntax:
1114.Ar host/port .
1115Multiple
Damien Millera243fde2001-03-19 23:16:08 +11001116.Cm permitopen
Ben Lindstrom24643222001-06-25 05:08:11 +00001117options may be applied separated by commas. No pattern matching is
1118performed on the specified hostnames, they must be literal domains or
Damien Millera243fde2001-03-19 23:16:08 +11001119addresses.
Damien Miller32aa1441999-10-29 09:15:49 +10001120.El
1121.Ss Examples
11221024 33 12121.\|.\|.\|312314325 ylo@foo.bar
1123.Pp
1124from="*.niksula.hut.fi,!pc.niksula.hut.fi" 1024 35 23.\|.\|.\|2334 ylo@niksula
1125.Pp
1126command="dump /home",no-pty,no-port-forwarding 1024 33 23.\|.\|.\|2323 backup.hut.fi
Damien Millera243fde2001-03-19 23:16:08 +11001127.Pp
1128permitopen="10.2.1.55:80",permitopen="10.2.1.56:25" 1024 33 23.\|.\|.\|2323
Damien Miller32aa1441999-10-29 09:15:49 +10001129.Sh SSH_KNOWN_HOSTS FILE FORMAT
Damien Miller22c77262000-04-13 12:26:34 +10001130The
Damien Miller05eda432002-02-10 18:32:28 +11001131.Pa /etc/ssh/ssh_known_hosts ,
Damien Miller22c77262000-04-13 12:26:34 +10001132and
Ben Lindstromd6481ea2001-06-25 04:37:41 +00001133.Pa $HOME/.ssh/known_hosts
Damien Miller450a7a12000-03-26 13:04:51 +10001134files contain host public keys for all known hosts.
1135The global file should
1136be prepared by the administrator (optional), and the per-user file is
Damien Miller942da032000-08-18 13:59:06 +10001137maintained automatically: whenever the user connects from an unknown host
Damien Miller450a7a12000-03-26 13:04:51 +10001138its key is added to the per-user file.
Damien Miller32aa1441999-10-29 09:15:49 +10001139.Pp
1140Each line in these files contains the following fields: hostnames,
Damien Miller450a7a12000-03-26 13:04:51 +10001141bits, exponent, modulus, comment.
1142The fields are separated by spaces.
Damien Miller32aa1441999-10-29 09:15:49 +10001143.Pp
1144Hostnames is a comma-separated list of patterns ('*' and '?' act as
1145wildcards); each pattern in turn is matched against the canonical host
1146name (when authenticating a client) or against the user-supplied
Damien Miller450a7a12000-03-26 13:04:51 +10001147name (when authenticating a server).
1148A pattern may also be preceded by
Damien Miller32aa1441999-10-29 09:15:49 +10001149.Ql !
1150to indicate negation: if the host name matches a negated
1151pattern, it is not accepted (by that line) even if it matched another
1152pattern on the line.
1153.Pp
Damien Millere247cc42000-05-07 12:03:14 +10001154Bits, exponent, and modulus are taken directly from the RSA host key; they
Damien Miller32aa1441999-10-29 09:15:49 +10001155can be obtained, e.g., from
Damien Miller05eda432002-02-10 18:32:28 +11001156.Pa /etc/ssh/ssh_host_key.pub .
Damien Miller32aa1441999-10-29 09:15:49 +10001157The optional comment field continues to the end of the line, and is not used.
1158.Pp
1159Lines starting with
1160.Ql #
1161and empty lines are ignored as comments.
1162.Pp
1163When performing host authentication, authentication is accepted if any
Damien Miller450a7a12000-03-26 13:04:51 +10001164matching line has the proper key.
1165It is thus permissible (but not
Damien Miller32aa1441999-10-29 09:15:49 +10001166recommended) to have several lines or different host keys for the same
Damien Miller450a7a12000-03-26 13:04:51 +10001167names.
1168This will inevitably happen when short forms of host names
1169from different domains are put in the file.
1170It is possible
Damien Miller32aa1441999-10-29 09:15:49 +10001171that the files contain conflicting information; authentication is
1172accepted if valid information can be found from either file.
1173.Pp
1174Note that the lines in these files are typically hundreds of characters
1175long, and you definitely don't want to type in the host keys by hand.
1176Rather, generate them by a script
Damien Miller22c77262000-04-13 12:26:34 +10001177or by taking
Damien Miller05eda432002-02-10 18:32:28 +11001178.Pa /etc/ssh/ssh_host_key.pub
Damien Miller32aa1441999-10-29 09:15:49 +10001179and adding the host names at the front.
1180.Ss Examples
Ben Lindstromc65e6a02001-04-23 13:02:16 +00001181.Bd -literal
1182closenet,.\|.\|.\|,130.233.208.41 1024 37 159.\|.\|.93 closenet.hut.fi
1183cvs.openbsd.org,199.185.137.3 ssh-rsa AAAA1234.....=
1184.Ed
Damien Miller32aa1441999-10-29 09:15:49 +10001185.Sh FILES
1186.Bl -tag -width Ds
Damien Miller05eda432002-02-10 18:32:28 +11001187.It Pa /etc/ssh/sshd_config
Damien Miller32aa1441999-10-29 09:15:49 +10001188Contains configuration data for
1189.Nm sshd .
1190This file should be writable by root only, but it is recommended
1191(though not necessary) that it be world-readable.
Damien Miller05eda432002-02-10 18:32:28 +11001192.It Pa /etc/ssh/ssh_host_key, /etc/ssh/ssh_host_dsa_key, /etc/ssh/ssh_host_rsa_key
Ben Lindstromc65e6a02001-04-23 13:02:16 +00001193These three files contain the private parts of the host keys.
Ben Lindstromd7f5b512001-03-05 06:57:23 +00001194These files should only be owned by root, readable only by root, and not
Damien Miller32aa1441999-10-29 09:15:49 +10001195accessible to others.
1196Note that
1197.Nm
1198does not start if this file is group/world-accessible.
Damien Miller05eda432002-02-10 18:32:28 +11001199.It Pa /etc/ssh/ssh_host_key.pub, /etc/ssh/ssh_host_dsa_key.pub, /etc/ssh/ssh_host_rsa_key.pub
Ben Lindstromc65e6a02001-04-23 13:02:16 +00001200These three files contain the public parts of the host keys.
Ben Lindstromd7f5b512001-03-05 06:57:23 +00001201These files should be world-readable but writable only by
Damien Miller450a7a12000-03-26 13:04:51 +10001202root.
Ben Lindstromd7f5b512001-03-05 06:57:23 +00001203Their contents should match the respective private parts.
1204These files are not
1205really used for anything; they are provided for the convenience of
1206the user so their contents can be copied to known hosts files.
1207These files are created using
Damien Miller32aa1441999-10-29 09:15:49 +10001208.Xr ssh-keygen 1 .
Ben Lindstromae1c51c2001-06-25 04:14:59 +00001209.It Pa /etc/moduli
Damien Millere39cacc2000-11-29 12:18:44 +11001210Contains Diffie-Hellman groups used for the "Diffie-Hellman Group Exchange".
Damien Miller886c63a2000-01-20 23:13:36 +11001211.It Pa /var/run/sshd.pid
Damien Miller32aa1441999-10-29 09:15:49 +10001212Contains the process ID of the
1213.Nm
1214listening for connections (if there are several daemons running
1215concurrently for different ports, this contains the pid of the one
Damien Miller450a7a12000-03-26 13:04:51 +10001216started last).
Damien Miller942da032000-08-18 13:59:06 +10001217The content of this file is not sensitive; it can be world-readable.
Damien Miller32aa1441999-10-29 09:15:49 +10001218.It Pa $HOME/.ssh/authorized_keys
Ben Lindstromc65e6a02001-04-23 13:02:16 +00001219Lists the public keys (RSA or DSA) that can be used to log into the user's account.
Damien Millere247cc42000-05-07 12:03:14 +10001220This file must be readable by root (which may on some machines imply
1221it being world-readable if the user's home directory resides on an NFS
1222volume).
1223It is recommended that it not be accessible by others.
1224The format of this file is described above.
1225Users will place the contents of their
Ben Lindstromf96704d2001-06-25 04:17:12 +00001226.Pa identity.pub ,
Damien Millere247cc42000-05-07 12:03:14 +10001227.Pa id_dsa.pub
Ben Lindstrom18a82ac2001-04-11 15:59:35 +00001228and/or
1229.Pa id_rsa.pub
Damien Millere247cc42000-05-07 12:03:14 +10001230files into this file, as described in
1231.Xr ssh-keygen 1 .
Damien Miller05eda432002-02-10 18:32:28 +11001232.It Pa "/etc/ssh/ssh_known_hosts" and "$HOME/.ssh/known_hosts"
Damien Miller5ce662a1999-11-11 17:57:39 +11001233These files are consulted when using rhosts with RSA host
Ben Lindstromd6481ea2001-06-25 04:37:41 +00001234authentication or protocol version 2 hostbased authentication
1235to check the public key of the host.
Damien Miller450a7a12000-03-26 13:04:51 +10001236The key must be listed in one of these files to be accepted.
Damien Miller33e511e1999-11-11 11:43:13 +11001237The client uses the same files
Ben Lindstromebd888d2001-03-05 05:49:29 +00001238to verify that it is connecting to the correct remote host.
Damien Miller450a7a12000-03-26 13:04:51 +10001239These files should be writable only by root/the owner.
Damien Miller05eda432002-02-10 18:32:28 +11001240.Pa /etc/ssh/ssh_known_hosts
Damien Miller32aa1441999-10-29 09:15:49 +10001241should be world-readable, and
1242.Pa $HOME/.ssh/known_hosts
1243can but need not be world-readable.
1244.It Pa /etc/nologin
Damien Miller22c77262000-04-13 12:26:34 +10001245If this file exists,
Damien Miller32aa1441999-10-29 09:15:49 +10001246.Nm
Damien Miller450a7a12000-03-26 13:04:51 +10001247refuses to let anyone except root log in.
1248The contents of the file
Damien Miller32aa1441999-10-29 09:15:49 +10001249are displayed to anyone trying to log in, and non-root connections are
Damien Miller450a7a12000-03-26 13:04:51 +10001250refused.
1251The file should be world-readable.
Damien Miller32aa1441999-10-29 09:15:49 +10001252.It Pa /etc/hosts.allow, /etc/hosts.deny
Ben Lindstrom6149a6c2001-10-03 17:15:32 +00001253Access controls that should be enforced by tcp-wrappers are defined here.
1254Further details are described in
Damien Miller32aa1441999-10-29 09:15:49 +10001255.Xr hosts_access 5 .
1256.It Pa $HOME/.rhosts
1257This file contains host-username pairs, separated by a space, one per
Damien Miller450a7a12000-03-26 13:04:51 +10001258line.
1259The given user on the corresponding host is permitted to log in
1260without password.
1261The same file is used by rlogind and rshd.
Damien Miller32aa1441999-10-29 09:15:49 +10001262The file must
1263be writable only by the user; it is recommended that it not be
1264accessible by others.
1265.Pp
Damien Miller450a7a12000-03-26 13:04:51 +10001266If is also possible to use netgroups in the file.
1267Either host or user
Damien Miller32aa1441999-10-29 09:15:49 +10001268name may be of the form +@groupname to specify all hosts or all users
1269in the group.
1270.It Pa $HOME/.shosts
1271For ssh,
1272this file is exactly the same as for
1273.Pa .rhosts .
1274However, this file is
1275not used by rlogin and rshd, so using this permits access using SSH only.
Damien Miller942da032000-08-18 13:59:06 +10001276.It Pa /etc/hosts.equiv
Damien Miller32aa1441999-10-29 09:15:49 +10001277This file is used during
1278.Pa .rhosts
Damien Miller450a7a12000-03-26 13:04:51 +10001279authentication.
1280In the simplest form, this file contains host names, one per line.
1281Users on
Damien Miller32aa1441999-10-29 09:15:49 +10001282those hosts are permitted to log in without a password, provided they
Damien Miller450a7a12000-03-26 13:04:51 +10001283have the same user name on both machines.
1284The host name may also be
Damien Miller32aa1441999-10-29 09:15:49 +10001285followed by a user name; such users are permitted to log in as
1286.Em any
Damien Miller450a7a12000-03-26 13:04:51 +10001287user on this machine (except root).
1288Additionally, the syntax
Damien Miller32aa1441999-10-29 09:15:49 +10001289.Dq +@group
Damien Miller450a7a12000-03-26 13:04:51 +10001290can be used to specify netgroups.
1291Negated entries start with
Damien Miller32aa1441999-10-29 09:15:49 +10001292.Ql \&- .
1293.Pp
1294If the client host/user is successfully matched in this file, login is
1295automatically permitted provided the client and server user names are the
Damien Miller450a7a12000-03-26 13:04:51 +10001296same.
1297Additionally, successful RSA host authentication is normally required.
1298This file must be writable only by root; it is recommended
Damien Miller32aa1441999-10-29 09:15:49 +10001299that it be world-readable.
1300.Pp
1301.Sy "Warning: It is almost never a good idea to use user names in"
1302.Pa hosts.equiv .
1303Beware that it really means that the named user(s) can log in as
1304.Em anybody ,
1305which includes bin, daemon, adm, and other accounts that own critical
Damien Miller450a7a12000-03-26 13:04:51 +10001306binaries and directories.
1307Using a user name practically grants the user root access.
1308The only valid use for user names that I can think
Damien Miller32aa1441999-10-29 09:15:49 +10001309of is in negative entries.
1310.Pp
1311Note that this warning also applies to rsh/rlogin.
Damien Miller886c63a2000-01-20 23:13:36 +11001312.It Pa /etc/shosts.equiv
Damien Miller32aa1441999-10-29 09:15:49 +10001313This is processed exactly as
1314.Pa /etc/hosts.equiv .
1315However, this file may be useful in environments that want to run both
1316rsh/rlogin and ssh.
1317.It Pa $HOME/.ssh/environment
Damien Miller450a7a12000-03-26 13:04:51 +10001318This file is read into the environment at login (if it exists).
1319It can only contain empty lines, comment lines (that start with
Damien Miller32aa1441999-10-29 09:15:49 +10001320.Ql # ) ,
Damien Miller450a7a12000-03-26 13:04:51 +10001321and assignment lines of the form name=value.
1322The file should be writable
Damien Miller32aa1441999-10-29 09:15:49 +10001323only by the user; it need not be readable by anyone else.
1324.It Pa $HOME/.ssh/rc
1325If this file exists, it is run with /bin/sh after reading the
Damien Miller450a7a12000-03-26 13:04:51 +10001326environment files but before starting the user's shell or command.
Ben Lindstroma11e2702002-04-05 22:18:48 +00001327It must not produce any output on stdout; stderr must be used
1328instead.
1329If X11 forwarding is in use, it will receive the "proto cookie" pair in
1330its standard input (and
Damien Miller32aa1441999-10-29 09:15:49 +10001331.Ev DISPLAY
Ben Lindstroma11e2702002-04-05 22:18:48 +00001332in its environment).
1333The script must call
Damien Miller32aa1441999-10-29 09:15:49 +10001334.Xr xauth 1
Ben Lindstroma11e2702002-04-05 22:18:48 +00001335because
1336.Nm
1337will not run xauth automatically to add X11 cookies.
Damien Miller32aa1441999-10-29 09:15:49 +10001338.Pp
1339The primary purpose of this file is to run any initialization routines
1340which may be needed before the user's home directory becomes
1341accessible; AFS is a particular example of such an environment.
1342.Pp
1343This file will probably contain some initialization code followed by
Ben Lindstromc65e6a02001-04-23 13:02:16 +00001344something similar to:
1345.Bd -literal
Ben Lindstroma11e2702002-04-05 22:18:48 +00001346if read proto cookie && [ -n "$DISPLAY" ]; then
1347 if [ `echo $DISPLAY | cut -c1-10` = 'localhost:' ]; then
1348 # X11UseLocalhost=yes
1349 xauth add unix:`echo $DISPLAY |
1350 cut -c11-` $proto $cookie
1351 else
1352 # X11UseLocalhost=no
1353 xauth add $DISPLAY $proto $cookie
Ben Lindstromc65e6a02001-04-23 13:02:16 +00001354 fi
Ben Lindstroma11e2702002-04-05 22:18:48 +00001355fi
Ben Lindstromc65e6a02001-04-23 13:02:16 +00001356.Ed
Damien Miller32aa1441999-10-29 09:15:49 +10001357.Pp
1358If this file does not exist,
Damien Miller05eda432002-02-10 18:32:28 +11001359.Pa /etc/ssh/sshrc
Damien Miller32aa1441999-10-29 09:15:49 +10001360is run, and if that
Ben Lindstroma11e2702002-04-05 22:18:48 +00001361does not exist either, xauth is used to add the cookie.
Damien Miller32aa1441999-10-29 09:15:49 +10001362.Pp
1363This file should be writable only by the user, and need not be
1364readable by anyone else.
Damien Miller05eda432002-02-10 18:32:28 +11001365.It Pa /etc/ssh/sshrc
Damien Miller32aa1441999-10-29 09:15:49 +10001366Like
1367.Pa $HOME/.ssh/rc .
1368This can be used to specify
Damien Miller450a7a12000-03-26 13:04:51 +10001369machine-specific login-time initializations globally.
1370This file should be writable only by root, and should be world-readable.
Damien Miller37023962000-07-11 17:31:38 +10001371.El
Damien Miller0bc1bd82000-11-13 22:57:25 +11001372.Sh AUTHORS
Ben Lindstrom8eec2c82001-01-29 08:39:16 +00001373OpenSSH is a derivative of the original and free
1374ssh 1.2.12 release by Tatu Ylonen.
1375Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
1376Theo de Raadt and Dug Song
1377removed many bugs, re-added newer features and
1378created OpenSSH.
1379Markus Friedl contributed the support for SSH
1380protocol versions 1.5 and 2.0.
Ben Lindstrom000dda52002-03-22 02:33:12 +00001381Niels Provos and Markus Friedl contributed support
1382for privilege separation.
Damien Miller32aa1441999-10-29 09:15:49 +10001383.Sh SEE ALSO
Damien Miller32aa1441999-10-29 09:15:49 +10001384.Xr scp 1 ,
Damien Miller33804262001-02-04 23:20:18 +11001385.Xr sftp 1 ,
Damien Miller32aa1441999-10-29 09:15:49 +10001386.Xr ssh 1 ,
1387.Xr ssh-add 1 ,
1388.Xr ssh-agent 1 ,
1389.Xr ssh-keygen 1 ,
Ben Lindstromc8e29ce2001-08-06 20:55:28 +00001390.Xr login.conf 5 ,
1391.Xr moduli 5 ,
Ben Lindstromd2bf0d62001-06-25 04:10:54 +00001392.Xr sftp-server 8
Ben Lindstrom160ec622001-04-22 17:17:46 +00001393.Rs
1394.%A T. Ylonen
1395.%A T. Kivinen
1396.%A M. Saarinen
1397.%A T. Rinne
1398.%A S. Lehtinen
1399.%T "SSH Protocol Architecture"
Ben Lindstromf1813842002-03-27 17:18:31 +00001400.%N draft-ietf-secsh-architecture-12.txt
1401.%D January 2002
Ben Lindstrom160ec622001-04-22 17:17:46 +00001402.%O work in progress material
1403.Re
Ben Lindstromc65e6a02001-04-23 13:02:16 +00001404.Rs
1405.%A M. Friedl
1406.%A N. Provos
1407.%A W. A. Simpson
1408.%T "Diffie-Hellman Group Exchange for the SSH Transport Layer Protocol"
Ben Lindstromf1813842002-03-27 17:18:31 +00001409.%N draft-ietf-secsh-dh-group-exchange-02.txt
1410.%D January 2002
Ben Lindstromc65e6a02001-04-23 13:02:16 +00001411.%O work in progress material
1412.Re