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.
Let’s walk through everything.
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
Port commands along with their options are all applied to the ssh connection. e.g.,
ssh psl is identical to running:
I’ve commonly seen
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 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.
ssh options take precedence by their proximity to the user:
- CLI options
- User’s configuration file (
- System-wide configuration file (
The first provided parameter’s value (top-down) will always be the one used.
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 sets the identity file; unlike most other keywords, multiple identities are OK.
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 sets the port to connect to the remote host. For security through obscurity, your server should use a different port than the default (22).
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.
Here, setting the default user can be useful if you commonly reuse the same username across multiple servers.
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).
gzip; set the compression level with the
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).
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.
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.
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
|%l||local host name (including domain name)|
|%L||first component of local host name|
|%h||target hostname specified on the CLI|
|%r||remote login username|
|%u||user 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
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:
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,
This is particulary useful if you set a passphrase for the key (recommended).
The permissions of the
~/.ssh and its files can be properly set with:
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:
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
Here’s how to fix it:
This will allow you to login to the server via your password and add the public key to the remote
To further prevent
ssh offering irrelevant keys, you can add the following to your local
If you aren’t using a
config file, then you’ll have to specifiy the correct key like so:
If you’re using
ssh-agent (which I recommend doing) you may have to clear any identies that have been previously added with:
Alternatively for a quick fix, you can bypass using an
ssh key (assuming your server allows it), by signing on with:
This forces non-key authentication and will allow you to login.
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.