Windows, Putty, and MercurialEclipse: A Love Triangle
Tonight I again found myself looking up Plink command line parameters and experimenting with variations of user names and SSH keys. I was attempting to stitch together another seamless development environment using Eclipse, MercurialEclipse, SSH and Mercurial-Server. This is something that I do so infrequently that, until now, I had simply not bothered to document the process. These days I'm working from several locations and with several machines (physical and virtual), so naturally, the number of clients has grown and this document has become necessary. So, in the interest of saving myself a bit of grief in the future and maybe helping some random out there on the net, lets do this.
Prerequisites
This article is for those of you running Windows (hopefully 7), with PuTTY and Eclipse installed. If you haven't done so yet, install the MercurialEclipse plugin available at (update site). When you install MercurialEclipse just go ahead and include the Mercurial binaries package as well. It makes life a bit easier.
Generate a New Public and Private Key Pair
To do this you'll likely want to use the PuTTY Key Generator (PuTTYgen). This tool is fairly self explanatory. Simply click the "Generate" button and move the mouse around the empty panel above to generate more random input. Once that has completed, save both the public and private keys in a protected space on disk. Finally, copy the displayed public key and stash that in some open editor for the time being.
Add the New Public Key to the Authorized Keys Repository
To add a new public key to the Mercurial-Server authorized key sets from a machine without hg access, you will need to first establish an SSH terminal session to the mercurial-server host as a user with sudoer access. If you are creating a new mercurial user, you will want to create a directory named for their username in either /etc/mercurial-server/keys/root or /etc/mercurial-server/keys/users depending on the desired access level of the user being created. For example, if I wanted to add jdoe as an administrator, I would create /etc/mercurial-server/keys/root/jdoe. Now that the user you want to grant access has a directory, create a new file in that directory named for the host they will be connecting from. Open the file with your favorite editor (vim FTW) and paste in the public key that you stashed away earlier. Save the file. Finally, the mercurial-server auth system needs to be updated for these changes. To do this, run:
sudo -u hg /usr/share/mercurial-server/refresh-auth
Note: If you're mercurial-server is running on Fedora or some other such distros, its a possibility that you'll instead need to run the following command.
sudo -u hg /usr/local/share/mercurial-server/refresh-auth
Registering SSH with MercurialEclipse and Configuring PKI Authentication
At this point the Mercurial.ini needs to be modified to register the command line to wrap communication with SSH. If you installed MercurialEclipse and included the Mercurial binaries, you'll need to hunt a bit to find the installation directory. An easy way to find this is by opening the Preferences in Eclipse, and navigating to Team > Mercurial. Near the top of the panel, there should be a disabled text field labeled, "Mercurial Executable." If you uncheck the "Use default Mercurial executable" checkbox, the field will enable, and you can simply select the text and copy the location of the executable. Open your favorite Windows editor (Textpad?) and open the Mercurial.ini located in the same folder as the hg.exe path you copied. Once open, add the following line under the [ui] section.
ssh = "C:\Program Files\PuTTY\plink.exe" -l hg -i <path to your private key>
Be sure to replace <path to your private key> with the actual path to the private key file you saved earlier. Once you're added the line, restart Eclipse for good measure and have at your repositories.
See Also
If you are interested in setting up or further configuring Mercurial-Server check out the lshift.net docs for the product. If you're going to be running it on Fedora, I made a few notes on the installation in an earlier article.