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