Merge branch 'vendor/LESS'
[dragonfly.git] / crypto / openssh / sshd.8
1 .\"
2 .\" Author: Tatu Ylonen <>
3 .\" Copyright (c) 1995 Tatu Ylonen <>, 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 .\"
35 .\"
36 .\" $OpenBSD: sshd.8,v 1.260 2010/10/28 18:33:28 jmc Exp $
37 .Dd $Mdocdate: October 28 2010 $
38 .Dt SSHD 8
39 .Os
40 .Sh NAME
41 .Nm sshd
42 .Nd OpenSSH SSH daemon
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
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
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 or hmac-ripemd160).
318 .Pp
319 Finally, the server and the client enter an authentication dialog.
320 The client tries to authenticate itself using
321 host-based authentication,
322 public key authentication,
323 challenge-response authentication,
324 or password authentication.
325 .Pp
326 Regardless of the authentication type, the account is checked to
327 ensure that it is accessible.  An account is not accessible if it is
328 locked, listed in
329 .Cm DenyUsers
330 or its group is listed in
331 .Cm DenyGroups
332 \&.  The definition of a locked account is system dependant. Some platforms
333 have their own account database (eg AIX) and some modify the passwd field (
334 .Ql \&*LK\&*
335 on Solaris and UnixWare,
336 .Ql \&*
337 on HP-UX, containing
338 .Ql Nologin
339 on Tru64,
340 a leading
341 .Ql \&*LOCKED\&*
342 on FreeBSD and a leading
343 .Ql \&!
344 on most Linuxes).
345 If there is a requirement to disable password authentication
346 for the account while allowing still public-key, then the passwd field
347 should be set to something other than these values (eg
348 .Ql NP
349 or
350 .Ql \&*NP\&*
351 ).
352 .Pp
353 If the client successfully authenticates itself, a dialog for
354 preparing the session is entered.
355 At this time the client may request
356 things like allocating a pseudo-tty, forwarding X11 connections,
357 forwarding TCP connections, or forwarding the authentication agent
358 connection over the secure channel.
359 .Pp
360 After this, the client either requests a shell or execution of a command.
361 The sides then enter session mode.
362 In this mode, either side may send
363 data at any time, and such data is forwarded to/from the shell or
364 command on the server side, and the user terminal in the client side.
365 .Pp
366 When the user program terminates and all forwarded X11 and other
367 connections have been closed, the server sends command exit status to
368 the client, and both sides exit.
370 When a user successfully logs in,
371 .Nm
372 does the following:
373 .Bl -enum -offset indent
374 .It
375 If the login is on a tty, and no command has been specified,
376 prints last login time and
377 .Pa /etc/motd
378 (unless prevented in the configuration file or by
379 .Pa ~/.hushlogin ;
380 see the
381 .Sx FILES
382 section).
383 .It
384 If the login is on a tty, records login time.
385 .It
386 Checks
387 .Pa /etc/nologin and
388 .Pa /var/run/nologin ;
389 if one exists, it prints the contents and quits
390 (unless root).
391 .It
392 Changes to run with normal user privileges.
393 .It
394 Sets up basic environment.
395 .It
396 Reads the file
397 .Pa ~/.ssh/environment ,
398 if it exists, and users are allowed to change their environment.
399 See the
400 .Cm PermitUserEnvironment
401 option in
402 .Xr sshd_config 5 .
403 .It
404 Changes to user's home directory.
405 .It
406 If
407 .Pa ~/.ssh/rc
408 exists, runs it; else if
409 .Pa /etc/ssh/sshrc
410 exists, runs
411 it; otherwise runs
412 .Xr xauth 1 .
413 The
414 .Dq rc
415 files are given the X11
416 authentication protocol and cookie (if applicable) in standard input.
417 See
418 .Sx SSHRC ,
419 below.
420 .It
421 Runs user's shell or command.
422 .El
423 .Sh SSHRC
424 If the file
425 .Pa ~/.ssh/rc
426 exists,
427 .Xr sh 1
428 runs it after reading the
429 environment files but before starting the user's shell or command.
430 It must not produce any output on stdout; stderr must be used
431 instead.
432 If X11 forwarding is in use, it will receive the "proto cookie" pair in
433 its standard input (and
435 in its environment).
436 The script must call
437 .Xr xauth 1
438 because
439 .Nm
440 will not run xauth automatically to add X11 cookies.
441 .Pp
442 The primary purpose of this file is to run any initialization routines
443 which may be needed before the user's home directory becomes
444 accessible; AFS is a particular example of such an environment.
445 .Pp
446 This file will probably contain some initialization code followed by
447 something similar to:
448 .Bd -literal -offset 3n
449 if read proto cookie && [ -n "$DISPLAY" ]; then
450         if [ `echo $DISPLAY | cut -c1-10` = 'localhost:' ]; then
451                 # X11UseLocalhost=yes
452                 echo add unix:`echo $DISPLAY |
453                     cut -c11-` $proto $cookie
454         else
455                 # X11UseLocalhost=no
456                 echo add $DISPLAY $proto $cookie
457         fi | xauth -q -
458 fi
459 .Ed
460 .Pp
461 If this file does not exist,
462 .Pa /etc/ssh/sshrc
463 is run, and if that
464 does not exist either, xauth is used to add the cookie.
466 .Cm AuthorizedKeysFile
467 specifies the file containing public keys for
468 public key authentication;
469 if none is specified, the default is
470 .Pa ~/.ssh/authorized_keys .
471 Each line of the file contains one
472 key (empty lines and lines starting with a
473 .Ql #
474 are ignored as
476 Protocol 1 public keys consist of the following space-separated fields:
477 options, bits, exponent, modulus, comment.
478 Protocol 2 public key consist of:
479 options, keytype, base64-encoded key, comment.
480 The options field is optional;
481 its presence is determined by whether the line starts
482 with a number or not (the options field never starts with a number).
483 The bits, exponent, modulus, and comment fields give the RSA key for
484 protocol version 1; the
485 comment field is not used for anything (but may be convenient for the
486 user to identify the key).
487 For protocol version 2 the keytype is
488 .Dq ecdsa-sha2-nistp256 ,
489 .Dq ecdsa-sha2-nistp384 ,
490 .Dq ecdsa-sha2-nistp521 ,
491 .Dq ssh-dss
492 or
493 .Dq ssh-rsa .
494 .Pp
495 Note that lines in this file are usually several hundred bytes long
496 (because of the size of the public key encoding) up to a limit of
497 8 kilobytes, which permits DSA keys up to 8 kilobits and RSA
498 keys up to 16 kilobits.
499 You don't want to type them in; instead, copy the
500 .Pa ,
501 .Pa ,
502 .Pa ,
503 or the
504 .Pa
505 file and edit it.
506 .Pp
507 .Nm
508 enforces a minimum RSA key modulus size for protocol 1
509 and protocol 2 keys of 768 bits.
510 .Pp
511 The options (if present) consist of comma-separated option
512 specifications.
513 No spaces are permitted, except within double quotes.
514 The following option specifications are supported (note
515 that option keywords are case-insensitive):
516 .Bl -tag -width Ds
517 .It Cm cert-authority
518 Specifies that the listed key is a certification authority (CA) that is
519 trusted to validate signed certificates for user authentication.
520 .Pp
521 Certificates may encode access restrictions similar to these key options.
522 If both certificate restrictions and key options are present, the most
523 restrictive union of the two is applied.
524 .It Cm command="command"
525 Specifies that the command is executed whenever this key is used for
526 authentication.
527 The command supplied by the user (if any) is ignored.
528 The command is run on a pty if the client requests a pty;
529 otherwise it is run without a tty.
530 If an 8-bit clean channel is required,
531 one must not request a pty or should specify
532 .Cm no-pty .
533 A quote may be included in the command by quoting it with a backslash.
534 This option might be useful
535 to restrict certain public keys to perform just a specific operation.
536 An example might be a key that permits remote backups but nothing else.
537 Note that the client may specify TCP and/or X11
538 forwarding unless they are explicitly prohibited.
539 The command originally supplied by the client is available in the
541 environment variable.
542 Note that this option applies to shell, command or subsystem execution.
543 Also note that this command may be superseded by either a
544 .Xr sshd_config 5
545 .Cm ForceCommand
546 directive or a command embedded in a certificate.
547 .It Cm environment="NAME=value"
548 Specifies that the string is to be added to the environment when
549 logging in using this key.
550 Environment variables set this way
551 override other default environment values.
552 Multiple options of this type are permitted.
553 Environment processing is disabled by default and is
554 controlled via the
555 .Cm PermitUserEnvironment
556 option.
557 This option is automatically disabled if
558 .Cm UseLogin
559 is enabled.
560 .It Cm from="pattern-list"
561 Specifies that in addition to public key authentication, either the canonical
562 name of the remote host or its IP address must be present in the
563 comma-separated list of patterns.
564 See
566 in
567 .Xr ssh_config 5
568 for more information on patterns.
569 .Pp
570 In addition to the wildcard matching that may be applied to hostnames or
571 addresses, a
572 .Cm from
573 stanza may match IP addresses using CIDR address/masklen notation.
574 .Pp
575 The purpose of this option is to optionally increase security: public key
576 authentication by itself does not trust the network or name servers or
577 anything (but the key); however, if somebody somehow steals the key, the key
578 permits an intruder to log in from anywhere in the world.
579 This additional option makes using a stolen key more difficult (name
580 servers and/or routers would have to be compromised in addition to
581 just the key).
582 .It Cm no-agent-forwarding
583 Forbids authentication agent forwarding when this key is used for
584 authentication.
585 .It Cm no-port-forwarding
586 Forbids TCP forwarding when this key is used for authentication.
587 Any port forward requests by the client will return an error.
588 This might be used, e.g. in connection with the
589 .Cm command
590 option.
591 .It Cm no-pty
592 Prevents tty allocation (a request to allocate a pty will fail).
593 .It Cm no-user-rc
594 Disables execution of
595 .Pa ~/.ssh/rc .
596 .It Cm no-X11-forwarding
597 Forbids X11 forwarding when this key is used for authentication.
598 Any X11 forward requests by the client will return an error.
599 .It Cm permitopen="host:port"
600 Limit local
601 .Li ``ssh -L''
602 port forwarding such that it may only connect to the specified host and
603 port.
604 IPv6 addresses can be specified by enclosing the address in square brackets.
605 Multiple
606 .Cm permitopen
607 options may be applied separated by commas.
608 No pattern matching is performed on the specified hostnames,
609 they must be literal domains or addresses.
610 .It Cm principals="principals"
611 On a
612 .Cm cert-authority
613 line, specifies allowed principals for certificate authentication as a
614 comma-separated list.
615 At least one name from the list must appear in the certificate's
616 list of principals for the certificate to be accepted.
617 This option is ignored for keys that are not marked as trusted certificate
618 signers using the
619 .Cm cert-authority
620 option.
621 .It Cm tunnel="n"
622 Force a
623 .Xr tun 4
624 device on the server.
625 Without this option, the next available device will be used if
626 the client requests a tunnel.
627 .El
628 .Pp
629 An example authorized_keys file:
630 .Bd -literal -offset 3n
631 # Comments allowed at start of line
632 ssh-rsa AAAAB3Nza...LiPk==
633 from="*,!" ssh-rsa
634 AAAAB2...19Q==
635 command="dump /home",no-pty,no-port-forwarding ssh-dss
636 AAAAC3...51R==
637 permitopen="",permitopen="" ssh-dss
638 AAAAB5...21S==
639 tunnel="0",command="sh /etc/netstart tun0" ssh-rsa AAAA...==
641 .Ed
643 The
644 .Pa /etc/ssh/ssh_known_hosts
645 and
646 .Pa ~/.ssh/known_hosts
647 files contain host public keys for all known hosts.
648 The global file should
649 be prepared by the administrator (optional), and the per-user file is
650 maintained automatically: whenever the user connects from an unknown host,
651 its key is added to the per-user file.
652 .Pp
653 Each line in these files contains the following fields: markers (optional),
654 hostnames, bits, exponent, modulus, comment.
655 The fields are separated by spaces.
656 .Pp
657 The marker is optional, but if it is present then it must be one of
658 .Dq @cert-authority ,
659 to indicate that the line contains a certification authority (CA) key,
660 or
661 .Dq @revoked ,
662 to indicate that the key contained on the line is revoked and must not ever
663 be accepted.
664 Only one marker should be used on a key line.
665 .Pp
666 Hostnames is a comma-separated list of patterns
667 .Pf ( Ql *
668 and
669 .Ql \&?
670 act as
671 wildcards); each pattern in turn is matched against the canonical host
672 name (when authenticating a client) or against the user-supplied
673 name (when authenticating a server).
674 A pattern may also be preceded by
675 .Ql \&!
676 to indicate negation: if the host name matches a negated
677 pattern, it is not accepted (by that line) even if it matched another
678 pattern on the line.
679 A hostname or address may optionally be enclosed within
680 .Ql \&[
681 and
682 .Ql \&]
683 brackets then followed by
684 .Ql \&:
685 and a non-standard port number.
686 .Pp
687 Alternately, hostnames may be stored in a hashed form which hides host names
688 and addresses should the file's contents be disclosed.
689 Hashed hostnames start with a
690 .Ql |
691 character.
692 Only one hashed hostname may appear on a single line and none of the above
693 negation or wildcard operators may be applied.
694 .Pp
695 Bits, exponent, and modulus are taken directly from the RSA host key; they
696 can be obtained, for example, from
697 .Pa /etc/ssh/ .
698 The optional comment field continues to the end of the line, and is not used.
699 .Pp
700 Lines starting with
701 .Ql #
702 and empty lines are ignored as comments.
703 .Pp
704 When performing host authentication, authentication is accepted if any
705 matching line has the proper key; either one that matches exactly or,
706 if the server has presented a certificate for authentication, the key
707 of the certification authority that signed the certificate.
708 For a key to be trusted as a certification authority, it must use the
709 .Dq @cert-authority
710 marker described above.
711 .Pp
712 The known hosts file also provides a facility to mark keys as revoked,
713 for example when it is known that the associated private key has been
714 stolen.
715 Revoked keys are specified by including the
716 .Dq @revoked
717 marker at the beginning of the key line, and are never accepted for
718 authentication or as certification authorities, but instead will
719 produce a warning from
720 .Xr ssh 1
721 when they are encountered.
722 .Pp
723 It is permissible (but not
724 recommended) to have several lines or different host keys for the same
725 names.
726 This will inevitably happen when short forms of host names
727 from different domains are put in the file.
728 It is possible
729 that the files contain conflicting information; authentication is
730 accepted if valid information can be found from either file.
731 .Pp
732 Note that the lines in these files are typically hundreds of characters
733 long, and you definitely don't want to type in the host keys by hand.
734 Rather, generate them by a script,
735 .Xr ssh-keyscan 1
736 or by taking
737 .Pa /etc/ssh/
738 and adding the host names at the front.
739 .Xr ssh-keygen 1
740 also offers some basic automated editing for
741 .Pa ~/.ssh/known_hosts
742 including removing hosts matching a host name and converting all host
743 names to their hashed representations.
744 .Pp
745 An example ssh_known_hosts file:
746 .Bd -literal -offset 3n
747 # Comments allowed at start of line
748 closenet,..., 1024 37 159...93
749, ssh-rsa AAAA1234.....=
750 # A hashed hostname
751 |1|JfKTdBh7rNbXkVAQCRp4OQoPfmI=|USECr3SWf1JUPsms5AqfD5QfxkM= ssh-rsa
752 AAAA1234.....=
753 # A revoked key
754 @revoked * ssh-rsa AAAAB5W...
755 # A CA key, accepted for any host in * or *
756 @cert-authority *,* ssh-rsa AAAAB5W...
757 .Ed
758 .Sh FILES
759 .Bl -tag -width Ds -compact
760 .It Pa ~/.hushlogin
761 This file is used to suppress printing the last login time and
762 .Pa /etc/motd ,
763 if
764 .Cm PrintLastLog
765 and
766 .Cm PrintMotd ,
767 respectively,
768 are enabled.
769 It does not suppress printing of the banner specified by
770 .Cm Banner .
771 .Pp
772 .It Pa ~/.rhosts
773 This file is used for host-based authentication (see
774 .Xr ssh 1
775 for more information).
776 On some machines this file may need to be
777 world-readable if the user's home directory is on an NFS partition,
778 because
779 .Nm
780 reads it as root.
781 Additionally, this file must be owned by the user,
782 and must not have write permissions for anyone else.
783 The recommended
784 permission for most machines is read/write for the user, and not
785 accessible by others.
786 .Pp
787 .It Pa ~/.shosts
788 This file is used in exactly the same way as
789 .Pa .rhosts ,
790 but allows host-based authentication without permitting login with
791 rlogin/rsh.
792 .Pp
793 .It Pa ~/.ssh/
794 This directory is the default location for all user-specific configuration
795 and authentication information.
796 There is no general requirement to keep the entire contents of this directory
797 secret, but the recommended permissions are read/write/execute for the user,
798 and not accessible by others.
799 .Pp
800 .It Pa ~/.ssh/authorized_keys
801 Lists the public keys (DSA/ECDSA/RSA) that can be used for logging in
802 as this user.
803 The format of this file is described above.
804 The content of the file is not highly sensitive, but the recommended
805 permissions are read/write for the user, and not accessible by others.
806 .Pp
807 If this file, the
808 .Pa ~/.ssh
809 directory, or the user's home directory are writable
810 by other users, then the file could be modified or replaced by unauthorized
811 users.
812 In this case,
813 .Nm
814 will not allow it to be used unless the
815 .Cm StrictModes
816 option has been set to
817 .Dq no .
818 .Pp
819 .It Pa ~/.ssh/environment
820 This file is read into the environment at login (if it exists).
821 It can only contain empty lines, comment lines (that start with
822 .Ql # ) ,
823 and assignment lines of the form name=value.
824 The file should be writable
825 only by the user; it need not be readable by anyone else.
826 Environment processing is disabled by default and is
827 controlled via the
828 .Cm PermitUserEnvironment
829 option.
830 .Pp
831 .It Pa ~/.ssh/known_hosts
832 Contains a list of host keys for all hosts the user has logged into
833 that are not already in the systemwide list of known host keys.
834 The format of this file is described above.
835 This file should be writable only by root/the owner and
836 can, but need not be, world-readable.
837 .Pp
838 .It Pa ~/.ssh/rc
839 Contains initialization routines to be run before
840 the user's home directory becomes accessible.
841 This file should be writable only by the user, and need not be
842 readable by anyone else.
843 .Pp
844 .It Pa /etc/hosts.allow
845 .It Pa /etc/hosts.deny
846 Access controls that should be enforced by tcp-wrappers are defined here.
847 Further details are described in
848 .Xr hosts_access 5 .
849 .Pp
850 .It Pa /etc/hosts.equiv
851 This file is for host-based authentication (see
852 .Xr ssh 1 ) .
853 It should only be writable by root.
854 .Pp
855 .It Pa /etc/ssh/moduli
856 Contains Diffie-Hellman groups used for the "Diffie-Hellman Group Exchange".
857 The file format is described in
858 .Xr moduli 5 .
859 .Pp
860 .It Pa /etc/motd
861 See
862 .Xr motd 5 .
863 .Pp
864 .It Pa /etc/nologin
865 If this file exists,
866 .Nm
867 refuses to let anyone except root log in.
868 The contents of the file
869 are displayed to anyone trying to log in, and non-root connections are
870 refused.
871 The file should be world-readable.
872 .Pp
873 .It Pa /etc/ssh/shosts.equiv
874 This file is used in exactly the same way as
875 .Pa hosts.equiv ,
876 but allows host-based authentication without permitting login with
877 rlogin/rsh.
878 .Pp
879 .It Pa /etc/ssh/ssh_host_key
880 .It Pa /etc/ssh/ssh_host_dsa_key
881 .It Pa /etc/ssh/ssh_host_ecdsa_key
882 .It Pa /etc/ssh/ssh_host_rsa_key
883 These three files contain the private parts of the host keys.
884 These files should only be owned by root, readable only by root, and not
885 accessible to others.
886 Note that
887 .Nm
888 does not start if these files are group/world-accessible.
889 .Pp
890 .It Pa /etc/ssh/
891 .It Pa /etc/ssh/
892 .It Pa /etc/ssh/
893 .It Pa /etc/ssh/
894 These three files contain the public parts of the host keys.
895 These files should be world-readable but writable only by
896 root.
897 Their contents should match the respective private parts.
898 These files are not
899 really used for anything; they are provided for the convenience of
900 the user so their contents can be copied to known hosts files.
901 These files are created using
902 .Xr ssh-keygen 1 .
903 .Pp
904 .It Pa /etc/ssh/ssh_known_hosts
905 Systemwide list of known host keys.
906 This file should be prepared by the
907 system administrator to contain the public host keys of all machines in the
908 organization.
909 The format of this file is described above.
910 This file should be writable only by root/the owner and
911 should be world-readable.
912 .Pp
913 .It Pa /etc/ssh/sshd_config
914 Contains configuration data for
915 .Nm sshd .
916 The file format and configuration options are described in
917 .Xr sshd_config 5 .
918 .Pp
919 .It Pa /etc/ssh/sshrc
920 Similar to
921 .Pa ~/.ssh/rc ,
922 it can be used to specify
923 machine-specific login-time initializations globally.
924 This file should be writable only by root, and should be world-readable.
925 .Pp
926 .It Pa /var/empty
927 .Xr chroot 2
928 directory used by
929 .Nm
930 during privilege separation in the pre-authentication phase.
931 The directory should not contain any files and must be owned by root
932 and not group or world-writable.
933 .Pp
934 .It Pa /var/run/
935 Contains the process ID of the
936 .Nm
937 listening for connections (if there are several daemons running
938 concurrently for different ports, this contains the process ID of the one
939 started last).
940 The content of this file is not sensitive; it can be world-readable.
941 .El
942 .Sh SEE ALSO
943 .Xr scp 1 ,
944 .Xr sftp 1 ,
945 .Xr ssh 1 ,
946 .Xr ssh-add 1 ,
947 .Xr ssh-agent 1 ,
948 .Xr ssh-keygen 1 ,
949 .Xr ssh-keyscan 1 ,
950 .Xr chroot 2 ,
951 .Xr hosts_access 5 ,
952 .Xr login.conf 5 ,
953 .Xr moduli 5 ,
954 .Xr sshd_config 5 ,
955 .Xr inetd 8 ,
956 .Xr sftp-server 8
958 OpenSSH is a derivative of the original and free
959 ssh 1.2.12 release by Tatu Ylonen.
960 Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
961 Theo de Raadt and Dug Song
962 removed many bugs, re-added newer features and
963 created OpenSSH.
964 Markus Friedl contributed the support for SSH
965 protocol versions 1.5 and 2.0.
966 Niels Provos and Markus Friedl contributed support
967 for privilege separation.
969 System security is not improved unless
970 .Nm rshd ,
971 .Nm rlogind ,
972 and
973 .Nm rexecd
974 are disabled (thus completely disabling
975 .Xr rlogin
976 and
977 .Xr rsh
978 into the machine).