blob: f2a529dd5ff27d8de4ea7b823de73600e5d5edcd [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 Lindstrombdc2beb2001-04-16 02:11:52 +000037.\" $OpenBSD: sshd.8,v 1.118 2001/04/15 21:41:29 deraadt 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 Lindstromd58eb5f2001-03-07 06:07:22 +000043.Nd OpenSSH ssh daemon
Damien Miller32aa1441999-10-29 09:15:49 +100044.Sh SYNOPSIS
45.Nm sshd
Ben Lindstrom9fce9f02001-04-11 23:10:09 +000046.Op Fl deiqD46
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
52.Op Fl p Ar port
Damien Miller942da032000-08-18 13:59:06 +100053.Op Fl u Ar len
Damien Miller95def091999-11-25 00:26:21 +110054.Op Fl V Ar client_protocol_id
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 ,
121.Xr rexecd 8 ,
122and
123.Xr rexd 8
124are disabled (thus completely disabling
125.Xr rlogin 1
126and
127.Xr rsh 1
Damien Miller35dabd02000-05-01 21:10:33 +1000128into the machine).
Damien Miller32aa1441999-10-29 09:15:49 +1000129.Pp
Damien Millere247cc42000-05-07 12:03:14 +1000130.Ss SSH protocol version 2
131.Pp
Damien Miller942da032000-08-18 13:59:06 +1000132Version 2 works similarly:
Damien Millere247cc42000-05-07 12:03:14 +1000133Each host has a host-specific DSA key used to identify the host.
134However, when the daemon starts, it does not generate a server key.
135Forward security is provided through a Diffie-Hellman key agreement.
136This key agreement results in a shared session key.
Ben Lindstromfd2e05b2001-03-05 07:48:45 +0000137The rest of the session is encrypted using a symmetric cipher, currently
138Blowfish, 3DES, CAST128, Arcfour, 128 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
Damien Miller0bc1bd82000-11-13 22:57:25 +1100146user authentication method (PubkeyAuthentication)
Damien Millere247cc42000-05-07 12:03:14 +1000147and conventional password authentication.
148.Pp
149.Ss Command execution and data forwarding
150.Pp
Damien Miller32aa1441999-10-29 09:15:49 +1000151If the client successfully authenticates itself, a dialog for
Damien Miller450a7a12000-03-26 13:04:51 +1000152preparing the session is entered.
153At this time the client may request
Damien Miller32aa1441999-10-29 09:15:49 +1000154things like allocating a pseudo-tty, forwarding X11 connections,
155forwarding TCP/IP connections, or forwarding the authentication agent
156connection over the secure channel.
157.Pp
158Finally, the client either requests a shell or execution of a command.
Damien Miller450a7a12000-03-26 13:04:51 +1000159The sides then enter session mode.
160In this mode, either side may send
Damien Miller32aa1441999-10-29 09:15:49 +1000161data at any time, and such data is forwarded to/from the shell or
162command on the server side, and the user terminal in the client side.
163.Pp
164When the user program terminates and all forwarded X11 and other
165connections have been closed, the server sends command exit status to
166the client, and both sides exit.
167.Pp
168.Nm
169can be configured using command-line options or a configuration
Damien Miller450a7a12000-03-26 13:04:51 +1000170file.
171Command-line options override values specified in the
Damien Miller32aa1441999-10-29 09:15:49 +1000172configuration file.
173.Pp
Damien Miller6162d121999-11-21 13:23:52 +1100174.Nm
175rereads its configuration file when it receives a hangup signal,
Ben Lindstrom49a098d2001-03-05 06:55:18 +0000176.Dv SIGHUP ,
177by executing itself with the name it was started as, ie.
178.Pa /usr/sbin/sshd .
Damien Miller6162d121999-11-21 13:23:52 +1100179.Pp
Damien Miller32aa1441999-10-29 09:15:49 +1000180The options are as follows:
181.Bl -tag -width Ds
182.It Fl b Ar bits
183Specifies the number of bits in the server key (default 768).
184.Pp
185.It Fl d
Damien Miller450a7a12000-03-26 13:04:51 +1000186Debug mode.
187The server sends verbose debug output to the system
188log, and does not put itself in the background.
189The server also will not fork and will only process one connection.
190This option is only intended for debugging for the server.
Damien Miller874d77b2000-10-14 16:23:11 +1100191Multiple -d options increases the debugging level.
192Maximum is 3.
Damien Miller32aa1441999-10-29 09:15:49 +1000193.It Fl f Ar configuration_file
Damien Miller450a7a12000-03-26 13:04:51 +1000194Specifies the name of the configuration file.
195The default is
Damien Miller886c63a2000-01-20 23:13:36 +1100196.Pa /etc/sshd_config .
Damien Miller32aa1441999-10-29 09:15:49 +1000197.Nm
198refuses to start if there is no configuration file.
199.It Fl g Ar login_grace_time
200Gives the grace time for clients to authenticate themselves (default
Kevin Steves9ce907c2001-01-07 11:53:40 +0000201600 seconds).
Damien Miller450a7a12000-03-26 13:04:51 +1000202If the client fails to authenticate the user within
203this many seconds, the server disconnects and exits.
204A value of zero indicates no limit.
Damien Miller32aa1441999-10-29 09:15:49 +1000205.It Fl h Ar host_key_file
Ben Lindstrom4dccfa52000-12-28 16:40:05 +0000206Specifies the file from which the host key is read (default
Damien Miller886c63a2000-01-20 23:13:36 +1100207.Pa /etc/ssh_host_key ) .
Damien Miller32aa1441999-10-29 09:15:49 +1000208This option must be given if
209.Nm
210is not run as root (as the normal
211host file is normally not readable by anyone but root).
Ben Lindstrom4dccfa52000-12-28 16:40:05 +0000212It is possible to have multiple host key files for
213the different protocol versions.
Damien Miller32aa1441999-10-29 09:15:49 +1000214.It Fl i
215Specifies that
216.Nm
Damien Miller22c77262000-04-13 12:26:34 +1000217is being run from inetd.
Damien Miller32aa1441999-10-29 09:15:49 +1000218.Nm
219is normally not run
220from inetd because it needs to generate the server key before it can
Damien Miller450a7a12000-03-26 13:04:51 +1000221respond to the client, and this may take tens of seconds.
222Clients would have to wait too long if the key was regenerated every time.
Damien Miller7684ee12000-03-17 23:40:15 +1100223However, with small key sizes (e.g., 512) using
Damien Miller32aa1441999-10-29 09:15:49 +1000224.Nm
225from inetd may
226be feasible.
227.It Fl k Ar key_gen_time
228Specifies how often the server key is regenerated (default 3600
Damien Miller450a7a12000-03-26 13:04:51 +1000229seconds, or one hour).
230The motivation for regenerating the key fairly
Damien Miller32aa1441999-10-29 09:15:49 +1000231often is that the key is not stored anywhere, and after about an hour,
232it becomes impossible to recover the key for decrypting intercepted
233communications even if the machine is cracked into or physically
Damien Miller450a7a12000-03-26 13:04:51 +1000234seized.
235A value of zero indicates that the key will never be regenerated.
Damien Miller32aa1441999-10-29 09:15:49 +1000236.It Fl p Ar port
237Specifies the port on which the server listens for connections
238(default 22).
239.It Fl q
Damien Miller450a7a12000-03-26 13:04:51 +1000240Quiet mode.
241Nothing is sent to the system log.
242Normally the beginning,
Damien Miller32aa1441999-10-29 09:15:49 +1000243authentication, and termination of each connection is logged.
Damien Miller942da032000-08-18 13:59:06 +1000244.It Fl u Ar len
245This option is used to specify the size of the field
246in the
247.Li utmp
248structure that holds the remote host name.
249If the resolved host name is longer than
250.Ar len ,
251the dotted decimal value will be used instead.
252This allows hosts with very long host names that
253overflow this field to still be uniquely identified.
254Specifying
255.Fl u0
256indicates that only dotted decimal addresses
257should be put into the
258.Pa utmp
259file.
Ben Lindstrom4dccfa52000-12-28 16:40:05 +0000260.It Fl D
261When this option is specified
262.Nm
263will not detach and does not become a daemon.
264This allows easy monitoring of
265.Nm sshd .
Ben Lindstrom9fce9f02001-04-11 23:10:09 +0000266.It Fl e
267When this option is specified,
268.Nm
269will send the output to the standard error instead of the system log.
Damien Miller95def091999-11-25 00:26:21 +1100270.It Fl V Ar client_protocol_id
Damien Miller874d77b2000-10-14 16:23:11 +1100271SSH-2 compatibility mode.
Damien Miller35dabd02000-05-01 21:10:33 +1000272When this option is specified
Damien Miller95def091999-11-25 00:26:21 +1100273.Nm
Damien Miller35dabd02000-05-01 21:10:33 +1000274assumes the client has sent the supplied version string
Damien Miller95def091999-11-25 00:26:21 +1100275and skips the
276Protocol Version Identification Exchange.
Damien Miller874d77b2000-10-14 16:23:11 +1100277This option is not intended to be called directly.
Damien Miller34132e52000-01-14 15:45:46 +1100278.It Fl 4
279Forces
280.Nm
281to use IPv4 addresses only.
282.It Fl 6
283Forces
284.Nm
285to use IPv6 addresses only.
Damien Miller32aa1441999-10-29 09:15:49 +1000286.El
287.Sh CONFIGURATION FILE
288.Nm
Damien Miller22c77262000-04-13 12:26:34 +1000289reads configuration data from
Damien Miller886c63a2000-01-20 23:13:36 +1100290.Pa /etc/sshd_config
Damien Miller32aa1441999-10-29 09:15:49 +1000291(or the file specified with
292.Fl f
Damien Miller450a7a12000-03-26 13:04:51 +1000293on the command line).
294The file contains keyword-value pairs, one per line.
295Lines starting with
Damien Miller32aa1441999-10-29 09:15:49 +1000296.Ql #
297and empty lines are interpreted as comments.
298.Pp
299The following keywords are possible.
300.Bl -tag -width Ds
301.It Cm AFSTokenPassing
Damien Miller450a7a12000-03-26 13:04:51 +1000302Specifies whether an AFS token may be forwarded to the server.
303Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000304.Dq yes .
305.It Cm AllowGroups
Ben Lindstroma1ebd892001-02-10 22:19:23 +0000306This keyword can be followed by a list of group names, separated
Damien Miller450a7a12000-03-26 13:04:51 +1000307by spaces.
308If specified, login is allowed only for users whose primary
Kevin Steves7b61cfa2001-01-14 19:11:00 +0000309group or supplementary group list matches one of the patterns.
Damien Miller32aa1441999-10-29 09:15:49 +1000310.Ql \&*
311and
312.Ql ?
313can be used as
Damien Miller450a7a12000-03-26 13:04:51 +1000314wildcards in the patterns.
Damien Miller942da032000-08-18 13:59:06 +1000315Only group names are valid; a numerical group ID isn't recognized.
Kevin Steves7b61cfa2001-01-14 19:11:00 +0000316By default login is allowed regardless of the group list.
Damien Miller32aa1441999-10-29 09:15:49 +1000317.Pp
Damien Miller50a41ed2000-10-16 12:14:42 +1100318.It Cm AllowTcpForwarding
319Specifies whether TCP forwarding is permitted.
320The default is
321.Dq yes .
322Note that disabling TCP forwarding does not improve security unless
323users are also denied shell access, as they can always install their
324own forwarders.
325.Pp
Damien Miller32aa1441999-10-29 09:15:49 +1000326.It Cm AllowUsers
Ben Lindstroma1ebd892001-02-10 22:19:23 +0000327This keyword can be followed by a list of user names, separated
Damien Miller450a7a12000-03-26 13:04:51 +1000328by spaces.
329If specified, login is allowed only for users names that
Damien Miller32aa1441999-10-29 09:15:49 +1000330match one of the patterns.
331.Ql \&*
332and
333.Ql ?
334can be used as
Damien Miller450a7a12000-03-26 13:04:51 +1000335wildcards in the patterns.
Damien Miller942da032000-08-18 13:59:06 +1000336Only user names are valid; a numerical user ID isn't recognized.
Damien Miller450a7a12000-03-26 13:04:51 +1000337By default login is allowed regardless of the user name.
Damien Miller32aa1441999-10-29 09:15:49 +1000338.Pp
Ben Lindstrom48bd7c12001-01-09 00:35:42 +0000339.It Cm Banner
340In some jurisdictions, sending a warning message before authentication
341may be relevant for getting legal protection.
342The contents of the specified file are sent to the remote user before
343authentication is allowed.
344This option is only available for protocol version 2.
345.Pp
Ben Lindstromff8b4942001-03-06 01:00:03 +0000346.It Cm ChallengeResponseAuthentication
347Specifies whether
348challenge response
349authentication is allowed.
350Currently there is only support for
351.Xr skey 1
352authentication.
353The default is
354.Dq yes .
Damien Miller22c77262000-04-13 12:26:34 +1000355.It Cm Ciphers
356Specifies the ciphers allowed for protocol version 2.
357Multiple ciphers must be comma-separated.
358The default is
Ben Lindstromc78a1872001-03-06 01:06:58 +0000359.Dq aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour.
Damien Miller32aa1441999-10-29 09:15:49 +1000360.It Cm CheckMail
361Specifies whether
362.Nm
363should check for new mail for interactive logins.
364The default is
365.Dq no .
Ben Lindstrom5744dc42001-04-13 23:28:01 +0000366.It Cm ClientAliveInterval
367Sets a timeout interval in seconds after which if no data has been received
368from the client,
369.Nm
370will send a message through the encrypted
Ben Lindstroma8f39722001-04-16 02:03:49 +0000371channel to request a response from the client.
372The default
Ben Lindstrom5744dc42001-04-13 23:28:01 +0000373is 0, indicating that these messages will not be sent to the client.
Ben Lindstroma8f39722001-04-16 02:03:49 +0000374This option applies to protocol version 2 only.
Ben Lindstrom5744dc42001-04-13 23:28:01 +0000375.It Cm ClientAliveCountMax
376Sets the number of client alive messages (see above) which may be
377sent without
378.Nm
379receiving any messages back from the client. If this threshold is
380reached while client alive messages are being sent,
381.Nm
382will disconnect the client, terminating the session. It is important
383to note that the use of client alive messages is very different from
Ben Lindstroma8f39722001-04-16 02:03:49 +0000384.Cm Keepalive
385(below). The client alive messages are sent through the
Ben Lindstrom5744dc42001-04-13 23:28:01 +0000386encrypted channel and therefore will not be spoofable. The TCP keepalive
Ben Lindstroma8f39722001-04-16 02:03:49 +0000387option enabled by
388.Cm Keepalive
389is spoofable. You want to use the client
Ben Lindstrom5744dc42001-04-13 23:28:01 +0000390alive mechanism when you are basing something important on
391clients having an active connection to the server.
Ben Lindstroma8f39722001-04-16 02:03:49 +0000392.Pp
393The default value is 3. If you set
394.Cm ClientAliveInterval
Ben Lindstrom5744dc42001-04-13 23:28:01 +0000395(above) to 15, and leave this value at the default, unresponsive ssh clients
396will be disconnected after approximately 45 seconds.
Damien Miller32aa1441999-10-29 09:15:49 +1000397.It Cm DenyGroups
398This keyword can be followed by a number of group names, separated
Damien Miller450a7a12000-03-26 13:04:51 +1000399by spaces.
Kevin Steves7b61cfa2001-01-14 19:11:00 +0000400Users whose primary group or supplementary group list matches
401one of the patterns aren't allowed to log in.
Damien Miller32aa1441999-10-29 09:15:49 +1000402.Ql \&*
403and
404.Ql ?
405can be used as
Damien Miller450a7a12000-03-26 13:04:51 +1000406wildcards in the patterns.
Damien Miller942da032000-08-18 13:59:06 +1000407Only group names are valid; a numerical group ID isn't recognized.
Kevin Steves7b61cfa2001-01-14 19:11:00 +0000408By default login is allowed regardless of the group list.
Damien Miller32aa1441999-10-29 09:15:49 +1000409.Pp
410.It Cm DenyUsers
411This keyword can be followed by a number of user names, separated
Damien Miller450a7a12000-03-26 13:04:51 +1000412by spaces.
413Login is disallowed for user names that match one of the patterns.
Damien Miller32aa1441999-10-29 09:15:49 +1000414.Ql \&*
415and
416.Ql ?
Damien Miller450a7a12000-03-26 13:04:51 +1000417can be used as wildcards in the patterns.
Damien Miller942da032000-08-18 13:59:06 +1000418Only user names are valid; a numerical user ID isn't recognized.
Damien Miller450a7a12000-03-26 13:04:51 +1000419By default login is allowed regardless of the user name.
Damien Millere247cc42000-05-07 12:03:14 +1000420.It Cm GatewayPorts
421Specifies whether remote hosts are allowed to connect to ports
422forwarded for the client.
423The argument must be
424.Dq yes
425or
426.Dq no .
427The default is
428.Dq no .
Damien Millere247cc42000-05-07 12:03:14 +1000429.It Cm HostKey
Damien Miller0bc1bd82000-11-13 22:57:25 +1100430Specifies the file containing the private host keys (default
Damien Millere247cc42000-05-07 12:03:14 +1000431.Pa /etc/ssh_host_key )
Damien Miller0bc1bd82000-11-13 22:57:25 +1100432used by SSH protocol versions 1 and 2.
Damien Millere247cc42000-05-07 12:03:14 +1000433Note that
434.Nm
Ben Lindstrom226cfa02001-01-22 05:34:40 +0000435will refuse to use a file if it is group/world-accessible.
Damien Miller0bc1bd82000-11-13 22:57:25 +1100436It is possible to have multiple host key files.
437.Dq rsa1
438keys are used for version 1 and
439.Dq dsa
440or
441.Dq rsa
442are used for version 2 of the SSH protocol.
Damien Miller32aa1441999-10-29 09:15:49 +1000443.It Cm IgnoreRhosts
Damien Miller98c7ad62000-03-09 21:27:49 +1100444Specifies that
445.Pa .rhosts
Damien Miller22c77262000-04-13 12:26:34 +1000446and
Damien Miller98c7ad62000-03-09 21:27:49 +1100447.Pa .shosts
448files will not be used in authentication.
Damien Miller32aa1441999-10-29 09:15:49 +1000449.Pa /etc/hosts.equiv
450and
Damien Miller22c77262000-04-13 12:26:34 +1000451.Pa /etc/shosts.equiv
Damien Miller450a7a12000-03-26 13:04:51 +1000452are still used.
Damien Miller22c77262000-04-13 12:26:34 +1000453The default is
Damien Miller98c7ad62000-03-09 21:27:49 +1100454.Dq yes .
Damien Miller32265091999-11-12 11:33:04 +1100455.It Cm IgnoreUserKnownHosts
456Specifies whether
457.Nm
458should ignore the user's
459.Pa $HOME/.ssh/known_hosts
460during
461.Cm RhostsRSAAuthentication .
462The default is
463.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000464.It Cm KeepAlive
465Specifies whether the system should send keepalive messages to the
Damien Miller450a7a12000-03-26 13:04:51 +1000466other side.
467If they are sent, death of the connection or crash of one
468of the machines will be properly noticed.
469However, this means that
Damien Miller32aa1441999-10-29 09:15:49 +1000470connections will die if the route is down temporarily, and some people
Damien Miller450a7a12000-03-26 13:04:51 +1000471find it annoying.
Damien Miller30c3d422000-05-09 11:02:59 +1000472On the other hand, if keepalives are not sent,
Damien Miller32aa1441999-10-29 09:15:49 +1000473sessions may hang indefinitely on the server, leaving
474.Dq ghost
475users and consuming server resources.
476.Pp
477The default is
478.Dq yes
479(to send keepalives), and the server will notice
Damien Miller450a7a12000-03-26 13:04:51 +1000480if the network goes down or the client host reboots.
481This avoids infinitely hanging sessions.
Damien Miller32aa1441999-10-29 09:15:49 +1000482.Pp
483To disable keepalives, the value should be set to
484.Dq no
485in both the server and the client configuration files.
486.It Cm KerberosAuthentication
Damien Miller450a7a12000-03-26 13:04:51 +1000487Specifies whether Kerberos authentication is allowed.
488This can be in the form of a Kerberos ticket, or if
Damien Miller32aa1441999-10-29 09:15:49 +1000489.Cm PasswordAuthentication
490is yes, the password provided by the user will be validated through
Damien Miller874d77b2000-10-14 16:23:11 +1100491the Kerberos KDC.
492To use this option, the server needs a
Damien Miller942da032000-08-18 13:59:06 +1000493Kerberos servtab which allows the verification of the KDC's identity.
Damien Miller450a7a12000-03-26 13:04:51 +1000494Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000495.Dq yes .
496.It Cm KerberosOrLocalPasswd
497If set then if password authentication through Kerberos fails then
498the password will be validated via any additional local mechanism
499such as
Damien Miller62cee002000-09-23 17:15:56 +1100500.Pa /etc/passwd .
Damien Miller450a7a12000-03-26 13:04:51 +1000501Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000502.Dq yes .
503.It Cm KerberosTgtPassing
504Specifies whether a Kerberos TGT may be forwarded to the server.
Damien Miller22c77262000-04-13 12:26:34 +1000505Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000506.Dq no ,
507as this only works when the Kerberos KDC is actually an AFS kaserver.
508.It Cm KerberosTicketCleanup
509Specifies whether to automatically destroy the user's ticket cache
Damien Miller450a7a12000-03-26 13:04:51 +1000510file on logout.
511Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000512.Dq yes .
513.It Cm KeyRegenerationInterval
514The server key is automatically regenerated after this many seconds
Damien Miller450a7a12000-03-26 13:04:51 +1000515(if it has been used).
516The purpose of regeneration is to prevent
Damien Miller32aa1441999-10-29 09:15:49 +1000517decrypting captured sessions by later breaking into the machine and
Damien Miller450a7a12000-03-26 13:04:51 +1000518stealing the keys.
519The key is never stored anywhere.
520If the value is 0, the key is never regenerated.
521The default is 3600 (seconds).
Damien Miller32aa1441999-10-29 09:15:49 +1000522.It Cm ListenAddress
Ben Lindstrom49e57a82001-04-08 18:02:43 +0000523Specifies the local addresses
Ben Lindstrom1a598a42001-04-10 02:48:50 +0000524.Xr sshd 8
Damien Miller32aa1441999-10-29 09:15:49 +1000525should listen on.
Ben Lindstrom49e57a82001-04-08 18:02:43 +0000526The following forms may be used:
527.Pp
528.Bl -item -offset indent -compact
529.It
530.Cm ListenAddress
Ben Lindstrom1a598a42001-04-10 02:48:50 +0000531.Sm off
532.Ar host No | Ar IPv4_addr No | Ar IPv6_addr
533.Sm on
Ben Lindstrom49e57a82001-04-08 18:02:43 +0000534.It
535.Cm ListenAddress
Ben Lindstrom1a598a42001-04-10 02:48:50 +0000536.Sm off
537.Ar host No | Ar IPv4_addr No : Ar port
538.Sm on
Ben Lindstrom49e57a82001-04-08 18:02:43 +0000539.It
540.Cm ListenAddress
Ben Lindstrom1a598a42001-04-10 02:48:50 +0000541.Sm off
542.Oo
543.Ar host No | Ar IPv6_addr Oc : Ar port
544.Sm on
Ben Lindstrom49e57a82001-04-08 18:02:43 +0000545.El
546.Pp
547If
Ben Lindstrom1a598a42001-04-10 02:48:50 +0000548.Ar port
Ben Lindstrom49e57a82001-04-08 18:02:43 +0000549is not specified,
Ben Lindstrom1a598a42001-04-10 02:48:50 +0000550.Xr sshd 8
Ben Lindstrom49e57a82001-04-08 18:02:43 +0000551will listen on the address and all prior
552.Cm Port
553options specified. The default is to listen on all local
554addresses. Multiple
555.Cm ListenAddress
556options are permitted. Additionally, any
557.Cm Port
558options must precede this option for non port qualified addresses.
Damien Miller32aa1441999-10-29 09:15:49 +1000559.It Cm LoginGraceTime
560The server disconnects after this time if the user has not
Damien Miller450a7a12000-03-26 13:04:51 +1000561successfully logged in.
562If the value is 0, there is no time limit.
Damien Miller32aa1441999-10-29 09:15:49 +1000563The default is 600 (seconds).
Damien Miller5ce662a1999-11-11 17:57:39 +1100564.It Cm LogLevel
565Gives the verbosity level that is used when logging messages from
566.Nm sshd .
567The possible values are:
Ben Lindstromdb65e8f2001-01-19 04:26:52 +0000568QUIET, FATAL, ERROR, INFO, VERBOSE and DEBUG.
569The default is INFO.
Damien Miller5ce662a1999-11-11 17:57:39 +1100570Logging with level DEBUG violates the privacy of users
571and is not recommended.
Ben Lindstrom06b33aa2001-02-15 03:01:59 +0000572.It Cm MACs
573Specifies the available MAC (message authentication code) algorithms.
574The MAC algorithm is used in protocol version 2
575for data integrity protection.
576Multiple algorithms must be comma-separated.
577The default is
578.Pp
579.Bd -literal
Ben Lindstromc78a1872001-03-06 01:06:58 +0000580 ``hmac-md5,hmac-sha1,hmac-ripemd160,hmac-ripemd160@openssh.com,
Ben Lindstrom06b33aa2001-02-15 03:01:59 +0000581 hmac-sha1-96,hmac-md5-96''
582.Ed
Damien Miller37023962000-07-11 17:31:38 +1000583.It Cm MaxStartups
584Specifies the maximum number of concurrent unauthenticated connections to the
585.Nm
586daemon.
587Additional connections will be dropped until authentication succeeds or the
588.Cm LoginGraceTime
589expires for a connection.
590The default is 10.
Damien Miller942da032000-08-18 13:59:06 +1000591.Pp
592Alternatively, random early drop can be enabled by specifying
593the three colon separated values
594.Dq start:rate:full
Damien Miller874d77b2000-10-14 16:23:11 +1100595(e.g., "10:30:60").
Damien Miller942da032000-08-18 13:59:06 +1000596.Nm
Ben Lindstroma7333502001-01-29 08:44:03 +0000597will refuse connection attempts with a probability of
Damien Miller942da032000-08-18 13:59:06 +1000598.Dq rate/100
599(30%)
600if there are currently
601.Dq start
602(10)
603unauthenticated connections.
Ben Lindstroma7333502001-01-29 08:44:03 +0000604The probability increases linearly and all connection attempts
Damien Miller942da032000-08-18 13:59:06 +1000605are refused if the number of unauthenticated connections reaches
606.Dq full
607(60).
Damien Miller32aa1441999-10-29 09:15:49 +1000608.It Cm PasswordAuthentication
609Specifies whether password authentication is allowed.
610The default is
611.Dq yes .
Damien Miller942da032000-08-18 13:59:06 +1000612Note that this option applies to both protocol versions 1 and 2.
Damien Miller32aa1441999-10-29 09:15:49 +1000613.It Cm PermitEmptyPasswords
614When password authentication is allowed, it specifies whether the
Damien Miller450a7a12000-03-26 13:04:51 +1000615server allows login to accounts with empty password strings.
616The default is
Damien Miller98c7ad62000-03-09 21:27:49 +1100617.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000618.It Cm PermitRootLogin
Ben Lindstrom323c98f2001-03-05 07:40:40 +0000619Specifies whether root can login using
Damien Miller32aa1441999-10-29 09:15:49 +1000620.Xr ssh 1 .
621The argument must be
622.Dq yes ,
Ben Lindstromd8a90212001-02-15 03:08:27 +0000623.Dq without-password ,
624.Dq forced-commands-only
Damien Miller32aa1441999-10-29 09:15:49 +1000625or
626.Dq no .
627The default is
628.Dq yes .
Damien Miller32aa1441999-10-29 09:15:49 +1000629.Pp
Ben Lindstromd8a90212001-02-15 03:08:27 +0000630If this option is set to
631.Dq without-password
632password authentication is disabled for root.
633.Pp
634If this option is set to
635.Dq forced-commands-only
636root login with public key authentication will be allowed,
637but only if the
Damien Miller32aa1441999-10-29 09:15:49 +1000638.Ar command
Ben Lindstromd8a90212001-02-15 03:08:27 +0000639option has been specified
Damien Miller32aa1441999-10-29 09:15:49 +1000640(which may be useful for taking remote backups even if root login is
Ben Lindstromd8a90212001-02-15 03:08:27 +0000641normally not allowed). All other authentication methods are disabled
642for root.
Ben Lindstrom323c98f2001-03-05 07:40:40 +0000643.Pp
644If this option is set to
645.Dq no
646root is not allowed to login.
Damien Miller6f83b8e2000-05-02 09:23:45 +1000647.It Cm PidFile
648Specifies the file that contains the process identifier of the
649.Nm
650daemon.
651The default is
652.Pa /var/run/sshd.pid .
Damien Miller32aa1441999-10-29 09:15:49 +1000653.It Cm Port
654Specifies the port number that
655.Nm
Damien Miller450a7a12000-03-26 13:04:51 +1000656listens on.
657The default is 22.
Damien Miller34132e52000-01-14 15:45:46 +1100658Multiple options of this type are permitted.
Ben Lindstrom7bfff362001-03-26 05:45:53 +0000659.It Cm PrintLastLog
660Specifies whether
661.Nm
662should print the date and time when the user last logged in.
663The default is
664.Dq yes .
Damien Miller32aa1441999-10-29 09:15:49 +1000665.It Cm PrintMotd
666Specifies whether
667.Nm
Damien Miller22c77262000-04-13 12:26:34 +1000668should print
Damien Miller32aa1441999-10-29 09:15:49 +1000669.Pa /etc/motd
Damien Miller450a7a12000-03-26 13:04:51 +1000670when a user logs in interactively.
671(On some systems it is also printed by the shell,
Damien Miller32aa1441999-10-29 09:15:49 +1000672.Pa /etc/profile ,
Damien Miller450a7a12000-03-26 13:04:51 +1000673or equivalent.)
674The default is
Damien Miller32aa1441999-10-29 09:15:49 +1000675.Dq yes .
Damien Miller22c77262000-04-13 12:26:34 +1000676.It Cm Protocol
677Specifies the protocol versions
678.Nm
679should support.
680The possible values are
681.Dq 1
682and
683.Dq 2 .
684Multiple versions must be comma-separated.
685The default is
Ben Lindstrombdc2beb2001-04-16 02:11:52 +0000686.Dq 2,1 .
Ben Lindstromff8b4942001-03-06 01:00:03 +0000687.It Cm PubkeyAuthentication
688Specifies whether public key authentication is allowed.
689The default is
690.Dq yes .
691Note that this option applies to protocol version 2 only.
Damien Miller33804262001-02-04 23:20:18 +1100692.It Cm ReverseMappingCheck
693Specifies whether
694.Nm
695should try to verify the remote host name and check that
696the resolved host name for the remote IP address maps back to the
697very same IP address.
698The default is
699.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000700.It Cm RhostsAuthentication
701Specifies whether authentication using rhosts or /etc/hosts.equiv
Damien Miller450a7a12000-03-26 13:04:51 +1000702files is sufficient.
703Normally, this method should not be permitted because it is insecure.
Damien Miller32aa1441999-10-29 09:15:49 +1000704.Cm RhostsRSAAuthentication
705should be used
706instead, because it performs RSA-based host authentication in addition
707to normal rhosts or /etc/hosts.equiv authentication.
708The default is
709.Dq no .
710.It Cm RhostsRSAAuthentication
711Specifies whether rhosts or /etc/hosts.equiv authentication together
Damien Miller450a7a12000-03-26 13:04:51 +1000712with successful RSA host authentication is allowed.
713The default is
Damien Miller98c7ad62000-03-09 21:27:49 +1100714.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000715.It Cm RSAAuthentication
Damien Miller450a7a12000-03-26 13:04:51 +1000716Specifies whether pure RSA authentication is allowed.
717The default is
Damien Miller32aa1441999-10-29 09:15:49 +1000718.Dq yes .
Damien Millere247cc42000-05-07 12:03:14 +1000719Note that this option applies to protocol version 1 only.
Damien Miller32aa1441999-10-29 09:15:49 +1000720.It Cm ServerKeyBits
Damien Miller450a7a12000-03-26 13:04:51 +1000721Defines the number of bits in the server key.
722The minimum value is 512, and the default is 768.
Damien Miller32aa1441999-10-29 09:15:49 +1000723.It Cm StrictModes
724Specifies whether
725.Nm
726should check file modes and ownership of the
Damien Miller450a7a12000-03-26 13:04:51 +1000727user's files and home directory before accepting login.
728This is normally desirable because novices sometimes accidentally leave their
729directory or files world-writable.
730The default is
Damien Miller32aa1441999-10-29 09:15:49 +1000731.Dq yes .
Damien Millerf6d9e222000-06-18 14:50:44 +1000732.It Cm Subsystem
Damien Miller874d77b2000-10-14 16:23:11 +1100733Configures an external subsystem (e.g., file transfer daemon).
734Arguments should be a subsystem name and a command to execute upon subsystem
735request.
Damien Miller7b28dc52000-09-05 13:34:53 +1100736The command
737.Xr sftp-server 8
738implements the
739.Dq sftp
740file transfer subsystem.
Damien Millerf6d9e222000-06-18 14:50:44 +1000741By default no subsystems are defined.
742Note that this option applies to protocol version 2 only.
Damien Miller32aa1441999-10-29 09:15:49 +1000743.It Cm SyslogFacility
744Gives the facility code that is used when logging messages from
745.Nm sshd .
746The possible values are: DAEMON, USER, AUTH, LOCAL0, LOCAL1, LOCAL2,
Damien Miller450a7a12000-03-26 13:04:51 +1000747LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7.
748The default is AUTH.
Damien Miller32aa1441999-10-29 09:15:49 +1000749.It Cm UseLogin
750Specifies whether
751.Xr login 1
Damien Millerd3a18572000-06-07 19:55:44 +1000752is used for interactive login sessions.
753Note that
754.Xr login 1
Damien Miller942da032000-08-18 13:59:06 +1000755is never used for remote command execution.
Damien Miller450a7a12000-03-26 13:04:51 +1000756The default is
Damien Miller32aa1441999-10-29 09:15:49 +1000757.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000758.It Cm X11DisplayOffset
759Specifies the first display number available for
760.Nm sshd Ns 's
Damien Miller450a7a12000-03-26 13:04:51 +1000761X11 forwarding.
762This prevents
Damien Miller32aa1441999-10-29 09:15:49 +1000763.Nm
764from interfering with real X11 servers.
Damien Miller98c7ad62000-03-09 21:27:49 +1100765The default is 10.
Damien Miller396691a2000-01-20 22:44:08 +1100766.It Cm X11Forwarding
Damien Miller450a7a12000-03-26 13:04:51 +1000767Specifies whether X11 forwarding is permitted.
768The default is
Damien Miller98c7ad62000-03-09 21:27:49 +1100769.Dq no .
Damien Miller396691a2000-01-20 22:44:08 +1100770Note that disabling X11 forwarding does not improve security in any
771way, as users can always install their own forwarders.
Damien Millerd3a18572000-06-07 19:55:44 +1000772.It Cm XAuthLocation
773Specifies the location of the
774.Xr xauth 1
775program.
776The default is
777.Pa /usr/X11R6/bin/xauth .
Damien Miller32aa1441999-10-29 09:15:49 +1000778.El
779.Sh LOGIN PROCESS
780When a user successfully logs in,
781.Nm
782does the following:
783.Bl -enum -offset indent
784.It
785If the login is on a tty, and no command has been specified,
Damien Miller22c77262000-04-13 12:26:34 +1000786prints last login time and
Damien Miller32aa1441999-10-29 09:15:49 +1000787.Pa /etc/motd
788(unless prevented in the configuration file or by
789.Pa $HOME/.hushlogin ;
790see the
Damien Miller22c77262000-04-13 12:26:34 +1000791.Sx FILES
Damien Miller32aa1441999-10-29 09:15:49 +1000792section).
793.It
794If the login is on a tty, records login time.
795.It
796Checks
797.Pa /etc/nologin ;
798if it exists, prints contents and quits
799(unless root).
800.It
801Changes to run with normal user privileges.
802.It
803Sets up basic environment.
804.It
805Reads
806.Pa $HOME/.ssh/environment
807if it exists.
808.It
809Changes to user's home directory.
810.It
811If
812.Pa $HOME/.ssh/rc
813exists, runs it; else if
Damien Miller886c63a2000-01-20 23:13:36 +1100814.Pa /etc/sshrc
Damien Miller32aa1441999-10-29 09:15:49 +1000815exists, runs
Damien Miller450a7a12000-03-26 13:04:51 +1000816it; otherwise runs xauth.
817The
Damien Miller32aa1441999-10-29 09:15:49 +1000818.Dq rc
819files are given the X11
820authentication protocol and cookie in standard input.
821.It
822Runs user's shell or command.
823.El
824.Sh AUTHORIZED_KEYS FILE FORMAT
Damien Miller22c77262000-04-13 12:26:34 +1000825The
Damien Miller32aa1441999-10-29 09:15:49 +1000826.Pa $HOME/.ssh/authorized_keys
827file lists the RSA keys that are
Damien Millere247cc42000-05-07 12:03:14 +1000828permitted for RSA authentication in SSH protocols 1.3 and 1.5
Damien Miller30c3d422000-05-09 11:02:59 +1000829Similarly, the
Damien Millere247cc42000-05-07 12:03:14 +1000830.Pa $HOME/.ssh/authorized_keys2
Ben Lindstrom4dccfa52000-12-28 16:40:05 +0000831file lists the DSA and RSA keys that are
832permitted for public key authentication (PubkeyAuthentication)
833in SSH protocol 2.0.
834.Pp
Damien Miller450a7a12000-03-26 13:04:51 +1000835Each line of the file contains one
Damien Miller32aa1441999-10-29 09:15:49 +1000836key (empty lines and lines starting with a
837.Ql #
838are ignored as
Damien Miller450a7a12000-03-26 13:04:51 +1000839comments).
Ben Lindstrom4dccfa52000-12-28 16:40:05 +0000840Each RSA public key consists of the following fields, separated by
Damien Miller450a7a12000-03-26 13:04:51 +1000841spaces: options, bits, exponent, modulus, comment.
Ben Lindstrom4dccfa52000-12-28 16:40:05 +0000842Each protocol version 2 public key consists of:
843options, keytype, base64 encoded key, comment.
844The options fields
845are optional; its presence is determined by whether the line starts
Damien Miller32aa1441999-10-29 09:15:49 +1000846with a number or not (the option field never starts with a number).
Ben Lindstrom4dccfa52000-12-28 16:40:05 +0000847The bits, exponent, modulus and comment fields give the RSA key for
848protocol version 1; the
Damien Miller32aa1441999-10-29 09:15:49 +1000849comment field is not used for anything (but may be convenient for the
850user to identify the key).
Ben Lindstrom4dccfa52000-12-28 16:40:05 +0000851For protocol version 2 the keytype is
852.Dq ssh-dss
853or
854.Dq ssh-rsa .
Damien Miller32aa1441999-10-29 09:15:49 +1000855.Pp
856Note that lines in this file are usually several hundred bytes long
Damien Miller450a7a12000-03-26 13:04:51 +1000857(because of the size of the RSA key modulus).
858You don't want to type them in; instead, copy the
Ben Lindstrom18a82ac2001-04-11 15:59:35 +0000859.Pa identity.pub ,
Ben Lindstrom4dccfa52000-12-28 16:40:05 +0000860.Pa id_dsa.pub
Ben Lindstrom18a82ac2001-04-11 15:59:35 +0000861or the
862.Pa id_rsa.pub
Damien Miller32aa1441999-10-29 09:15:49 +1000863file and edit it.
864.Pp
Damien Miller942da032000-08-18 13:59:06 +1000865The options (if present) consist of comma-separated option
Damien Miller450a7a12000-03-26 13:04:51 +1000866specifications.
867No spaces are permitted, except within double quotes.
Damien Miller32aa1441999-10-29 09:15:49 +1000868The following option specifications are supported:
869.Bl -tag -width Ds
870.It Cm from="pattern-list"
871Specifies that in addition to RSA authentication, the canonical name
872of the remote host must be present in the comma-separated list of
Damien Miller450a7a12000-03-26 13:04:51 +1000873patterns
874.Pf ( Ql *
875and
876.Ql ?
877serve as wildcards).
878The list may also contain
879patterns negated by prefixing them with
880.Ql ! ;
881if the canonical host name matches a negated pattern, the key is not accepted.
882The purpose
Damien Miller32aa1441999-10-29 09:15:49 +1000883of this option is to optionally increase security: RSA authentication
884by itself does not trust the network or name servers or anything (but
885the key); however, if somebody somehow steals the key, the key
Damien Miller450a7a12000-03-26 13:04:51 +1000886permits an intruder to log in from anywhere in the world.
887This additional option makes using a stolen key more difficult (name
Damien Miller32aa1441999-10-29 09:15:49 +1000888servers and/or routers would have to be compromised in addition to
889just the key).
890.It Cm command="command"
891Specifies that the command is executed whenever this key is used for
Damien Miller450a7a12000-03-26 13:04:51 +1000892authentication.
893The command supplied by the user (if any) is ignored.
Damien Miller32aa1441999-10-29 09:15:49 +1000894The command is run on a pty if the connection requests a pty;
Damien Miller450a7a12000-03-26 13:04:51 +1000895otherwise it is run without a tty.
Damien Miller33804262001-02-04 23:20:18 +1100896Note that if you want a 8-bit clean channel,
897you must not request a pty or should specify
898.Cm no-pty .
Damien Miller450a7a12000-03-26 13:04:51 +1000899A quote may be included in the command by quoting it with a backslash.
900This option might be useful
901to restrict certain RSA keys to perform just a specific operation.
902An example might be a key that permits remote backups but nothing else.
Damien Miller30c3d422000-05-09 11:02:59 +1000903Note that the client may specify TCP/IP and/or X11
904forwarding unless they are explicitly prohibited.
Damien Miller32aa1441999-10-29 09:15:49 +1000905.It Cm environment="NAME=value"
906Specifies that the string is to be added to the environment when
Damien Miller450a7a12000-03-26 13:04:51 +1000907logging in using this key.
908Environment variables set this way
909override other default environment values.
910Multiple options of this type are permitted.
Damien Miller32aa1441999-10-29 09:15:49 +1000911.It Cm no-port-forwarding
912Forbids TCP/IP forwarding when this key is used for authentication.
Damien Miller450a7a12000-03-26 13:04:51 +1000913Any port forward requests by the client will return an error.
914This might be used, e.g., in connection with the
Damien Miller32aa1441999-10-29 09:15:49 +1000915.Cm command
916option.
917.It Cm no-X11-forwarding
918Forbids X11 forwarding when this key is used for authentication.
919Any X11 forward requests by the client will return an error.
920.It Cm no-agent-forwarding
921Forbids authentication agent forwarding when this key is used for
922authentication.
923.It Cm no-pty
924Prevents tty allocation (a request to allocate a pty will fail).
Damien Millera243fde2001-03-19 23:16:08 +1100925.It Cm permitopen="host:port"
926Limit local
927.Li ``ssh -L''
Ben Lindstrom4b3564e2001-04-10 02:41:56 +0000928port forwarding such that it may only connect to the specified host and
Damien Millera243fde2001-03-19 23:16:08 +1100929port. Multiple
930.Cm permitopen
Ben Lindstrom4b3564e2001-04-10 02:41:56 +0000931options may be applied separated by commas. No pattern matching is
Damien Millera243fde2001-03-19 23:16:08 +1100932performed on the specified hostnames, they must be literal domains or
933addresses.
Damien Miller32aa1441999-10-29 09:15:49 +1000934.El
935.Ss Examples
9361024 33 12121.\|.\|.\|312314325 ylo@foo.bar
937.Pp
938from="*.niksula.hut.fi,!pc.niksula.hut.fi" 1024 35 23.\|.\|.\|2334 ylo@niksula
939.Pp
940command="dump /home",no-pty,no-port-forwarding 1024 33 23.\|.\|.\|2323 backup.hut.fi
Damien Millera243fde2001-03-19 23:16:08 +1100941.Pp
942permitopen="10.2.1.55:80",permitopen="10.2.1.56:25" 1024 33 23.\|.\|.\|2323
Damien Miller32aa1441999-10-29 09:15:49 +1000943.Sh SSH_KNOWN_HOSTS FILE FORMAT
Damien Miller22c77262000-04-13 12:26:34 +1000944The
Damien Millere247cc42000-05-07 12:03:14 +1000945.Pa /etc/ssh_known_hosts ,
946.Pa /etc/ssh_known_hosts2 ,
947.Pa $HOME/.ssh/known_hosts ,
Damien Miller22c77262000-04-13 12:26:34 +1000948and
Damien Millere247cc42000-05-07 12:03:14 +1000949.Pa $HOME/.ssh/known_hosts2
Damien Miller450a7a12000-03-26 13:04:51 +1000950files contain host public keys for all known hosts.
951The global file should
952be prepared by the administrator (optional), and the per-user file is
Damien Miller942da032000-08-18 13:59:06 +1000953maintained automatically: whenever the user connects from an unknown host
Damien Miller450a7a12000-03-26 13:04:51 +1000954its key is added to the per-user file.
Damien Miller32aa1441999-10-29 09:15:49 +1000955.Pp
956Each line in these files contains the following fields: hostnames,
Damien Miller450a7a12000-03-26 13:04:51 +1000957bits, exponent, modulus, comment.
958The fields are separated by spaces.
Damien Miller32aa1441999-10-29 09:15:49 +1000959.Pp
960Hostnames is a comma-separated list of patterns ('*' and '?' act as
961wildcards); each pattern in turn is matched against the canonical host
962name (when authenticating a client) or against the user-supplied
Damien Miller450a7a12000-03-26 13:04:51 +1000963name (when authenticating a server).
964A pattern may also be preceded by
Damien Miller32aa1441999-10-29 09:15:49 +1000965.Ql !
966to indicate negation: if the host name matches a negated
967pattern, it is not accepted (by that line) even if it matched another
968pattern on the line.
969.Pp
Damien Millere247cc42000-05-07 12:03:14 +1000970Bits, exponent, and modulus are taken directly from the RSA host key; they
Damien Miller32aa1441999-10-29 09:15:49 +1000971can be obtained, e.g., from
Damien Miller886c63a2000-01-20 23:13:36 +1100972.Pa /etc/ssh_host_key.pub .
Damien Miller32aa1441999-10-29 09:15:49 +1000973The optional comment field continues to the end of the line, and is not used.
974.Pp
975Lines starting with
976.Ql #
977and empty lines are ignored as comments.
978.Pp
979When performing host authentication, authentication is accepted if any
Damien Miller450a7a12000-03-26 13:04:51 +1000980matching line has the proper key.
981It is thus permissible (but not
Damien Miller32aa1441999-10-29 09:15:49 +1000982recommended) to have several lines or different host keys for the same
Damien Miller450a7a12000-03-26 13:04:51 +1000983names.
984This will inevitably happen when short forms of host names
985from different domains are put in the file.
986It is possible
Damien Miller32aa1441999-10-29 09:15:49 +1000987that the files contain conflicting information; authentication is
988accepted if valid information can be found from either file.
989.Pp
990Note that the lines in these files are typically hundreds of characters
991long, and you definitely don't want to type in the host keys by hand.
992Rather, generate them by a script
Damien Miller22c77262000-04-13 12:26:34 +1000993or by taking
Damien Miller886c63a2000-01-20 23:13:36 +1100994.Pa /etc/ssh_host_key.pub
Damien Miller32aa1441999-10-29 09:15:49 +1000995and adding the host names at the front.
996.Ss Examples
997closenet,closenet.hut.fi,.\|.\|.\|,130.233.208.41 1024 37 159.\|.\|.93 closenet.hut.fi
998.Sh FILES
999.Bl -tag -width Ds
Damien Miller886c63a2000-01-20 23:13:36 +11001000.It Pa /etc/sshd_config
Damien Miller32aa1441999-10-29 09:15:49 +10001001Contains configuration data for
1002.Nm sshd .
1003This file should be writable by root only, but it is recommended
1004(though not necessary) that it be world-readable.
Ben Lindstromd7f5b512001-03-05 06:57:23 +00001005.It Pa /etc/ssh_host_key, /etc/ssh_host_dsa_key, /etc/ssh_host_rsa_key
1006These three files contain the private parts of the
1007(SSH1, SSH2 DSA, and SSH2 RSA) host keys.
1008These files should only be owned by root, readable only by root, and not
Damien Miller32aa1441999-10-29 09:15:49 +10001009accessible to others.
1010Note that
1011.Nm
1012does not start if this file is group/world-accessible.
Ben Lindstromd7f5b512001-03-05 06:57:23 +00001013.It Pa /etc/ssh_host_key.pub, /etc/ssh_host_dsa_key.pub, /etc/ssh_host_rsa_key.pub
Ben Lindstrom55b99e32001-04-02 18:18:21 +00001014These three files contain the public parts of the
Ben Lindstromd7f5b512001-03-05 06:57:23 +00001015(SSH1, SSH2 DSA, and SSH2 RSA) host keys.
1016These files should be world-readable but writable only by
Damien Miller450a7a12000-03-26 13:04:51 +10001017root.
Ben Lindstromd7f5b512001-03-05 06:57:23 +00001018Their contents should match the respective private parts.
1019These files are not
1020really used for anything; they are provided for the convenience of
1021the user so their contents can be copied to known hosts files.
1022These files are created using
Damien Miller32aa1441999-10-29 09:15:49 +10001023.Xr ssh-keygen 1 .
Damien Millere39cacc2000-11-29 12:18:44 +11001024.It Pa /etc/primes
1025Contains Diffie-Hellman groups used for the "Diffie-Hellman Group Exchange".
Damien Miller886c63a2000-01-20 23:13:36 +11001026.It Pa /var/run/sshd.pid
Damien Miller32aa1441999-10-29 09:15:49 +10001027Contains the process ID of the
1028.Nm
1029listening for connections (if there are several daemons running
1030concurrently for different ports, this contains the pid of the one
Damien Miller450a7a12000-03-26 13:04:51 +10001031started last).
Damien Miller942da032000-08-18 13:59:06 +10001032The content of this file is not sensitive; it can be world-readable.
Damien Miller32aa1441999-10-29 09:15:49 +10001033.It Pa $HOME/.ssh/authorized_keys
1034Lists the RSA keys that can be used to log into the user's account.
1035This file must be readable by root (which may on some machines imply
1036it being world-readable if the user's home directory resides on an NFS
Damien Miller450a7a12000-03-26 13:04:51 +10001037volume).
1038It is recommended that it not be accessible by others.
1039The format of this file is described above.
Damien Millere247cc42000-05-07 12:03:14 +10001040Users will place the contents of their
1041.Pa identity.pub
1042files into this file, as described in
1043.Xr ssh-keygen 1 .
1044.It Pa $HOME/.ssh/authorized_keys2
1045Lists the DSA keys that can be used to log into the user's account.
1046This file must be readable by root (which may on some machines imply
1047it being world-readable if the user's home directory resides on an NFS
1048volume).
1049It is recommended that it not be accessible by others.
1050The format of this file is described above.
1051Users will place the contents of their
1052.Pa id_dsa.pub
Ben Lindstrom18a82ac2001-04-11 15:59:35 +00001053and/or
1054.Pa id_rsa.pub
Damien Millere247cc42000-05-07 12:03:14 +10001055files into this file, as described in
1056.Xr ssh-keygen 1 .
Damien Miller886c63a2000-01-20 23:13:36 +11001057.It Pa "/etc/ssh_known_hosts" and "$HOME/.ssh/known_hosts"
Damien Miller5ce662a1999-11-11 17:57:39 +11001058These files are consulted when using rhosts with RSA host
Damien Miller450a7a12000-03-26 13:04:51 +10001059authentication to check the public key of the host.
1060The key must be listed in one of these files to be accepted.
Damien Miller33e511e1999-11-11 11:43:13 +11001061The client uses the same files
Ben Lindstromebd888d2001-03-05 05:49:29 +00001062to verify that it is connecting to the correct remote host.
Damien Miller450a7a12000-03-26 13:04:51 +10001063These files should be writable only by root/the owner.
Damien Miller886c63a2000-01-20 23:13:36 +11001064.Pa /etc/ssh_known_hosts
Damien Miller32aa1441999-10-29 09:15:49 +10001065should be world-readable, and
1066.Pa $HOME/.ssh/known_hosts
1067can but need not be world-readable.
1068.It Pa /etc/nologin
Damien Miller22c77262000-04-13 12:26:34 +10001069If this file exists,
Damien Miller32aa1441999-10-29 09:15:49 +10001070.Nm
Damien Miller450a7a12000-03-26 13:04:51 +10001071refuses to let anyone except root log in.
1072The contents of the file
Damien Miller32aa1441999-10-29 09:15:49 +10001073are displayed to anyone trying to log in, and non-root connections are
Damien Miller450a7a12000-03-26 13:04:51 +10001074refused.
1075The file should be world-readable.
Damien Miller32aa1441999-10-29 09:15:49 +10001076.It Pa /etc/hosts.allow, /etc/hosts.deny
1077If compiled with
1078.Sy LIBWRAP
1079support, tcp-wrappers access controls may be defined here as described in
1080.Xr hosts_access 5 .
1081.It Pa $HOME/.rhosts
1082This file contains host-username pairs, separated by a space, one per
Damien Miller450a7a12000-03-26 13:04:51 +10001083line.
1084The given user on the corresponding host is permitted to log in
1085without password.
1086The same file is used by rlogind and rshd.
Damien Miller32aa1441999-10-29 09:15:49 +10001087The file must
1088be writable only by the user; it is recommended that it not be
1089accessible by others.
1090.Pp
Damien Miller450a7a12000-03-26 13:04:51 +10001091If is also possible to use netgroups in the file.
1092Either host or user
Damien Miller32aa1441999-10-29 09:15:49 +10001093name may be of the form +@groupname to specify all hosts or all users
1094in the group.
1095.It Pa $HOME/.shosts
1096For ssh,
1097this file is exactly the same as for
1098.Pa .rhosts .
1099However, this file is
1100not used by rlogin and rshd, so using this permits access using SSH only.
Damien Miller942da032000-08-18 13:59:06 +10001101.It Pa /etc/hosts.equiv
Damien Miller32aa1441999-10-29 09:15:49 +10001102This file is used during
1103.Pa .rhosts
Damien Miller450a7a12000-03-26 13:04:51 +10001104authentication.
1105In the simplest form, this file contains host names, one per line.
1106Users on
Damien Miller32aa1441999-10-29 09:15:49 +10001107those hosts are permitted to log in without a password, provided they
Damien Miller450a7a12000-03-26 13:04:51 +10001108have the same user name on both machines.
1109The host name may also be
Damien Miller32aa1441999-10-29 09:15:49 +10001110followed by a user name; such users are permitted to log in as
1111.Em any
Damien Miller450a7a12000-03-26 13:04:51 +10001112user on this machine (except root).
1113Additionally, the syntax
Damien Miller32aa1441999-10-29 09:15:49 +10001114.Dq +@group
Damien Miller450a7a12000-03-26 13:04:51 +10001115can be used to specify netgroups.
1116Negated entries start with
Damien Miller32aa1441999-10-29 09:15:49 +10001117.Ql \&- .
1118.Pp
1119If the client host/user is successfully matched in this file, login is
1120automatically permitted provided the client and server user names are the
Damien Miller450a7a12000-03-26 13:04:51 +10001121same.
1122Additionally, successful RSA host authentication is normally required.
1123This file must be writable only by root; it is recommended
Damien Miller32aa1441999-10-29 09:15:49 +10001124that it be world-readable.
1125.Pp
1126.Sy "Warning: It is almost never a good idea to use user names in"
1127.Pa hosts.equiv .
1128Beware that it really means that the named user(s) can log in as
1129.Em anybody ,
1130which includes bin, daemon, adm, and other accounts that own critical
Damien Miller450a7a12000-03-26 13:04:51 +10001131binaries and directories.
1132Using a user name practically grants the user root access.
1133The only valid use for user names that I can think
Damien Miller32aa1441999-10-29 09:15:49 +10001134of is in negative entries.
1135.Pp
1136Note that this warning also applies to rsh/rlogin.
Damien Miller886c63a2000-01-20 23:13:36 +11001137.It Pa /etc/shosts.equiv
Damien Miller32aa1441999-10-29 09:15:49 +10001138This is processed exactly as
1139.Pa /etc/hosts.equiv .
1140However, this file may be useful in environments that want to run both
1141rsh/rlogin and ssh.
1142.It Pa $HOME/.ssh/environment
Damien Miller450a7a12000-03-26 13:04:51 +10001143This file is read into the environment at login (if it exists).
1144It can only contain empty lines, comment lines (that start with
Damien Miller32aa1441999-10-29 09:15:49 +10001145.Ql # ) ,
Damien Miller450a7a12000-03-26 13:04:51 +10001146and assignment lines of the form name=value.
1147The file should be writable
Damien Miller32aa1441999-10-29 09:15:49 +10001148only by the user; it need not be readable by anyone else.
1149.It Pa $HOME/.ssh/rc
1150If this file exists, it is run with /bin/sh after reading the
Damien Miller450a7a12000-03-26 13:04:51 +10001151environment files but before starting the user's shell or command.
1152If X11 spoofing is in use, this will receive the "proto cookie" pair in
Damien Miller32aa1441999-10-29 09:15:49 +10001153standard input (and
1154.Ev DISPLAY
Damien Miller450a7a12000-03-26 13:04:51 +10001155in environment).
1156This must call
Damien Miller32aa1441999-10-29 09:15:49 +10001157.Xr xauth 1
1158in that case.
1159.Pp
1160The primary purpose of this file is to run any initialization routines
1161which may be needed before the user's home directory becomes
1162accessible; AFS is a particular example of such an environment.
1163.Pp
1164This file will probably contain some initialization code followed by
1165something similar to: "if read proto cookie; then echo add $DISPLAY
1166$proto $cookie | xauth -q -; fi".
1167.Pp
1168If this file does not exist,
Damien Miller886c63a2000-01-20 23:13:36 +11001169.Pa /etc/sshrc
Damien Miller32aa1441999-10-29 09:15:49 +10001170is run, and if that
1171does not exist either, xauth is used to store the cookie.
1172.Pp
1173This file should be writable only by the user, and need not be
1174readable by anyone else.
Damien Miller886c63a2000-01-20 23:13:36 +11001175.It Pa /etc/sshrc
Damien Miller32aa1441999-10-29 09:15:49 +10001176Like
1177.Pa $HOME/.ssh/rc .
1178This can be used to specify
Damien Miller450a7a12000-03-26 13:04:51 +10001179machine-specific login-time initializations globally.
1180This file should be writable only by root, and should be world-readable.
Damien Miller37023962000-07-11 17:31:38 +10001181.El
Damien Miller0bc1bd82000-11-13 22:57:25 +11001182.Sh AUTHORS
Ben Lindstrom8eec2c82001-01-29 08:39:16 +00001183OpenSSH is a derivative of the original and free
1184ssh 1.2.12 release by Tatu Ylonen.
1185Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
1186Theo de Raadt and Dug Song
1187removed many bugs, re-added newer features and
1188created OpenSSH.
1189Markus Friedl contributed the support for SSH
1190protocol versions 1.5 and 2.0.
Damien Miller32aa1441999-10-29 09:15:49 +10001191.Sh SEE ALSO
Damien Miller32aa1441999-10-29 09:15:49 +10001192.Xr scp 1 ,
Damien Miller33804262001-02-04 23:20:18 +11001193.Xr sftp 1 ,
Damien Miller7b28dc52000-09-05 13:34:53 +11001194.Xr sftp-server 8 ,
Damien Miller32aa1441999-10-29 09:15:49 +10001195.Xr ssh 1 ,
1196.Xr ssh-add 1 ,
1197.Xr ssh-agent 1 ,
1198.Xr ssh-keygen 1 ,
Damien Millerb38eff82000-04-01 11:09:21 +10001199.Xr rlogin 1 ,
1200.Xr rsh 1