In this article, I’ll go over several of the most useful settings I’ve found for ssh_config and how to troubleshoot some of the issues I’ve come across while doing so.

An example configuration file

This example configuration file has both a specific host and the global host’s configuration.

# [email protected]
Host www.psl.com psl.com psl
User harvey
HostName www.psl.com
IdentityFile ~/.ssh/id_rsa
IdentitiesOnly yes
Port 1972
# Global
Host *
User reginald
ServerAliveCountMax 10
ServerAliveInterval 30
Compression yes
ControlMaster auto
ControlPath ~/.ssh/master-%l-%r@%h:%p
ControlPersist 1m

Let’s walk through everything.

Host

Host www.psl.com psl.com psl

The Host keyword restricts the configuration options that follow it on subsequent lines to the pattern provided on those same lines. Here, whether you enter ssh www.psl.com or ssh psl at the command line interface (CLI), the User, HostName, IdentityFile, IdentiesOnly, and Port commands along with their options are all applied to the ssh connection. e.g., ssh psl is identical to running:

ssh -p 1972 -i ~/.ssh/id_rsa [email protected]

I’ve commonly seen ssh commands aliased in shell configuration files. Using the ~/.ssh/config is a far more robust means to alias your ssh connections. It has the added benefit of enhancing the configuration of (S)FTP apps like the excellent Transmit.

User

Host www.psl.com psl.com psl
User harvey

User sets the default username for the Host. The username can be overridden, if need be, by providing a different one: ssh [email protected] but it will still maintain the same identity file and port.

Order matters

If fact, ssh options take precedence by their proximity to the user:

  1. CLI options
  2. User’s configuration file (~/.ssh/config)
  3. System-wide configuration file (/etc/ssh/ssh_config)

The first provided parameter’s value (top-down) will always be the one used.

HostName

Host www.psl.com psl.com psl
HostName www.psl.com

HostName is the real, unaliased host name to log into. IP addresses are also permitted. I recommend using the IP address of your server if you know it won’t change often; this will provide a small increase in security by preventing DNS spoofing.

IdentityFile

Host www.psl.com psl.com psl
IdentityFile ~/.ssh/id_rsa
IdentitiesOnly yes

IdentityFile sets the identity file; unlike most other keywords, multiple identities are OK.

IdentitiesOnly tells ssh to use only the listed identity files. This will prevent too many authentications failures errors (see below) and is helpful if you have multiple ssh keys.

Port

Host www.psl.com psl.com psl
Port 1972

Port sets the port to connect to the remote host. For security through obscurity, your server should use a different port than the default (22).

Global config

Host *

Using an asterisk applies the subsequent keywords and their parameters to all connections. Since ssh applies commands in its config file top-down (the first wins), the global set should always be placed at the bottom of the config file.

Host *
User reginald

Here, setting the default user can be useful if you commonly reuse the same username across multiple servers.

Compression

Host *
Compression yes

Enabling compression can help speed up a slow connection, or one in which a large amount of data is transferred (X11 forwarding is a good candidate). Compression utilizes gzip; set the compression level with the CompressionLevel keyword.

If all you’re doing is typing commands on a remote server, enabling Compression could be overkill (depending on your connection and server)—it may slow the connection down (slightly).

Use wisely.

Flaky connections

Host *
ServerAliveCountMax 10
ServerAliveInterval 30

ServerAliveCountMax and ServerAliveInterval are both used to keep a flaky connection from inadvertently closing. ServerAliveCountMax is the maximum number of messages ssh can send to the server without hearing a response back before ssh will drop the connection. ServerAliveInterval is the timeout interval after which the client will request a response from the server.

In the example above, the ssh connection will close after 10 messages * 30 s = 5 min. This back-and-forth is all done over a secure channel and therefore can’t be spoofed.

Session multiplexing

Host *
ControlMaster auto
ControlPath ~/.ssh/tmp/master-%l-%r@%h:%p
ControlPersist 1m

ControlMaster auto will allow the sharing of multiple sessions over a single network connection. This can greatly speed up the launching of new connections. The auto option is opportunistic: it will allow multiplexing but fall back to creating a new master if one does not already exist.

The ControlPath is the location of the control socket used for connection sharing. It is entirely appropriate to assign ControlPath to the ~/.ssh/tmp directory: closing the connection deletes these files. The path set must be unique from other open sockets. Below are the options for setting ControlPath; at a minimum it’s recommended to use %h, %p, and %r.

OptionsDescription
%llocal host name (including domain name)
%Lfirst component of local host name
%htarget hostname
%htarget hostname specified on the CLI
%pport
%rremote login username
%uuser running ssh

ControlPersist is the time that the master socket will remain open in the background after the last client connection closed. This is especially useful if the connection is accidentally closed. The option yes keeps the connection open indefinitely (until closed by some other means).

Further information and other commands

For more information about each of these commands and others I haven’t mentioned, see man ssh_config.

Generating a new ssh key and sending it over to the server

At this point, I hope you’re convinced that an ssh key and config file are worthwhile. Here’s how to setup a server with a new keyfile:

ssh-keygen -t rsa -b 4096 -C comment
cat ~/.ssh/id_rsa.pub | ssh [email protected] 'cat >> ~/.ssh/authorized_keys'

The first command will generate an RSA key of 4096 bit length (twice the sufficient length) and whatever comment you specify at the end of the key file.

The second will pipe the public key’s information over ssh into the authorized_keys file on the server.

After successfully logging in with your new key, you should be able to add the key to the authentication agent, ssh-agent:

ssh-add -K id_rsa

This is particulary useful if you set a passphrase for the key (recommended).

Troubleshooting

ERROR: Permissions

The permissions of the ~/.ssh and its files can be properly set with:

chmod go-w ~/
chmod 700 ~/.ssh
chmod 600 ~/.ssh/*
chmod 644 ~/.ssh/*.pub

Note that the 4th command overrides the public keys that will have had their permissions changed by the 3rd—this is a good thing—so the commands should be run in the order provided.

ERROR: Too many authentication failures

If for some reason you receive the message that:

Received disconnect from your-domain: 2: Too many authentication failures for username

It is likely that your public key has not been properly added to ~/.ssh/authorized_keys on the remote server. You can confirm this yourself with ssh -vvv.

Here’s how to fix it:

cat ~/.ssh/id_rsa | ssh -p 22 -o PubkeyAuthentication=no [email protected] 'cat >> ~/.ssh/authorized_keys'

This will allow you to login to the server via your password and add the public key to the remote authorized_keys file.

To further prevent ssh offering irrelevant keys, you can add the following to your local ~/.ssh/config file:

Host www.psl.com
IdentityFile ~/.ssh/id_rsa
IdentitiesOnly yes

If you aren’t using a config file, then you’ll have to specifiy the correct key like so:

ssh -i id_rsa -o 'IdentitiesOnly yes' [email protected]

If you’re using ssh-agent (which I recommend doing) you may have to clear any identies that have been previously added with:

ssh-add -D

Alternatively for a quick fix, you can bypass using an ssh key (assuming your server allows it), by signing on with:

ssh -o PubkeyAuthentication=no [email protected]

This forces non-key authentication and will allow you to login.

Concluding remarks

ssh is powerful. It’s use becomes easier to wield through the use of ssh key files and a config file. Using both can provide greater convenience and security.

If you know of other useful hints or a better way entirely, please leave them below in the comments.