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