blob: f59bf31997dc14402dccd5ac2d256fed7b43f7f3 [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.\"
Damien Millera243fde2001-03-19 23:16:08 +110037.\" $OpenBSD: sshd.8,v 1.107 2001/03/19 12:10:17 djm 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 Lindstromc12a6b72001-01-29 08:41:05 +000046.Op Fl diqD46
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 .
Damien Miller95def091999-11-25 00:26:21 +1100266.It Fl V Ar client_protocol_id
Damien Miller874d77b2000-10-14 16:23:11 +1100267SSH-2 compatibility mode.
Damien Miller35dabd02000-05-01 21:10:33 +1000268When this option is specified
Damien Miller95def091999-11-25 00:26:21 +1100269.Nm
Damien Miller35dabd02000-05-01 21:10:33 +1000270assumes the client has sent the supplied version string
Damien Miller95def091999-11-25 00:26:21 +1100271and skips the
272Protocol Version Identification Exchange.
Damien Miller874d77b2000-10-14 16:23:11 +1100273This option is not intended to be called directly.
Damien Miller34132e52000-01-14 15:45:46 +1100274.It Fl 4
275Forces
276.Nm
277to use IPv4 addresses only.
278.It Fl 6
279Forces
280.Nm
281to use IPv6 addresses only.
Damien Miller32aa1441999-10-29 09:15:49 +1000282.El
283.Sh CONFIGURATION FILE
284.Nm
Damien Miller22c77262000-04-13 12:26:34 +1000285reads configuration data from
Damien Miller886c63a2000-01-20 23:13:36 +1100286.Pa /etc/sshd_config
Damien Miller32aa1441999-10-29 09:15:49 +1000287(or the file specified with
288.Fl f
Damien Miller450a7a12000-03-26 13:04:51 +1000289on the command line).
290The file contains keyword-value pairs, one per line.
291Lines starting with
Damien Miller32aa1441999-10-29 09:15:49 +1000292.Ql #
293and empty lines are interpreted as comments.
294.Pp
295The following keywords are possible.
296.Bl -tag -width Ds
297.It Cm AFSTokenPassing
Damien Miller450a7a12000-03-26 13:04:51 +1000298Specifies whether an AFS token may be forwarded to the server.
299Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000300.Dq yes .
301.It Cm AllowGroups
Ben Lindstroma1ebd892001-02-10 22:19:23 +0000302This keyword can be followed by a list of group names, separated
Damien Miller450a7a12000-03-26 13:04:51 +1000303by spaces.
304If specified, login is allowed only for users whose primary
Kevin Steves7b61cfa2001-01-14 19:11:00 +0000305group or supplementary group list matches one of the patterns.
Damien Miller32aa1441999-10-29 09:15:49 +1000306.Ql \&*
307and
308.Ql ?
309can be used as
Damien Miller450a7a12000-03-26 13:04:51 +1000310wildcards in the patterns.
Damien Miller942da032000-08-18 13:59:06 +1000311Only group names are valid; a numerical group ID isn't recognized.
Kevin Steves7b61cfa2001-01-14 19:11:00 +0000312By default login is allowed regardless of the group list.
Damien Miller32aa1441999-10-29 09:15:49 +1000313.Pp
Damien Miller50a41ed2000-10-16 12:14:42 +1100314.It Cm AllowTcpForwarding
315Specifies whether TCP forwarding is permitted.
316The default is
317.Dq yes .
318Note that disabling TCP forwarding does not improve security unless
319users are also denied shell access, as they can always install their
320own forwarders.
321.Pp
Damien Miller32aa1441999-10-29 09:15:49 +1000322.It Cm AllowUsers
Ben Lindstroma1ebd892001-02-10 22:19:23 +0000323This keyword can be followed by a list of user names, separated
Damien Miller450a7a12000-03-26 13:04:51 +1000324by spaces.
325If specified, login is allowed only for users names that
Damien Miller32aa1441999-10-29 09:15:49 +1000326match one of the patterns.
327.Ql \&*
328and
329.Ql ?
330can be used as
Damien Miller450a7a12000-03-26 13:04:51 +1000331wildcards in the patterns.
Damien Miller942da032000-08-18 13:59:06 +1000332Only user names are valid; a numerical user ID isn't recognized.
Damien Miller450a7a12000-03-26 13:04:51 +1000333By default login is allowed regardless of the user name.
Damien Miller32aa1441999-10-29 09:15:49 +1000334.Pp
Ben Lindstrom48bd7c12001-01-09 00:35:42 +0000335.It Cm Banner
336In some jurisdictions, sending a warning message before authentication
337may be relevant for getting legal protection.
338The contents of the specified file are sent to the remote user before
339authentication is allowed.
340This option is only available for protocol version 2.
341.Pp
Ben Lindstromff8b4942001-03-06 01:00:03 +0000342.It Cm ChallengeResponseAuthentication
343Specifies whether
344challenge response
345authentication is allowed.
346Currently there is only support for
347.Xr skey 1
348authentication.
349The default is
350.Dq yes .
Damien Miller22c77262000-04-13 12:26:34 +1000351.It Cm Ciphers
352Specifies the ciphers allowed for protocol version 2.
353Multiple ciphers must be comma-separated.
354The default is
Ben Lindstromc78a1872001-03-06 01:06:58 +0000355.Dq aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour.
Damien Miller32aa1441999-10-29 09:15:49 +1000356.It Cm CheckMail
357Specifies whether
358.Nm
359should check for new mail for interactive logins.
360The default is
361.Dq no .
362.It Cm DenyGroups
363This keyword can be followed by a number of group names, separated
Damien Miller450a7a12000-03-26 13:04:51 +1000364by spaces.
Kevin Steves7b61cfa2001-01-14 19:11:00 +0000365Users whose primary group or supplementary group list matches
366one of the patterns aren't allowed to log in.
Damien Miller32aa1441999-10-29 09:15:49 +1000367.Ql \&*
368and
369.Ql ?
370can be used as
Damien Miller450a7a12000-03-26 13:04:51 +1000371wildcards in the patterns.
Damien Miller942da032000-08-18 13:59:06 +1000372Only group names are valid; a numerical group ID isn't recognized.
Kevin Steves7b61cfa2001-01-14 19:11:00 +0000373By default login is allowed regardless of the group list.
Damien Miller32aa1441999-10-29 09:15:49 +1000374.Pp
375.It Cm DenyUsers
376This keyword can be followed by a number of user names, separated
Damien Miller450a7a12000-03-26 13:04:51 +1000377by spaces.
378Login is disallowed for user names that match one of the patterns.
Damien Miller32aa1441999-10-29 09:15:49 +1000379.Ql \&*
380and
381.Ql ?
Damien Miller450a7a12000-03-26 13:04:51 +1000382can be used as wildcards in the patterns.
Damien Miller942da032000-08-18 13:59:06 +1000383Only user names are valid; a numerical user ID isn't recognized.
Damien Miller450a7a12000-03-26 13:04:51 +1000384By default login is allowed regardless of the user name.
Damien Millere247cc42000-05-07 12:03:14 +1000385.It Cm GatewayPorts
386Specifies whether remote hosts are allowed to connect to ports
387forwarded for the client.
388The argument must be
389.Dq yes
390or
391.Dq no .
392The default is
393.Dq no .
Damien Millere247cc42000-05-07 12:03:14 +1000394.It Cm HostKey
Damien Miller0bc1bd82000-11-13 22:57:25 +1100395Specifies the file containing the private host keys (default
Damien Millere247cc42000-05-07 12:03:14 +1000396.Pa /etc/ssh_host_key )
Damien Miller0bc1bd82000-11-13 22:57:25 +1100397used by SSH protocol versions 1 and 2.
Damien Millere247cc42000-05-07 12:03:14 +1000398Note that
399.Nm
Ben Lindstrom226cfa02001-01-22 05:34:40 +0000400will refuse to use a file if it is group/world-accessible.
Damien Miller0bc1bd82000-11-13 22:57:25 +1100401It is possible to have multiple host key files.
402.Dq rsa1
403keys are used for version 1 and
404.Dq dsa
405or
406.Dq rsa
407are used for version 2 of the SSH protocol.
Damien Miller32aa1441999-10-29 09:15:49 +1000408.It Cm IgnoreRhosts
Damien Miller98c7ad62000-03-09 21:27:49 +1100409Specifies that
410.Pa .rhosts
Damien Miller22c77262000-04-13 12:26:34 +1000411and
Damien Miller98c7ad62000-03-09 21:27:49 +1100412.Pa .shosts
413files will not be used in authentication.
Damien Miller32aa1441999-10-29 09:15:49 +1000414.Pa /etc/hosts.equiv
415and
Damien Miller22c77262000-04-13 12:26:34 +1000416.Pa /etc/shosts.equiv
Damien Miller450a7a12000-03-26 13:04:51 +1000417are still used.
Damien Miller22c77262000-04-13 12:26:34 +1000418The default is
Damien Miller98c7ad62000-03-09 21:27:49 +1100419.Dq yes .
Damien Miller32265091999-11-12 11:33:04 +1100420.It Cm IgnoreUserKnownHosts
421Specifies whether
422.Nm
423should ignore the user's
424.Pa $HOME/.ssh/known_hosts
425during
426.Cm RhostsRSAAuthentication .
427The default is
428.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000429.It Cm KeepAlive
430Specifies whether the system should send keepalive messages to the
Damien Miller450a7a12000-03-26 13:04:51 +1000431other side.
432If they are sent, death of the connection or crash of one
433of the machines will be properly noticed.
434However, this means that
Damien Miller32aa1441999-10-29 09:15:49 +1000435connections will die if the route is down temporarily, and some people
Damien Miller450a7a12000-03-26 13:04:51 +1000436find it annoying.
Damien Miller30c3d422000-05-09 11:02:59 +1000437On the other hand, if keepalives are not sent,
Damien Miller32aa1441999-10-29 09:15:49 +1000438sessions may hang indefinitely on the server, leaving
439.Dq ghost
440users and consuming server resources.
441.Pp
442The default is
443.Dq yes
444(to send keepalives), and the server will notice
Damien Miller450a7a12000-03-26 13:04:51 +1000445if the network goes down or the client host reboots.
446This avoids infinitely hanging sessions.
Damien Miller32aa1441999-10-29 09:15:49 +1000447.Pp
448To disable keepalives, the value should be set to
449.Dq no
450in both the server and the client configuration files.
451.It Cm KerberosAuthentication
Damien Miller450a7a12000-03-26 13:04:51 +1000452Specifies whether Kerberos authentication is allowed.
453This can be in the form of a Kerberos ticket, or if
Damien Miller32aa1441999-10-29 09:15:49 +1000454.Cm PasswordAuthentication
455is yes, the password provided by the user will be validated through
Damien Miller874d77b2000-10-14 16:23:11 +1100456the Kerberos KDC.
457To use this option, the server needs a
Damien Miller942da032000-08-18 13:59:06 +1000458Kerberos servtab which allows the verification of the KDC's identity.
Damien Miller450a7a12000-03-26 13:04:51 +1000459Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000460.Dq yes .
461.It Cm KerberosOrLocalPasswd
462If set then if password authentication through Kerberos fails then
463the password will be validated via any additional local mechanism
464such as
Damien Miller62cee002000-09-23 17:15:56 +1100465.Pa /etc/passwd .
Damien Miller450a7a12000-03-26 13:04:51 +1000466Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000467.Dq yes .
468.It Cm KerberosTgtPassing
469Specifies whether a Kerberos TGT may be forwarded to the server.
Damien Miller22c77262000-04-13 12:26:34 +1000470Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000471.Dq no ,
472as this only works when the Kerberos KDC is actually an AFS kaserver.
473.It Cm KerberosTicketCleanup
474Specifies whether to automatically destroy the user's ticket cache
Damien Miller450a7a12000-03-26 13:04:51 +1000475file on logout.
476Default is
Damien Miller32aa1441999-10-29 09:15:49 +1000477.Dq yes .
478.It Cm KeyRegenerationInterval
479The server key is automatically regenerated after this many seconds
Damien Miller450a7a12000-03-26 13:04:51 +1000480(if it has been used).
481The purpose of regeneration is to prevent
Damien Miller32aa1441999-10-29 09:15:49 +1000482decrypting captured sessions by later breaking into the machine and
Damien Miller450a7a12000-03-26 13:04:51 +1000483stealing the keys.
484The key is never stored anywhere.
485If the value is 0, the key is never regenerated.
486The default is 3600 (seconds).
Damien Miller32aa1441999-10-29 09:15:49 +1000487.It Cm ListenAddress
488Specifies what local address
489.Nm
490should listen on.
491The default is to listen to all local addresses.
Damien Miller34132e52000-01-14 15:45:46 +1100492Multiple options of this type are permitted.
493Additionally, the
494.Cm Ports
495options must precede this option.
Damien Miller32aa1441999-10-29 09:15:49 +1000496.It Cm LoginGraceTime
497The server disconnects after this time if the user has not
Damien Miller450a7a12000-03-26 13:04:51 +1000498successfully logged in.
499If the value is 0, there is no time limit.
Damien Miller32aa1441999-10-29 09:15:49 +1000500The default is 600 (seconds).
Damien Miller5ce662a1999-11-11 17:57:39 +1100501.It Cm LogLevel
502Gives the verbosity level that is used when logging messages from
503.Nm sshd .
504The possible values are:
Ben Lindstromdb65e8f2001-01-19 04:26:52 +0000505QUIET, FATAL, ERROR, INFO, VERBOSE and DEBUG.
506The default is INFO.
Damien Miller5ce662a1999-11-11 17:57:39 +1100507Logging with level DEBUG violates the privacy of users
508and is not recommended.
Ben Lindstrom06b33aa2001-02-15 03:01:59 +0000509.It Cm MACs
510Specifies the available MAC (message authentication code) algorithms.
511The MAC algorithm is used in protocol version 2
512for data integrity protection.
513Multiple algorithms must be comma-separated.
514The default is
515.Pp
516.Bd -literal
Ben Lindstromc78a1872001-03-06 01:06:58 +0000517 ``hmac-md5,hmac-sha1,hmac-ripemd160,hmac-ripemd160@openssh.com,
Ben Lindstrom06b33aa2001-02-15 03:01:59 +0000518 hmac-sha1-96,hmac-md5-96''
519.Ed
Damien Miller37023962000-07-11 17:31:38 +1000520.It Cm MaxStartups
521Specifies the maximum number of concurrent unauthenticated connections to the
522.Nm
523daemon.
524Additional connections will be dropped until authentication succeeds or the
525.Cm LoginGraceTime
526expires for a connection.
527The default is 10.
Damien Miller942da032000-08-18 13:59:06 +1000528.Pp
529Alternatively, random early drop can be enabled by specifying
530the three colon separated values
531.Dq start:rate:full
Damien Miller874d77b2000-10-14 16:23:11 +1100532(e.g., "10:30:60").
Damien Miller942da032000-08-18 13:59:06 +1000533.Nm
Ben Lindstroma7333502001-01-29 08:44:03 +0000534will refuse connection attempts with a probability of
Damien Miller942da032000-08-18 13:59:06 +1000535.Dq rate/100
536(30%)
537if there are currently
538.Dq start
539(10)
540unauthenticated connections.
Ben Lindstroma7333502001-01-29 08:44:03 +0000541The probability increases linearly and all connection attempts
Damien Miller942da032000-08-18 13:59:06 +1000542are refused if the number of unauthenticated connections reaches
543.Dq full
544(60).
Damien Miller32aa1441999-10-29 09:15:49 +1000545.It Cm PasswordAuthentication
546Specifies whether password authentication is allowed.
547The default is
548.Dq yes .
Damien Miller942da032000-08-18 13:59:06 +1000549Note that this option applies to both protocol versions 1 and 2.
Damien Miller32aa1441999-10-29 09:15:49 +1000550.It Cm PermitEmptyPasswords
551When password authentication is allowed, it specifies whether the
Damien Miller450a7a12000-03-26 13:04:51 +1000552server allows login to accounts with empty password strings.
553The default is
Damien Miller98c7ad62000-03-09 21:27:49 +1100554.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000555.It Cm PermitRootLogin
Ben Lindstrom323c98f2001-03-05 07:40:40 +0000556Specifies whether root can login using
Damien Miller32aa1441999-10-29 09:15:49 +1000557.Xr ssh 1 .
558The argument must be
559.Dq yes ,
Ben Lindstromd8a90212001-02-15 03:08:27 +0000560.Dq without-password ,
561.Dq forced-commands-only
Damien Miller32aa1441999-10-29 09:15:49 +1000562or
563.Dq no .
564The default is
565.Dq yes .
Damien Miller32aa1441999-10-29 09:15:49 +1000566.Pp
Ben Lindstromd8a90212001-02-15 03:08:27 +0000567If this option is set to
568.Dq without-password
569password authentication is disabled for root.
570.Pp
571If this option is set to
572.Dq forced-commands-only
573root login with public key authentication will be allowed,
574but only if the
Damien Miller32aa1441999-10-29 09:15:49 +1000575.Ar command
Ben Lindstromd8a90212001-02-15 03:08:27 +0000576option has been specified
Damien Miller32aa1441999-10-29 09:15:49 +1000577(which may be useful for taking remote backups even if root login is
Ben Lindstromd8a90212001-02-15 03:08:27 +0000578normally not allowed). All other authentication methods are disabled
579for root.
Ben Lindstrom323c98f2001-03-05 07:40:40 +0000580.Pp
581If this option is set to
582.Dq no
583root is not allowed to login.
Damien Miller6f83b8e2000-05-02 09:23:45 +1000584.It Cm PidFile
585Specifies the file that contains the process identifier of the
586.Nm
587daemon.
588The default is
589.Pa /var/run/sshd.pid .
Damien Miller32aa1441999-10-29 09:15:49 +1000590.It Cm Port
591Specifies the port number that
592.Nm
Damien Miller450a7a12000-03-26 13:04:51 +1000593listens on.
594The default is 22.
Damien Miller34132e52000-01-14 15:45:46 +1100595Multiple options of this type are permitted.
Damien Miller32aa1441999-10-29 09:15:49 +1000596.It Cm PrintMotd
597Specifies whether
598.Nm
Damien Miller22c77262000-04-13 12:26:34 +1000599should print
Damien Miller32aa1441999-10-29 09:15:49 +1000600.Pa /etc/motd
Damien Miller450a7a12000-03-26 13:04:51 +1000601when a user logs in interactively.
602(On some systems it is also printed by the shell,
Damien Miller32aa1441999-10-29 09:15:49 +1000603.Pa /etc/profile ,
Damien Miller450a7a12000-03-26 13:04:51 +1000604or equivalent.)
605The default is
Damien Miller32aa1441999-10-29 09:15:49 +1000606.Dq yes .
Damien Miller22c77262000-04-13 12:26:34 +1000607.It Cm Protocol
608Specifies the protocol versions
609.Nm
610should support.
611The possible values are
612.Dq 1
613and
614.Dq 2 .
615Multiple versions must be comma-separated.
616The default is
617.Dq 1 .
Ben Lindstromff8b4942001-03-06 01:00:03 +0000618.It Cm PubkeyAuthentication
619Specifies whether public key authentication is allowed.
620The default is
621.Dq yes .
622Note that this option applies to protocol version 2 only.
Damien Miller33804262001-02-04 23:20:18 +1100623.It Cm ReverseMappingCheck
624Specifies whether
625.Nm
626should try to verify the remote host name and check that
627the resolved host name for the remote IP address maps back to the
628very same IP address.
629The default is
630.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000631.It Cm RhostsAuthentication
632Specifies whether authentication using rhosts or /etc/hosts.equiv
Damien Miller450a7a12000-03-26 13:04:51 +1000633files is sufficient.
634Normally, this method should not be permitted because it is insecure.
Damien Miller32aa1441999-10-29 09:15:49 +1000635.Cm RhostsRSAAuthentication
636should be used
637instead, because it performs RSA-based host authentication in addition
638to normal rhosts or /etc/hosts.equiv authentication.
639The default is
640.Dq no .
641.It Cm RhostsRSAAuthentication
642Specifies whether rhosts or /etc/hosts.equiv authentication together
Damien Miller450a7a12000-03-26 13:04:51 +1000643with successful RSA host authentication is allowed.
644The default is
Damien Miller98c7ad62000-03-09 21:27:49 +1100645.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000646.It Cm RSAAuthentication
Damien Miller450a7a12000-03-26 13:04:51 +1000647Specifies whether pure RSA authentication is allowed.
648The default is
Damien Miller32aa1441999-10-29 09:15:49 +1000649.Dq yes .
Damien Millere247cc42000-05-07 12:03:14 +1000650Note that this option applies to protocol version 1 only.
Damien Miller32aa1441999-10-29 09:15:49 +1000651.It Cm ServerKeyBits
Damien Miller450a7a12000-03-26 13:04:51 +1000652Defines the number of bits in the server key.
653The minimum value is 512, and the default is 768.
Damien Miller32aa1441999-10-29 09:15:49 +1000654.It Cm StrictModes
655Specifies whether
656.Nm
657should check file modes and ownership of the
Damien Miller450a7a12000-03-26 13:04:51 +1000658user's files and home directory before accepting login.
659This is normally desirable because novices sometimes accidentally leave their
660directory or files world-writable.
661The default is
Damien Miller32aa1441999-10-29 09:15:49 +1000662.Dq yes .
Damien Millerf6d9e222000-06-18 14:50:44 +1000663.It Cm Subsystem
Damien Miller874d77b2000-10-14 16:23:11 +1100664Configures an external subsystem (e.g., file transfer daemon).
665Arguments should be a subsystem name and a command to execute upon subsystem
666request.
Damien Miller7b28dc52000-09-05 13:34:53 +1100667The command
668.Xr sftp-server 8
669implements the
670.Dq sftp
671file transfer subsystem.
Damien Millerf6d9e222000-06-18 14:50:44 +1000672By default no subsystems are defined.
673Note that this option applies to protocol version 2 only.
Damien Miller32aa1441999-10-29 09:15:49 +1000674.It Cm SyslogFacility
675Gives the facility code that is used when logging messages from
676.Nm sshd .
677The possible values are: DAEMON, USER, AUTH, LOCAL0, LOCAL1, LOCAL2,
Damien Miller450a7a12000-03-26 13:04:51 +1000678LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7.
679The default is AUTH.
Damien Miller32aa1441999-10-29 09:15:49 +1000680.It Cm UseLogin
681Specifies whether
682.Xr login 1
Damien Millerd3a18572000-06-07 19:55:44 +1000683is used for interactive login sessions.
684Note that
685.Xr login 1
Damien Miller942da032000-08-18 13:59:06 +1000686is never used for remote command execution.
Damien Miller450a7a12000-03-26 13:04:51 +1000687The default is
Damien Miller32aa1441999-10-29 09:15:49 +1000688.Dq no .
Damien Miller32aa1441999-10-29 09:15:49 +1000689.It Cm X11DisplayOffset
690Specifies the first display number available for
691.Nm sshd Ns 's
Damien Miller450a7a12000-03-26 13:04:51 +1000692X11 forwarding.
693This prevents
Damien Miller32aa1441999-10-29 09:15:49 +1000694.Nm
695from interfering with real X11 servers.
Damien Miller98c7ad62000-03-09 21:27:49 +1100696The default is 10.
Damien Miller396691a2000-01-20 22:44:08 +1100697.It Cm X11Forwarding
Damien Miller450a7a12000-03-26 13:04:51 +1000698Specifies whether X11 forwarding is permitted.
699The default is
Damien Miller98c7ad62000-03-09 21:27:49 +1100700.Dq no .
Damien Miller396691a2000-01-20 22:44:08 +1100701Note that disabling X11 forwarding does not improve security in any
702way, as users can always install their own forwarders.
Damien Millerd3a18572000-06-07 19:55:44 +1000703.It Cm XAuthLocation
704Specifies the location of the
705.Xr xauth 1
706program.
707The default is
708.Pa /usr/X11R6/bin/xauth .
Damien Miller32aa1441999-10-29 09:15:49 +1000709.El
710.Sh LOGIN PROCESS
711When a user successfully logs in,
712.Nm
713does the following:
714.Bl -enum -offset indent
715.It
716If the login is on a tty, and no command has been specified,
Damien Miller22c77262000-04-13 12:26:34 +1000717prints last login time and
Damien Miller32aa1441999-10-29 09:15:49 +1000718.Pa /etc/motd
719(unless prevented in the configuration file or by
720.Pa $HOME/.hushlogin ;
721see the
Damien Miller22c77262000-04-13 12:26:34 +1000722.Sx FILES
Damien Miller32aa1441999-10-29 09:15:49 +1000723section).
724.It
725If the login is on a tty, records login time.
726.It
727Checks
728.Pa /etc/nologin ;
729if it exists, prints contents and quits
730(unless root).
731.It
732Changes to run with normal user privileges.
733.It
734Sets up basic environment.
735.It
736Reads
737.Pa $HOME/.ssh/environment
738if it exists.
739.It
740Changes to user's home directory.
741.It
742If
743.Pa $HOME/.ssh/rc
744exists, runs it; else if
Damien Miller886c63a2000-01-20 23:13:36 +1100745.Pa /etc/sshrc
Damien Miller32aa1441999-10-29 09:15:49 +1000746exists, runs
Damien Miller450a7a12000-03-26 13:04:51 +1000747it; otherwise runs xauth.
748The
Damien Miller32aa1441999-10-29 09:15:49 +1000749.Dq rc
750files are given the X11
751authentication protocol and cookie in standard input.
752.It
753Runs user's shell or command.
754.El
755.Sh AUTHORIZED_KEYS FILE FORMAT
Damien Miller22c77262000-04-13 12:26:34 +1000756The
Damien Miller32aa1441999-10-29 09:15:49 +1000757.Pa $HOME/.ssh/authorized_keys
758file lists the RSA keys that are
Damien Millere247cc42000-05-07 12:03:14 +1000759permitted for RSA authentication in SSH protocols 1.3 and 1.5
Damien Miller30c3d422000-05-09 11:02:59 +1000760Similarly, the
Damien Millere247cc42000-05-07 12:03:14 +1000761.Pa $HOME/.ssh/authorized_keys2
Ben Lindstrom4dccfa52000-12-28 16:40:05 +0000762file lists the DSA and RSA keys that are
763permitted for public key authentication (PubkeyAuthentication)
764in SSH protocol 2.0.
765.Pp
Damien Miller450a7a12000-03-26 13:04:51 +1000766Each line of the file contains one
Damien Miller32aa1441999-10-29 09:15:49 +1000767key (empty lines and lines starting with a
768.Ql #
769are ignored as
Damien Miller450a7a12000-03-26 13:04:51 +1000770comments).
Ben Lindstrom4dccfa52000-12-28 16:40:05 +0000771Each RSA public key consists of the following fields, separated by
Damien Miller450a7a12000-03-26 13:04:51 +1000772spaces: options, bits, exponent, modulus, comment.
Ben Lindstrom4dccfa52000-12-28 16:40:05 +0000773Each protocol version 2 public key consists of:
774options, keytype, base64 encoded key, comment.
775The options fields
776are optional; its presence is determined by whether the line starts
Damien Miller32aa1441999-10-29 09:15:49 +1000777with a number or not (the option field never starts with a number).
Ben Lindstrom4dccfa52000-12-28 16:40:05 +0000778The bits, exponent, modulus and comment fields give the RSA key for
779protocol version 1; the
Damien Miller32aa1441999-10-29 09:15:49 +1000780comment field is not used for anything (but may be convenient for the
781user to identify the key).
Ben Lindstrom4dccfa52000-12-28 16:40:05 +0000782For protocol version 2 the keytype is
783.Dq ssh-dss
784or
785.Dq ssh-rsa .
Damien Miller32aa1441999-10-29 09:15:49 +1000786.Pp
787Note that lines in this file are usually several hundred bytes long
Damien Miller450a7a12000-03-26 13:04:51 +1000788(because of the size of the RSA key modulus).
789You don't want to type them in; instead, copy the
Damien Miller32aa1441999-10-29 09:15:49 +1000790.Pa identity.pub
Ben Lindstrom4dccfa52000-12-28 16:40:05 +0000791or the
792.Pa id_dsa.pub
Damien Miller32aa1441999-10-29 09:15:49 +1000793file and edit it.
794.Pp
Damien Miller942da032000-08-18 13:59:06 +1000795The options (if present) consist of comma-separated option
Damien Miller450a7a12000-03-26 13:04:51 +1000796specifications.
797No spaces are permitted, except within double quotes.
Damien Miller32aa1441999-10-29 09:15:49 +1000798The following option specifications are supported:
799.Bl -tag -width Ds
800.It Cm from="pattern-list"
801Specifies that in addition to RSA authentication, the canonical name
802of the remote host must be present in the comma-separated list of
Damien Miller450a7a12000-03-26 13:04:51 +1000803patterns
804.Pf ( Ql *
805and
806.Ql ?
807serve as wildcards).
808The list may also contain
809patterns negated by prefixing them with
810.Ql ! ;
811if the canonical host name matches a negated pattern, the key is not accepted.
812The purpose
Damien Miller32aa1441999-10-29 09:15:49 +1000813of this option is to optionally increase security: RSA authentication
814by itself does not trust the network or name servers or anything (but
815the key); however, if somebody somehow steals the key, the key
Damien Miller450a7a12000-03-26 13:04:51 +1000816permits an intruder to log in from anywhere in the world.
817This additional option makes using a stolen key more difficult (name
Damien Miller32aa1441999-10-29 09:15:49 +1000818servers and/or routers would have to be compromised in addition to
819just the key).
820.It Cm command="command"
821Specifies that the command is executed whenever this key is used for
Damien Miller450a7a12000-03-26 13:04:51 +1000822authentication.
823The command supplied by the user (if any) is ignored.
Damien Miller32aa1441999-10-29 09:15:49 +1000824The command is run on a pty if the connection requests a pty;
Damien Miller450a7a12000-03-26 13:04:51 +1000825otherwise it is run without a tty.
Damien Miller33804262001-02-04 23:20:18 +1100826Note that if you want a 8-bit clean channel,
827you must not request a pty or should specify
828.Cm no-pty .
Damien Miller450a7a12000-03-26 13:04:51 +1000829A quote may be included in the command by quoting it with a backslash.
830This option might be useful
831to restrict certain RSA keys to perform just a specific operation.
832An example might be a key that permits remote backups but nothing else.
Damien Miller30c3d422000-05-09 11:02:59 +1000833Note that the client may specify TCP/IP and/or X11
834forwarding unless they are explicitly prohibited.
Damien Miller32aa1441999-10-29 09:15:49 +1000835.It Cm environment="NAME=value"
836Specifies that the string is to be added to the environment when
Damien Miller450a7a12000-03-26 13:04:51 +1000837logging in using this key.
838Environment variables set this way
839override other default environment values.
840Multiple options of this type are permitted.
Damien Miller32aa1441999-10-29 09:15:49 +1000841.It Cm no-port-forwarding
842Forbids TCP/IP forwarding when this key is used for authentication.
Damien Miller450a7a12000-03-26 13:04:51 +1000843Any port forward requests by the client will return an error.
844This might be used, e.g., in connection with the
Damien Miller32aa1441999-10-29 09:15:49 +1000845.Cm command
846option.
847.It Cm no-X11-forwarding
848Forbids X11 forwarding when this key is used for authentication.
849Any X11 forward requests by the client will return an error.
850.It Cm no-agent-forwarding
851Forbids authentication agent forwarding when this key is used for
852authentication.
853.It Cm no-pty
854Prevents tty allocation (a request to allocate a pty will fail).
Damien Millera243fde2001-03-19 23:16:08 +1100855.It Cm permitopen="host:port"
856Limit local
857.Li ``ssh -L''
858port-forwading such that it may only connect to the specified host and
859port. Multiple
860.Cm permitopen
861options may be applied seperated by commas. No pattern matching is
862performed on the specified hostnames, they must be literal domains or
863addresses.
Damien Miller32aa1441999-10-29 09:15:49 +1000864.El
865.Ss Examples
8661024 33 12121.\|.\|.\|312314325 ylo@foo.bar
867.Pp
868from="*.niksula.hut.fi,!pc.niksula.hut.fi" 1024 35 23.\|.\|.\|2334 ylo@niksula
869.Pp
870command="dump /home",no-pty,no-port-forwarding 1024 33 23.\|.\|.\|2323 backup.hut.fi
Damien Millera243fde2001-03-19 23:16:08 +1100871.Pp
872permitopen="10.2.1.55:80",permitopen="10.2.1.56:25" 1024 33 23.\|.\|.\|2323
Damien Miller32aa1441999-10-29 09:15:49 +1000873.Sh SSH_KNOWN_HOSTS FILE FORMAT
Damien Miller22c77262000-04-13 12:26:34 +1000874The
Damien Millere247cc42000-05-07 12:03:14 +1000875.Pa /etc/ssh_known_hosts ,
876.Pa /etc/ssh_known_hosts2 ,
877.Pa $HOME/.ssh/known_hosts ,
Damien Miller22c77262000-04-13 12:26:34 +1000878and
Damien Millere247cc42000-05-07 12:03:14 +1000879.Pa $HOME/.ssh/known_hosts2
Damien Miller450a7a12000-03-26 13:04:51 +1000880files contain host public keys for all known hosts.
881The global file should
882be prepared by the administrator (optional), and the per-user file is
Damien Miller942da032000-08-18 13:59:06 +1000883maintained automatically: whenever the user connects from an unknown host
Damien Miller450a7a12000-03-26 13:04:51 +1000884its key is added to the per-user file.
Damien Miller32aa1441999-10-29 09:15:49 +1000885.Pp
886Each line in these files contains the following fields: hostnames,
Damien Miller450a7a12000-03-26 13:04:51 +1000887bits, exponent, modulus, comment.
888The fields are separated by spaces.
Damien Miller32aa1441999-10-29 09:15:49 +1000889.Pp
890Hostnames is a comma-separated list of patterns ('*' and '?' act as
891wildcards); each pattern in turn is matched against the canonical host
892name (when authenticating a client) or against the user-supplied
Damien Miller450a7a12000-03-26 13:04:51 +1000893name (when authenticating a server).
894A pattern may also be preceded by
Damien Miller32aa1441999-10-29 09:15:49 +1000895.Ql !
896to indicate negation: if the host name matches a negated
897pattern, it is not accepted (by that line) even if it matched another
898pattern on the line.
899.Pp
Damien Millere247cc42000-05-07 12:03:14 +1000900Bits, exponent, and modulus are taken directly from the RSA host key; they
Damien Miller32aa1441999-10-29 09:15:49 +1000901can be obtained, e.g., from
Damien Miller886c63a2000-01-20 23:13:36 +1100902.Pa /etc/ssh_host_key.pub .
Damien Miller32aa1441999-10-29 09:15:49 +1000903The optional comment field continues to the end of the line, and is not used.
904.Pp
905Lines starting with
906.Ql #
907and empty lines are ignored as comments.
908.Pp
909When performing host authentication, authentication is accepted if any
Damien Miller450a7a12000-03-26 13:04:51 +1000910matching line has the proper key.
911It is thus permissible (but not
Damien Miller32aa1441999-10-29 09:15:49 +1000912recommended) to have several lines or different host keys for the same
Damien Miller450a7a12000-03-26 13:04:51 +1000913names.
914This will inevitably happen when short forms of host names
915from different domains are put in the file.
916It is possible
Damien Miller32aa1441999-10-29 09:15:49 +1000917that the files contain conflicting information; authentication is
918accepted if valid information can be found from either file.
919.Pp
920Note that the lines in these files are typically hundreds of characters
921long, and you definitely don't want to type in the host keys by hand.
922Rather, generate them by a script
Damien Miller22c77262000-04-13 12:26:34 +1000923or by taking
Damien Miller886c63a2000-01-20 23:13:36 +1100924.Pa /etc/ssh_host_key.pub
Damien Miller32aa1441999-10-29 09:15:49 +1000925and adding the host names at the front.
926.Ss Examples
927closenet,closenet.hut.fi,.\|.\|.\|,130.233.208.41 1024 37 159.\|.\|.93 closenet.hut.fi
928.Sh FILES
929.Bl -tag -width Ds
Damien Miller886c63a2000-01-20 23:13:36 +1100930.It Pa /etc/sshd_config
Damien Miller32aa1441999-10-29 09:15:49 +1000931Contains configuration data for
932.Nm sshd .
933This file should be writable by root only, but it is recommended
934(though not necessary) that it be world-readable.
Ben Lindstromd7f5b512001-03-05 06:57:23 +0000935.It Pa /etc/ssh_host_key, /etc/ssh_host_dsa_key, /etc/ssh_host_rsa_key
936These three files contain the private parts of the
937(SSH1, SSH2 DSA, and SSH2 RSA) host keys.
938These files should only be owned by root, readable only by root, and not
Damien Miller32aa1441999-10-29 09:15:49 +1000939accessible to others.
940Note that
941.Nm
942does not start if this file is group/world-accessible.
Ben Lindstromd7f5b512001-03-05 06:57:23 +0000943.It Pa /etc/ssh_host_key.pub, /etc/ssh_host_dsa_key.pub, /etc/ssh_host_rsa_key.pub
944There three files contain the public parts of the
945(SSH1, SSH2 DSA, and SSH2 RSA) host keys.
946These files should be world-readable but writable only by
Damien Miller450a7a12000-03-26 13:04:51 +1000947root.
Ben Lindstromd7f5b512001-03-05 06:57:23 +0000948Their contents should match the respective private parts.
949These files are not
950really used for anything; they are provided for the convenience of
951the user so their contents can be copied to known hosts files.
952These files are created using
Damien Miller32aa1441999-10-29 09:15:49 +1000953.Xr ssh-keygen 1 .
Damien Millere39cacc2000-11-29 12:18:44 +1100954.It Pa /etc/primes
955Contains Diffie-Hellman groups used for the "Diffie-Hellman Group Exchange".
Damien Miller886c63a2000-01-20 23:13:36 +1100956.It Pa /var/run/sshd.pid
Damien Miller32aa1441999-10-29 09:15:49 +1000957Contains the process ID of the
958.Nm
959listening for connections (if there are several daemons running
960concurrently for different ports, this contains the pid of the one
Damien Miller450a7a12000-03-26 13:04:51 +1000961started last).
Damien Miller942da032000-08-18 13:59:06 +1000962The content of this file is not sensitive; it can be world-readable.
Damien Miller32aa1441999-10-29 09:15:49 +1000963.It Pa $HOME/.ssh/authorized_keys
964Lists the RSA keys that can be used to log into the user's account.
965This file must be readable by root (which may on some machines imply
966it being world-readable if the user's home directory resides on an NFS
Damien Miller450a7a12000-03-26 13:04:51 +1000967volume).
968It is recommended that it not be accessible by others.
969The format of this file is described above.
Damien Millere247cc42000-05-07 12:03:14 +1000970Users will place the contents of their
971.Pa identity.pub
972files into this file, as described in
973.Xr ssh-keygen 1 .
974.It Pa $HOME/.ssh/authorized_keys2
975Lists the DSA keys that can be used to log into the user's account.
976This file must be readable by root (which may on some machines imply
977it being world-readable if the user's home directory resides on an NFS
978volume).
979It is recommended that it not be accessible by others.
980The format of this file is described above.
981Users will place the contents of their
982.Pa id_dsa.pub
983files into this file, as described in
984.Xr ssh-keygen 1 .
Damien Miller886c63a2000-01-20 23:13:36 +1100985.It Pa "/etc/ssh_known_hosts" and "$HOME/.ssh/known_hosts"
Damien Miller5ce662a1999-11-11 17:57:39 +1100986These files are consulted when using rhosts with RSA host
Damien Miller450a7a12000-03-26 13:04:51 +1000987authentication to check the public key of the host.
988The key must be listed in one of these files to be accepted.
Damien Miller33e511e1999-11-11 11:43:13 +1100989The client uses the same files
Ben Lindstromebd888d2001-03-05 05:49:29 +0000990to verify that it is connecting to the correct remote host.
Damien Miller450a7a12000-03-26 13:04:51 +1000991These files should be writable only by root/the owner.
Damien Miller886c63a2000-01-20 23:13:36 +1100992.Pa /etc/ssh_known_hosts
Damien Miller32aa1441999-10-29 09:15:49 +1000993should be world-readable, and
994.Pa $HOME/.ssh/known_hosts
995can but need not be world-readable.
996.It Pa /etc/nologin
Damien Miller22c77262000-04-13 12:26:34 +1000997If this file exists,
Damien Miller32aa1441999-10-29 09:15:49 +1000998.Nm
Damien Miller450a7a12000-03-26 13:04:51 +1000999refuses to let anyone except root log in.
1000The contents of the file
Damien Miller32aa1441999-10-29 09:15:49 +10001001are displayed to anyone trying to log in, and non-root connections are
Damien Miller450a7a12000-03-26 13:04:51 +10001002refused.
1003The file should be world-readable.
Damien Miller32aa1441999-10-29 09:15:49 +10001004.It Pa /etc/hosts.allow, /etc/hosts.deny
1005If compiled with
1006.Sy LIBWRAP
1007support, tcp-wrappers access controls may be defined here as described in
1008.Xr hosts_access 5 .
1009.It Pa $HOME/.rhosts
1010This file contains host-username pairs, separated by a space, one per
Damien Miller450a7a12000-03-26 13:04:51 +10001011line.
1012The given user on the corresponding host is permitted to log in
1013without password.
1014The same file is used by rlogind and rshd.
Damien Miller32aa1441999-10-29 09:15:49 +10001015The file must
1016be writable only by the user; it is recommended that it not be
1017accessible by others.
1018.Pp
Damien Miller450a7a12000-03-26 13:04:51 +10001019If is also possible to use netgroups in the file.
1020Either host or user
Damien Miller32aa1441999-10-29 09:15:49 +10001021name may be of the form +@groupname to specify all hosts or all users
1022in the group.
1023.It Pa $HOME/.shosts
1024For ssh,
1025this file is exactly the same as for
1026.Pa .rhosts .
1027However, this file is
1028not used by rlogin and rshd, so using this permits access using SSH only.
Damien Miller942da032000-08-18 13:59:06 +10001029.It Pa /etc/hosts.equiv
Damien Miller32aa1441999-10-29 09:15:49 +10001030This file is used during
1031.Pa .rhosts
Damien Miller450a7a12000-03-26 13:04:51 +10001032authentication.
1033In the simplest form, this file contains host names, one per line.
1034Users on
Damien Miller32aa1441999-10-29 09:15:49 +10001035those hosts are permitted to log in without a password, provided they
Damien Miller450a7a12000-03-26 13:04:51 +10001036have the same user name on both machines.
1037The host name may also be
Damien Miller32aa1441999-10-29 09:15:49 +10001038followed by a user name; such users are permitted to log in as
1039.Em any
Damien Miller450a7a12000-03-26 13:04:51 +10001040user on this machine (except root).
1041Additionally, the syntax
Damien Miller32aa1441999-10-29 09:15:49 +10001042.Dq +@group
Damien Miller450a7a12000-03-26 13:04:51 +10001043can be used to specify netgroups.
1044Negated entries start with
Damien Miller32aa1441999-10-29 09:15:49 +10001045.Ql \&- .
1046.Pp
1047If the client host/user is successfully matched in this file, login is
1048automatically permitted provided the client and server user names are the
Damien Miller450a7a12000-03-26 13:04:51 +10001049same.
1050Additionally, successful RSA host authentication is normally required.
1051This file must be writable only by root; it is recommended
Damien Miller32aa1441999-10-29 09:15:49 +10001052that it be world-readable.
1053.Pp
1054.Sy "Warning: It is almost never a good idea to use user names in"
1055.Pa hosts.equiv .
1056Beware that it really means that the named user(s) can log in as
1057.Em anybody ,
1058which includes bin, daemon, adm, and other accounts that own critical
Damien Miller450a7a12000-03-26 13:04:51 +10001059binaries and directories.
1060Using a user name practically grants the user root access.
1061The only valid use for user names that I can think
Damien Miller32aa1441999-10-29 09:15:49 +10001062of is in negative entries.
1063.Pp
1064Note that this warning also applies to rsh/rlogin.
Damien Miller886c63a2000-01-20 23:13:36 +11001065.It Pa /etc/shosts.equiv
Damien Miller32aa1441999-10-29 09:15:49 +10001066This is processed exactly as
1067.Pa /etc/hosts.equiv .
1068However, this file may be useful in environments that want to run both
1069rsh/rlogin and ssh.
1070.It Pa $HOME/.ssh/environment
Damien Miller450a7a12000-03-26 13:04:51 +10001071This file is read into the environment at login (if it exists).
1072It can only contain empty lines, comment lines (that start with
Damien Miller32aa1441999-10-29 09:15:49 +10001073.Ql # ) ,
Damien Miller450a7a12000-03-26 13:04:51 +10001074and assignment lines of the form name=value.
1075The file should be writable
Damien Miller32aa1441999-10-29 09:15:49 +10001076only by the user; it need not be readable by anyone else.
1077.It Pa $HOME/.ssh/rc
1078If this file exists, it is run with /bin/sh after reading the
Damien Miller450a7a12000-03-26 13:04:51 +10001079environment files but before starting the user's shell or command.
1080If X11 spoofing is in use, this will receive the "proto cookie" pair in
Damien Miller32aa1441999-10-29 09:15:49 +10001081standard input (and
1082.Ev DISPLAY
Damien Miller450a7a12000-03-26 13:04:51 +10001083in environment).
1084This must call
Damien Miller32aa1441999-10-29 09:15:49 +10001085.Xr xauth 1
1086in that case.
1087.Pp
1088The primary purpose of this file is to run any initialization routines
1089which may be needed before the user's home directory becomes
1090accessible; AFS is a particular example of such an environment.
1091.Pp
1092This file will probably contain some initialization code followed by
1093something similar to: "if read proto cookie; then echo add $DISPLAY
1094$proto $cookie | xauth -q -; fi".
1095.Pp
1096If this file does not exist,
Damien Miller886c63a2000-01-20 23:13:36 +11001097.Pa /etc/sshrc
Damien Miller32aa1441999-10-29 09:15:49 +10001098is run, and if that
1099does not exist either, xauth is used to store the cookie.
1100.Pp
1101This file should be writable only by the user, and need not be
1102readable by anyone else.
Damien Miller886c63a2000-01-20 23:13:36 +11001103.It Pa /etc/sshrc
Damien Miller32aa1441999-10-29 09:15:49 +10001104Like
1105.Pa $HOME/.ssh/rc .
1106This can be used to specify
Damien Miller450a7a12000-03-26 13:04:51 +10001107machine-specific login-time initializations globally.
1108This file should be writable only by root, and should be world-readable.
Damien Miller37023962000-07-11 17:31:38 +10001109.El
Damien Miller0bc1bd82000-11-13 22:57:25 +11001110.Sh AUTHORS
Ben Lindstrom8eec2c82001-01-29 08:39:16 +00001111OpenSSH is a derivative of the original and free
1112ssh 1.2.12 release by Tatu Ylonen.
1113Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
1114Theo de Raadt and Dug Song
1115removed many bugs, re-added newer features and
1116created OpenSSH.
1117Markus Friedl contributed the support for SSH
1118protocol versions 1.5 and 2.0.
Damien Miller32aa1441999-10-29 09:15:49 +10001119.Sh SEE ALSO
Damien Miller32aa1441999-10-29 09:15:49 +10001120.Xr scp 1 ,
Damien Miller33804262001-02-04 23:20:18 +11001121.Xr sftp 1 ,
Damien Miller7b28dc52000-09-05 13:34:53 +11001122.Xr sftp-server 8 ,
Damien Miller32aa1441999-10-29 09:15:49 +10001123.Xr ssh 1 ,
1124.Xr ssh-add 1 ,
1125.Xr ssh-agent 1 ,
1126.Xr ssh-keygen 1 ,
Damien Millerb38eff82000-04-01 11:09:21 +10001127.Xr rlogin 1 ,
1128.Xr rsh 1