On Demand

You can run HGKeeper on demand to integrate it directly with an OpenSSH Server. This is accomplished by having a local user on the host, typically named hg, and telling the OpenSSH server to do something specific when that user logs in.

HGKeeper will also be run via this user and all of the repositories will belong to them in the filesystem.

Installing

When running in on demand mode HGKeeper needs to be installed in a place where OpenSSH Server can find it. However, since OpenSSH Server is also going to be running it, there are some additional requirements that must be met.

These requirements are that the program:

  • must be owned by root
  • is not writeable by group or others
  • is specified by an absolute path

Luckily for us, something like /usr/local/bin meets all of these requirements and will put it on the $PATH so that we can use it to set up the administration repository later.

So we will just copy the file to /usr/local/bin/ and make sure it has a file mode of 0755:

sudo cp hgkeeper /usr/local/bin/
sudo chown root:root /usr/local/bin/hgkeeper
sudo chmod 0755 /usr/local/bin/hgkeeper

Create The hg User

You can name this user whatever you like, but for the sake of simplicity, we will just be using hg here. We are also going to create an hg group to keep to make sure file permissions remain tight. For most Linux/BSD distributions, you can create the hg user and group with the following commands:

sudo groupadd --system hg
sudo useradd --home-dir /var/lib/hg --create-home --system --gid hg

This is the username that you will need to specify when connecting to the OpenSSH Server and is how we will configure the server to tell it how to serve Mercurial repositories.

NOTE: This user must have a valid and usable shell. If not you will get mysterious and difficult to debug failures.

Administration Repository

To make life easier, we're going to run the setup command as the hg user. The easiest way to do this is with the following commands:

sudo su hg
cd ~
whoami

We changed to the hg user's home directory as this is where we are going to store all of the files. The last line of output should just say hg, which we are using to verify that you did in fact switch to the hg user.

Now that we're in the proper location we can create the administration repository. For this, we'll need an SSH public key of the initial administrator saved in a file, and a name for the administrator. The name is used to determine where to put the public key and by the authentication system.

In this example, we have the administrator's SSH public key in a file named admin.pub in the current directory. We are also giving them a name of me.

hgkeeper setup --admin-pubkey=admin.pub --admin-username=me

Configuring OpenSSH Server

Configuring OpenSSH Server is very straightforward. All we need to do is drop the following snippet into /etc/ssh/sshd_config. Of course, if you customized the install location or username you will have to adjust the snippet.

You may be able to use /etc/ssh/sshd_config.d/hgkeeper.conf but in our testing on Debian unstable we were unable to get it working properly. If you have some pointers here, we'd love to hear them!

Match User hg
    AuthorizedKeysCommand /usr/local/bin/hgkeeper --repos-path=/var/lib/hg/repos/ authorized-keys "%t %k"
    AuthorizedKeysCommandUser hg
    PasswordAuthentication no

Open you've saved the file, you will need to reload OpenSSH Server. This is usually done via sudo service ssh reload but will vary based on your operating system.

Testing

You should now be able to clone the hgkeeper administration repo through your normal OpenSSH Server. You can verify this by trying to clone the hgkeeper administration repository with the following command, replacing <my hostname> with the actual hostname of your server:

hg clone ssh://<my hostname>/hgkeeper

If the repository cloned, you are good to go!

If that didn't work, be sure to double check all of your configuration.