diff options
Diffstat (limited to 'sshd.8')
| -rw-r--r-- | sshd.8 | 1044 |
1 files changed, 1044 insertions, 0 deletions
@@ -0,0 +1,1044 @@ +.\" +.\" Author: Tatu Ylonen <ylo@cs.hut.fi> +.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland +.\" All rights reserved +.\" +.\" As far as I am concerned, the code I have written for this software +.\" can be used freely for any purpose. Any derived versions of this +.\" software must be clearly marked as such, and if the derived work is +.\" incompatible with the protocol description in the RFC file, it must be +.\" called by a name other than "ssh" or "Secure Shell". +.\" +.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. +.\" Copyright (c) 1999 Aaron Campbell. All rights reserved. +.\" Copyright (c) 1999 Theo de Raadt. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $OpenBSD: sshd.8,v 1.325 2023/09/19 20:37:07 deraadt Exp $ +.Dd $Mdocdate: September 19 2023 $ +.Dt SSHD 8 +.Os +.Sh NAME +.Nm sshd +.Nd OpenSSH daemon +.Sh SYNOPSIS +.Nm sshd +.Bk -words +.Op Fl 46DdeGiqTtV +.Op Fl C Ar connection_spec +.Op Fl c Ar host_certificate_file +.Op Fl E Ar log_file +.Op Fl f Ar config_file +.Op Fl g Ar login_grace_time +.Op Fl h Ar host_key_file +.Op Fl o Ar option +.Op Fl p Ar port +.Op Fl u Ar len +.Ek +.Sh DESCRIPTION +.Nm +(OpenSSH Daemon) is the daemon program for +.Xr ssh 1 . +It provides secure encrypted communications between two untrusted hosts +over an insecure network. +.Pp +.Nm +listens for connections from clients. +It is normally started at boot from +.Pa /etc/rc . +It forks a new +daemon for each incoming connection. +The forked daemons handle +key exchange, encryption, authentication, command execution, +and data exchange. +.Pp +.Nm +can be configured using command-line options or a configuration file +(by default +.Xr sshd_config 5 ) ; +command-line options override values specified in the +configuration file. +.Nm +rereads its configuration file when it receives a hangup signal, +.Dv SIGHUP , +by executing itself with the name and options it was started with, e.g.\& +.Pa /usr/sbin/sshd . +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl 4 +Forces +.Nm +to use IPv4 addresses only. +.It Fl 6 +Forces +.Nm +to use IPv6 addresses only. +.It Fl C Ar connection_spec +Specify the connection parameters to use for the +.Fl T +extended test mode. +If provided, any +.Cm Match +directives in the configuration file that would apply are applied before the +configuration is written to standard output. +The connection parameters are supplied as keyword=value pairs and may be +supplied in any order, either with multiple +.Fl C +options or as a comma-separated list. +The keywords are +.Dq addr , +.Dq user , +.Dq host , +.Dq laddr , +.Dq lport , +and +.Dq rdomain +and correspond to source address, user, resolved source host name, +local address, local port number and routing domain respectively. +.It Fl c Ar host_certificate_file +Specifies a path to a certificate file to identify +.Nm +during key exchange. +The certificate file must match a host key file specified using the +.Fl h +option or the +.Cm HostKey +configuration directive. +.It Fl D +When this option is specified, +.Nm +will not detach and does not become a daemon. +This allows easy monitoring of +.Nm sshd . +.It Fl d +Debug mode. +The server sends verbose debug output to standard error, +and does not put itself in the background. +The server also will not +.Xr fork 2 +and will only process one connection. +This option is only intended for debugging for the server. +Multiple +.Fl d +options increase the debugging level. +Maximum is 3. +.It Fl E Ar log_file +Append debug logs to +.Ar log_file +instead of the system log. +.It Fl e +Write debug logs to standard error instead of the system log. +.It Fl f Ar config_file +Specifies the name of the configuration file. +The default is +.Pa /etc/ssh/sshd_config . +.Nm +refuses to start if there is no configuration file. +.It Fl G +Parse and print configuration file. +Check the validity of the configuration file, output the effective configuration +to stdout and then exit. +Optionally, +.Cm Match +rules may be applied by specifying the connection parameters using one or more +.Fl C +options. +.It Fl g Ar login_grace_time +Gives the grace time for clients to authenticate themselves (default +120 seconds). +If the client fails to authenticate the user within +this many seconds, the server disconnects and exits. +A value of zero indicates no limit. +.It Fl h Ar host_key_file +Specifies a file from which a host key is read. +This option must be given if +.Nm +is not run as root (as the normal +host key files are normally not readable by anyone but root). +The default is +.Pa /etc/ssh/ssh_host_ecdsa_key , +.Pa /etc/ssh/ssh_host_ed25519_key +and +.Pa /etc/ssh/ssh_host_rsa_key . +It is possible to have multiple host key files for +the different host key algorithms. +.It Fl i +Specifies that +.Nm +is being run from +.Xr inetd 8 . +.It Fl o Ar option +Can be used to give options in the format used in the configuration file. +This is useful for specifying options for which there is no separate +command-line flag. +For full details of the options, and their values, see +.Xr sshd_config 5 . +.It Fl p Ar port +Specifies the port on which the server listens for connections +(default 22). +Multiple port options are permitted. +Ports specified in the configuration file with the +.Cm Port +option are ignored when a command-line port is specified. +Ports specified using the +.Cm ListenAddress +option override command-line ports. +.It Fl q +Quiet mode. +Nothing is sent to the system log. +Normally the beginning, +authentication, and termination of each connection is logged. +.It Fl T +Extended test mode. +Check the validity of the configuration file, output the effective configuration +to stdout and then exit. +Optionally, +.Cm Match +rules may be applied by specifying the connection parameters using one or more +.Fl C +options. +This is similar to the +.Fl G +flag, but it includes the additional testing performed by the +.Fl t +flag. +.It Fl t +Test mode. +Only check the validity of the configuration file and sanity of the keys. +This is useful for updating +.Nm +reliably as configuration options may change. +.It Fl u Ar len +This option is used to specify the size of the field +in the +.Vt utmp +structure that holds the remote host name. +If the resolved host name is longer than +.Ar len , +the dotted decimal value will be used instead. +This allows hosts with very long host names that +overflow this field to still be uniquely identified. +Specifying +.Fl u0 +indicates that only dotted decimal addresses +should be put into the +.Pa utmp +file. +.Fl u0 +may also be used to prevent +.Nm +from making DNS requests unless the authentication +mechanism or configuration requires it. +Authentication mechanisms that may require DNS include +.Cm HostbasedAuthentication +and using a +.Cm from="pattern-list" +option in a key file. +Configuration options that require DNS include using a +USER@HOST pattern in +.Cm AllowUsers +or +.Cm DenyUsers . +.It Fl V +Display the version number and exit. +.El +.Sh AUTHENTICATION +The OpenSSH SSH daemon supports SSH protocol 2 only. +Each host has a host-specific key, +used to identify the host. +Whenever a client connects, the daemon responds with its public +host key. +The client compares the +host key against its own database to verify that it has not changed. +Forward secrecy is provided through a Diffie-Hellman key agreement. +This key agreement results in a shared session key. +The rest of the session is encrypted using a symmetric cipher. +The client selects the encryption algorithm +to use from those offered by the server. +Additionally, session integrity is provided +through a cryptographic message authentication code (MAC). +.Pp +Finally, the server and the client enter an authentication dialog. +The client tries to authenticate itself using +host-based authentication, +public key authentication, +challenge-response authentication, +or password authentication. +.Pp +Regardless of the authentication type, the account is checked to +ensure that it is accessible. An account is not accessible if it is +locked, listed in +.Cm DenyUsers +or its group is listed in +.Cm DenyGroups +\&. The definition of a locked account is system dependent. Some platforms +have their own account database (eg AIX) and some modify the passwd field ( +.Ql \&*LK\&* +on Solaris and UnixWare, +.Ql \&* +on HP-UX, containing +.Ql Nologin +on Tru64, +a leading +.Ql \&*LOCKED\&* +on FreeBSD and a leading +.Ql \&! +on most Linuxes). +If there is a requirement to disable password authentication +for the account while allowing still public-key, then the passwd field +should be set to something other than these values (eg +.Ql NP +or +.Ql \&*NP\&* +). +.Pp +If the client successfully authenticates itself, a dialog for +preparing the session is entered. +At this time the client may request +things like allocating a pseudo-tty, forwarding X11 connections, +forwarding TCP connections, or forwarding the authentication agent +connection over the secure channel. +.Pp +After this, the client either requests an interactive shell or execution +of a non-interactive command, which +.Nm +will execute via the user's shell using its +.Fl c +option. +The sides then enter session mode. +In this mode, either side may send +data at any time, and such data is forwarded to/from the shell or +command on the server side, and the user terminal in the client side. +.Pp +When the user program terminates and all forwarded X11 and other +connections have been closed, the server sends command exit status to +the client, and both sides exit. +.Sh LOGIN PROCESS +When a user successfully logs in, +.Nm +does the following: +.Bl -enum -offset indent +.It +If the login is on a tty, and no command has been specified, +prints last login time and +.Pa /etc/motd +(unless prevented in the configuration file or by +.Pa ~/.hushlogin ; +see the +.Sx FILES +section). +.It +If the login is on a tty, records login time. +.It +Checks +.Pa /etc/nologin ; +if it exists, prints contents and quits +(unless root). +.It +Changes to run with normal user privileges. +.It +Sets up basic environment. +.It +Reads the file +.Pa ~/.ssh/environment , +if it exists, and users are allowed to change their environment. +See the +.Cm PermitUserEnvironment +option in +.Xr sshd_config 5 . +.It +Changes to user's home directory. +.It +If +.Pa ~/.ssh/rc +exists and the +.Xr sshd_config 5 +.Cm PermitUserRC +option is set, runs it; else if +.Pa /etc/ssh/sshrc +exists, runs +it; otherwise runs +.Xr xauth 1 . +The +.Dq rc +files are given the X11 +authentication protocol and cookie in standard input. +See +.Sx SSHRC , +below. +.It +Runs user's shell or command. +All commands are run under the user's login shell as specified in the +system password database. +.El +.Sh SSHRC +If the file +.Pa ~/.ssh/rc +exists, +.Xr sh 1 +runs it after reading the +environment files but before starting the user's shell or command. +It must not produce any output on stdout; stderr must be used +instead. +If X11 forwarding is in use, it will receive the "proto cookie" pair in +its standard input (and +.Ev DISPLAY +in its environment). +The script must call +.Xr xauth 1 +because +.Nm +will not run xauth automatically to add X11 cookies. +.Pp +The primary purpose of this file is to run any initialization routines +which may be needed before the user's home directory becomes +accessible; AFS is a particular example of such an environment. +.Pp +This file will probably contain some initialization code followed by +something similar to: +.Bd -literal -offset 3n +if read proto cookie && [ -n "$DISPLAY" ]; then + if [ `echo $DISPLAY | cut -c1-10` = 'localhost:' ]; then + # X11UseLocalhost=yes + echo add unix:`echo $DISPLAY | + cut -c11-` $proto $cookie + else + # X11UseLocalhost=no + echo add $DISPLAY $proto $cookie + fi | xauth -q - +fi +.Ed +.Pp +If this file does not exist, +.Pa /etc/ssh/sshrc +is run, and if that +does not exist either, xauth is used to add the cookie. +.Sh AUTHORIZED_KEYS FILE FORMAT +.Cm AuthorizedKeysFile +specifies the files containing public keys for +public key authentication; +if this option is not specified, the default is +.Pa ~/.ssh/authorized_keys +and +.Pa ~/.ssh/authorized_keys2 . +Each line of the file contains one +key (empty lines and lines starting with a +.Ql # +are ignored as +comments). +Public keys consist of the following space-separated fields: +options, keytype, base64-encoded key, comment. +The options field is optional. +The supported key types are: +.Pp +.Bl -item -compact -offset indent +.It +sk-ecdsa-sha2-nistp256@openssh.com +.It +ecdsa-sha2-nistp256 +.It +ecdsa-sha2-nistp384 +.It +ecdsa-sha2-nistp521 +.It +sk-ssh-ed25519@openssh.com +.It +ssh-ed25519 +.It +ssh-dss +.It +ssh-rsa +.El +.Pp +The comment field is not used for anything (but may be convenient for the +user to identify the key). +.Pp +Note that lines in this file can be several hundred bytes long +(because of the size of the public key encoding) up to a limit of +8 kilobytes, which permits RSA keys up to 16 kilobits. +You don't want to type them in; instead, copy the +.Pa id_dsa.pub , +.Pa id_ecdsa.pub , +.Pa id_ecdsa_sk.pub , +.Pa id_ed25519.pub , +.Pa id_ed25519_sk.pub , +or the +.Pa id_rsa.pub +file and edit it. +.Pp +.Nm +enforces a minimum RSA key modulus size of 1024 bits. +.Pp +The options (if present) consist of comma-separated option +specifications. +No spaces are permitted, except within double quotes. +The following option specifications are supported (note +that option keywords are case-insensitive): +.Bl -tag -width Ds +.It Cm agent-forwarding +Enable authentication agent forwarding previously disabled by the +.Cm restrict +option. +.It Cm cert-authority +Specifies that the listed key is a certification authority (CA) that is +trusted to validate signed certificates for user authentication. +.Pp +Certificates may encode access restrictions similar to these key options. +If both certificate restrictions and key options are present, the most +restrictive union of the two is applied. +.It Cm command="command" +Specifies that the command is executed whenever this key is used for +authentication. +The command supplied by the user (if any) is ignored. +The command is run on a pty if the client requests a pty; +otherwise it is run without a tty. +If an 8-bit clean channel is required, +one must not request a pty or should specify +.Cm no-pty . +A quote may be included in the command by quoting it with a backslash. +.Pp +This option might be useful +to restrict certain public keys to perform just a specific operation. +An example might be a key that permits remote backups but nothing else. +Note that the client may specify TCP and/or X11 +forwarding unless they are explicitly prohibited, e.g. using the +.Cm restrict +key option. +.Pp +The command originally supplied by the client is available in the +.Ev SSH_ORIGINAL_COMMAND +environment variable. +Note that this option applies to shell, command or subsystem execution. +Also note that this command may be superseded by a +.Xr sshd_config 5 +.Cm ForceCommand +directive. +.Pp +If a command is specified and a forced-command is embedded in a certificate +used for authentication, then the certificate will be accepted only if the +two commands are identical. +.It Cm environment="NAME=value" +Specifies that the string is to be added to the environment when +logging in using this key. +Environment variables set this way +override other default environment values. +Multiple options of this type are permitted. +Environment processing is disabled by default and is +controlled via the +.Cm PermitUserEnvironment +option. +.It Cm expiry-time="timespec" +Specifies a time after which the key will not be accepted. +The time may be specified as a YYYYMMDD[Z] date or a YYYYMMDDHHMM[SS][Z] time. +Dates and times will be interpreted in the system time zone unless suffixed +by a Z character, in which case they will be interpreted in the UTC time zone. +.It Cm from="pattern-list" +Specifies that in addition to public key authentication, either the canonical +name of the remote host or its IP address must be present in the +comma-separated list of patterns. +See PATTERNS in +.Xr ssh_config 5 +for more information on patterns. +.Pp +In addition to the wildcard matching that may be applied to hostnames or +addresses, a +.Cm from +stanza may match IP addresses using CIDR address/masklen notation. +.Pp +The purpose of this option is to optionally increase security: public key +authentication by itself does not trust the network or name servers or +anything (but the key); however, if somebody somehow steals the key, the key +permits an intruder to log in from anywhere in the world. +This additional option makes using a stolen key more difficult (name +servers and/or routers would have to be compromised in addition to +just the key). +.It Cm no-agent-forwarding +Forbids authentication agent forwarding when this key is used for +authentication. +.It Cm no-port-forwarding +Forbids TCP forwarding when this key is used for authentication. +Any port forward requests by the client will return an error. +This might be used, e.g. in connection with the +.Cm command +option. +.It Cm no-pty +Prevents tty allocation (a request to allocate a pty will fail). +.It Cm no-user-rc +Disables execution of +.Pa ~/.ssh/rc . +.It Cm no-X11-forwarding +Forbids X11 forwarding when this key is used for authentication. +Any X11 forward requests by the client will return an error. +.It Cm permitlisten="[host:]port" +Limit remote port forwarding with the +.Xr ssh 1 +.Fl R +option such that it may only listen on the specified host (optional) and port. +IPv6 addresses can be specified by enclosing the address in square brackets. +Multiple +.Cm permitlisten +options may be applied separated by commas. +Hostnames may include wildcards as described in the PATTERNS section in +.Xr ssh_config 5 . +A port specification of +.Cm * +matches any port. +Note that the setting of +.Cm GatewayPorts +may further restrict listen addresses. +Note that +.Xr ssh 1 +will send a hostname of +.Dq localhost +if a listen host was not specified when the forwarding was requested, and +that this name is treated differently to the explicit localhost addresses +.Dq 127.0.0.1 +and +.Dq ::1 . +.It Cm permitopen="host:port" +Limit local port forwarding with the +.Xr ssh 1 +.Fl L +option such that it may only connect to the specified host and port. +IPv6 addresses can be specified by enclosing the address in square brackets. +Multiple +.Cm permitopen +options may be applied separated by commas. +No pattern matching or name lookup is performed on the +specified hostnames, they must be literal host names and/or addresses. +A port specification of +.Cm * +matches any port. +.It Cm port-forwarding +Enable port forwarding previously disabled by the +.Cm restrict +option. +.It Cm principals="principals" +On a +.Cm cert-authority +line, specifies allowed principals for certificate authentication as a +comma-separated list. +At least one name from the list must appear in the certificate's +list of principals for the certificate to be accepted. +This option is ignored for keys that are not marked as trusted certificate +signers using the +.Cm cert-authority +option. +.It Cm pty +Permits tty allocation previously disabled by the +.Cm restrict +option. +.It Cm no-touch-required +Do not require demonstration of user presence +for signatures made using this key. +This option only makes sense for the FIDO authenticator algorithms +.Cm ecdsa-sk +and +.Cm ed25519-sk . +.It Cm verify-required +Require that signatures made using this key attest that they verified +the user, e.g. via a PIN. +This option only makes sense for the FIDO authenticator algorithms +.Cm ecdsa-sk +and +.Cm ed25519-sk . +.It Cm restrict +Enable all restrictions, i.e. disable port, agent and X11 forwarding, +as well as disabling PTY allocation +and execution of +.Pa ~/.ssh/rc . +If any future restriction capabilities are added to authorized_keys files, +they will be included in this set. +.It Cm tunnel="n" +Force a +.Xr tun 4 +device on the server. +Without this option, the next available device will be used if +the client requests a tunnel. +.It Cm user-rc +Enables execution of +.Pa ~/.ssh/rc +previously disabled by the +.Cm restrict +option. +.It Cm X11-forwarding +Permits X11 forwarding previously disabled by the +.Cm restrict +option. +.El +.Pp +An example authorized_keys file: +.Bd -literal -offset 3n +# Comments are allowed at start of line. Blank lines are allowed. +# Plain key, no restrictions +ssh-rsa ... +# Forced command, disable PTY and all forwarding +restrict,command="dump /home" ssh-rsa ... +# Restriction of ssh -L forwarding destinations +permitopen="192.0.2.1:80",permitopen="192.0.2.2:25" ssh-rsa ... +# Restriction of ssh -R forwarding listeners +permitlisten="localhost:8080",permitlisten="[::1]:22000" ssh-rsa ... +# Configuration for tunnel forwarding +tunnel="0",command="sh /etc/netstart tun0" ssh-rsa ... +# Override of restriction to allow PTY allocation +restrict,pty,command="nethack" ssh-rsa ... +# Allow FIDO key without requiring touch +no-touch-required sk-ecdsa-sha2-nistp256@openssh.com ... +# Require user-verification (e.g. PIN or biometric) for FIDO key +verify-required sk-ecdsa-sha2-nistp256@openssh.com ... +# Trust CA key, allow touch-less FIDO if requested in certificate +cert-authority,no-touch-required,principals="user_a" ssh-rsa ... +.Ed +.Sh SSH_KNOWN_HOSTS FILE FORMAT +The +.Pa /etc/ssh/ssh_known_hosts +and +.Pa ~/.ssh/known_hosts +files contain host public keys for all known hosts. +The global file should +be prepared by the administrator (optional), and the per-user file is +maintained automatically: whenever the user connects to an unknown host, +its key is added to the per-user file. +.Pp +Each line in these files contains the following fields: marker (optional), +hostnames, keytype, base64-encoded key, comment. +The fields are separated by spaces. +.Pp +The marker is optional, but if it is present then it must be one of +.Dq @cert-authority , +to indicate that the line contains a certification authority (CA) key, +or +.Dq @revoked , +to indicate that the key contained on the line is revoked and must not ever +be accepted. +Only one marker should be used on a key line. +.Pp +Hostnames is a comma-separated list of patterns +.Pf ( Ql * +and +.Ql \&? +act as +wildcards); each pattern in turn is matched against the host name. +When +.Nm sshd +is authenticating a client, such as when using +.Cm HostbasedAuthentication , +this will be the canonical client host name. +When +.Xr ssh 1 +is authenticating a server, this will be the host name +given by the user, the value of the +.Xr ssh 1 +.Cm HostkeyAlias +if it was specified, or the canonical server hostname if the +.Xr ssh 1 +.Cm CanonicalizeHostname +option was used. +.Pp +A pattern may also be preceded by +.Ql \&! +to indicate negation: if the host name matches a negated +pattern, it is not accepted (by that line) even if it matched another +pattern on the line. +A hostname or address may optionally be enclosed within +.Ql \&[ +and +.Ql \&] +brackets then followed by +.Ql \&: +and a non-standard port number. +.Pp +Alternately, hostnames may be stored in a hashed form which hides host names +and addresses should the file's contents be disclosed. +Hashed hostnames start with a +.Ql | +character. +Only one hashed hostname may appear on a single line and none of the above +negation or wildcard operators may be applied. +.Pp +The keytype and base64-encoded key are taken directly from the host key; they +can be obtained, for example, from +.Pa /etc/ssh/ssh_host_rsa_key.pub . +The optional comment field continues to the end of the line, and is not used. +.Pp +Lines starting with +.Ql # +and empty lines are ignored as comments. +.Pp +When performing host authentication, authentication is accepted if any +matching line has the proper key; either one that matches exactly or, +if the server has presented a certificate for authentication, the key +of the certification authority that signed the certificate. +For a key to be trusted as a certification authority, it must use the +.Dq @cert-authority +marker described above. +.Pp +The known hosts file also provides a facility to mark keys as revoked, +for example when it is known that the associated private key has been +stolen. +Revoked keys are specified by including the +.Dq @revoked +marker at the beginning of the key line, and are never accepted for +authentication or as certification authorities, but instead will +produce a warning from +.Xr ssh 1 +when they are encountered. +.Pp +It is permissible (but not +recommended) to have several lines or different host keys for the same +names. +This will inevitably happen when short forms of host names +from different domains are put in the file. +It is possible +that the files contain conflicting information; authentication is +accepted if valid information can be found from either file. +.Pp +Note that the lines in these files are typically hundreds of characters +long, and you definitely don't want to type in the host keys by hand. +Rather, generate them by a script, +.Xr ssh-keyscan 1 +or by taking, for example, +.Pa /etc/ssh/ssh_host_rsa_key.pub +and adding the host names at the front. +.Xr ssh-keygen 1 +also offers some basic automated editing for +.Pa ~/.ssh/known_hosts +including removing hosts matching a host name and converting all host +names to their hashed representations. +.Pp +An example ssh_known_hosts file: +.Bd -literal -offset 3n +# Comments allowed at start of line +cvs.example.net,192.0.2.10 ssh-rsa AAAA1234.....= +# A hashed hostname +|1|JfKTdBh7rNbXkVAQCRp4OQoPfmI=|USECr3SWf1JUPsms5AqfD5QfxkM= ssh-rsa +AAAA1234.....= +# A revoked key +@revoked * ssh-rsa AAAAB5W... +# A CA key, accepted for any host in *.mydomain.com or *.mydomain.org +@cert-authority *.mydomain.org,*.mydomain.com ssh-rsa AAAAB5W... +.Ed +.Sh FILES +.Bl -tag -width Ds -compact +.It Pa ~/.hushlogin +This file is used to suppress printing the last login time and +.Pa /etc/motd , +if +.Cm PrintLastLog +and +.Cm PrintMotd , +respectively, +are enabled. +It does not suppress printing of the banner specified by +.Cm Banner . +.Pp +.It Pa ~/.rhosts +This file is used for host-based authentication (see +.Xr ssh 1 +for more information). +On some machines this file may need to be +world-readable if the user's home directory is on an NFS partition, +because +.Nm +reads it as root. +Additionally, this file must be owned by the user, +and must not have write permissions for anyone else. +The recommended +permission for most machines is read/write for the user, and not +accessible by others. +.Pp +.It Pa ~/.shosts +This file is used in exactly the same way as +.Pa .rhosts , +but allows host-based authentication without permitting login with +rlogin/rsh. +.Pp +.It Pa ~/.ssh/ +This directory is the default location for all user-specific configuration +and authentication information. +There is no general requirement to keep the entire contents of this directory +secret, but the recommended permissions are read/write/execute for the user, +and not accessible by others. +.Pp +.It Pa ~/.ssh/authorized_keys +Lists the public keys (DSA, ECDSA, Ed25519, RSA) +that can be used for logging in as this user. +The format of this file is described above. +The content of the file is not highly sensitive, but the recommended +permissions are read/write for the user, and not accessible by others. +.Pp +If this file, the +.Pa ~/.ssh +directory, or the user's home directory are writable +by other users, then the file could be modified or replaced by unauthorized +users. +In this case, +.Nm +will not allow it to be used unless the +.Cm StrictModes +option has been set to +.Dq no . +.Pp +.It Pa ~/.ssh/environment +This file is read into the environment at login (if it exists). +It can only contain empty lines, comment lines (that start with +.Ql # ) , +and assignment lines of the form name=value. +The file should be writable +only by the user; it need not be readable by anyone else. +Environment processing is disabled by default and is +controlled via the +.Cm PermitUserEnvironment +option. +.Pp +.It Pa ~/.ssh/known_hosts +Contains a list of host keys for all hosts the user has logged into +that are not already in the systemwide list of known host keys. +The format of this file is described above. +This file should be writable only by root/the owner and +can, but need not be, world-readable. +.Pp +.It Pa ~/.ssh/rc +Contains initialization routines to be run before +the user's home directory becomes accessible. +This file should be writable only by the user, and need not be +readable by anyone else. +.Pp +.It Pa /etc/hosts.equiv +This file is for host-based authentication (see +.Xr ssh 1 ) . +It should only be writable by root. +.Pp +.It Pa /etc/moduli +Contains Diffie-Hellman groups used for the "Diffie-Hellman Group Exchange" +key exchange method. +The file format is described in +.Xr moduli 5 . +If no usable groups are found in this file then fixed internal groups will +be used. +.Pp +.It Pa /etc/motd +See +.Xr motd 5 . +.Pp +.It Pa /etc/nologin +If this file exists, +.Nm +refuses to let anyone except root log in. +The contents of the file +are displayed to anyone trying to log in, and non-root connections are +refused. +The file should be world-readable. +.Pp +.It Pa /etc/shosts.equiv +This file is used in exactly the same way as +.Pa hosts.equiv , +but allows host-based authentication without permitting login with +rlogin/rsh. +.Pp +.It Pa /etc/ssh/ssh_host_ecdsa_key +.It Pa /etc/ssh/ssh_host_ed25519_key +.It Pa /etc/ssh/ssh_host_rsa_key +These files contain the private parts of the host keys. +These files should only be owned by root, readable only by root, and not +accessible to others. +Note that +.Nm +does not start if these files are group/world-accessible. +.Pp +.It Pa /etc/ssh/ssh_host_ecdsa_key.pub +.It Pa /etc/ssh/ssh_host_ed25519_key.pub +.It Pa /etc/ssh/ssh_host_rsa_key.pub +These files contain the public parts of the host keys. +These files should be world-readable but writable only by +root. +Their contents should match the respective private parts. +These files are not +really used for anything; they are provided for the convenience of +the user so their contents can be copied to known hosts files. +These files are created using +.Xr ssh-keygen 1 . +.Pp +.It Pa /etc/ssh/ssh_known_hosts +Systemwide list of known host keys. +This file should be prepared by the +system administrator to contain the public host keys of all machines in the +organization. +The format of this file is described above. +This file should be writable only by root/the owner and +should be world-readable. +.Pp +.It Pa /etc/ssh/sshd_config +Contains configuration data for +.Nm sshd . +The file format and configuration options are described in +.Xr sshd_config 5 . +.Pp +.It Pa /etc/ssh/sshrc +Similar to +.Pa ~/.ssh/rc , +it can be used to specify +machine-specific login-time initializations globally. +This file should be writable only by root, and should be world-readable. +.Pp +.It Pa /var/empty +.Xr chroot 2 +directory used by +.Nm +during privilege separation in the pre-authentication phase. +The directory should not contain any files and must be owned by root +and not group or world-writable. +.Pp +.It Pa /var/run/sshd.pid +Contains the process ID of the +.Nm +listening for connections (if there are several daemons running +concurrently for different ports, this contains the process ID of the one +started last). +The content of this file is not sensitive; it can be world-readable. +.El +.Sh SEE ALSO +.Xr scp 1 , +.Xr sftp 1 , +.Xr ssh 1 , +.Xr ssh-add 1 , +.Xr ssh-agent 1 , +.Xr ssh-keygen 1 , +.Xr ssh-keyscan 1 , +.Xr chroot 2 , +.Xr login.conf 5 , +.Xr moduli 5 , +.Xr sshd_config 5 , +.Xr inetd 8 , +.Xr sftp-server 8 +.Sh AUTHORS +OpenSSH is a derivative of the original and free +ssh 1.2.12 release by Tatu Ylonen. +Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, +Theo de Raadt and Dug Song +removed many bugs, re-added newer features and +created OpenSSH. +Markus Friedl contributed the support for SSH +protocol versions 1.5 and 2.0. +Niels Provos and Markus Friedl contributed support +for privilege separation. |