SSH config file syntax and how-tos for configuring the OpenSSH client (2024)

This page is about OpenSSH client configuration. For OpenSSH server configuration, see sshd_config. For Tectia SSH configuration, see Tectia SSH Server Administrator Manual. For configuring passwordless public key authentication, see ssh-keygen.

The ssh program on a host receives its configuration from either the command line or from configuration files ~/.ssh/config and /etc/ssh/ssh_config.

Command-line options take precedence over configuration files. The user-specific configuration file ~/.ssh/config is used next. Finally, the global /etc/ssh/ssh_config file is used. The first obtained value for each configuration parameter will be used.

Commonly used configuration options

There are many configuration options available. In practice, only a few of them are ever changed, and user-specific configuration files are rarely used. In most cases, just /etc/ssh/ssh_config is edited.

Enabling X11 forwarding and agent forwarding

Developers, students, and researchers often want to enable X11 forwarding and SSH agent forwarding. These allow running graphical applications remotely and eliminate the need for typing a password whenever moving from one server to another, respectively. Setting these options in /etc/ssh/ssh_config makes life easier for end users, saves overhead, and reduces support load. However, they increase the risk of an attack spreading from a compromised server to a user's desktop, so the most security-critical environments may want to leave them disabled. There is generally no reason to enable them on production servers in enterprises.

ForwardAgent yes ForwardX11 yes

Port forwarding

Local and remote port forwarding can be used for tunneling applications, accessing intranet web services from home, tunneling database access, and many other purposes. For instructions on configuring port forwarding, see the port forwarding configuration page. Note, however, that port forwarding can also be used to tunnel traffic from the external Internet into a corporate intranet. Employees sometimes do this to be able to work from home even when company policy does not permit it. Hackers use it to leave permanent backdoor. See the page on SSH tunneling for more information.

Configuring public key authentication

Public authentication is used for passwordless logins between systems. It is often used for automated processes, such as backups, configuration management, and file transfers. It is also used by sophisticated end users and system administrators for single sign-on. See the public key authentication for configuring it.

When a user has created more than one SSH key for authentication, the -i command line option may be helpful for specifying which key to use. In the client configuration file, this can be specified using the IdentityFile options.

Certificate-based authentication

OpenSSH certificates can be used for authentication either using ssh-agent or by specifying the CertificateFile option in the client configuration file. See SSH certificates for more information.

Format of SSH client config file ssh_config

The ssh_config client configuration file has the following format. Both the global /etc/ssh/ssh_config and per-user ~/ssh/config have the same format.

• Empty lines and lines starting with '#' are comments.

• Each line begins with a keyword, followed by argument(s).

• Configuration options may be separated by whitespace or optional whitespace and exactly one =.

