step-by-step: ssh on OSX, Ubuntu and Windows

This is an add-on to part 4 of my DVCS – blogseries: – working with remote repositories of Git and Mercurial. There are already step-by-step instrcutions to install Git and to install Mercury.

Accessing a remote Repository it’s a good practice to use ssh. SSH (Secure Shell) is a protocol for creating a secure connection between two computers. SSH provides authentication and encryption.

Eclipse SSH2: the easy way to ssh and generating keys

If you skip the commandline – part and scroll down to the last part “Eclipse Preferences SSH2” you’ll see that you can use ssh and also generate key-pairs from inside eclipse without the need of a commandline. This makes life much easier – esp. if you’re working on windows  and only using Git.

Unfortunately at the moment only EGit uses Eclipse-SSH2 – would be great if HgEclipse could use it too – would greatly simplify work on Windows. (Issue 10582)

If you’re using Mercurial under Windows or your workflows are missing some functions from EGit or HgEclips, then you need to work from commandline, too.

On the other side it’s always a good idea to know what happens behind the scenes, so I recommend (at least for one person of your development team) to go to the process and try making all from the commandline. You’ll have a better feeling what happens using EGit and HgEclipse and you’ll be very thankful to the developers of EGit and HgEclipse making your life easier.

In part 6 from my blogseries I’ll describe some usual workflows while using a DVCS – and I’ll always try to find ways without the need switching to the commandline.

configuration of ssh (commandline)

I read many blogs and documentation and it seems that there are many ways to have success with ssh where others fail. So I cannot guarantee that the way how I’m doing it works for you, too. Please comment if there are better ways or if something doesn’t work for you.

On OSX and Ubuntu “ssh” should be installed by default. A simple test from your commandline to see if ssh is installed, type “ssh“:

Unfortunately ssh on Windows isn’t so easy – I read many blogs and here are my ways to do it now. (If someone knows better or easier ways to use ssh with Git and Mercurial on Windows, feel free to comment)

If you have installed Git using msysGit on Windows (explained in part1 of my blog series and this step-by-step-addon), then you’ll have “GitBash“. Please execute

…then type “ssh” and you’ll see that “ssh” is part of “GitBash“:

If you only use Git on Windows, then “msysGit” gave you all you need and ssh should work well. But if you want to work also with Mercurial on Windows using “ssh“, you cannot use the “ssh” provided by “GitBash” for both.

Unfortunately the Mercury windows installation doesn’t provide “ssh” like msysGit AFAIK. To integrate “ssh” into Mercurial workflows on windows, one way is to use “Putty“. Here’s some documentation from Mercurial: AccessingSshRepositoriesFromWindows and Bitbucket: Using ssh.

And here how I’m using it – please go to PuTTY’s Website:

We need to download putty, plink, pageant and puttygen:

Attention: Your PuTTY applications (putty.exe, plink.exe, puttygen.exe, pageant.exe) MUST be at the same location as “Mercurial.ini” – this means directly in the Mercurial Installation Folder.

Next step is to generate and use ssh -public and -private keys.

Working with ssh keys

We have to distinct between the use of “ssh” from commandline and using “PuTTY” under windows. If you’re only working on OSX and Ubuntu or only using Git, you’re in luck and have to learn only one way – if you’re also using Mercurial under Windows, then you also have to learn the PuTTY way.

In general – if using ssh you have a public key and a private key. Some important rules:

• Only your public key must be sent to servers.
• NEVER give your private key to others !
• Store and backup your private key at a safe place.
• Always use a password (passphrase).

I’ll also explain how to deal with only one public/private key pair if you’re working under OSX, Ubuntu, Windows as I’m doing on my MacBookPro + Parallels VM. (I have to test that redView works on all those OS, so I install Eclipse everywhere and use DVCS to push/pull to/from my “main”-repository – I’ll talk about this later)

Generate ssh keys using ssh commandline or GitBash

The command ssh-keygen is used to generate a pair of public/private keys. Open Terminal Application or “GitBash” and type

ssh-keygen -C yourname@yourdomain

Its a good idea to add your mailaddress as Comment, because this will be part of your public key file. If you dont enter a Comment, as default userName@machineName will be included.

Generating ssh keys on OSX:

You have to enter the password (passphrase):

Your public key is generated into id_rsa.pub and your private key is id_rsa – both placed under /Users/yourUserName/.ssh/id_rsa and …id_rsa.pub

The key fingerprint is only another cryptic way to represent your public key. Sometimes the fingerprint is displayed instead of the full public key.

Under OSX you can easy add your passphrases to OSX keychain using this command:

/usr/bin/ssh-add -K

Using Ubuntu you’ll also use ssh-keygen from Terminal – the files are placed under /home/yourUserName/.ssh/id_rsa and …id_rsa.pub:

