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.

Installing Mercurial-Server on Fedora Core

Those of you who are familiar with distributed version control systems likely understand that the notion of a central repository has been removed from the required architecture. However, there remain several benefits to having one or more shared repositories. LShift were kind enough to bestow upon the world Mercurial-Server, an open source Mercurial authentication, authorization and repository management system. This is the tool you've been looking for to setup a single server which hosts shared repositories. To really get an appreciation of what this can do, check out the online docs.

A prerequisite to successful installation of Mercurial-Server is Mercurial itself. Yum.

yum install mercurial

While I know my way around a nix box, I'm far from what some would call adept. So, when I go to start experimenting with some new product, I usually pray for a smooth installation. This is rarely the case, and my experience with this product brought no such fortune.

The provided README and online documentation indicates that mercurial-server is targeted toward Debian based systems and most easily installed via some package management system. Had I been installing this on one of my Ubuntu boxes, I'm sure I would not be writing this article, but I was stuck with FC 14. So, reading on, they kindly suggest that on Red Hat and other variants running 'sudo make setup-useradd' would possibly work. After giving it a whirl, it very nearly did. After examining the output, it seems that the manual generation was failing due to an XSL parsing problem. "No biggy. It looks like its just a reflection of their online docs anyway." Taking a look at the MakeFile it was trivial to identify the phase which was causing the failure. Simply running the sub commands directly, while omitting the doc generation did the trick. Without further adieu:

wget http://dev.lshift.net/paul/mercurial-server/mercurial-server_1.1.tar.gz
tar -xzvf mercurial-server_1.1.tar.gz
cd mercurial-server_1.1
sudo make installetc
sudo make pythoninstall
sudo make useradd
sudo make inituser

Another thing to note is that the documentation makes reference to tooling installed at, "/usr/share/mercurial-server/", examination of the MakeFile shows that these goodies are actually installed at, "/usr/local/share/mercurial-server/." Once you're done setting it up, you might want to read up on how to config it. Check out their docs at http://dev.lshift.net/paul/mercurial-server/docbook.html.

Update: One thing the docs will not mention is that your newly created hg user will likely need to have a password set on the account before you will be able to connect. While you will be using PKI authentication, accounts without passwords set are recognized as disabled by the system. Though the mercurial-server software does prevent direct logins with the hg user, it is important to choose a significantly complex password to protect from possible vulnerabilities.