• Arguments may be enclosed in double quotes (") in order to specify arguments that contain spaces.

Listing of client configuration options

The following keywords can be used in SSH client configuration files. Keywords are case-insensitive and arguments are case-sensitive. Any algorithm or method names that include an at sign (@) are for experimental use only and not recommended for production.

Host

Restricts the following declarations to be only for those hosts that match one of the patterns given after the keyword. The pattern is matched against the host name given on the command line.

Match

Restricts the following declarations to apply only for hosts that match the specified criteria. For detailed information, see SSH man page.

AddressFamily

Specifies which address family to use when connecting. Valid arguments are: any, inet, inet6.

BatchMode

If set to yes, passphrase/password querying will be disabled. This is useful for running the ssh client from shell script that do not have an interactive user, and prevents accidentally blocking on a password prompt.

BindAddress

Specifies to use the specified address on the local machine as the source address of the connection.

ChallengeResponseAuthentication

Specifies whether to use challenge-response authentication. This is mostly a legacy method and has been replaced by KbdInteractiveAuthentication.

CheckHostIP

Directs ssh to additionally check the host IP address in the known_hosts file.

Cipher

Specifies the cipher to use for encrypting the session in protocol version 1. Note that use of protocol 1 is not recommended.

Ciphers

Specifies the ciphers allowed for protocol version 2 in order of preference. Multiple ciphers must be comma-separated. The ssh -Q cipher command can be used to query supported ciphers. The following list is supported in OpenSSH 6.7:

3des-cbc blowfish-cbc cast128-cbc arcfour arcfour128 arcfour256 aes128-cbc aes192-cbc aes256-cbc

[email protected] aes128-ctr aes192-ctr aes256-ctr [email protected]

[email protected] [email protected]

ClearAllForwardings

Specifies that all local, remote, and dynamic port forwardings specified in the configuration files or on the command line be cleared.

Compression

Specifies whether to use compression. yes enables compression.

CompressionLevel

Specifies the compression level to use if compression is enabled.

ConnectionAttempts

Specifies the number of attempts to make before exiting.

ConnectTimeout

Specifies the timeout (in seconds) used when connecting to the SSH server, instead of using the default system TCP timeout.

ControlMaster

Enables the sharing of multiple sessions over a single network connection.

ControlPath

Specify the path to the control socket used for connection sharing as described in the ControlMaster section above or the string none to disable connection sharing.

DynamicForward

Specifies that a TCP port on the local machine be forwarded over the secure channel, and the application protocol is then used to determine where to connect to from the remote machine.

EscapeChar

Sets the escape character.

ExitOnForwardFailure

Specifies whether ssh should terminate the connection if it cannot set up all requested dynamic, tunnel, local, and remote port forwardings.

ForwardAgent

Specifies whether the connection to the authentication agent will be forwarded to the remote machine.

ForwardX11

Specifies whether X11 connections will be automatically redirected over the secure channel and DISPLAY set.

ForwardX11Trusted

If this option is set to yes, remote X11 clients will have full access to the original X11 display.

GatewayPorts

Specifies whether remote hosts are allowed to connect to local forwarded ports.

GlobalKnownHostsFile

Specifies a file to use for the global host key database instead of /etc/ssh/ssh_known_hosts.

GSSAPIAuthentication

Specifies whether user authentication based on GSSAPI is allowed. GSSAPI is typically used for Kerberos authentication, e.g., with Active Directory.

GSSAPIKeyExchange

Specifies whether key exchange based on GSSAPI may be used.

GSSAPIClientIdentity

If set, specifies the GSSAPI client identity that ssh should use when connecting to the server.

GSSAPIDelegateCredentials

Forward (delegate) credentials to the server.

GSSAPIRenewalForcesRekey

If set to yes then renewal of the client's GSSAPI credentials will force the rekeying of the ssh connection.

GSSAPITrustDns

Set to yes to indicate that the DNS is trusted to securely canonicalize the name of the host being connected to. If no, the hostname entered on the command line will be passed untouched to the GSSAPI library.

HashKnownHosts

Indicates that ssh should hash host names and addresses when they are added to ~/.ssh/known_hosts. These hashed names may be used normally by ssh and sshd, but they do not reveal identifying information should the file's contents be disclosed.

HostbasedAuthentication

Specifies whether to try rhosts based authentication with public key authentication, using the .rhosts or .shosts files in the user's home directory and /etc/hosts.equiv and /etc/shosts.equiv in global configuration.

HostKeyAlgorithms

Specifies the protocol version 2 host key algorithms that the client wants to use in order of preference. The following values are supported in OpenSSH 6.7:

ssh-ed25519 [email protected] ssh-rsa ssh-dss ecdsa-sha2-nistp256 ecdsa-sha2-nistp384 ecdsa-sha2-nistp521 [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected]

HostKeyAlias

Specifies an alias that should be used instead of the real host name when looking up or saving the host key in the host key database files.

HostName

Specifies the real host name to log into. This can be used to specify nicknames or abbreviations for hosts. The default is the name given on the command line. Numeric IP addresses are also permitted (both on the command line and in HostName specifications).

IdentitiesOnly

Specifies that ssh should only use the identity keys configured in the ssh_config files, even if ssh-agent offers more identities.

IdentityFile

Specifies a file from which the user's identity key is read when using public key authentication. The default for protocol version 1 is ~/.ssh/identity; and ~/.ssh/id_rsa or ~/.ssh/id_dsa for protocol version 2.

KbdInteractiveAuthentication

Specifies whether to use keyboard-interactive authentication. This is a common method for password authentication, one-time passwords, and multi-factor authentication.

KbdInteractiveDevices

Specifies the list of methods to use in keyboard-interactive authentication.

LocalCommand

Specifies a command to execute on the local machine after successfully connecting to the server.

LocalForward

Specifies that a TCP port on the local machine be forwarded over the secure channel to the specified host and port from the remote machine. The first argument must be [bind_address:]port and the second argument must be host:port.

LogLevel

Specifies the verbosity level of logging messages from ssh. The possible values are: QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3.

MACs

Specifies the MAC (message authentication code) algorithms in order of preference. The ssh -Q mac command can be used to query supported MAC algorithms. The following list is supported in OpenSSH 6.7:

hmac-sha1 hmac-sha1-96 hmac-sha2-256 hmac-sha2-512 hmac-md5 hmac-md5-96 hmac-ripemd160 

[email protected] [email protected] [email protected] [email protected]

[email protected] [email protected] [email protected]

[email protected] [email protected] [email protected] [email protected]

[email protected]

NoHostAuthenticationForLocalhost

This option can be used if the home directory is shared across machines. In this case localhost will refer to a different machine on each of the machines and the user will get many warnings about changed host keys.

PreferredAuthentications

Specifies the order in which the client should try protocol 2 authentication methods.

Protocol

Specifies the protocol versions in order of preference. The possible values are '1' and '2'. Multiple versions must be comma-separated. Use of protocol version 1 is NOT RECOMMENDED for security reasons. There is reason to believe it may be susceptible to man-in-the-middle attacks.

ProxyCommand

Specifies the command to use to connect to the server. The SSH client communicates with the proxy command using its standard input and standard output, and the proxy command should pass the communication to an SSH server.

PubkeyAuthentication

Specifies whether to try public key authentication using SSH keys. Valid values are yes and no. When public key authentication is used in a production environment, a proper SSH key management system should also be put in place.

RemoteForward

Specifies that a TCP port on the remote machine be forwarded over the secure channel to the specified host and port from the local machine. The first argument must be: [bind_address:]port and the second argument must be host:port. SSH tunneling is a powerful tool, but see security considerations on SSH tunneling.

RhostsRSAAuthentication

Specifies whether to try rhosts based authentication with RSA host authentication. This is for protocol version 1 only and is deprecated.

RSAAuthentication

Specifies whether to try RSA authentication. This is for protocol version 1 only and is deprecated.

SendEnv

Specifies what environment variables should be sent to the server.

ServerAliveCountMax

Sets the number of keepalive messages that may be sent by the client without the client receiving any messages back from the server. When this threshold is reached the client will terminate the session.

ServerAliveInterval

Specifies interval for sending keepalive messages to the server. The messages are sent through the encrypted channel, and serve to detect if the server has crashed or the network has gone down.

SmartcardDevice

Specifies which smartcard device to use.

StrictHostKeyChecking

Specifies if ssh should never automatically add host keys to the ~/.ssh/known_hosts file, and refuses to connect to hosts whose host key has changed.

TCPKeepAlive

Specifies whether to send TCP keepalives to the other side. These operate on the level of the TCP protocol. Sending keepalives helps properly close the socket when the network or server goes down. On the other hand, without it, the connection may stay alive and any windows open, even if the network is down for a while.

Tunnel

If yes, request tun device forwarding between the client and the server. This used for implementing a VPN over SSH.

TunnelDevice

Specifies the tun devices to open on the client (local_tun) and the server (remote_tun).

UsePrivilegedPort

Specifies whether or not to use a privileged port for outgoing connections. The client must run as root to use a privileged port. A privileged port is required for host-based authentication.

UserKnownHostsFile

Specifies a file to use for per-user known host key database instead of the default ~/.ssh/known_hosts.

VerifyHostKeyDNS

Specifies whether to verify the remote key using DNS and SSHFP resource records.

VisualHostKey

Specifies whether an ASCII art representation of the remote host key fingerprint is printed in addition to the hex fingerprint string at login and for unknown host keys.