path: root/sshd.8

.\"  -*- nroff -*-
.\"
.\" sshd.8.in
.\"
.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
.\"
.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
.\"                    All rights reserved
.\"
.\" Created: Sat Apr 22 21:55:14 1995 ylo
.\"
.\" $Id: sshd.8,v 1.27 2000/08/29 00:33:51 djm Exp $
.\"
.Dd September 25, 1999
.Dt SSHD 8
.Os
.Sh NAME
.Nm sshd
.Nd secure shell daemon
.Sh SYNOPSIS
.Nm sshd
.Op Fl diqQ46
.Op Fl b Ar bits
.Op Fl f Ar config_file
.Op Fl g Ar login_grace_time
.Op Fl h Ar host_key_file
.Op Fl k Ar key_gen_time
.Op Fl p Ar port
.Op Fl u Ar len
.Op Fl V Ar client_protocol_id
.Sh DESCRIPTION
.Nm
(Secure Shell 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.
The programs are intended to be as easy to
install and use as possible.
.Pp
.Nm
is the daemon that 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.
This implementation of
.Nm
supports both SSH protocol version 1 and 2 simultaneously.
.Nm
works as follows.
.Pp
.Ss SSH protocol version 1
.Pp
Each host has a host-specific RSA key
(normally 1024 bits) used to identify the host.
Additionally, when
the daemon starts, it generates a server RSA key (normally 768 bits).
This key is normally regenerated every hour if it has been used, and
is never stored on disk.
.Pp
Whenever a client connects the daemon responds with its public
host and server keys.
The client compares the
RSA host key against its own database to verify that it has not changed.
The client then generates a 256 bit random number.
It encrypts this
random number using both the host key and the server key, and sends
the encrypted number to the server.
Both sides then use this
random number as a session key which is used to encrypt all further
communications in the session.
The rest of the session is encrypted
using a conventional cipher, currently Blowfish or 3DES, with 3DES
being used by default.
The client selects the encryption algorithm
to use from those offered by the server.
.Pp
Next, the server and the client enter an authentication dialog.
The client tries to authenticate itself using
.Pa .rhosts
authentication,
.Pa .rhosts
authentication combined with RSA host
authentication, RSA challenge-response authentication, or password
based authentication.
.Pp
Rhosts authentication is normally disabled
because it is fundamentally insecure, but can be enabled in the server
configuration file if desired.
System security is not improved unless
.Xr rshd 8 ,
.Xr rlogind 8 ,
.Xr rexecd 8 ,
and
.Xr rexd 8
are disabled (thus completely disabling
.Xr rlogin 1
and
.Xr rsh 1
into the machine).
.Pp
.Ss SSH protocol version 2
.Pp
Version 2 works similarly:
Each host has a host-specific DSA key used to identify the host.
However, when the daemon starts, it does not generate a server key.
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
Blowfish, 3DES or CAST128 in CBC mode or Arcfour.
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-sha1 or hmac-md5).
.Pp
Protocol version 2 provides a public key based
user authentication method (DSAAuthentication)
and conventional password authentication.
.Pp
.Ss Command execution and data forwarding
.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/IP connections, or forwarding the authentication agent
connection over the secure channel.
.Pp
Finally, 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.
.Pp
.Nm
can be configured using command-line options or a configuration
file.
Command-line options override values specified in the
configuration file.
.Pp
.Nm
rereads its configuration file when it receives a hangup signal,
.Dv SIGHUP .
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl b Ar bits
Specifies the number of bits in the server key (default 768).
.Pp
.It Fl d
Debug mode.
The server sends verbose debug output to the system
log, 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.
.It Fl f Ar configuration_file
Specifies the name of the configuration file.
The default is
.Pa /etc/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
300 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 the file from which the RSA host key is read (default
.Pa /etc/ssh_host_key ) .
This option must be given if
.Nm
is not run as root (as the normal
host file is normally not readable by anyone but root).
.It Fl i
Specifies that
.Nm
is being run from inetd.
.Nm
is normally not run
from inetd because it needs to generate the server key before it can
respond to the client, and this may take tens of seconds.
Clients would have to wait too long if the key was regenerated every time.
However, with small key sizes (e.g., 512) using
.Nm
from inetd may
be feasible.
.It Fl k Ar key_gen_time
Specifies how often the server key is regenerated (default 3600
seconds, or one hour).
The motivation for regenerating the key fairly
often is that the key is not stored anywhere, and after about an hour,
it becomes impossible to recover the key for decrypting intercepted
communications even if the machine is cracked into or physically
seized.
A value of zero indicates that the key will never be regenerated.
.It Fl p Ar port
Specifies the port on which the server listens for connections
(default 22).
.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 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.
.It Fl Q
Do not print an error message if RSA support is missing.
.It Fl V Ar client_protocol_id
SSH2 compatibility mode.
When this option is specified
.Nm
assumes the client has sent the supplied version string
and skips the
Protocol Version Identification Exchange.
.It Fl 4
Forces
.Nm
to use IPv4 addresses only.
.It Fl 6
Forces
.Nm
to use IPv6 addresses only.
.El
.Sh CONFIGURATION FILE
.Nm
reads configuration data from
.Pa /etc/sshd_config
(or the file specified with
.Fl f
on the command line).
The file contains keyword-value pairs, one per line.
Lines starting with
.Ql #
and empty lines are interpreted as comments.
.Pp
The following keywords are possible.
.Bl -tag -width Ds
.It Cm AFSTokenPassing
Specifies whether an AFS token may be forwarded to the server.
Default is
.Dq yes .
.It Cm AllowGroups
This keyword can be followed by a number of group names, separated
by spaces.
If specified, login is allowed only for users whose primary
group matches one of the patterns.
.Ql \&*
and
.Ql ?
can be used as
wildcards in the patterns.
Only group names are valid; a numerical group ID isn't recognized.
By default login is allowed regardless of the primary group.
.Pp
.It Cm AllowUsers
This keyword can be followed by a number of user names, separated
by spaces.
If specified, login is allowed only for users names that
match one of the patterns.
.Ql \&*
and
.Ql ?
can be used as
wildcards in the patterns.
Only user names are valid; a numerical user ID isn't recognized.
By default login is allowed regardless of the user name.
.Pp
.It Cm Ciphers
Specifies the ciphers allowed for protocol version 2.
Multiple ciphers must be comma-separated.
The default is
.Dq 3des-cbc,blowfish-cbc,arcfour,cast128-cbc .
.It Cm CheckMail
Specifies whether
.Nm
should check for new mail for interactive logins.
The default is
.Dq no .
.It Cm DenyGroups
This keyword can be followed by a number of group names, separated
by spaces.
Users whose primary group matches one of the patterns
aren't allowed to log in.
.Ql \&*
and
.Ql ?
can be used as
wildcards in the patterns.
Only group names are valid; a numerical group ID isn't recognized.
By default login is allowed regardless of the primary group.
.Pp
.It Cm DenyUsers
This keyword can be followed by a number of user names, separated
by spaces.
Login is disallowed for user names that match one of the patterns.
.Ql \&*
and
.Ql ?
can be used as wildcards in the patterns.
Only user names are valid; a numerical user ID isn't recognized.
By default login is allowed regardless of the user name.
.It Cm DSAAuthentication
Specifies whether DSA authentication is allowed.
The default is
.Dq yes .
Note that this option applies to protocol version 2 only.
.It Cm GatewayPorts
Specifies whether remote hosts are allowed to connect to ports
forwarded for the client.
The argument must be
.Dq yes
or
.Dq no .
The default is
.Dq no .
.It Cm HostDSAKey
Specifies the file containing the private DSA host key (default
.Pa /etc/ssh_host_dsa_key )
used by SSH protocol 2.0.
Note that
.Nm
disables protocol 2.0 if this file is group/world-accessible.
.It Cm HostKey
Specifies the file containing the private RSA host key (default
.Pa /etc/ssh_host_key )
used by SSH protocols 1.3 and 1.5.
Note that
.Nm
disables protocols 1.3 and 1.5 if this file is group/world-accessible.
.It Cm IgnoreRhosts
Specifies that
.Pa .rhosts
and
.Pa .shosts
files will not be used in authentication.
.Pa /etc/hosts.equiv
and
.Pa /etc/shosts.equiv
are still used.
The default is
.Dq yes