SSH Config File
The ssh program on a host receives its configuration from either the command line or from configuration files
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
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
Format of SSH client config file
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.
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.
Restricts the following declarations to apply only for hosts that match the specified criteria. For detailed information, see SSH man page.
Specifies which address family to use when connecting. Valid arguments are:
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.
Specifies to use the specified address on the local machine as the source address of the connection.
Specifies whether to use challenge-response authentication. This is mostly a legacy method and has been replaced by
Directs ssh to additionally check the host IP address in the
Specifies the cipher to use for encrypting the session in protocol version 1. Note that use of protocol 1 is not recommended.
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 firstname.lastname@example.org aes128-ctr aes192-ctr aes256-ctr email@example.com firstname.lastname@example.org email@example.com
Specifies that all local, remote, and dynamic port forwardings specified in the configuration files or on the command line be cleared.
Specifies whether to use compression.
yes enables compression.
Specifies the compression level to use if compression is enabled.
Specifies the number of attempts to make before exiting.
Specifies the timeout (in seconds) used when connecting to the SSH server, instead of using the default system TCP timeout.
Enables the sharing of multiple sessions over a single network connection.
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.
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.
Sets the escape character.
Specifies whether ssh should terminate the connection if it cannot set up all requested dynamic, tunnel, local, and remote port forwardings.
Specifies whether the connection to the authentication agent will be forwarded to the remote machine.
Specifies whether X11 connections will be automatically redirected over the secure channel and DISPLAY set.
If this option is set to
yes, remote X11 clients will have full access to the original X11 display.
Specifies whether remote hosts are allowed to connect to local forwarded ports.
Specifies a file to use for the global host key database instead of
Specifies whether key exchange based on GSSAPI may be used.
If set, specifies the GSSAPI client identity that ssh should use when connecting to the server.
Forward (delegate) credentials to the server.
If set to
yes then renewal of the client's GSSAPI credentials will force the rekeying of the ssh connection.
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.
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.
Specifies whether to try rhosts based authentication with public key authentication, using the
.shosts files in the user's home directory and
/etc/shosts.equiv in global configuration.
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 firstname.lastname@example.org ssh-rsa ssh-dss ecdsa-sha2-nistp256 ecdsa-sha2-nistp384 ecdsa-sha2-nistp521 email@example.com firstname.lastname@example.org email@example.com firstname.lastname@example.org email@example.com firstname.lastname@example.org email@example.com
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.
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).
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/id_dsa for protocol version 2.
Specifies whether to use keyboard-interactive authentication. This is a common method for password authentication, one-time passwords, and multi-factor authentication.
Specifies the list of methods to use in keyboard-interactive authentication.
Specifies a command to execute on the local machine after successfully connecting to the server.
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
Specifies the verbosity level of logging messages from ssh. The possible values are:
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 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 email@example.com
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.
Specifies the order in which the client should try protocol 2 authentication methods.
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.
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.
Specifies whether to try public key authentication using SSH keys. Valid values are
no. When public key authentication is used in a production environment, a proper SSH key management system should also be put in place.
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.
Specifies whether to try rhosts based authentication with RSA host authentication. This is for protocol version 1 only and is deprecated.
Specifies whether to try RSA authentication. This is for protocol version 1 only and is deprecated.
Specifies what environment variables should be sent to the server.
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.
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.
Specifies which smartcard device to use.
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.
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.
tun device forwarding between the client and the server. This used for implementing a VPN over SSH.
Specifies the tun devices to open on the client (local_tun) and the server (remote_tun).
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.
Specifies a file to use for per-user known host key database instead of the default
Specifies whether to verify the remote key using DNS and SSHFP resource records.
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.