Debian Codegraph @

upstream/fedora-44/man8/sshd.8

raw
1 .\"
2 .\" Author: Tatu Ylonen <[email protected]>
3 .\" Copyright (c) 1995 Tatu Ylonen <[email protected]>, 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.328 2025/10/04 21:41:35 naddy Exp $
37 .Dd $Mdocdate: October 4 2025 $
38 .Dt SSHD 8
39 .Os
40 .Sh NAME
41 .Nm sshd
42 .Nd OpenSSH daemon
43 .Sh SYNOPSIS
44 .Nm sshd
45 .Bk -words
46 .Op Fl 46DdeGiqTtV
47 .Op Fl C Ar connection_spec
48 .Op Fl c Ar host_certificate_file
49 .Op Fl E Ar log_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 o Ar option
54 .Op Fl p Ar port
55 .Op Fl u Ar len
56 .Ek
57 .Sh DESCRIPTION
58 .Nm
59 (OpenSSH Daemon) is the daemon program for
60 .Xr ssh 1 .
61 It provides secure encrypted communications between two untrusted hosts
62 over an insecure network.
63 .Pp
64 .Nm
65 listens for connections from clients.
66 It is normally started at boot from
67 .Pa /etc/rc .
68 It forks a new
69 daemon for each incoming connection.
70 The forked daemons handle
71 key exchange, encryption, authentication, command execution,
72 and data exchange.
73 .Pp
74 .Nm
75 can be configured using command-line options or a configuration file
76 (by default
77 .Xr sshd_config 5 ) ;
78 command-line options override values specified in the
79 configuration file.
80 .Nm
81 rereads its configuration file when it receives a hangup signal,
82 .Dv SIGHUP ,
83 by executing itself with the name and options it was started with, e.g.\&
84 .Pa /usr/sbin/sshd .
85 .Pp
86 The options are as follows:
87 .Bl -tag -width Ds
88 .It Fl 4
89 Forces
90 .Nm
91 to use IPv4 addresses only.
92 .It Fl 6
93 Forces
94 .Nm
95 to use IPv6 addresses only.
96 .It Fl C Ar connection_spec
97 Specify the connection parameters to use for the
98 .Fl T
99 extended test mode.
100 If provided, any
101 .Cm Match
102 directives in the configuration file that would apply are applied before the
103 configuration is written to standard output.
104 The connection parameters are supplied as keyword=value pairs and may be
105 supplied in any order, either with multiple
106 .Fl C
107 options or as a comma-separated list.
108 The keywords are
109 .Dq addr ,
110 .Dq user ,
111 .Dq host ,
112 .Dq laddr ,
113 .Dq lport ,
114 and
115 .Dq rdomain
116 and correspond to source address, user, resolved source host name,
117 local address, local port number and routing domain respectively.
118 Additionally the
119 .Dq invalid-user
120 flag (which does not take a value argument) may be specified to simulate
121 a connection from an unrecognised username.
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
142 .Xr fork 2
143 and will only process one connection.
144 This option is only intended for debugging for the server.
145 Multiple
146 .Fl d
147 options increase the debugging level.
148 Maximum is 3.
149 .It Fl E Ar log_file
150 Append debug logs to
151 .Ar log_file
152 instead of the system log.
153 .It Fl e
154 Write debug logs to standard error instead of the system log.
155 .It Fl f Ar config_file
156 Specifies the name of the configuration file.
157 The default is
158 .Pa /etc/ssh/sshd_config .
159 .Nm
160 refuses to start if there is no configuration file.
161 .It Fl G
162 Parse and print configuration file.
163 Check the validity of the configuration file, output the effective configuration
164 to stdout and then exit.
165 Optionally,
166 .Cm Match
167 rules may be applied by specifying the connection parameters using one or more
168 .Fl C
169 options.
170 .It Fl g Ar login_grace_time
171 Gives the grace time for clients to authenticate themselves (default
172 120 seconds).
173 If the client fails to authenticate the user within
174 this many seconds, the server disconnects and exits.
175 A value of zero indicates no limit.
176 .It Fl h Ar host_key_file
177 Specifies a file from which a host key is read.
178 This option must be given if
179 .Nm
180 is not run as root (as the normal
181 host key files are normally not readable by anyone but root).
182 The default is
183 .Pa /etc/ssh/ssh_host_ecdsa_key ,
184 .Pa /etc/ssh/ssh_host_ed25519_key
185 and
186 .Pa /etc/ssh/ssh_host_rsa_key .
187 It is possible to have multiple host key files for
188 the different host key algorithms.
189 .It Fl i
190 Specifies that
191 .Nm
192 is being run from
193 .Xr inetd 8 .
194 .It Fl o Ar option
195 Can be used to give options in the format used in the configuration file.
196 This is useful for specifying options for which there is no separate
197 command-line flag.
198 For full details of the options, and their values, see
199 .Xr sshd_config 5 .
200 .It Fl p Ar port
201 Specifies the port on which the server listens for connections
202 (default 22).
203 Multiple port options are permitted.
204 Ports specified in the configuration file with the
205 .Cm Port
206 option are ignored when a command-line port is specified.
207 Ports specified using the
208 .Cm ListenAddress
209 option override command-line ports.
210 .It Fl q
211 Quiet mode.
212 Nothing is sent to the system log.
213 Normally the beginning,
214 authentication, and termination of each connection is logged.
215 .It Fl T
216 Extended test mode.
217 Check the validity of the configuration file, output the effective configuration
218 to stdout and then exit.
219 Optionally,
220 .Cm Match
221 rules may be applied by specifying the connection parameters using one or more
222 .Fl C
223 options.
224 This is similar to the
225 .Fl G
226 flag, but it includes the additional testing performed by the
227 .Fl t
228 flag.
229 .It Fl t
230 Test mode.
231 Only check the validity of the configuration file and sanity of the keys.
232 This is useful for updating
233 .Nm
234 reliably as configuration options may change.
235 .It Fl u Ar len
236 This option is used to specify the size of the field
237 in the
238 .Vt utmp
239 structure that holds the remote host name.
240 If the resolved host name is longer than
241 .Ar len ,
242 the dotted decimal value will be used instead.
243 This allows hosts with very long host names that
244 overflow this field to still be uniquely identified.
245 Specifying
246 .Fl u0
247 indicates that only dotted decimal addresses
248 should be put into the
249 .Pa utmp
250 file.
251 .Fl u0
252 may also be used to prevent
253 .Nm
254 from making DNS requests unless the authentication
255 mechanism or configuration requires it.
256 Authentication mechanisms that may require DNS include
257 .Cm HostbasedAuthentication
258 and using a
259 .Cm from="pattern-list"
260 option in a key file.
261 Configuration options that require DNS include using a
262 USER@HOST pattern in
263 .Cm AllowUsers
264 or
265 .Cm DenyUsers .
266 .It Fl V
267 Display the version number and exit.
268 .El
269 .Sh AUTHENTICATION
270 The OpenSSH SSH daemon supports SSH protocol 2 only.
271 Each host has a host-specific key,
272 used to identify the host.
273 Whenever a client connects, the daemon responds with its public
274 host key.
275 The client compares the
276 host key against its own database to verify that it has not changed.
277 Forward secrecy is provided through a Diffie-Hellman key agreement.
278 This key agreement results in a shared session key.
279 The rest of the session is encrypted using a symmetric cipher.
280 The client selects the encryption algorithm
281 to use from those offered by the server.
282 Additionally, session integrity is provided
283 through a cryptographic message authentication code (MAC).
284 .Pp
285 Finally, the server and the client enter an authentication dialog.
286 The client tries to authenticate itself using
287 host-based authentication,
288 public key authentication,
289 GSSAPI authentication,
290 challenge-response authentication,
291 or password authentication.
292 .Pp
293 Regardless of the authentication type, the account is checked to
294 ensure that it is accessible. An account is not accessible if it is
295 locked, listed in
296 .Cm DenyUsers
297 or its group is listed in
298 .Cm DenyGroups
299 \&. The definition of a locked account is system dependent. Some platforms
300 have their own account database (eg AIX) and some modify the passwd field (
301 .Ql \&*LK\&*
302 on Solaris and UnixWare,
303 .Ql \&*
304 on HP-UX, containing
305 .Ql Nologin
306 on Tru64,
307 a leading
308 .Ql \&*LOCKED\&*
309 on FreeBSD and a leading
310 .Ql \&!
311 on most Linuxes).
312 If there is a requirement to disable password authentication
313 for the account while allowing still public-key, then the passwd field
314 should be set to something other than these values (eg
315 .Ql NP
316 or
317 .Ql \&*NP\&*
318 ).
319 .Pp
320 If the client successfully authenticates itself, a dialog for
321 preparing the session is entered.
322 At this time the client may request
323 things like allocating a pseudo-tty, forwarding X11 connections,
324 forwarding TCP connections, or forwarding the authentication agent
325 connection over the secure channel.
326 .Pp
327 After this, the client either requests an interactive shell or execution
328 of a non-interactive command, which
329 .Nm
330 will execute via the user's shell using its
331 .Fl c
332 option.
333 The sides then enter session mode.
334 In this mode, either side may send
335 data at any time, and such data is forwarded to/from the shell or
336 command on the server side, and the user terminal in the client side.
337 .Pp
338 When the user program terminates and all forwarded X11 and other
339 connections have been closed, the server sends command exit status to
340 the client, and both sides exit.
341 .Sh LOGIN PROCESS
342 When a user successfully logs in,
343 .Nm
344 does the following:
345 .Bl -enum -offset indent
346 .It
347 If the login is on a tty, and no command has been specified,
348 prints last login time and
349 .Pa /etc/motd
350 (unless prevented in the configuration file or by
351 .Pa ~/.hushlogin ;
352 see the
353 .Sx FILES
354 section).
355 .It
356 If the login is on a tty, records login time.
357 .It
358 Checks
359 .Pa /etc/nologin ;
360 if it exists, prints contents and quits
361 (unless root).
362 .It
363 Changes to run with normal user privileges.
364 .It
365 Sets up basic environment.
366 .It
367 Reads the file
368 .Pa ~/.ssh/environment ,
369 if it exists, and users are allowed to change their environment.
370 See the
371 .Cm PermitUserEnvironment
372 option in
373 .Xr sshd_config 5 .
374 .It
375 Changes to user's home directory.
376 .It
377 If
378 .Pa ~/.ssh/rc
379 exists and the
380 .Xr sshd_config 5
381 .Cm PermitUserRC
382 option is set, runs it; else if
383 .Pa /etc/ssh/sshrc
384 exists, runs
385 it; otherwise runs
386 .Xr xauth 1 .
387 The
388 .Dq rc
389 files are given the X11
390 authentication protocol and cookie in standard input.
391 See
392 .Sx SSHRC ,
393 below.
394 .It
395 Runs user's shell or command.
396 All commands are run under the user's login shell as specified in the
397 system password database.
398 .El
399 .Sh SSHRC
400 If the file
401 .Pa ~/.ssh/rc
402 exists,
403 .Xr sh 1
404 runs it after reading the
405 environment files but before starting the user's shell or command.
406 It must not produce any output on stdout; stderr must be used
407 instead.
408 If X11 forwarding is in use, it will receive the "proto cookie" pair in
409 its standard input (and
410 .Ev DISPLAY
411 in its environment).
412 The script must call
413 .Xr xauth 1
414 because
415 .Nm
416 will not run xauth automatically to add X11 cookies.
417 .Pp
418 The primary purpose of this file is to run any initialization routines
419 which may be needed before the user's home directory becomes
420 accessible; AFS is a particular example of such an environment.
421 .Pp
422 This file will probably contain some initialization code followed by
423 something similar to:
424 .Bd -literal -offset 3n
425 if read proto cookie && [ -n "$DISPLAY" ]; then
426 if [ `echo $DISPLAY | cut -c1-10` = 'localhost:' ]; then
427 # X11UseLocalhost=yes
428 echo add unix:`echo $DISPLAY |
429 cut -c11-` $proto $cookie
430 else
431 # X11UseLocalhost=no
432 echo add $DISPLAY $proto $cookie
433 fi | xauth -q -
434 fi
435 .Ed
436 .Pp
437 If this file does not exist,
438 .Pa /etc/ssh/sshrc
439 is run, and if that
440 does not exist either, xauth is used to add the cookie.
441 .Sh AUTHORIZED_KEYS FILE FORMAT
442 .Cm AuthorizedKeysFile
443 specifies the files containing public keys for
444 public key authentication;
445 if this option is not specified, the default is
446 .Pa ~/.ssh/authorized_keys
447 and
448 .Pa ~/.ssh/authorized_keys2 .
449 Each line of the file contains one
450 key (empty lines and lines starting with a
451 .Ql #
452 are ignored as
453 comments).
454 Public keys consist of the following space-separated fields:
455 options, keytype, base64-encoded key, comment.
456 The options field is optional.
457 The supported key types are:
458 .Pp
459 .Bl -item -compact -offset indent
460 .It
461 [email protected]
462 .It
463 ecdsa-sha2-nistp256
464 .It
465 ecdsa-sha2-nistp384
466 .It
467 ecdsa-sha2-nistp521
468 .It
469 [email protected]
470 .It
471 ssh-ed25519
472 .It
473 ssh-rsa
474 .El
475 .Pp
476 The comment field is not used for anything (but may be convenient for the
477 user to identify the key).
478 .Pp
479 Note that lines in this file can be several hundred bytes long
480 (because of the size of the public key encoding) up to a limit of
481 8 kilobytes, which permits RSA keys up to 16 kilobits.
482 You don't want to type them in; instead, copy the
483 .Pa id_ecdsa.pub ,
484 .Pa id_ecdsa_sk.pub ,
485 .Pa id_ed25519.pub ,
486 .Pa id_ed25519_sk.pub ,
487 or the
488 .Pa id_rsa.pub
489 file and edit it.
490 .Pp
491 .Nm
492 enforces a minimum RSA key modulus size of 1024 bits.
493 .Pp
494 The options (if present) consist of comma-separated option
495 specifications.
496 No spaces are permitted, except within double quotes.
497 The following option specifications are supported (note
498 that option keywords are case-insensitive):
499 .Bl -tag -width Ds
500 .It Cm agent-forwarding
501 Enable authentication agent forwarding previously disabled by the
502 .Cm restrict
503 option.
504 .It Cm cert-authority
505 Specifies that the listed key is a certification authority (CA) that is
506 trusted to validate signed certificates for user authentication.
507 .Pp
508 Certificates may encode access restrictions similar to these key options.
509 If both certificate restrictions and key options are present, the most
510 restrictive union of the two is applied.
511 .It Cm command="command"
512 Specifies that the command is executed whenever this key is used for
513 authentication.
514 The command supplied by the user (if any) is ignored.
515 The command is run on a pty if the client requests a pty;
516 otherwise it is run without a tty.
517 If an 8-bit clean channel is required,
518 one must not request a pty or should specify
519 .Cm no-pty .
520 A quote may be included in the command by quoting it with a backslash.
521 .Pp
522 This option might be useful
523 to restrict certain public keys to perform just a specific operation.
524 An example might be a key that permits remote backups but nothing else.
525 Note that the client may specify TCP and/or X11
526 forwarding unless they are explicitly prohibited, e.g. using the
527 .Cm restrict
528 key option.
529 .Pp
530 The command originally supplied by the client is available in the
531 .Ev SSH_ORIGINAL_COMMAND
532 environment variable.
533 Note that this option applies to shell, command or subsystem execution.
534 Also note that this command may be superseded by an
535 .Xr sshd_config 5
536 .Cm ForceCommand
537 directive.
538 .Pp
539 If a command is specified and a forced-command is embedded in a certificate
540 used for authentication, then the certificate will be accepted only if the
541 two commands are identical.
542 .It Cm environment="NAME=value"
543 Specifies that the string is to be added to the environment when
544 logging in using this key.
545 Environment variables set this way
546 override other default environment values.
547 Multiple options of this type are permitted.
548 Environment processing is disabled by default and is
549 controlled via the
550 .Cm PermitUserEnvironment
551 option.
552 .It Cm expiry-time="timespec"
553 Specifies a time after which the key will not be accepted.
554 The time may be specified as a YYYYMMDD[Z] date or a YYYYMMDDHHMM[SS][Z] time.
555 Dates and times will be interpreted in the system time zone unless suffixed
556 by a Z character, in which case they will be interpreted in the UTC time zone.
557 .It Cm from="pattern-list"
558 Specifies that in addition to public key authentication, either the canonical
559 name of the remote host or its IP address must be present in the
560 comma-separated list of patterns.
561 See PATTERNS in
562 .Xr ssh_config 5
563 for more information on patterns.
564 .Pp
565 In addition to the wildcard matching that may be applied to hostnames or
566 addresses, a
567 .Cm from
568 stanza may match IP addresses using CIDR address/masklen notation.
569 .Pp
570 The purpose of this option is to optionally increase security: public key
571 authentication by itself does not trust the network or name servers or
572 anything (but the key); however, if somebody somehow steals the key, the key
573 permits an intruder to log in from anywhere in the world.
574 This additional option makes using a stolen key more difficult (name
575 servers and/or routers would have to be compromised in addition to
576 just the key).
577 .It Cm no-agent-forwarding
578 Forbids authentication agent forwarding when this key is used for
579 authentication.
580 .It Cm no-port-forwarding
581 Forbids TCP forwarding when this key is used for authentication.
582 Any port forward requests by the client will return an error.
583 This might be used, e.g. in connection with the
584 .Cm command
585 option.
586 .It Cm no-pty
587 Prevents tty allocation (a request to allocate a pty will fail).
588 .It Cm no-user-rc
589 Disables execution of
590 .Pa ~/.ssh/rc .
591 .It Cm no-X11-forwarding
592 Forbids X11 forwarding when this key is used for authentication.
593 Any X11 forward requests by the client will return an error.
594 .It Cm permitlisten="[host:]port"
595 Limit remote port forwarding with the
596 .Xr ssh 1
597 .Fl R
598 option such that it may only listen on the specified host (optional) and port.
599 IPv6 addresses can be specified by enclosing the address in square brackets.
600 Multiple
601 .Cm permitlisten
602 options may be applied separated by commas.
603 Hostnames may include wildcards as described in the PATTERNS section in
604 .Xr ssh_config 5 .
605 A port specification of
606 .Cm *
607 matches any port.
608 Note that the setting of
609 .Cm GatewayPorts
610 may further restrict listen addresses.
611 Note that
612 .Xr ssh 1
613 will send a hostname of
614 .Dq localhost
615 if a listen host was not specified when the forwarding was requested, and
616 that this name is treated differently to the explicit localhost addresses
617 .Dq 127.0.0.1
618 and
619 .Dq ::1 .
620 .It Cm permitopen="host:port"
621 Limit local port forwarding with the
622 .Xr ssh 1
623 .Fl L
624 option such that it may only connect to the specified host and port.
625 IPv6 addresses can be specified by enclosing the address in square brackets.
626 Multiple
627 .Cm permitopen
628 options may be applied separated by commas.
629 No pattern matching or name lookup is performed on the
630 specified hostnames, they must be literal host names and/or addresses.
631 A port specification of
632 .Cm *
633 matches any port.
634 .It Cm port-forwarding
635 Enable port forwarding previously disabled by the
636 .Cm restrict
637 option.
638 .It Cm principals="principals"
639 On a
640 .Cm cert-authority
641 line, specifies allowed principals for certificate authentication as a
642 comma-separated list.
643 At least one name from the list must appear in the certificate's
644 list of principals for the certificate to be accepted.
645 This option is ignored for keys that are not marked as trusted certificate
646 signers using the
647 .Cm cert-authority
648 option.
649 .It Cm pty
650 Permits tty allocation previously disabled by the
651 .Cm restrict
652 option.
653 .It Cm no-touch-required
654 Do not require demonstration of user presence
655 for signatures made using this key.
656 This option only makes sense for the FIDO authenticator algorithms
657 .Cm ecdsa-sk
658 and
659 .Cm ed25519-sk .
660 .It Cm verify-required
661 Require that signatures made using this key attest that they verified
662 the user, e.g. via a PIN.
663 This option only makes sense for the FIDO authenticator algorithms
664 .Cm ecdsa-sk
665 and
666 .Cm ed25519-sk .
667 .It Cm restrict
668 Enable all restrictions, i.e. disable port, agent and X11 forwarding,
669 as well as disabling PTY allocation
670 and execution of
671 .Pa ~/.ssh/rc .
672 If any future restriction capabilities are added to authorized_keys files,
673 they will be included in this set.
674 .It Cm tunnel="n"
675 Force a
676 .Xr tun 4
677 device on the server.
678 Without this option, the next available device will be used if
679 the client requests a tunnel.
680 .It Cm user-rc
681 Enables execution of
682 .Pa ~/.ssh/rc
683 previously disabled by the
684 .Cm restrict
685 option.
686 .It Cm X11-forwarding
687 Permits X11 forwarding previously disabled by the
688 .Cm restrict
689 option.
690 .El
691 .Pp
692 An example authorized_keys file:
693 .Bd -literal -offset 3n
694 # Comments are allowed at start of line. Blank lines are allowed.
695 # Plain key, no restrictions
696 ssh-rsa ...
697 # Forced command, disable PTY and all forwarding
698 restrict,command="dump /home" ssh-rsa ...
699 # Restriction of ssh -L forwarding destinations
700 permitopen="192.0.2.1:80",permitopen="192.0.2.2:25" ssh-rsa ...
701 # Restriction of ssh -R forwarding listeners
702 permitlisten="localhost:8080",permitlisten="[::1]:22000" ssh-rsa ...
703 # Configuration for tunnel forwarding
704 tunnel="0",command="sh /etc/netstart tun0" ssh-rsa ...
705 # Override of restriction to allow PTY allocation
706 restrict,pty,command="nethack" ssh-rsa ...
707 # Allow FIDO key without requiring touch
708 no-touch-required [email protected] ...
709 # Require user-verification (e.g. PIN or biometric) for FIDO key
710 verify-required [email protected] ...
711 # Trust CA key, allow touch-less FIDO if requested in certificate
712 cert-authority,no-touch-required,principals="user_a" ssh-rsa ...
713 .Ed
714 .Sh SSH_KNOWN_HOSTS FILE FORMAT
715 The
716 .Pa /etc/ssh/ssh_known_hosts
717 and
718 .Pa ~/.ssh/known_hosts
719 files contain host public keys for all known hosts.
720 The global file should
721 be prepared by the administrator (optional), and the per-user file is
722 maintained automatically: whenever the user connects to an unknown host,
723 its key is added to the per-user file.
724 .Pp
725 Each line in these files contains the following fields: marker (optional),
726 hostnames, keytype, base64-encoded key, comment.
727 The fields are separated by spaces.
728 .Pp
729 The marker is optional, but if it is present then it must be one of
730 .Dq @cert-authority ,
731 to indicate that the line contains a certification authority (CA) key,
732 or
733 .Dq @revoked ,
734 to indicate that the key contained on the line is revoked and must not ever
735 be accepted.
736 Only one marker should be used on a key line.
737 .Pp
738 Hostnames is a comma-separated list of patterns
739 .Pf ( Ql *
740 and
741 .Ql \&?
742 act as
743 wildcards); each pattern in turn is matched against the host name.
744 When
745 .Nm sshd
746 is authenticating a client, such as when using
747 .Cm HostbasedAuthentication ,
748 this will be the canonical client host name.
749 When
750 .Xr ssh 1
751 is authenticating a server, this will be the host name
752 given by the user, the value of the
753 .Xr ssh 1
754 .Cm HostkeyAlias
755 if it was specified, or the canonical server hostname if the
756 .Xr ssh 1
757 .Cm CanonicalizeHostname
758 option was used.
759 .Pp
760 A pattern may also be preceded by
761 .Ql \&!
762 to indicate negation: if the host name matches a negated
763 pattern, it is not accepted (by that line) even if it matched another
764 pattern on the line.
765 A hostname or address may optionally be enclosed within
766 .Ql \&[
767 and
768 .Ql \&]
769 brackets then followed by
770 .Ql \&:
771 and a non-standard port number.
772 .Pp
773 Alternately, hostnames may be stored in a hashed form which hides host names
774 and addresses should the file's contents be disclosed.
775 Hashed hostnames start with a
776 .Ql |
777 character.
778 Only one hashed hostname may appear on a single line and none of the above
779 negation or wildcard operators may be applied.
780 .Pp
781 The keytype and base64-encoded key are taken directly from the host key; they
782 can be obtained, for example, from
783 .Pa /etc/ssh/ssh_host_rsa_key.pub .
784 The optional comment field continues to the end of the line, and is not used.
785 .Pp
786 Lines starting with
787 .Ql #
788 and empty lines are ignored as comments.
789 .Pp
790 When performing host authentication, authentication is accepted if any
791 matching line has the proper key; either one that matches exactly or,
792 if the server has presented a certificate for authentication, the key
793 of the certification authority that signed the certificate.
794 For a key to be trusted as a certification authority, it must use the
795 .Dq @cert-authority
796 marker described above.
797 .Pp
798 The known hosts file also provides a facility to mark keys as revoked,
799 for example when it is known that the associated private key has been
800 stolen.
801 Revoked keys are specified by including the
802 .Dq @revoked
803 marker at the beginning of the key line, and are never accepted for
804 authentication or as certification authorities, but instead will
805 produce a warning from
806 .Xr ssh 1
807 when they are encountered.
808 .Pp
809 It is permissible (but not
810 recommended) to have several lines or different host keys for the same
811 names.
812 This will inevitably happen when short forms of host names
813 from different domains are put in the file.
814 It is possible
815 that the files contain conflicting information; authentication is
816 accepted if valid information can be found from either file.
817 .Pp
818 Note that the lines in these files are typically hundreds of characters
819 long, and you definitely don't want to type in the host keys by hand.
820 Rather, generate them by a script,
821 .Xr ssh-keyscan 1
822 or by taking, for example,
823 .Pa /etc/ssh/ssh_host_rsa_key.pub
824 and adding the host names at the front.
825 .Xr ssh-keygen 1
826 also offers some basic automated editing for
827 .Pa ~/.ssh/known_hosts
828 including removing hosts matching a host name and converting all host
829 names to their hashed representations.
830 .Pp
831 An example ssh_known_hosts file:
832 .Bd -literal -offset 3n
833 # Comments allowed at start of line
834 cvs.example.net,192.0.2.10 ssh-rsa AAAA1234.....=
835 # A hashed hostname
836 |1|JfKTdBh7rNbXkVAQCRp4OQoPfmI=|USECr3SWf1JUPsms5AqfD5QfxkM= ssh-rsa
837 AAAA1234.....=
838 # A revoked key
839 @revoked * ssh-rsa AAAAB5W...
840 # A CA key, accepted for any host in *.mydomain.com or *.mydomain.org
841 @cert-authority *.mydomain.org,*.mydomain.com ssh-rsa AAAAB5W...
842 .Ed
843 .Sh FILES
844 .Bl -tag -width Ds -compact
845 .It Pa ~/.hushlogin
846 This file is used to suppress printing the last login time and
847 .Pa /etc/motd ,
848 if
849 .Cm PrintLastLog
850 and
851 .Cm PrintMotd ,
852 respectively,
853 are enabled.
854 It does not suppress printing of the banner specified by
855 .Cm Banner .
856 .Pp
857 .It Pa ~/.rhosts
858 This file is used for host-based authentication (see
859 .Xr ssh 1
860 for more information).
861 On some machines this file may need to be
862 world-readable if the user's home directory is on an NFS partition,
863 because
864 .Nm
865 reads it as root.
866 Additionally, this file must be owned by the user,
867 and must not have write permissions for anyone else.
868 The recommended
869 permission for most machines is read/write for the user, and not
870 accessible by others.
871 .Pp
872 .It Pa ~/.shosts
873 This file is used in exactly the same way as
874 .Pa .rhosts ,
875 but allows host-based authentication without permitting login with
876 rlogin/rsh.
877 .Pp
878 .It Pa ~/.k5login
879 .It Pa ~/.k5users
880 These files enforce GSSAPI/Kerberos authentication access control.
881 Further details are described in
882 .Xr ksu 1 .
883 The location of the k5login file depends on the configuration option
884 .Cm k5login_directory
885 in the
886 .Xr krb5.conf 5 .
887 .Pp
888 .It Pa ~/.ssh/
889 This directory is the default location for all user-specific configuration
890 and authentication information.
891 There is no general requirement to keep the entire contents of this directory
892 secret, but the recommended permissions are read/write/execute for the user,
893 and not accessible by others.
894 .Pp
895 .It Pa ~/.ssh/authorized_keys
896 Lists the public keys (ECDSA, Ed25519, RSA)
897 that can be used for logging in as this user.
898 The format of this file is described above.
899 The content of the file is not highly sensitive, but the recommended
900 permissions are read/write for the user, and not accessible by others.
901 .Pp
902 If this file, the
903 .Pa ~/.ssh
904 directory, or the user's home directory are writable
905 by other users, then the file could be modified or replaced by unauthorized
906 users.
907 In this case,
908 .Nm
909 will not allow it to be used unless the
910 .Cm StrictModes
911 option has been set to
912 .Dq no .
913 .Pp
914 .It Pa ~/.ssh/environment
915 This file is read into the environment at login (if it exists).
916 It can only contain empty lines, comment lines (that start with
917 .Ql # ) ,
918 and assignment lines of the form name=value.
919 The file should be writable
920 only by the user; it need not be readable by anyone else.
921 Environment processing is disabled by default and is
922 controlled via the
923 .Cm PermitUserEnvironment
924 option.
925 .Pp
926 .It Pa ~/.ssh/known_hosts
927 Contains a list of host keys for all hosts the user has logged into
928 that are not already in the systemwide list of known host keys.
929 The format of this file is described above.
930 This file should be writable only by root/the owner and
931 can, but need not be, world-readable.
932 .Pp
933 .It Pa ~/.ssh/rc
934 Contains initialization routines to be run before
935 the user's home directory becomes accessible.
936 This file should be writable only by the user, and need not be
937 readable by anyone else.
938 .Pp
939 .It Pa /etc/hosts.equiv
940 This file is for host-based authentication (see
941 .Xr ssh 1 ) .
942 It should only be writable by root.
943 .Pp
944 .It Pa /etc/ssh/moduli
945 Contains Diffie-Hellman groups used for the "Diffie-Hellman Group Exchange"
946 key exchange method.
947 The file format is described in
948 .Xr moduli 5 .
949 If no usable groups are found in this file then fixed internal groups will
950 be used.
951 .Pp
952 .It Pa /etc/motd
953 See
954 .Xr motd 5 .
955 .Pp
956 .It Pa /etc/nologin
957 If this file exists,
958 .Nm
959 refuses to let anyone except root log in.
960 The contents of the file
961 are displayed to anyone trying to log in, and non-root connections are
962 refused.
963 The file should be world-readable.
964 .Pp
965 .It Pa /etc/ssh/shosts.equiv
966 This file is used in exactly the same way as
967 .Pa hosts.equiv ,
968 but allows host-based authentication without permitting login with
969 rlogin/rsh.
970 .Pp
971 .It Pa /etc/ssh/ssh_host_ecdsa_key
972 .It Pa /etc/ssh/ssh_host_ed25519_key
973 .It Pa /etc/ssh/ssh_host_rsa_key
974 These files contain the private parts of the host keys.
975 These files should only be owned by root, readable only by root, and not
976 accessible to others.
977 Note that
978 .Nm
979 does not start if these files are group/world-accessible.
980 .Pp
981 .It Pa /etc/ssh/ssh_host_ecdsa_key.pub
982 .It Pa /etc/ssh/ssh_host_ed25519_key.pub
983 .It Pa /etc/ssh/ssh_host_rsa_key.pub
984 These files contain the public parts of the host keys.
985 These files should be world-readable but writable only by
986 root.
987 Their contents should match the respective private parts.
988 These files are not
989 really used for anything; they are provided for the convenience of
990 the user so their contents can be copied to known hosts files.
991 These files are created using
992 .Xr ssh-keygen 1 .
993 .Pp
994 .It Pa /etc/ssh/ssh_known_hosts
995 Systemwide list of known host keys.
996 This file should be prepared by the
997 system administrator to contain the public host keys of all machines in the
998 organization.
999 The format of this file is described above.
1000 This file should be writable only by root/the owner and
1001 should be world-readable.
1002 .Pp
1003 .It Pa /etc/ssh/sshd_config
1004 Contains configuration data for
1005 .Nm sshd .
1006 The file format and configuration options are described in
1007 .Xr sshd_config 5 .
1008 .Pp
1009 .It Pa /etc/ssh/sshrc
1010 Similar to
1011 .Pa ~/.ssh/rc ,
1012 it can be used to specify
1013 machine-specific login-time initializations globally.
1014 This file should be writable only by root, and should be world-readable.
1015 .Pp
1016 .It Pa /usr/share/empty.sshd
1017 .Xr chroot 2
1018 directory used by
1019 .Nm
1020 during privilege separation in the pre-authentication phase.
1021 The directory should not contain any files and must be owned by root
1022 and not group or world-writable.
1023 .Pp
1024 .It Pa /var/run/sshd.pid
1025 Contains the process ID of the
1026 .Nm
1027 listening for connections (if there are several daemons running
1028 concurrently for different ports, this contains the process ID of the one
1029 started last).
1030 The content of this file is not sensitive; it can be world-readable.
1031 .El
1032 .Sh IPV6
1033 IPv6 address can be used everywhere where IPv4 address. In all entries must be the IPv6 address enclosed in square brackets. Note: The square brackets are metacharacters for the shell and must be escaped in shell.
1034 .Sh SEE ALSO
1035 .Xr scp 1 ,
1036 .Xr sftp 1 ,
1037 .Xr ssh 1 ,
1038 .Xr ssh-add 1 ,
1039 .Xr ssh-agent 1 ,
1040 .Xr ssh-keygen 1 ,
1041 .Xr ssh-keyscan 1 ,
1042 .Xr chroot 2 ,
1043 .Xr login.conf 5 ,
1044 .Xr moduli 5 ,
1045 .Xr sshd_config 5 ,
1046 .Xr inetd 8 ,
1047 .Xr sftp-server 8
1048 .Sh AUTHORS
1049 OpenSSH is a derivative of the original and free
1050 ssh 1.2.12 release by Tatu Ylonen.
1051 Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
1052 Theo de Raadt and Dug Song
1053 removed many bugs, re-added newer features and
1054 created OpenSSH.
1055 Markus Friedl contributed the support for SSH
1056 protocol versions 1.5 and 2.0.
1057 Niels Provos and Markus Friedl contributed support
1058 for privilege separation.