Merge branch 'vendor/BMAKE'
[dragonfly.git] / crypto / openssh / sshd.8
1 .\"
2 .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
3 .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
4 .\"                    All rights reserved
5 .\"
6 .\" As far as I am concerned, the code I have written for this software
7 .\" can be used freely for any purpose.  Any derived versions of this
8 .\" software must be clearly marked as such, and if the derived work is
9 .\" incompatible with the protocol description in the RFC file, it must be
10 .\" called by a name other than "ssh" or "Secure Shell".
11 .\"
12 .\" Copyright (c) 1999,2000 Markus Friedl.  All rights reserved.
13 .\" Copyright (c) 1999 Aaron Campbell.  All rights reserved.
14 .\" Copyright (c) 1999 Theo de Raadt.  All rights reserved.
15 .\"
16 .\" Redistribution and use in source and binary forms, with or without
17 .\" modification, are permitted provided that the following conditions
18 .\" are met:
19 .\" 1. Redistributions of source code must retain the above copyright
20 .\"    notice, this list of conditions and the following disclaimer.
21 .\" 2. Redistributions in binary form must reproduce the above copyright
22 .\"    notice, this list of conditions and the following disclaimer in the
23 .\"    documentation and/or other materials provided with the distribution.
24 .\"
25 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
26 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
27 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
28 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
29 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
30 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
31 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
32 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
33 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
34 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
35 .\"
36 .\" $OpenBSD: sshd.8,v 1.263 2011/08/02 01:22:11 djm Exp $
37 .Dd $Mdocdate: August 2 2011 $
38 .Dt SSHD 8
39 .Os
40 .Sh NAME
41 .Nm sshd
42 .Nd OpenSSH SSH daemon
43 .Sh SYNOPSIS
44 .Nm sshd
45 .Bk -words
46 .Op Fl 46DdeiqTt
47 .Op Fl b Ar bits
48 .Op Fl C Ar connection_spec
49 .Op Fl c Ar host_certificate_file
50 .Op Fl f Ar config_file
51 .Op Fl g Ar login_grace_time
52 .Op Fl h Ar host_key_file
53 .Op Fl k Ar key_gen_time
54 .Op Fl o Ar option
55 .Op Fl p Ar port
56 .Op Fl u Ar len
57 .Ek
58 .Sh DESCRIPTION
59 .Nm
60 (OpenSSH Daemon) is the daemon program for
61 .Xr ssh 1 .
62 Together these programs replace
63 .Xr rlogin 1
64 and
65 .Xr rsh 1 ,
66 and provide secure encrypted communications between two untrusted hosts
67 over an insecure network.
68 .Pp
69 .Nm
70 listens for connections from clients.
71 It is normally started at boot from
72 .Pa /etc/rc.d/sshd .
73 It forks a new
74 daemon for each incoming connection.
75 The forked daemons handle
76 key exchange, encryption, authentication, command execution,
77 and data exchange.
78 .Pp
79 .Nm
80 can be configured using command-line options or a configuration file
81 (by default
82 .Xr sshd_config 5 ) ;
83 command-line options override values specified in the
84 configuration file.
85 .Nm
86 rereads its configuration file when it receives a hangup signal,
87 .Dv SIGHUP ,
88 by executing itself with the name and options it was started with, e.g.\&
89 .Pa /usr/sbin/sshd .
90 .Pp
91 The options are as follows:
92 .Bl -tag -width Ds
93 .It Fl 4
94 Forces
95 .Nm
96 to use IPv4 addresses only.
97 .It Fl 6
98 Forces
99 .Nm
100 to use IPv6 addresses only.
101 .It Fl b Ar bits
102 Specifies the number of bits in the ephemeral protocol version 1
103 server key (default 1024).
104 .It Fl C Ar connection_spec
105 Specify the connection parameters to use for the
106 .Fl T
107 extended test mode.
108 If provided, any
109 .Cm Match
110 directives in the configuration file
111 that would apply to the specified user, host, and address will be set before
112 the configuration is written to standard output.
113 The connection parameters are supplied as keyword=value pairs.
114 The keywords are
115 .Dq user ,
116 .Dq host ,
117 and
118 .Dq addr .
119 All are required and may be supplied in any order, either with multiple
120 .Fl C
121 options or as a comma-separated list.
122 .It Fl c Ar host_certificate_file
123 Specifies a path to a certificate file to identify
124 .Nm
125 during key exchange.
126 The certificate file must match a host key file specified using the
127 .Fl h
128 option or the
129 .Cm HostKey
130 configuration directive.
131 .It Fl D
132 When this option is specified,
133 .Nm
134 will not detach and does not become a daemon.
135 This allows easy monitoring of
136 .Nm sshd .
137 .It Fl d
138 Debug mode.
139 The server sends verbose debug output to standard error,
140 and does not put itself in the background.
141 The server also will not fork and will only process one connection.
142 This option is only intended for debugging for the server.
143 Multiple
144 .Fl d
145 options increase the debugging level.
146 Maximum is 3.
147 .It Fl e
148 When this option is specified,
149 .Nm
150 will send the output to the standard error instead of the system log.
151 .It Fl f Ar config_file
152 Specifies the name of the configuration file.
153 The default is
154 .Pa /etc/ssh/sshd_config .
155 .Nm
156 refuses to start if there is no configuration file.
157 .It Fl g Ar login_grace_time
158 Gives the grace time for clients to authenticate themselves (default
159 120 seconds).
160 If the client fails to authenticate the user within
161 this many seconds, the server disconnects and exits.
162 A value of zero indicates no limit.
163 .It Fl h Ar host_key_file
164 Specifies a file from which a host key is read.
165 This option must be given if
166 .Nm
167 is not run as root (as the normal
168 host key files are normally not readable by anyone but root).
169 The default is
170 .Pa /etc/ssh/ssh_host_key
171 for protocol version 1, and
172 .Pa /etc/ssh/ssh_host_dsa_key ,
173 .Pa /etc/ssh/ssh_host_ecdsa_key
174 and
175 .Pa /etc/ssh/ssh_host_rsa_key
176 for protocol version 2.
177 It is possible to have multiple host key files for
178 the different protocol versions and host key algorithms.
179 .It Fl i
180 Specifies that
181 .Nm
182 is being run from
183 .Xr inetd 8 .
184 .Nm
185 is normally not run
186 from inetd because it needs to generate the server key before it can
187 respond to the client, and this may take tens of seconds.
188 Clients would have to wait too long if the key was regenerated every time.
189 However, with small key sizes (e.g. 512) using
190 .Nm
191 from inetd may
192 be feasible.
193 .It Fl k Ar key_gen_time
194 Specifies how often the ephemeral protocol version 1 server key is
195 regenerated (default 3600 seconds, or one hour).
196 The motivation for regenerating the key fairly
197 often is that the key is not stored anywhere, and after about an hour
198 it becomes impossible to recover the key for decrypting intercepted
199 communications even if the machine is cracked into or physically
200 seized.
201 A value of zero indicates that the key will never be regenerated.
202 .It Fl o Ar option
203 Can be used to give options in the format used in the configuration file.
204 This is useful for specifying options for which there is no separate
205 command-line flag.
206 For full details of the options, and their values, see
207 .Xr sshd_config 5 .
208 .It Fl p Ar port
209 Specifies the port on which the server listens for connections
210 (default 22).
211 Multiple port options are permitted.
212 Ports specified in the configuration file with the
213 .Cm Port
214 option are ignored when a command-line port is specified.
215 Ports specified using the
216 .Cm ListenAddress
217 option override command-line ports.
218 .It Fl q
219 Quiet mode.
220 Nothing is sent to the system log.
221 Normally the beginning,
222 authentication, and termination of each connection is logged.
223 .It Fl T
224 Extended test mode.
225 Check the validity of the configuration file, output the effective configuration
226 to stdout and then exit.
227 Optionally,
228 .Cm Match
229 rules may be applied by specifying the connection parameters using one or more
230 .Fl C
231 options.
232 .It Fl t
233 Test mode.
234 Only check the validity of the configuration file and sanity of the keys.
235 This is useful for updating
236 .Nm
237 reliably as configuration options may change.
238 .It Fl u Ar len
239 This option is used to specify the size of the field
240 in the
241 .Li utmp
242 structure that holds the remote host name.
243 If the resolved host name is longer than
244 .Ar len ,
245 the dotted decimal value will be used instead.
246 This allows hosts with very long host names that
247 overflow this field to still be uniquely identified.
248 Specifying
249 .Fl u0
250 indicates that only dotted decimal addresses
251 should be put into the
252 .Pa utmp
253 file.
254 .Fl u0
255 may also be used to prevent
256 .Nm
257 from making DNS requests unless the authentication
258 mechanism or configuration requires it.
259 Authentication mechanisms that may require DNS include
260 .Cm RhostsRSAAuthentication ,
261 .Cm HostbasedAuthentication ,
262 and using a
263 .Cm from="pattern-list"
264 option in a key file.
265 Configuration options that require DNS include using a
266 USER@HOST pattern in
267 .Cm AllowUsers
268 or
269 .Cm DenyUsers .
270 .El
271 .Sh AUTHENTICATION
272 The OpenSSH SSH daemon supports SSH protocols 1 and 2.
273 The default is to use protocol 2 only,
274 though this can be changed via the
275 .Cm Protocol
276 option in
277 .Xr sshd_config 5 .
278 Protocol 2 supports DSA, ECDSA and RSA keys;
279 protocol 1 only supports RSA keys.
280 For both protocols,
281 each host has a host-specific key,
282 normally 2048 bits,
283 used to identify the host.
284 .Pp
285 Forward security for protocol 1 is provided through
286 an additional server key,
287 normally 768 bits,
288 generated when the server starts.
289 This key is normally regenerated every hour if it has been used, and
290 is never stored on disk.
291 Whenever a client connects, the daemon responds with its public
292 host and server keys.
293 The client compares the
294 RSA host key against its own database to verify that it has not changed.
295 The client then generates a 256-bit random number.
296 It encrypts this
297 random number using both the host key and the server key, and sends
298 the encrypted number to the server.
299 Both sides then use this
300 random number as a session key which is used to encrypt all further
301 communications in the session.
302 The rest of the session is encrypted
303 using a conventional cipher, currently Blowfish or 3DES, with 3DES
304 being used by default.
305 The client selects the encryption algorithm
306 to use from those offered by the server.
307 .Pp
308 For protocol 2,
309 forward security is provided through a Diffie-Hellman key agreement.
310 This key agreement results in a shared session key.
311 The rest of the session is encrypted using a symmetric cipher, currently
312 128-bit AES, Blowfish, 3DES, CAST128, Arcfour, 192-bit AES, or 256-bit AES.
313 The client selects the encryption algorithm
314 to use from those offered by the server.
315 Additionally, session integrity is provided
316 through a cryptographic message authentication code
317 (hmac-md5, hmac-sha1, umac-64, hmac-ripemd160,
318 hmac-sha2-256 or hmac-sha2-512).
319 .Pp
320 Finally, the server and the client enter an authentication dialog.
321 The client tries to authenticate itself using
322 host-based authentication,
323 public key authentication,
324 challenge-response authentication,
325 or password authentication.
326 .Pp
327 Regardless of the authentication type, the account is checked to
328 ensure that it is accessible.  An account is not accessible if it is
329 locked, listed in
330 .Cm DenyUsers
331 or its group is listed in
332 .Cm DenyGroups
333 \&.  The definition of a locked account is system dependant. Some platforms
334 have their own account database (eg AIX) and some modify the passwd field (
335 .Ql \&*LK\&*
336 on Solaris and UnixWare,
337 .Ql \&*
338 on HP-UX, containing
339 .Ql Nologin
340 on Tru64,
341 a leading
342 .Ql \&*LOCKED\&*
343 on FreeBSD and a leading
344 .Ql \&!
345 on most Linuxes).
346 If there is a requirement to disable password authentication
347 for the account while allowing still public-key, then the passwd field
348 should be set to something other than these values (eg
349 .Ql NP
350 or
351 .Ql \&*NP\&*
352 ).
353 .Pp
354 If the client successfully authenticates itself, a dialog for
355 preparing the session is entered.
356 At this time the client may request
357 things like allocating a pseudo-tty, forwarding X11 connections,
358 forwarding TCP connections, or forwarding the authentication agent
359 connection over the secure channel.
360 .Pp
361 After this, the client either requests a shell or execution of a command.
362 The sides then enter session mode.
363 In this mode, either side may send
364 data at any time, and such data is forwarded to/from the shell or
365 command on the server side, and the user terminal in the client side.
366 .Pp
367 When the user program terminates and all forwarded X11 and other
368 connections have been closed, the server sends command exit status to
369 the client, and both sides exit.
370 .Sh LOGIN PROCESS
371 When a user successfully logs in,
372 .Nm
373 does the following:
374 .Bl -enum -offset indent
375 .It
376 If the login is on a tty, and no command has been specified,
377 prints last login time and
378 .Pa /etc/motd
379 (unless prevented in the configuration file or by
380 .Pa ~/.hushlogin ;
381 see the
382 .Sx FILES
383 section).
384 .It
385 If the login is on a tty, records login time.
386 .It
387 Checks
388 .Pa /etc/nologin and
389 .Pa /var/run/nologin ;
390 if one exists, it prints the contents and quits
391 (unless root).
392 .It
393 Changes to run with normal user privileges.
394 .It
395 Sets up basic environment.
396 .It
397 Reads the file
398 .Pa ~/.ssh/environment ,
399 if it exists, and users are allowed to change their environment.
400 See the
401 .Cm PermitUserEnvironment
402 option in
403 .Xr sshd_config 5 .
404 .It
405 Changes to user's home directory.
406 .It
407 If
408 .Pa ~/.ssh/rc
409 exists, runs it; else if
410 .Pa /etc/ssh/sshrc
411 exists, runs
412 it; otherwise runs
413 .Xr xauth 1 .
414 The
415 .Dq rc
416 files are given the X11
417 authentication protocol and cookie (if applicable) in standard input.
418 See
419 .Sx SSHRC ,
420 below.
421 .It
422 Runs user's shell or command.
423 .El
424 .Sh SSHRC
425 If the file
426 .Pa ~/.ssh/rc
427 exists,
428 .Xr sh 1
429 runs it after reading the
430 environment files but before starting the user's shell or command.
431 It must not produce any output on stdout; stderr must be used
432 instead.
433 If X11 forwarding is in use, it will receive the "proto cookie" pair in
434 its standard input (and
435 .Ev DISPLAY
436 in its environment).
437 The script must call
438 .Xr xauth 1
439 because
440 .Nm
441 will not run xauth automatically to add X11 cookies.
442 .Pp
443 The primary purpose of this file is to run any initialization routines
444 which may be needed before the user's home directory becomes
445 accessible; AFS is a particular example of such an environment.
446 .Pp
447 This file will probably contain some initialization code followed by
448 something similar to:
449 .Bd -literal -offset 3n
450 if read proto cookie && [ -n "$DISPLAY" ]; then
451         if [ `echo $DISPLAY | cut -c1-10` = 'localhost:' ]; then
452                 # X11UseLocalhost=yes
453                 echo add unix:`echo $DISPLAY |
454                     cut -c11-` $proto $cookie
455         else
456                 # X11UseLocalhost=no
457                 echo add $DISPLAY $proto $cookie
458         fi | xauth -q -
459 fi
460 .Ed
461 .Pp
462 If this file does not exist,
463 .Pa /etc/ssh/sshrc
464 is run, and if that
465 does not exist either, xauth is used to add the cookie.
466 .Sh AUTHORIZED_KEYS FILE FORMAT
467 .Cm AuthorizedKeysFile
468 specifies the files containing public keys for
469 public key authentication;
470 if none is specified, the default is
471 .Pa ~/.ssh/authorized_keys
472 and
473 .Pa ~/.ssh/authorized_keys2 .
474 Each line of the file contains one
475 key (empty lines and lines starting with a
476 .Ql #
477 are ignored as
478 comments).
479 Protocol 1 public keys consist of the following space-separated fields:
480 options, bits, exponent, modulus, comment.
481 Protocol 2 public key consist of:
482 options, keytype, base64-encoded key, comment.
483 The options field is optional;
484 its presence is determined by whether the line starts
485 with a number or not (the options field never starts with a number).
486 The bits, exponent, modulus, and comment fields give the RSA key for
487 protocol version 1; the
488 comment field is not used for anything (but may be convenient for the
489 user to identify the key).
490 For protocol version 2 the keytype is
491 .Dq ecdsa-sha2-nistp256 ,
492 .Dq ecdsa-sha2-nistp384 ,
493 .Dq ecdsa-sha2-nistp521 ,
494 .Dq ssh-dss
495 or
496 .Dq ssh-rsa .
497 .Pp
498 Note that lines in this file are usually several hundred bytes long
499 (because of the size of the public key encoding) up to a limit of
500 8 kilobytes, which permits DSA keys up to 8 kilobits and RSA
501 keys up to 16 kilobits.
502 You don't want to type them in; instead, copy the
503 .Pa identity.pub ,
504 .Pa id_dsa.pub ,
505 .Pa id_ecdsa.pub ,
506 or the
507 .Pa id_rsa.pub
508 file and edit it.
509 .Pp
510 .Nm
511 enforces a minimum RSA key modulus size for protocol 1
512 and protocol 2 keys of 768 bits.
513 .Pp
514 The options (if present) consist of comma-separated option
515 specifications.
516 No spaces are permitted, except within double quotes.
517 The following option specifications are supported (note
518 that option keywords are case-insensitive):
519 .Bl -tag -width Ds
520 .It Cm cert-authority
521 Specifies that the listed key is a certification authority (CA) that is
522 trusted to validate signed certificates for user authentication.
523 .Pp
524 Certificates may encode access restrictions similar to these key options.
525 If both certificate restrictions and key options are present, the most
526 restrictive union of the two is applied.
527 .It Cm command="command"
528 Specifies that the command is executed whenever this key is used for
529 authentication.
530 The command supplied by the user (if any) is ignored.
531 The command is run on a pty if the client requests a pty;
532 otherwise it is run without a tty.
533 If an 8-bit clean channel is required,
534 one must not request a pty or should specify
535 .Cm no-pty .
536 A quote may be included in the command by quoting it with a backslash.
537 This option might be useful
538 to restrict certain public keys to perform just a specific operation.
539 An example might be a key that permits remote backups but nothing else.
540 Note that the client may specify TCP and/or X11
541 forwarding unless they are explicitly prohibited.
542 The command originally supplied by the client is available in the
543 .Ev SSH_ORIGINAL_COMMAND
544 environment variable.
545 Note that this option applies to shell, command or subsystem execution.
546 Also note that this command may be superseded by either a
547 .Xr sshd_config 5
548 .Cm ForceCommand
549 directive or a command embedded in a certificate.
550 .It Cm environment="NAME=value"
551 Specifies that the string is to be added to the environment when
552 logging in using this key.
553 Environment variables set this way
554 override other default environment values.
555 Multiple options of this type are permitted.
556 Environment processing is disabled by default and is
557 controlled via the
558 .Cm PermitUserEnvironment
559 option.
560 This option is automatically disabled if
561 .Cm UseLogin
562 is enabled.
563 .It Cm from="pattern-list"
564 Specifies that in addition to public key authentication, either the canonical
565 name of the remote host or its IP address must be present in the
566 comma-separated list of patterns.
567 See
568 .Sx PATTERNS
569 in
570 .Xr ssh_config 5
571 for more information on patterns.
572 .Pp
573 In addition to the wildcard matching that may be applied to hostnames or
574 addresses, a
575 .Cm from
576 stanza may match IP addresses using CIDR address/masklen notation.
577 .Pp
578 The purpose of this option is to optionally increase security: public key
579 authentication by itself does not trust the network or name servers or
580 anything (but the key); however, if somebody somehow steals the key, the key
581 permits an intruder to log in from anywhere in the world.
582 This additional option makes using a stolen key more difficult (name
583 servers and/or routers would have to be compromised in addition to
584 just the key).
585 .It Cm no-agent-forwarding
586 Forbids authentication agent forwarding when this key is used for
587 authentication.
588 .It Cm no-port-forwarding
589 Forbids TCP forwarding when this key is used for authentication.
590 Any port forward requests by the client will return an error.
591 This might be used, e.g. in connection with the
592 .Cm command
593 option.
594 .It Cm no-pty
595 Prevents tty allocation (a request to allocate a pty will fail).
596 .It Cm no-user-rc
597 Disables execution of
598 .Pa ~/.ssh/rc .
599 .It Cm no-X11-forwarding
600 Forbids X11 forwarding when this key is used for authentication.
601 Any X11 forward requests by the client will return an error.
602 .It Cm permitopen="host:port"
603 Limit local
604 .Li ``ssh -L''
605 port forwarding such that it may only connect to the specified host and
606 port.
607 IPv6 addresses can be specified by enclosing the address in square brackets.
608 Multiple
609 .Cm permitopen
610 options may be applied separated by commas.
611 No pattern matching is performed on the specified hostnames,
612 they must be literal domains or addresses.
613 .It Cm principals="principals"
614 On a
615 .Cm cert-authority
616 line, specifies allowed principals for certificate authentication as a
617 comma-separated list.
618 At least one name from the list must appear in the certificate's
619 list of principals for the certificate to be accepted.
620 This option is ignored for keys that are not marked as trusted certificate
621 signers using the
622 .Cm cert-authority
623 option.
624 .It Cm tunnel="n"
625 Force a
626 .Xr tun 4
627 device on the server.
628 Without this option, the next available device will be used if
629 the client requests a tunnel.
630 .El
631 .Pp
632 An example authorized_keys file:
633 .Bd -literal -offset 3n
634 # Comments allowed at start of line
635 ssh-rsa AAAAB3Nza...LiPk== user@example.net
636 from="*.sales.example.net,!pc.sales.example.net" ssh-rsa
637 AAAAB2...19Q== john@example.net
638 command="dump /home",no-pty,no-port-forwarding ssh-dss
639 AAAAC3...51R== example.net
640 permitopen="192.0.2.1:80",permitopen="192.0.2.2:25" ssh-dss
641 AAAAB5...21S==
642 tunnel="0",command="sh /etc/netstart tun0" ssh-rsa AAAA...==
643 jane@example.net
644 .Ed
645 .Sh SSH_KNOWN_HOSTS FILE FORMAT
646 The
647 .Pa /etc/ssh/ssh_known_hosts
648 and
649 .Pa ~/.ssh/known_hosts
650 files contain host public keys for all known hosts.
651 The global file should
652 be prepared by the administrator (optional), and the per-user file is
653 maintained automatically: whenever the user connects from an unknown host,
654 its key is added to the per-user file.
655 .Pp
656 Each line in these files contains the following fields: markers (optional),
657 hostnames, bits, exponent, modulus, comment.
658 The fields are separated by spaces.
659 .Pp
660 The marker is optional, but if it is present then it must be one of
661 .Dq @cert-authority ,
662 to indicate that the line contains a certification authority (CA) key,
663 or
664 .Dq @revoked ,
665 to indicate that the key contained on the line is revoked and must not ever
666 be accepted.
667 Only one marker should be used on a key line.
668 .Pp
669 Hostnames is a comma-separated list of patterns
670 .Pf ( Ql *
671 and
672 .Ql \&?
673 act as
674 wildcards); each pattern in turn is matched against the canonical host
675 name (when authenticating a client) or against the user-supplied
676 name (when authenticating a server).
677 A pattern may also be preceded by
678 .Ql \&!
679 to indicate negation: if the host name matches a negated
680 pattern, it is not accepted (by that line) even if it matched another
681 pattern on the line.
682 A hostname or address may optionally be enclosed within
683 .Ql \&[
684 and
685 .Ql \&]
686 brackets then followed by
687 .Ql \&:
688 and a non-standard port number.
689 .Pp
690 Alternately, hostnames may be stored in a hashed form which hides host names
691 and addresses should the file's contents be disclosed.
692 Hashed hostnames start with a
693 .Ql |
694 character.
695 Only one hashed hostname may appear on a single line and none of the above
696 negation or wildcard operators may be applied.
697 .Pp
698 Bits, exponent, and modulus are taken directly from the RSA host key; they
699 can be obtained, for example, from
700 .Pa /etc/ssh/ssh_host_key.pub .
701 The optional comment field continues to the end of the line, and is not used.
702 .Pp
703 Lines starting with
704 .Ql #
705 and empty lines are ignored as comments.
706 .Pp
707 When performing host authentication, authentication is accepted if any
708 matching line has the proper key; either one that matches exactly or,
709 if the server has presented a certificate for authentication, the key
710 of the certification authority that signed the certificate.
711 For a key to be trusted as a certification authority, it must use the
712 .Dq @cert-authority
713 marker described above.
714 .Pp
715 The known hosts file also provides a facility to mark keys as revoked,
716 for example when it is known that the associated private key has been
717 stolen.
718 Revoked keys are specified by including the
719 .Dq @revoked
720 marker at the beginning of the key line, and are never accepted for
721 authentication or as certification authorities, but instead will
722 produce a warning from
723 .Xr ssh 1
724 when they are encountered.
725 .Pp
726 It is permissible (but not
727 recommended) to have several lines or different host keys for the same
728 names.
729 This will inevitably happen when short forms of host names
730 from different domains are put in the file.
731 It is possible
732 that the files contain conflicting information; authentication is
733 accepted if valid information can be found from either file.
734 .Pp
735 Note that the lines in these files are typically hundreds of characters
736 long, and you definitely don't want to type in the host keys by hand.
737 Rather, generate them by a script,
738 .Xr ssh-keyscan 1
739 or by taking
740 .Pa /etc/ssh/ssh_host_key.pub
741 and adding the host names at the front.
742 .Xr ssh-keygen 1
743 also offers some basic automated editing for
744 .Pa ~/.ssh/known_hosts
745 including removing hosts matching a host name and converting all host
746 names to their hashed representations.
747 .Pp
748 An example ssh_known_hosts file:
749 .Bd -literal -offset 3n
750 # Comments allowed at start of line
751 closenet,...,192.0.2.53 1024 37 159...93 closenet.example.net
752 cvs.example.net,192.0.2.10 ssh-rsa AAAA1234.....=
753 # A hashed hostname
754 |1|JfKTdBh7rNbXkVAQCRp4OQoPfmI=|USECr3SWf1JUPsms5AqfD5QfxkM= ssh-rsa
755 AAAA1234.....=
756 # A revoked key
757 @revoked * ssh-rsa AAAAB5W...
758 # A CA key, accepted for any host in *.mydomain.com or *.mydomain.org
759 @cert-authority *.mydomain.org,*.mydomain.com ssh-rsa AAAAB5W...
760 .Ed
761 .Sh FILES
762 .Bl -tag -width Ds -compact
763 .It Pa ~/.hushlogin
764 This file is used to suppress printing the last login time and
765 .Pa /etc/motd ,
766 if
767 .Cm PrintLastLog
768 and
769 .Cm PrintMotd ,
770 respectively,
771 are enabled.
772 It does not suppress printing of the banner specified by
773 .Cm Banner .
774 .Pp
775 .It Pa ~/.rhosts
776 This file is used for host-based authentication (see
777 .Xr ssh 1
778 for more information).
779 On some machines this file may need to be
780 world-readable if the user's home directory is on an NFS partition,
781 because
782 .Nm
783 reads it as root.
784 Additionally, this file must be owned by the user,
785 and must not have write permissions for anyone else.
786 The recommended
787 permission for most machines is read/write for the user, and not
788 accessible by others.
789 .Pp
790 .It Pa ~/.shosts
791 This file is used in exactly the same way as
792 .Pa .rhosts ,
793 but allows host-based authentication without permitting login with
794 rlogin/rsh.
795 .Pp
796 .It Pa ~/.ssh/
797 This directory is the default location for all user-specific configuration
798 and authentication information.
799 There is no general requirement to keep the entire contents of this directory
800 secret, but the recommended permissions are read/write/execute for the user,
801 and not accessible by others.
802 .Pp
803 .It Pa ~/.ssh/authorized_keys
804 Lists the public keys (DSA/ECDSA/RSA) that can be used for logging in
805 as this user.
806 The format of this file is described above.
807 The content of the file is not highly sensitive, but the recommended
808 permissions are read/write for the user, and not accessible by others.
809 .Pp
810 If this file, the
811 .Pa ~/.ssh
812 directory, or the user's home directory are writable
813 by other users, then the file could be modified or replaced by unauthorized
814 users.
815 In this case,
816 .Nm
817 will not allow it to be used unless the
818 .Cm StrictModes
819 option has been set to
820 .Dq no .
821 .Pp
822 .It Pa ~/.ssh/environment
823 This file is read into the environment at login (if it exists).
824 It can only contain empty lines, comment lines (that start with
825 .Ql # ) ,
826 and assignment lines of the form name=value.
827 The file should be writable
828 only by the user; it need not be readable by anyone else.
829 Environment processing is disabled by default and is
830 controlled via the
831 .Cm PermitUserEnvironment
832 option.
833 .Pp
834 .It Pa ~/.ssh/known_hosts
835 Contains a list of host keys for all hosts the user has logged into
836 that are not already in the systemwide list of known host keys.
837 The format of this file is described above.
838 This file should be writable only by root/the owner and
839 can, but need not be, world-readable.
840 .Pp
841 .It Pa ~/.ssh/rc
842 Contains initialization routines to be run before
843 the user's home directory becomes accessible.
844 This file should be writable only by the user, and need not be
845 readable by anyone else.
846 .Pp
847 .It Pa /etc/hosts.allow
848 .It Pa /etc/hosts.deny
849 Access controls that should be enforced by tcp-wrappers are defined here.
850 Further details are described in
851 .Xr hosts_access 5 .
852 .Pp
853 .It Pa /etc/hosts.equiv
854 This file is for host-based authentication (see
855 .Xr ssh 1 ) .
856 It should only be writable by root.
857 .Pp
858 .It Pa /etc/ssh/moduli
859 Contains Diffie-Hellman groups used for the "Diffie-Hellman Group Exchange".
860 The file format is described in
861 .Xr moduli 5 .
862 .Pp
863 .It Pa /etc/motd
864 See
865 .Xr motd 5 .
866 .Pp
867 .It Pa /etc/nologin
868 If this file exists,
869 .Nm
870 refuses to let anyone except root log in.
871 The contents of the file
872 are displayed to anyone trying to log in, and non-root connections are
873 refused.
874 The file should be world-readable.
875 .Pp
876 .It Pa /etc/ssh/shosts.equiv
877 This file is used in exactly the same way as
878 .Pa hosts.equiv ,
879 but allows host-based authentication without permitting login with
880 rlogin/rsh.
881 .Pp
882 .It Pa /etc/ssh/ssh_host_key
883 .It Pa /etc/ssh/ssh_host_dsa_key
884 .It Pa /etc/ssh/ssh_host_ecdsa_key
885 .It Pa /etc/ssh/ssh_host_rsa_key
886 These three files contain the private parts of the host keys.
887 These files should only be owned by root, readable only by root, and not
888 accessible to others.
889 Note that
890 .Nm
891 does not start if these files are group/world-accessible.
892 .Pp
893 .It Pa /etc/ssh/ssh_host_key.pub
894 .It Pa /etc/ssh/ssh_host_dsa_key.pub
895 .It Pa /etc/ssh/ssh_host_ecdsa_key.pub
896 .It Pa /etc/ssh/ssh_host_rsa_key.pub
897 These three files contain the public parts of the host keys.
898 These files should be world-readable but writable only by
899 root.
900 Their contents should match the respective private parts.
901 These files are not
902 really used for anything; they are provided for the convenience of
903 the user so their contents can be copied to known hosts files.
904 These files are created using
905 .Xr ssh-keygen 1 .
906 .Pp
907 .It Pa /etc/ssh/ssh_known_hosts
908 Systemwide list of known host keys.
909 This file should be prepared by the
910 system administrator to contain the public host keys of all machines in the
911 organization.
912 The format of this file is described above.
913 This file should be writable only by root/the owner and
914 should be world-readable.
915 .Pp
916 .It Pa /etc/ssh/sshd_config
917 Contains configuration data for
918 .Nm sshd .
919 The file format and configuration options are described in
920 .Xr sshd_config 5 .
921 .Pp
922 .It Pa /etc/ssh/sshrc
923 Similar to
924 .Pa ~/.ssh/rc ,
925 it can be used to specify
926 machine-specific login-time initializations globally.
927 This file should be writable only by root, and should be world-readable.
928 .Pp
929 .It Pa /var/empty
930 .Xr chroot 2
931 directory used by
932 .Nm
933 during privilege separation in the pre-authentication phase.
934 The directory should not contain any files and must be owned by root
935 and not group or world-writable.
936 .Pp
937 .It Pa /var/run/sshd.pid
938 Contains the process ID of the
939 .Nm
940 listening for connections (if there are several daemons running
941 concurrently for different ports, this contains the process ID of the one
942 started last).
943 The content of this file is not sensitive; it can be world-readable.
944 .El
945 .Sh SEE ALSO
946 .Xr scp 1 ,
947 .Xr sftp 1 ,
948 .Xr ssh 1 ,
949 .Xr ssh-add 1 ,
950 .Xr ssh-agent 1 ,
951 .Xr ssh-keygen 1 ,
952 .Xr ssh-keyscan 1 ,
953 .Xr chroot 2 ,
954 .Xr hosts_access 5 ,
955 .Xr login.conf 5 ,
956 .Xr moduli 5 ,
957 .Xr sshd_config 5 ,
958 .Xr inetd 8 ,
959 .Xr sftp-server 8
960 .Sh AUTHORS
961 OpenSSH is a derivative of the original and free
962 ssh 1.2.12 release by Tatu Ylonen.
963 Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
964 Theo de Raadt and Dug Song
965 removed many bugs, re-added newer features and
966 created OpenSSH.
967 Markus Friedl contributed the support for SSH
968 protocol versions 1.5 and 2.0.
969 Niels Provos and Markus Friedl contributed support
970 for privilege separation.
971 .Sh CAVEATS
972 System security is not improved unless
973 .Nm rshd ,
974 .Nm rlogind ,
975 and
976 .Nm rexecd
977 are disabled (thus completely disabling
978 .Xr rlogin
979 and
980 .Xr rsh
981 into the machine).