Your SSH config file allows you to define specific settings for each SSH host that makes connecting to that host far easier. By defining many of these common, or uncommon, properties within the file, it eliminates the need to remember this parameter set each and every time a connection is needed.
Defining an SSH Connection
If the file,
~/.ssh/config does not exist, you might go ahead and create this now. Typically, this file exists in a
.ssh “hidden” directory, hidden only because most operating systems don’t show directories prefaced by a
.. Also, this directory is usually located in one’s home directory, or the home directory of the user running ssh, hence the
~ notation, signifying the home directory.
It’s important to keep an eye on permissions within the
.ssh folder. Most SSH clients want the files to be mode
600 within this folder. If referencing this folder from Windows Subsystem for Linux, you should make sure to
chmod 600 ~\\.ssh\\*
So, what does a simple SSH connection look like in this file? An example of a simple configuration is below.
Host my-ssh-host HostName 10.0.0.5 Port 22 User myuser
As you can tell from the above configuration, this is about as basic as one can get. In fact, you can omit the Port as it’s not strictly necessary because
22 is the default SSH port. By defining this connection, on the command line we can simply do the following.
The connection will usually prompt for a password, as an SSH connection should not be unprotected.
Almost every SSH tutorial or setup guide out there will usually reference public/private keys at one point or another. These are the preferred way to setup an SSH connection. Instead of a password that can be hacked or guessed, it’s necessary to actually obtain the key file. This tutorial is not going into how to create those, so let’s assume that a set already exists and is properly setup. How do we tell our host configuration to use this file?
Host my-ssh-host HostName 10.0.0.5 Port 22 User myuser IdentityFile ~/.ssh/id_ed25519_myuser IdentitiesOnly yes
There are two new commands that we have introduced here. The
IdentityFile and the
IdentitiesOnly commands. First, we need to tell SSH where the key file is, in this case we have stored the file in the
.ssh directory (be wary of permissions). Second, we have defined a tag named
IdentitiesOnly. This will tell SSH to not try every identity file within that folder, but only the one’s defined. By default, SSH will walk through and try every identity file until it finds the right one. Often this will lead to a “Too many authentication failures for user myuser” on the target server if there are a lot of identities.
There are many scenarios that we could cover in this article, but let’s go over a few common and useful ones.
What if you have a scenario where you have opened an SSH connection to a target server, which then needs to make another SSH connection to a second server from that original target server? You might think that you will need to store those same SSH keys on that target server to make this next hop. There is a command, aptly named
ForwardAgent, that allows you to “forward” your local keys to the next server in the hop by setting up SSH agent key forwarding.
Host my-ssh-host HostName 10.0.0.5 Port 22 User myuser IdentityFile ~/.ssh/id_ed25519_myuser IdentitiesOnly yes ForwardAgent yes
ForwardAgent, often it is needed to open a secondary SSH connection directly through a a first (or second) target. Many times this is because a machine may be firewalled off from the general internet, but have a connection to a “jump box,” that then allows one to open a connection on the firewalled server. Starting in SSH version 7.3 and higher, the
ProxyJump command allows us to easily accomplish this.
Host my-ssh-host HostName 10.0.0.5 Port 22 User myuser IdentityFile ~/.ssh/id_ed25519_myuser IdentitiesOnly yes ForwardAgent yes ProxyJump email@example.com:22,firstname.lastname@example.org:10005
As seen above, there are two servers here. Initially, the SSH connection will go to
10.0.0.5 but then immediately open a connection to
10.0.0.6, then it will finally open a connection using a different user and port to
It’s worth pointing out that you really should make sure your SSH server is locked down.
SSH Proxy Tunnel
What if you have the need to set up a SOCKSv5 tunnel? Doing so is quite easy using the config file. We are introducing three new commands here,
Host my-ssh-host HostName 10.0.0.5 Port 22 User myuser IdentityFile ~/.ssh/id_ed25519_myuser IdentitiesOnly yes DynamicForward 8080 ControlMaster auto ControlPath ~/.ssh/%r@%h:%p
DynamicForward command is the port that we are actually looking to proxy across our SSH connection, such as port
ControlMaster is set to
auto, which means that if a connection exists, then use that, but if not create a new one. Finally, the
ControlPath sets the location of the actual socket file. In this case, it’s using the naming format of
%r@%h:%p, which corresponds to
email@example.com:22 in this connections case.
There is a lot of power in the SSH Configuration file. Far more complex examples can be defined, in addition to the ease of defining many different hosts within a single location. By doing so, not only are the host connections well-documented, but they allow for quick and easy access on the command line. If you choose to put this file under version control, you add the ability to have a running history of your hosts and potentially save yourself a large headache in the future. As you can tell, the SSH config file makes defining SSH hosts easy!