Configuring your favourite hosts in SSH

A while back, I spent a bit of time digging into the SSH man pages to understand how to configure shortcuts for hosts I frequently log in to remotely. This is far from obvious from reading the man pages, so I thought I’d write up some useful tips here.

First, you need to create an SSH config file. Create the file in ~/.ssh/config, and and make sure the file has read-write permission to only your user. Similarly the directory, ~/.ssh/, must only be accessible to your user.

$ mkdir ~/.ssh/
$ chmod 700 ~/.ssh/

$ touch ~/.ssh/config
$ chmod 600 ~/.ssh/config

I had the file secured as ‘700’ on one machine (execute in addition to read-write permission), and the configuration didn’t work at all. Make sure you get the permissions right if SSH appears to be ignoring your configuration.

Now, configure a your favourite hosts in that file. The format is fully described by the ssh_config (5) man page, but I’ll give you a few examples to get you started. Here is a sample ~/.ssh/config file:

Host mattryall
User mryall

Host cac atlassian45

Host *
User mattr

This example file shows some of the most useful configuration options. First, I’ve configured a global default username of ‘mattr’ for all hosts I log in to. This is at the bottom of the file. Normally SSH will use your current username unless you specify one on the command-line, so setting a global default username is great if you’re using a computer where your username is different to most other systems you have access to.

The next section is the configuration for logging into my hosting at The Host line specifies an alias of ‘mattryall’ which I can use on the command-line to open a connection to the HostName value, ‘’. The User value says connections to this host should use the username ‘mryall’. Now, rather than writing this:

$ ssh

I can write this instead:

$ ssh mattryall

Much simpler, and I no longer have to remember my username or what the exact hostname is.

A slightly more complex example is the last one, which provides two aliases ‘cac’ and ‘atlassian45’ for the host This will use my default username to log in. Here again, we replace:

$ ssh

with this much shorter alternative:

$ ssh cac

Frequent users of SSH will find this a great time-saver.

Update, 3pm: I forgot to mention that the SSH aliases and usernames configured in ~/.ssh/config also work for scp. That means the command to download a GC log via SCP from one our servers becomes very easy:

$ scp cac:gc-2008-06-21_044659.log.gz .

All you have to remember (or copy-and-paste) is the file name.

Update, 29 June: The wildcard entry needs to go at the bottom of the file so that it doesn’t override the User option provided by other hosts.

Portrait of Matt Ryall

About Matt

I’m a technology nerd, husband and father of four, living in beautiful Sydney, Australia.

My passion is building software products that make the world a better place. For the last 15 years, I’ve led product teams at Atlassian to create collaboration tools.

I'm also a startup advisor and investor, with an interest in advancing the Australian space industry. You can read more about my work on my LinkedIn profile.

To contact me, please send an email or reply on Twitter.