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