ACA Blog

ACA Blog

October 2020


SSH Summer School: basic principles and correct client config

Jan BeerdenJan Beerden

SSH authentication and correct client config

This blog post is the first of a 3 part series about SSH (Secure Shell) connections with OpenSSH. The aim of this blog post series is to teach you more about SSH, so I call it SSH Summer School (I posted the first blog post right before the start of the fall so technically, it’s still summer!). In these blog posts, I assume you are using a UNIX-like operating system with OpenSSH. In this first part of the series, I’ll talk about some basic SSH principles and how to correctly configure your client.

As an IT professional, you’ve probably used SSH before to connect to a remote Linux server.  However, in case you haven’t, let’s start from the beginning with SSH authentication.

SSH authentication

The two most common authentication methods for SSH are password authentication and key authentication. Since a large portion of the systems running an SSH server are directly connected to the internet, they are also at risk of brute force attacks. This is the reason why you should never allow password authentication.

A more secure and convenient method is key based authentication. With RSA keys being the most commonly used, a key of at least 2048bit is a lot more difficult to guess than a passphrase. In the example below, I use a 4096bit key.

Creating your SSH key

Creating an SSH key is quite simple using the ssh-keygen command:

-t: Specifies the type of key to create. In this case rsa.

-b: Specifies the number of bits in the key to create.

During the creation you’ll be asked where you’d like to save this key. Most of the times the default location will do. Once you’ve confirmed or entered a location, you’ll be asked for a passphrase to protect your key with. I strongly recommend you to do so, because a key without a passphrase can be used by everyone who can get their hands on it.

You’ll notice that two files have been created:

You can probably guess which one you should never share! Hint: it starts with a p. 😉

Using your private key

The SSH client will assume your private key is located at one of the default locations, so you most likely won’t need to specify its location. For now, let’s assume your private key is located in one of those default locations (if you’re too curious and can’t wait, scroll down to the ‘SSH options’ below).

But how is this more convenient? Well, it isn’t yet, but you can make it more convenient by first adding your private key to something called an ssh-agent. This helper program will keep track of your private keys in their decrypted form.

After logging in and before using SSH, you can add your private key to ssh-agent. Ssh-agent will ask your passphrase to decrypt it and store it in memory. Once your private key has been added, you won’t be asked for your passphrase as long as you’re logged in to your own system.

As you can see in the example above, ssh-agent will also assume your private key is located in one of the default locations. If that isn’t the case, you can pass its location as a command line argument. With “ssh-add -l” you can get a list of all keys that have been added to your ssh-agent. You can also have a look at its man page by typing “man ssh-agent”.

Connecting to a remote server for the first time

To be able to use your private key to gain access to your account on a remote server, the public part of your private key needs to be stored in the authorized_keys file of your remote user.

Your public key consists of three parts:

The first time you connect to a remote server, you’ll be presented with its fingerprint.

This fingerprint is appended to your known hosts file.

When someone tries to perform a MITM attack or the remote server is re-installed or replaced, your SSH client will warn you.

At this point it’s best to check with the remote server’s administrator before continuing. After all, you want to make sure nobody’s eavesdropping on you. Should this have happened because the remote server has been replaced by a new one, you can remove the old fingerprint from your known_hosts file. You can use your favorite text editor for this, but the following command is probably much easier and also automatically creates a backup in case you would need to undo your change.

After this, connecting to the server will look like it’s the first time you’re connecting to it.

SSH options

In case you didn’t save your private key to one of the default locations, you can use the -i option to specify its location.

Perhaps your remote server does not listen on the default SSH port (22), but instead uses port 443.

There are numerous options that can be used, all of which can be found in the man page.

Specifying these options each time you connect can be a hassle, especially when you need multiple options. Luckily, there’s also a config file in which you can store these settings:

With this config in place you no longer have to specify all those command line options:

Neat, huh? That’s it for SSH authentication! Let’s move on to the details of the SSH config file.

Command line options vs. config file options

Like I mentioned above, there are two methods to specify your connection details.

You’ll notice that there are far more config file options than command line options. That doesn’t mean that you’re limited to the command line options without using your config file. In case you want to use one of the config file options without having to edit your configuration file, you can use the -o option. For example, to specify a different, lower, log level:

Common config file options

The SSH config file consists of configuration blocks delimited by the “Host” or “Match” keywords. When using the “Host” keyword, it must be followed by the server’s hostname, IP address or an alias. I usually use an alias and will show you later on why this might be more convenient.

“Global” options and “adding” options to existing configuration blocks

When configuring your SSH client connections through a config file, SSH will parse the config file chronologically and will build up your connection config with the unique config options of matching host blocks. By unique, I mean that a config option can only be set once and not overwritten later on. There is, however, one exception: a command line argument can always overwrite options from the config file.

This can be explained best using an example:

Using this example config file results in the following connection options for:

Additionally, you can split your SSH configuration into multiple files that are included by your main config file.

Sharing SSH config across team members

With a few conventions, you can leverage the methods shown above to create a set of config files that can be shared within your team using your favorite version control system.


You should already know this, but a reminder never hurts: never share your SSH key!


You’ll need two directories, one you share and one that remains private.

Next, you need to include these directories in your SSH config file. Add the following line at the top of ~/.ssh/config:

By including the private directory first, its config blocks will take precedence over the ones from the shared config files.

New team member?

When a new member joins the team, they need to:

Of course their SSH key still needs to be added to the remote servers, but not having to build the SSH config from scratch saves a lot of time. This is especially true when the remote servers require a lot of config options.

We’ll revisit this topic in the next part of this blog post series, so stay tuned! If you have any questions or remarks, leave them below as a comment and I’ll answer them asap or address them in a future blog post.

System Engineer at ACA IT-Solutions