Knowledge Base - SSH

Config File Tutorial

If you are regularly connecting to multiple remote systems over SSH on a daily basis, you’ll find that remembering all of the remote IP addresses, different usernames, non standard ports and various command line options is difficult, if not impossible.

OpenSSH allows you to set up per-user configuration file where you can store different SSH options for each remote machine you connect to.

This guide covers the basics of the SSH client configuration file and explains some of the most common configuration options.

SSH Config File Location

OpenSSH client-side configuration file is named config and it is stored in .ssh directory under user’s home directory. The ~/.ssh directory is automatically created when the user runs the ssh command for the first time.

If you have never used the ssh command first you’ll need to create the directory using:

mkdir -p ~/.ssh && chmod 700 ~/.ssh

By default, the SSH configuration file may not exist so you may need to create it using the touch command:

touch ~/.ssh/config && chmod 600 ~/.ssh/config

This file must be readable and writable only by the user, and not accessible by others:

chmod 700 ~/.ssh/config

SSH Config File Structure and Patterns

The SSH Config File takes the following structure:

Host hostname1
    SSH_OPTION value
    SSH_OPTION value

Host hostname2
    SSH_OPTION value

Host *
    SSH_OPTION value

The contents of the SSH client config file is organized into stanzas (sections). Each stanza starts with the Host directive and contains options that are used when establishing a connection with an SSH server.

Indentation is not required, but is recommended since it will make the file easier to read.

The Host directive can contain a single pattern or a whitespace-separated list of patterns. Each pattern can contain zero or more non-whitespace character or one of the following pattern specifiers:

* - matches zero or more characters. For example, Host * will match all host, while 192.168.0.* will match all hosts in the 192.168.0.0/24 subnet.
? - matches exactly one character. The pattern, Host 10.10.0.? will match all hosts in 10.10.0.[0-9] range.
! - at the start of a pattern will negate its match For example, Host 10.10.0.* !10.10.0.5 will match any host in the 10.10.0.0/24 subnet except 10.10.0.5.

The SSH client reads the configuration file stanza by stanza and if more than one patterns match, the options from the first matching stanza takes precedence. Therefore more host-specific declarations should be given at the beginning of the file, and more general overrides at the end of the file.

You can find a full list of available ssh options by typing man ssh_config in your terminal.

The SSH config file is also read by other programs such as scp, sftp and rsync.

Basic SSH Config File Example

Now that we’ve covered the basics of SSH configuration files, let’s take a look at an example.

Typically, when connecting to an SSH server, the user name, hostname, and port number are specified.

For example, to connect as a user named john to a host called dev.example.com on port 2322 from the command line, you would type:

ssh john@dev.example.com -p 2322

An SSH config file with the following lines can be used to connect to a server with the above options simply by typing ssh dev in a terminal.

Host dev
    HostName dev.example.com
    User john
    Port 2322

Shared SSH Config File Example

This example gives more detailed information about the host patterns and option precedence:

Host targaryen
    HostName 192.168.1.10
    User daenerys
    Port 7654
    IdentityFile ~/.ssh/targaryen.key

Host tyrell
    HostName 192.168.10.20

Host martell
    HostName 192.168.10.50

Host *ell
    user oberyn

Host * !martell
    LogLevel INFO

Host *
    User root
    Compression yes

If you type ssh targaryen the ssh client will read the file and will apply the options from the first match which is Host targaryen. Then it will check the next stanzas one by one for matching pattern. The next matching one is Host * !martell which means all hosts except martell and it will apply the connection option from this stanza. Finally the last definition Host * also mathes but the ssh client will take only the Compression option because the User option is already defined in the Host targaryen stanza. The full list of options used in this case is as follows:

HostName 192.168.1.10
User daenerys
Port 7654
IdentityFile ~/.ssh/targaryen.key
LogLevel INFO
Compression yes

When running ssh tyrell the matching host patterns are: Host tyrell, Host *ell, Host * !martell and Host *. The options used in this case are:

HostName 192.168.10.20
User oberyn
LogLevel INFO
Compression yes

If you run ssh martell the matching host patterns are: Host martell, Host *ell and Host *. The options used in this case are:

HostName 192.168.10.50
User oberyn
Compression yes

For all other connections options specified in the Host * !martell and Host * sections will be used.

Override SSH Config File Option

The ssh client receives its configuration in the following precedence order:

Options specified from the command line
Options defined in the ~/.ssh/config
Options defined in the /etc/ssh/ssh_config

If you want to override a single option you can specify it on the command line. For example if you have the following definition:

Host dev
    HostName dev.example.com
    User john
    Port 2322

and you want to use all other options but to connect as user root instead of john simply specify the user on the command line:

ssh -o "User=root" dev

The -F (configfile) switch allows you to specify an alternative per-user configuration file.

If you want your ssh client to ignore all of the options specified in your ssh configuration file, you can use:

ssh -F /dev/null user@example.com

NULL