blob: aa7b7c7d4eae578c04651ea89b90890d3b22ec76 [file] [log] [blame]
Ben Lindstrom9f049032002-06-21 00:59:05 +00001.\" -*- nroff -*-
2.\"
3.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
4.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
5.\" All rights reserved
6.\"
7.\" 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".
12.\"
13.\" 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.
16.\"
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.
36.\"
Ben Lindstrom959de992002-06-23 00:35:25 +000037.\" $OpenBSD: sshd_config.5,v 1.4 2002/06/22 16:45:29 stevesk Exp $
Ben Lindstrom9f049032002-06-21 00:59:05 +000038.Dd September 25, 1999
39.Dt SSHD_CONFIG 5
40.Os
41.Sh NAME
42.Nm sshd_config
43.Nd OpenSSH SSH daemon configuration file
44.Sh SYNOPSIS
45.Bl -tag -width Ds -compact
46.It Pa /etc/ssh/sshd_config
47.El
48.Sh DESCRIPTION
49.Nm sshd
50reads configuration data from
51.Pa /etc/ssh/sshd_config
52(or the file specified with
53.Fl f
54on the command line).
55The file contains keyword-argument pairs, one per line.
56Lines starting with
57.Ql #
58and empty lines are interpreted as comments.
59.Pp
60The possible
61keywords and their meanings are as follows (note that
62keywords are case-insensitive and arguments are case-sensitive):
63.Bl -tag -width Ds
64.It Cm AFSTokenPassing
65Specifies whether an AFS token may be forwarded to the server.
66Default is
67.Dq no .
68.It Cm AllowGroups
69This keyword can be followed by a list of group name patterns, separated
70by spaces.
71If specified, login is allowed only for users whose primary
72group or supplementary group list matches one of the patterns.
73.Ql \&*
74and
75.Ql ?
76can be used as
77wildcards in the patterns.
78Only group names are valid; a numerical group ID is not recognized.
79By default, login is allowed for all groups.
80.Pp
81.It Cm AllowTcpForwarding
82Specifies whether TCP forwarding is permitted.
83The default is
84.Dq yes .
85Note that disabling TCP forwarding does not improve security unless
86users are also denied shell access, as they can always install their
87own forwarders.
88.Pp
89.It Cm AllowUsers
90This keyword can be followed by a list of user name patterns, separated
91by spaces.
92If specified, login is allowed only for users names that
93match one of the patterns.
94.Ql \&*
95and
96.Ql ?
97can be used as
98wildcards in the patterns.
99Only user names are valid; a numerical user ID is not recognized.
100By default, login is allowed for all users.
101If the pattern takes the form USER@HOST then USER and HOST
102are separately checked, restricting logins to particular
103users from particular hosts.
104.Pp
105.It Cm AuthorizedKeysFile
106Specifies the file that contains the public keys that can be used
107for user authentication.
108.Cm AuthorizedKeysFile
109may contain tokens of the form %T which are substituted during connection
110set-up. The following tokens are defined: %% is replaced by a literal '%',
111%h is replaced by the home directory of the user being authenticated and
112%u is replaced by the username of that user.
113After expansion,
114.Cm AuthorizedKeysFile
115is taken to be an absolute path or one relative to the user's home
116directory.
117The default is
118.Dq .ssh/authorized_keys .
119.It Cm Banner
120In some jurisdictions, sending a warning message before authentication
121may be relevant for getting legal protection.
122The contents of the specified file are sent to the remote user before
123authentication is allowed.
124This option is only available for protocol version 2.
125By default, no banner is displayed.
126.Pp
127.It Cm ChallengeResponseAuthentication
128Specifies whether challenge response authentication is allowed.
129All authentication styles from
130.Xr login.conf 5
131are supported.
132The default is
133.Dq yes .
134.It Cm Ciphers
135Specifies the ciphers allowed for protocol version 2.
136Multiple ciphers must be comma-separated.
137The default is
138.Pp
139.Bd -literal
140 ``aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour,
141 aes192-cbc,aes256-cbc''
142.Ed
143.It Cm ClientAliveInterval
144Sets a timeout interval in seconds after which if no data has been received
145from the client,
146.Nm sshd
147will send a message through the encrypted
148channel to request a response from the client.
149The default
150is 0, indicating that these messages will not be sent to the client.
151This option applies to protocol version 2 only.
152.It Cm ClientAliveCountMax
153Sets the number of client alive messages (see above) which may be
154sent without
155.Nm sshd
156receiving any messages back from the client. If this threshold is
157reached while client alive messages are being sent,
158.Nm sshd
159will disconnect the client, terminating the session. It is important
160to note that the use of client alive messages is very different from
161.Cm KeepAlive
162(below). The client alive messages are sent through the
163encrypted channel and therefore will not be spoofable. The TCP keepalive
164option enabled by
165.Cm KeepAlive
166is spoofable. The client alive mechanism is valuable when the client or
167server depend on knowing when a connection has become inactive.
168.Pp
169The default value is 3. If
170.Cm ClientAliveInterval
171(above) is set to 15, and
172.Cm ClientAliveCountMax
173is left at the default, unresponsive ssh clients
174will be disconnected after approximately 45 seconds.
175.It Cm Compression
176Specifies whether compression is allowed.
177The argument must be
178.Dq yes
179or
180.Dq no .
181The default is
182.Dq yes .
183.It Cm DenyGroups
184This keyword can be followed by a list of group name patterns, separated
185by spaces.
186Login is disallowed for users whose primary group or supplementary
187group list matches one of the patterns.
188.Ql \&*
189and
190.Ql ?
191can be used as
192wildcards in the patterns.
193Only group names are valid; a numerical group ID is not recognized.
194By default, login is allowed for all groups.
195.Pp
196.It Cm DenyUsers
197This keyword can be followed by a list of user name patterns, separated
198by spaces.
199Login is disallowed for user names that match one of the patterns.
200.Ql \&*
201and
202.Ql ?
203can be used as wildcards in the patterns.
204Only user names are valid; a numerical user ID is not recognized.
205By default, login is allowed for all users.
206If the pattern takes the form USER@HOST then USER and HOST
207are separately checked, restricting logins to particular
208users from particular hosts.
209.It Cm GatewayPorts
210Specifies whether remote hosts are allowed to connect to ports
211forwarded for the client.
212By default,
213.Nm sshd
214binds remote port forwardings to the loopback address. This
215prevents other remote hosts from connecting to forwarded ports.
216.Cm GatewayPorts
217can be used to specify that
218.Nm sshd
219should bind remote port forwardings to the wildcard address,
220thus allowing remote hosts to connect to forwarded ports.
221The argument must be
222.Dq yes
223or
224.Dq no .
225The default is
226.Dq no .
227.It Cm HostbasedAuthentication
228Specifies whether rhosts or /etc/hosts.equiv authentication together
229with successful public key client host authentication is allowed
230(hostbased authentication).
231This option is similar to
232.Cm RhostsRSAAuthentication
233and applies to protocol version 2 only.
234The default is
235.Dq no .
236.It Cm HostKey
237Specifies a file containing a private host key
238used by SSH.
239The default is
240.Pa /etc/ssh/ssh_host_key
241for protocol version 1, and
242.Pa /etc/ssh/ssh_host_rsa_key
243and
244.Pa /etc/ssh/ssh_host_dsa_key
245for protocol version 2.
246Note that
247.Nm sshd
248will refuse to use a file if it is group/world-accessible.
249It is possible to have multiple host key files.
250.Dq rsa1
251keys are used for version 1 and
252.Dq dsa
253or
254.Dq rsa
255are used for version 2 of the SSH protocol.
256.It Cm IgnoreRhosts
257Specifies that
258.Pa .rhosts
259and
260.Pa .shosts
261files will not be used in
262.Cm RhostsAuthentication ,
263.Cm RhostsRSAAuthentication
264or
265.Cm HostbasedAuthentication .
266.Pp
267.Pa /etc/hosts.equiv
268and
269.Pa /etc/shosts.equiv
270are still used.
271The default is
272.Dq yes .
273.It Cm IgnoreUserKnownHosts
274Specifies whether
275.Nm sshd
276should ignore the user's
277.Pa $HOME/.ssh/known_hosts
278during
279.Cm RhostsRSAAuthentication
280or
281.Cm HostbasedAuthentication .
282The default is
283.Dq no .
284.It Cm KeepAlive
285Specifies whether the system should send TCP keepalive messages to the
286other side.
287If they are sent, death of the connection or crash of one
288of the machines will be properly noticed.
289However, this means that
290connections will die if the route is down temporarily, and some people
291find it annoying.
292On the other hand, if keepalives are not sent,
293sessions may hang indefinitely on the server, leaving
294.Dq ghost
295users and consuming server resources.
296.Pp
297The default is
298.Dq yes
299(to send keepalives), and the server will notice
300if the network goes down or the client host crashes.
301This avoids infinitely hanging sessions.
302.Pp
303To disable keepalives, the value should be set to
304.Dq no .
305.It Cm KerberosAuthentication
306Specifies whether Kerberos authentication is allowed.
307This can be in the form of a Kerberos ticket, or if
Ben Lindstrom9f049032002-06-21 00:59:05 +0000308.Cm PasswordAuthentication
309is yes, the password provided by the user will be validated through
310the Kerberos KDC.
311To use this option, the server needs a
312Kerberos servtab which allows the verification of the KDC's identity.
313Default is
314.Dq no .
315.It Cm KerberosOrLocalPasswd
316If set then if password authentication through Kerberos fails then
317the password will be validated via any additional local mechanism
318such as
319.Pa /etc/passwd .
320Default is
321.Dq yes .
322.It Cm KerberosTgtPassing
323Specifies whether a Kerberos TGT may be forwarded to the server.
324Default is
325.Dq no ,
326as this only works when the Kerberos KDC is actually an AFS kaserver.
327.It Cm KerberosTicketCleanup
328Specifies whether to automatically destroy the user's ticket cache
329file on logout.
330Default is
331.Dq yes .
332.It Cm KeyRegenerationInterval
333In protocol version 1, the ephemeral server key is automatically regenerated
334after this many seconds (if it has been used).
335The purpose of regeneration is to prevent
336decrypting captured sessions by later breaking into the machine and
337stealing the keys.
338The key is never stored anywhere.
339If the value is 0, the key is never regenerated.
340The default is 3600 (seconds).
341.It Cm ListenAddress
342Specifies the local addresses
343.Nm sshd
344should listen on.
345The following forms may be used:
346.Pp
347.Bl -item -offset indent -compact
348.It
349.Cm ListenAddress
350.Sm off
351.Ar host No | Ar IPv4_addr No | Ar IPv6_addr
352.Sm on
353.It
354.Cm ListenAddress
355.Sm off
356.Ar host No | Ar IPv4_addr No : Ar port
357.Sm on
358.It
359.Cm ListenAddress
360.Sm off
361.Oo
362.Ar host No | Ar IPv6_addr Oc : Ar port
363.Sm on
364.El
365.Pp
366If
367.Ar port
368is not specified,
369.Nm sshd
370will listen on the address and all prior
371.Cm Port
372options specified. The default is to listen on all local
373addresses. Multiple
374.Cm ListenAddress
375options are permitted. Additionally, any
376.Cm Port
377options must precede this option for non port qualified addresses.
378.It Cm LoginGraceTime
379The server disconnects after this time if the user has not
380successfully logged in.
381If the value is 0, there is no time limit.
382The default is 600 (seconds).
383.It Cm LogLevel
384Gives the verbosity level that is used when logging messages from
385.Nm sshd .
386The possible values are:
387QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2 and DEBUG3.
388The default is INFO. DEBUG and DEBUG1 are equivalent. DEBUG2
389and DEBUG3 each specify higher levels of debugging output.
390Logging with a DEBUG level violates the privacy of users
391and is not recommended.
392.It Cm MACs
393Specifies the available MAC (message authentication code) algorithms.
394The MAC algorithm is used in protocol version 2
395for data integrity protection.
396Multiple algorithms must be comma-separated.
397The default is
398.Dq hmac-md5,hmac-sha1,hmac-ripemd160,hmac-sha1-96,hmac-md5-96 .
399.It Cm MaxStartups
400Specifies the maximum number of concurrent unauthenticated connections to the
401.Nm sshd
402daemon.
403Additional connections will be dropped until authentication succeeds or the
404.Cm LoginGraceTime
405expires for a connection.
406The default is 10.
407.Pp
408Alternatively, random early drop can be enabled by specifying
409the three colon separated values
410.Dq start:rate:full
411(e.g., "10:30:60").
412.Nm sshd
413will refuse connection attempts with a probability of
414.Dq rate/100
415(30%)
416if there are currently
417.Dq start
418(10)
419unauthenticated connections.
420The probability increases linearly and all connection attempts
421are refused if the number of unauthenticated connections reaches
422.Dq full
423(60).
Damien Miller136d4412002-06-26 23:05:16 +1000424.It Cm PAMAuthenticationViaKbdInt
425Specifies whether PAM challenge response authentication is allowed. This
426allows the use of most PAM challenge response authentication modules, but
427it will allow password authentication regardless of whether
428.Cm PasswordAuthentication
429is enabled.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000430.It Cm PasswordAuthentication
431Specifies whether password authentication is allowed.
432The default is
433.Dq yes .
434.It Cm PermitEmptyPasswords
435When password authentication is allowed, it specifies whether the
436server allows login to accounts with empty password strings.
437The default is
438.Dq no .
439.It Cm PermitRootLogin
440Specifies whether root can login using
441.Xr ssh 1 .
442The argument must be
443.Dq yes ,
444.Dq without-password ,
445.Dq forced-commands-only
446or
447.Dq no .
448The default is
449.Dq yes .
450.Pp
451If this option is set to
452.Dq without-password
453password authentication is disabled for root.
454.Pp
455If this option is set to
456.Dq forced-commands-only
457root login with public key authentication will be allowed,
458but only if the
459.Ar command
460option has been specified
461(which may be useful for taking remote backups even if root login is
462normally not allowed). All other authentication methods are disabled
463for root.
464.Pp
465If this option is set to
466.Dq no
467root is not allowed to login.
468.It Cm PidFile
Ben Lindstrom959de992002-06-23 00:35:25 +0000469Specifies the file that contains the process ID of the
Ben Lindstrom9f049032002-06-21 00:59:05 +0000470.Nm sshd
471daemon.
472The default is
473.Pa /var/run/sshd.pid .
474.It Cm Port
475Specifies the port number that
476.Nm sshd
477listens on.
478The default is 22.
479Multiple options of this type are permitted.
480See also
481.Cm ListenAddress .
482.It Cm PrintLastLog
483Specifies whether
484.Nm sshd
485should print the date and time when the user last logged in.
486The default is
487.Dq yes .
488.It Cm PrintMotd
489Specifies whether
490.Nm sshd
491should print
492.Pa /etc/motd
493when a user logs in interactively.
494(On some systems it is also printed by the shell,
495.Pa /etc/profile ,
496or equivalent.)
497The default is
498.Dq yes .
499.It Cm Protocol
500Specifies the protocol versions
501.Nm sshd
502should support.
503The possible values are
504.Dq 1
505and
506.Dq 2 .
507Multiple versions must be comma-separated.
508The default is
509.Dq 2,1 .
510.It Cm PubkeyAuthentication
511Specifies whether public key authentication is allowed.
512The default is
513.Dq yes .
514Note that this option applies to protocol version 2 only.
515.It Cm RhostsAuthentication
516Specifies whether authentication using rhosts or /etc/hosts.equiv
517files is sufficient.
518Normally, this method should not be permitted because it is insecure.
519.Cm RhostsRSAAuthentication
520should be used
521instead, because it performs RSA-based host authentication in addition
522to normal rhosts or /etc/hosts.equiv authentication.
523The default is
524.Dq no .
525This option applies to protocol version 1 only.
526.It Cm RhostsRSAAuthentication
527Specifies whether rhosts or /etc/hosts.equiv authentication together
528with successful RSA host authentication is allowed.
529The default is
530.Dq no .
531This option applies to protocol version 1 only.
532.It Cm RSAAuthentication
533Specifies whether pure RSA authentication is allowed.
534The default is
535.Dq yes .
536This option applies to protocol version 1 only.
537.It Cm ServerKeyBits
538Defines the number of bits in the ephemeral protocol version 1 server key.
539The minimum value is 512, and the default is 768.
540.It Cm StrictModes
541Specifies whether
542.Nm sshd
543should check file modes and ownership of the
544user's files and home directory before accepting login.
545This is normally desirable because novices sometimes accidentally leave their
546directory or files world-writable.
547The default is
548.Dq yes .
549.It Cm Subsystem
550Configures an external subsystem (e.g., file transfer daemon).
551Arguments should be a subsystem name and a command to execute upon subsystem
552request.
553The command
554.Xr sftp-server 8
555implements the
556.Dq sftp
557file transfer subsystem.
558By default no subsystems are defined.
559Note that this option applies to protocol version 2 only.
560.It Cm SyslogFacility
561Gives the facility code that is used when logging messages from
562.Nm sshd .
563The possible values are: DAEMON, USER, AUTH, LOCAL0, LOCAL1, LOCAL2,
564LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7.
565The default is AUTH.
566.It Cm UseLogin
567Specifies whether
568.Xr login 1
569is used for interactive login sessions.
570The default is
571.Dq no .
572Note that
573.Xr login 1
574is never used for remote command execution.
575Note also, that if this is enabled,
576.Cm X11Forwarding
577will be disabled because
578.Xr login 1
579does not know how to handle
580.Xr xauth 1
581cookies. If
582.Cm UsePrivilegeSeparation
583is specified, it will be disabled after authentication.
584.It Cm UsePrivilegeSeparation
585Specifies whether
586.Nm sshd
587separates privileges by creating an unprivileged child process
588to deal with incoming network traffic. After successful authentication,
589another process will be created that has the privilege of the authenticated
590user. The goal of privilege separation is to prevent privilege
591escalation by containing any corruption within the unprivileged processes.
592The default is
593.Dq yes .
594.It Cm VerifyReverseMapping
595Specifies whether
596.Nm sshd
597should try to verify the remote host name and check that
598the resolved host name for the remote IP address maps back to the
599very same IP address.
600The default is
601.Dq no .
602.It Cm X11DisplayOffset
603Specifies the first display number available for
604.Nm sshd Ns 's
605X11 forwarding.
606This prevents
607.Nm sshd
608from interfering with real X11 servers.
609The default is 10.
610.It Cm X11Forwarding
611Specifies whether X11 forwarding is permitted.
612The default is
613.Dq no .
614Note that disabling X11 forwarding does not improve security in any
615way, as users can always install their own forwarders.
616X11 forwarding is automatically disabled if
617.Cm UseLogin
618is enabled.
619.It Cm X11UseLocalhost
620Specifies whether
621.Nm sshd
622should bind the X11 forwarding server to the loopback address or to
623the wildcard address. By default,
624.Nm sshd
625binds the forwarding server to the loopback address and sets the
626hostname part of the
627.Ev DISPLAY
628environment variable to
629.Dq localhost .
630This prevents remote hosts from connecting to the fake display.
631However, some older X11 clients may not function with this
632configuration.
633.Cm X11UseLocalhost
634may be set to
635.Dq no
636to specify that the forwarding server should be bound to the wildcard
637address.
638The argument must be
639.Dq yes
640or
641.Dq no .
642The default is
643.Dq yes .
644.It Cm XAuthLocation
645Specifies the location of the
646.Xr xauth 1
647program.
648The default is
649.Pa /usr/X11R6/bin/xauth .
650.El
651.Ss Time Formats
652.Pp
653.Nm sshd
654command-line arguments and configuration file options that specify time
655may be expressed using a sequence of the form:
656.Sm off
657.Ar time Oo Ar qualifier Oc ,
658.Sm on
659where
660.Ar time
661is a positive integer value and
662.Ar qualifier
663is one of the following:
664.Pp
665.Bl -tag -width Ds -compact -offset indent
666.It Cm <none>
667seconds
668.It Cm s | Cm S
669seconds
670.It Cm m | Cm M
671minutes
672.It Cm h | Cm H
673hours
674.It Cm d | Cm D
675days
676.It Cm w | Cm W
677weeks
678.El
679.Pp
680Each member of the sequence is added together to calculate
681the total time value.
682.Pp
683Time format examples:
684.Pp
685.Bl -tag -width Ds -compact -offset indent
686.It 600
687600 seconds (10 minutes)
688.It 10m
68910 minutes
690.It 1h30m
6911 hour 30 minutes (90 minutes)
692.El
693.Sh FILES
694.Bl -tag -width Ds
695.It Pa /etc/ssh/sshd_config
696Contains configuration data for
697.Nm sshd .
698This file should be writable by root only, but it is recommended
699(though not necessary) that it be world-readable.
700.El
701.Sh AUTHORS
702OpenSSH is a derivative of the original and free
703ssh 1.2.12 release by Tatu Ylonen.
704Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
705Theo de Raadt and Dug Song
706removed many bugs, re-added newer features and
707created OpenSSH.
708Markus Friedl contributed the support for SSH
709protocol versions 1.5 and 2.0.
710Niels Provos and Markus Friedl contributed support
711for privilege separation.
712.Sh SEE ALSO
713.Xr sshd 8