ATTENTION: don’ forget to add the key to be used from ssh-agent:

ssh-agent
ssh-add

Hint: on OSX above we added -k which means it would also be added to OSX keychain.

if you forget this, then perhaps while trying to get access to a remote server using ssh, HgEclipse fails with:

this doesn’t mean that something’s wrong with your remote public key, simply the key’s are not known because of missing ssh-add. (I learned the hard way 😉

Using “GitBash” under Windows it’s the same process to generate key pairs:

Vista / Windows 7 put the keys under /c/Users/yourUserName/.ssh/id_rsa and …/id_rsa.pub

Windows XP uses /c/Documents and Settings/yourUserName/.ssh/id_rsa and …/id_rsa.pub

Use your ssh keys with PuTTY on Windows

PuTTY uses an own format for SSH key-pairs. We already have generated ssh  keys using “GitBash” above. Now we’ll use the same key-pair from PuTTY.

PuTTYgen is the application needed to convert your existing key-pairs:

Conversions -> Import Key then select your private key file (we stored them above using GitBash):

now you have to enter your passphrase and hit “OK”

PuTTY imports your key-pair – please change the Comment:

Now we have to save the private key in PuTTY’s own format, please hit “Save private key”

PuTTY’s key files ends with “.ppk” – I always store them together with id_rsa and id_rsa.pub into .ssh folder:

As next step we have to execute another PuTTY application: “Pageant” (the agent for PuTTY like ssh-agent for ssh)

After Double-clicking our agent is available from System Tray:

Right-Click to add a key:

Select your PuTTY key – file:

enter your passphrase:

and now Pageant knows your key with passphrase – whats needed later if Mercurial uses your ssh key.

Attention! Pageant holds keys only in memory – nothing was saved to disc for security reason. This means: after restarting windows you have to start Pageant and add the keys again !

one last configuration-step: Mercurial has to know how to get your key. Please open “Mercurial.ini” file – you’ll find it at the root of your Mercurial Installation Path.

look for the UI section – there you have to add something like ssh=”C:\path to\plink.exe” -ssh -i “C:\your path to\private.key”. Because you’re just editing the Mercurial.ini perhaps you also like to add your userinfo into the ui section.

[ui]
...
username = yourName <yourEmail@xxx.org>
ssh="plink.exe" -ssh -i "C:\Users\Administrator\.ssh\ekke_at_ekkescorner.ppk"

Attention: Your PuTTY applications (putty.exe, plink.exe, puttygen.exe, pageant.exe) MUST be at the same location as “Mercurial.ini” to be in Mercurial’s search path. If not – HgEclipse will hang…. Also Pageant must be started and your *.ppk key added – otherwise HgEclipse will hang….

BTW: this is really uncomfortable 😦 Hopefully Mercurial will include ssh support into future releases of Mercurial for Windows as Git does using GitBash OR HgEclipse will use Eclipse SSH2 (Issue 10582).

Eclipse Preferences -> SSH2 (the easy ssh way)

This is the really easy way to work with SSH2: open Eclipse Preferences -> General -> Network Connections -> SSH2. AFAIK at the moment only EGit uses ssh from Eclipse Preferences. (Issue 10582)

This is an elegant way to manage ssh 🙂 Feel free to generate your rsa keys from here or import your keys you generated from commandline or even add aHost to the list of “Known Hosts”

Example Key Management: Eclipse -> Preferences -> General -> Network Connections -> SSH2 on Ubuntu:

Tab “Key Management” “Load Existing Key” select your id_rsa, then type the Passphrase and hit OK.

Then you can change the passphrase, copy the public key ….. all without the need to go to the commandline. You can also generate a new pair of keys from here.

The most important informations to make it work are the settings under “General” Tab:

SSH2 home should point to the directory where your key pairs are stored.

Hint: Running on Parallels you can also point to a shared directory from your Mac OSX

Under Windows XP I had to change the SSH2 home from username\ssh into username\.ssh (the dot was missing):

Manage your ssh keys

If you’re using DVCS like me (in my home-office: Laptop and Desktop, OSX, Ubuntu, Windows 7, Windows XP) then you should think about how to manage your Keys.

1. Generate your keys using a commandline or from inside Eclipse (Preferences – SSH2)
2. Copy the keys to all needed locations (see above the different locations for OSX, Ubuntu, Windows 7, XP)
3. Convert key for Putty, add to Pageant

You need your public key ?

If you need your public key, please open the id_rsa.pub file with a Text Editor and copy/paste the complete content. Or load the Key using Eclipse Preferences SSH2 Key Management as described above.

Have Fun Using Secure Connections To Remote Git Or Mercurial Repositories 🙂

The overview of this blog series can be found here: https://ekkescorner.wordpress.com/blog-series/git-mercurial/.