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