sshd_config - How to configure the OpenSSH server
This page is about configuring the OpenSSH server. For Tectia SSH, see Tectia SSH Server Administrator Manual. For configuring public key authentication, see ssh-keygen. For configuring authorized keys for public key authentication, see authorized_keys.
The OpenSSH server reads a configuration file when it is started. Usually this file is
/etc/ssh/sshd_config, but the location can be changed using the
-f command line option when starting sshd. Some organizations run multiple SSH servers at different port numbers, specifying a different configuration file for each server using this option.
The default values for certain configuration options in OpenSSH are quite restrictive and often need to be changed. Usually this is done by editing the default configuration file to change just a few options.
ContentsRelationship of configuration files Common configuration options for individual use Common configuration changes for the enterprise Cryptographic policy Verbose logging AuthorizedKeysFile location Root login Login banner Port forwarding Certificate-based authentication Detailed
Relationship of configuration files
The SSH server actually reads several configuration files. The
sshd_config file specifies the locations of one or more host key files (mandatory) and the location of authorized_keys files for users. It may also refer to a number of other files.
Common configuration options for individual use
Many individual developers and power users wish to maximize their convenience rather than go for maximum security. For such use, we recommend the following settings for homes, development servers, and universities. For important systems even such organizations should follow the guidelines for configuring enterprise servers.
X11Forwarding yes AllowAgentForwarding yes PermitRootLogin yes
Common configuration changes for the enterprise
Larger enterprises, or others wanting to run a tight security policy for certain servers, may want to configure the following configuration options.
Symmetric algorithms for encrypting the bulk of transferred data are configured using the
Ciphers option. A good value is
aes128-ctr,aes192-ctr,aes256-ctr. This should also provide good interoperability.
Host key algorithms are selected by the
HostKeyAlgorithms option. A good value is
Key exchange algorithms are selected by the
KexAlgorithms option. We recommend
ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521,diffie-hellman-group14-sha1,diffie-hellman-group-exchange-sha256. In particular, we do not recommend allowing
diffie-hellman-group1-sha1, unless needed for compatibility. It uses a 768 bit prime number, which is too small by today's standards and may be breakable by intelligence agencies in real time. Using it could expose connections to man-in-the-middle attacks when faced with such adversaries.
Message authentication code algorithms are configured using the
MACs option. A good value is
We have included the sha-1 algorithm in the above sets only for compatibility. Its use is questionable from a security perspective. If it is not needed for compatibility, we recommend disabling it. NIST has also issued guidance on it.
Ciphers aes128-ctr,aes192-ctr,aes256-ctr HostKeyAlgorithms ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,ssh-rsa,ssh-dss KexAlgorithms ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521,diffie-hellman-group14-sha1,diffie-hellman-group-exchange-sha256 MACs hmac-sha2-256,hmac-sha2-512,hmac-sha1
Some organizations may also want to set policy for
PubkeyAcceptedKeyTypes. Same value as for
HostKeyAlgorithms would make sense. However, restricting this value could abruptly break business-critical connections, and we recommend only setting it after analyzing all existing authorized keys for the algorithms they use.
It is strongly recommended that
LogLevel be set to
VERBOSE. This way, the key fingerprint for any SSH key used for login is logged. This information is important for SSH key management, especially in legacy environments.
Note: the newer OpenSSH releases do not need a verbose mode setting anymore as the required SSH key activity information is written into the syslog by the default OpenSSH config.
Historically, most organizations have not touched the location of the authorized keys files. This means they are in each user's home directory, and each user can configure additional permanent credentials for themselves and their friends. They can also add additional permanent credentials for any service account or root account they are able to log into. This has lead to massive problems in large organizations around managing SSH keys.
We strongly recommend that organizations establish proper life cycle management for key-based credentials, and set the related options as part of this process. See SSH key management and contact us for additional help.
Enterprises should also pay attention to the
AuthorizedKeysCommandUser options. They are typically used when SELinux is enabled and to fetch SSH keys from LDAP directories or other data sources. Their use can make auditing SSH keys cumbersome and they can be used to hide backdoor keys from casual observation.
For enterprise use, root access should generally go through a privileged access management system. This is necessary to enable auditing. A privilege escalation method such as sudo may then be used to execute commands as root. Ideally, the root account will not have any password at all. (See also PrivX for eliminating all admin account passwords.)
However, many organizations need to allow scripts to run commands as root using SSH keys. With proper SSH key lifecycle management, this is the recommended way to script access. We furthermore recommend setting a forced command for any key configured to allow access as root. This can be enforced using the configuration file.
To disable passwords for root, but still allow key-based access without forced command, use:
To disable passwords and only allow key-based access with a forced command, use:
We also need to point out that we have seen some organizations use forced commands that in practice allow the client to run any command, just to nominally satisfy a policy/audit requirement that all keys must have forced commands. Forced commands must be EFFECTIVE. In general, the forced command should make no reference to the
SSH_ORIGINAL_COMMAND environment-variable. Auditors should check for this; if the forced command does reference this, odds are 99% that the forced command has been intentionally designed to fool auditors.
Many enterprises, especially in the government, may want to print a login banner with legal warnings before asking for a password. The
Banner option does this. If this option is specified, the contents of the file will be printed to the client before login.
Enterprises would generally want to prevent port forwarding on their servers, unless expressly needed for tunneling legacy applications. There is substantial risk that users will use SSH tunneling to open backdoors into the organization through the firewall to get access to work machines from home. We've seen this done in numerous organizations and the technique is widely known.
Even if port forwarding is disabled, there is still the possibility of a user running their own SSH server or having their own laptop run one.
AllowTcpForwarding no AllowStreamLocalForwarding no GatewayPorts no PermitTunnel no
OpenSSH also supports its own certificate formats for host and user authentication. See PrivX On-Demand Access Manager for how to use these for privileged access without passwords and automated access without SSH keys, based on Active Directory roles.
In host authentication, host certificates can be a major convenience. Tectia SSH supports standards-based X.509 certificates for this. OpenSSH requires its own certificate authority and secure certification authorities for it are not yet commercially available as of this writing. Therefore we don't recommend using OpenSSH certificates quite yet.
See OpenSSH certificates for more information on OpenSSH certificates and how to configure them and what is available for issuing them.
sshd_config file format
sshd_config file is an ASCII text based file where the different configuration options of the SSH server are indicated and configured with keyword/argument pairs. Arguments that contain spaces are to be enclosed in double quotes (").
sshd_config file the keywords are case-insensitive while arguments are case-sensitive.
Each line that starts with '#' is interpreted as a comment.
The following is a list of some of the most commonly used
sshd_config keywords. Full listing of all available configuration options can be found on the sshd Config Manual Pages.
Specifies which environment variables sent by the client will be copied to the session's user environment.
Specifies which IP address family sshd should use. Valid arguments are:
inet (IPv4 only),
inet6 (IPv6 only).
Specifies whether ssh-agent forwarding is permitted. The default is
Specifies whether forwarding Unix domain sockets is permitted. The default is
Specifies whether TCP forwarding is permitted. The default is
Specifies that login is allowed only for those user names that match a pattern listed with this keyword. By default, login is allowed for all user names.
Specifies the authentication methods that must be successfully completed in order to grant access to a user.
Specifies the file containing the public keys that can be used for user authentication. For more information, see Configuring Authorized Keys for OpenSSH.
ChallengeResponseAuthentication Specifies whether challenge-response authentication is allowed. The default is
Specifies the pathname of a directory to chroot (change root directory) to after authentication.
Specified the ciphers allowed. The ciphers supported in OpenSSH 7.3 are:
3des-cbc, aes128-cbc, aes192-cbc, aes256-cbc, aes128-ctr, aes192-ctr, aes256-ctr, firstname.lastname@example.org, email@example.com, arcfour, arcfour128, arcfour256, blowfish-cbc, cast128-cbc, firstname.lastname@example.org.
Specifies whether compression is allowed (
yes), denied (
no) or delayed until the user has authenticated successfully (
delayed - default).
Specifies that login is denied for those user names that match a pattern listed with this keyword. By default, login is allowed for all user names.
Forces the execution of the command specified by this keyword, ignoring any command supplied by the client and
~/.ssh/rc if present.
Specifies whether remote hosts are allowed to connect to ports forwarded for the client. The default is
Specifies whether user authentication based on GSSAPI is allowed. The default is
Specifies whether rhosts or
/etc/hosts.equiv authentication together with successful public key client host authentication (i.e. using the public key of the client machine to authenticate a user to the remote server, providing a non-interactive form of authentication) is allowed. The default is
Specifies whether or not the server will attempt to perform a reverse name lookup when matching the name in the
/etc/hosts.equiv files during host-based authentication.
Specifies a file containing a private host key used by SSH. It is possible to have multiple host key files. The default is
/etc/ssh/ssh_host_rsa_key for SSH protocol version 2.
Specifies the host key algorithms offered by the server. The defaults (OpenSSH 7.3) are:
email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, ecdsa-sha2-nistp256,ecdsa-sha2-nistp384, ecdsa-sha2-nistp521,ssh-ed25519, ssh-rsa,ssh-dss.
.shosts files will not be used in
Specified whether keyboard-interactive authentication is allowed. By default, the value of
Specifies the available Key Exchange algorithms. The KEX algorithms supported in OpenSSH 7.3 are:
email@example.com, diffie-hellman-group1-sha1, diffie-hellman-group14-sha1, diffie-hellman-group-exchange-sha1, diffie-hellman-group-exchange-sha256, ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521.
Specifies the local addresses sshd should listen on. The following forms are allowed:
The time after which the server disconnects if the user has not successfully logged in.
Specifies the level of verbosity for logging messages from sshd.
Specifies the available message authentication code algorithms that are used for protecting data integrity. The MACs supported in OpenSSH 7.3 are:
hmac-md5, hmac-md5-96, hmac-ripemd160, hmac-sha1, hmac-sha1-96, hmac-sha2-256, hmac-sha2-512, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org.
In the algorithm names,
-etm means "encrypt-then-mac", i.e. the message authentication code is calculated after encryption. It is recommended to use these algorithms because they are considered safer.
The detailed configuration file format documentation is still work in progress...