ssh-based Mercurial repositories

Paul Crowley, paul@lshift.net, 2008

WHAT IT GIVES YOU

You maintain a local Mercurial repository called "hgadmin" which

controls what access is allowed to whom.  When you push a new version

of this repository to the repository host, changes take effect

immediately, so familiar "hg" commands are all that are needed to

maintain it.  A "keys" directory contains the SSH keys of all the

developers who have access, while "hg-ssh-access.conf" gives a set of

rules defining who can do what to what.

HOW IT WORKS

The repository is owned by a single user (the "hg" user in what

follows), but many remote users can act on it.  We don't use file

permissions to achieve that - instead, developers log in as the "hg"

user when they connect to the repository host using ssh, using ssh

URLs of the form "ssh://hg@repository-host/repository-name".  A

restricted shell prevents them from using this access for unauthorized

purposes.

Developers are authenticated only using SSH keys; no other form of

authentication is supported.  When a developer attempts to connect to

a repository via ssh, the SSH daemon searches for a match for that

user's key in ~hg/.ssh/authorized_keys.  If the developer is

authorised to connect to the repository they will have an entry in

this file.  The entry includes a "command" prefix which specifies that

the restricted shell should be used; this shell is passed an argument

identifying the developer.  The shell parses the command the developer

is trying to execute, and consults a rules file to see if that

developer is allowed to perform that action on that repository.  The

bulk of the work of the restricted shell is done by the Python program

"hg-ssh", but the shell script "hg-ssh-wrapper" sets up some

configuration so that you can change it to suit your local installation.

The file ~hg/.ssh/authorized_keys is generated by "refresh-auth",

which recurses through a directory of files containing SSH keys and

generates an entry in authorized_keys for each one, using the name of

the key file as the identifier for the developer.  These keys will

live in the "keys" subdirectory of a repository, "hgadmin".  A hook in

this repository re-runs "refresh-auth" on the most recent version

after every push.

INSTRUCTIONS FOR USE

Issue these commands to become the hg user and set up the repository.

Use your own name in place of "myname".

   mkdir -p admin repos/hgadmin/keys/admin

   cd admin

   tar xvzf /tmp/hg-admin-tools.tar.gz

   mv hg-admin-tools* hg-admin-tools

   cp hg-admin-tools/hg-ssh-wrapper ~

   cd ../repos/hgadmin

   hg init .

   echo "init admin/* *" > hg-ssh-access.conf

   cp /tmp/my-ssh-public-key keys/admin/myname

   cp ~/admin/hg-admin-tools/hgadmin-hgrc .hg/hgrc

   exit

You should now have SSH access to this repository and full control.

To administer these controls (and test your access), check out hgadmin:

   mkdir ~/hg

   cd ~/hg

   hg clone ssh://hg@repository-host-name/hgadmin

   cd hgadmin