14 10 / 2013

I’ve been recently posting a series of this “how-to” docs on this blog. This is mostly a (public) self-reminder. Many of the things I do, as a developer, fall into a category of “setup” tasks, or the type of tasks that are otherwise required to be done only occasionally. Setting up and configuring SSH client is one such example. You do it once in a while and next time you try to do it, you don’t really remember what you did previously.

A few days ago, I set up SSH for my new open source git projects hosted on GitHub and BitBucket. And, I already forgot what I did. Well, almost. :) Here’s the list of steps I took to set up my SSH on Windows. (BTW, GitHub and BitBucket do not provide shell access, just git protocol over SSH, but the setup steps are the same.) 

On Windows, putty is one of the most popular SSH program. It is a SSH shell/terminal as well as a suite of SSH related tools such as SSH agent (called pageant), etc. I’ll however use the SSH on GitBash that comes with the git installation. GitBash seems like a pretty decent shell (with many Un*x type tools), and I’ll describe the steps as done in GitBash (which includes OpenSSH). If you use a Un*x like platform such as Linux or Mac, you can just use the standard shell.

[1] Create Key Pairs

Open a GitBash terminal. Type:

ssh-keygen -t rsa -C "comment"

By convention, many people seem to use their email as the comment. But, note that this comment will be part of the generated public key and hence world-readable (in theory). Note also that you will end up using many different key pairs (for different purposes), and therefore use the comment meaningful (and, preferably unique) to you. The -t flag specifies the key type (e.g., RSA vs DSA, etc.). When prompted, specify the meaningful name (not just the default name) for the key pairs. For example, I used names like “id_rsa_github_harrywye”, etc. to indicate the key pair is for use on GiitHub with my account name “harrywye”. The ssh-keygen generates a pair of public key and private key, in your .ssh folder (under your home directory) be default. You should guard your private key files (in addition to using a secure passphrase).

[2] Upload public key to GitHub/BitBucket

Both GitHub and BitBucket have account settings page, from which you can upload your public keys. Refer to their docs. You can just copy and paste the public key into the upload form. In some cases, you may want to upload multiple keys for various reasons (e.g., because you have multiple computers and each computer has a separate key pair, etc.). Sometimes, you may want to include at least one passphrase-less key so that you can perform certain background/automated actions that require SSH access.

[3] Test

In the GitBash terminal, type

ssh -T <hostname>

where <hostname> is “git@github.com” on GitHub and “git@bitbucket.org” on BitBucket.

If you don’t see the error (while you cannot actually open a remote shell on these services), then your SSH key setup is complete.

[4] Configure / Create Aliases

An alias is a very convenient feature. Instead of using <hostname> or <user@hostname> when you open a SSH connection with a particular identity/key, you can define an alias. Create a text file named “config” under your .ssh directory, and add a “Host” entry like this:

Host ghharrywye
 HostName github.com
 ForwardAgent yes
 IdentityFile ~/.ssh/id_rsa_github_harrywye

Each entry should be separated by a newline. The first line defines an alias, “ghharrywye” in this case (indicating that it’s for harrywye account on GitHub). The subsequent lines should be indented. HostName defines the domain of the SSH connection, github.com in this case. The IdentityFile item specifies the identity file that needs to be used for this particular connection. (Note that this is the private key/identity corresponding to the public key, or one of the keys, that I uploaded to GitHub.)

Now you can use the alias as the hostname in the ssh protocol. For example, for the MiniAuth project hosted on GitHub, I use the following URL:


where the <hostname> part has been replaced by the alias “ghharrywye” (instead of “github.com”), which is associated with a particular identity of mine.

[5] Run SSH Agent

Whenever you need to use your private key, you need to provide a passphrase (if one is set). Clearly, this may not be very convenient in many situations. An SSH agent program remembers your private key passphrases and supplies it to other programs when needed. On GitBash you can start SSH-Agent through this:

eval `ssh-agent`

Then, you can add any identify files using ssh-add:

ssh-add <identity>

where <identity> is the private key file name, e.g., “~/.ssh/id_rsa_github_harrywye”. You need to provide the key’s passphrase. You can check which identities have been currently added by typing:

ssh-add -L

In order to be able to use ssh-agent you need to set “ForwardAgent yes” for those connections in the config file, as shown in the above example.

You can set this up on your shell startup script (e.g., in .bashrc), or you can just run a simple shell script whenever you need it. On windows, you can also use pageant (part of the putty suite as mentioned earlier) along with putty, which are easier to use.