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.
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.
Public/Private Keys
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?
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.
Complex Configurations
There are many scenarios that we could cover in this article, but let’s go over a few common and useful ones.
ForwardAgent
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.
RELATED: What is SSH Agent Forwarding and How Do You Use It?
ProxyJump
Similar to 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.
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 10.0.0.7.
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, DynamicForward, ControlMaster, and ControlPath.
The DynamicForward command is the port that we are actually looking to proxy across our SSH connection, such as port 8080. 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 myuser@10.0.0.5:22 in this connections case.
Conclusion
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!
