path: root/sshd.8

.\"
.\" 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.296 2018/03/03 06:37:53 dtucker Exp $
.Dd $Mdocdate: March 3 2018 $
.Dt SSHD 8
.Os
.Sh NAME
.Nm sshd
.Nd OpenSSH SSH daemon
.Sh SYNOPSIS
.Nm sshd
.Bk -words
.Op Fl 46DdeiqTt
.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 .
Together these programs replace rlogin and rsh,
and provide 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 fork 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 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.
.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
.Li 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 .
.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 security 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, currently
128-bit AES, Blowfish, 3DES, CAST128, Arcfour, 192-bit AES, or 256-bit AES.
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
(hmac-md5, hmac-sha1, umac-64, umac-128,
hmac-sha2-256 or hmac-sha2-512).
.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 dependant. 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 a shell or execution of a command.
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 xauth.
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