Using the SSH Config file

SSH, or Secure SHell, is a Linux utility that allows remote access to other machines. In this article, we will learn how to use configuration files to simplify the process of connecting to SSH hosts.

The SSH Config File

Connecting to a SSH host involves a very long command and many options. It’s hard to memorize, especially when you connect to multiple hosts on a regular basis. Luckily, we can turn this

$ ssh -i /path/private-key.pem user@5.34.152.68 -p 3300

into this

ssh smart-fridge

with the help of a config file, which acts like a dictionary (but even smarter!) and fills in all the correct fields.

Step 1. Find the Config File

On UNIX systems such as macOS, there are two locations where we can store SSH configurations: /etc/ssh/ssh_config for a system-wide file, and ~/.ssh/config for a user-specific file.

If these files don’t exist, you can:

• create the directory with mkdir, then
• create the file with your favorite text editor or touch, then
• Change the permissions for them: chmod 644 /etc/ssh/ssh_config for system-wide config, or chmod 600 ~/.ssh/config for personal file.

Step 2. Add Hosts

You can brave the MAN page for a full list of keywords or follow the tutorial here. The config file is a text file with zero or more host entries, each formatted like the following:

Host your_hostname(s)
    KEYWORD1 argument1
    KEYWORD2 argument2
[Empty line]

The hostnames is a space-separated list of patterns. Patterns can include

• non-whitespace characters,
• * wildcard, which matches zero or more characters,
• ? wildcard, which matches exactly one character, and
• ! negation, which rejects any query that would match the following pattern. But this negation does not turn a non-match into a match.

Example: Add a Simple Host

To avoid typing this command,

$ ssh -i /path/private-key.pem user@5.34.152.68 -p 3300

we add the following lines to the beginning of ~/.ssh/config:

Host smart-fridge
    HostName    5.34.152.68
    User        user
    Port        3300
    IdentityFile    ~/.ssh/fridge-private-key.pem

Now when we type ssh smart-fridge into the shell, the client finds this match and adds all parameters for us!

Details: how SSH obtains parameters

When we type an SSH command, the SSH client obtains parameters from three places, in the following order:

1. Parameters provided on the command line,
2. Parameters provided by matching entries in ~/.ssh/config, and
3. Parameters provided by matching entries in /etc/ssh/ssh_config.

Once a parameter like “user” is specified, SSH locks in and ignores all later sources that try to specify that parameter. SSH searches the config files for matching hostnames from top to bottom.

Example: Multiple matches

The user types this command into their terminal.

ssh -p 3001 ardeo.tavern.co.uk

First, SSH determines from the command that port is 3001.

Then, SSH searches through the following ~/.ssh/config file:

HostName ardeo.*
    User lachlan

HostName *.tavern.*
    User    adventurer
    Port    3000
    ConnectionAttempts 5

Because of the wildcard, the first host matches. The SSH client sets the User to lachlan.

Because of wildcards, the second host also matches. The SSH client sees that User and Port are already set, so they are ignored. The last line does specify a new parameter: ConnectionAttempts is set to 5, as taverns may have unstable service.

Next, SSH searches through the system-wide config file at /etc/ssh/ssh_config, where the system administrator, distrusting the security of the British net, has set the following:

HostName *.co.uk
    ConnectTimeout 600

This is a match, so the ConnectTimeout field will be set to 10 minutes. The SSH connection will terminate after 10 minutes.

Conclusion

The SSH config files simplify SSH connections by storing rules for parameters on specific hosts. There are many more fields you can specify in these configuration files, so check the MAN page for specifics.