hg-admin-tools

A set of tools for managing authorization and access control for
ssh-based Mercurial repositories

Paul Crowley, paul@lshift.net, 2008

This software may be used and distributed according to the terms
of the GNU General Public License, incorporated herein by reference.

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.

GETTING STARTED

This is only one setup - it can be tweaked in many ways, and is as
specific as it is only in the interests of brevity.

You, and all users of your Hg repository, will need SSH public key
authentication set up, preferably working with ssh-agent so you don't
have to type in your passphrase all the time.  I assume you've done
that in what follows, so if you've done something different you'll
need to change it appropriately.

Create a user called "hg" on the machine where the repository will
live.  I used the command

  sudo adduser --system --shell /bin/sh --group --disabled-password \
    --gecos "Mercural repository" hg

Issue these commands to become the hg user and set up the repository.
Use your own name in place of "myname".

   ssh-add -L >> /tmp/my-ssh-public-key
   sudo -u hg -s
   cd ~hg
   mkdir -p admin repos/hgadmin/keys/admin
   cd admin
   hg clone http://hg.opensource.lshift.net/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
   hg add
   hg commit
   cp ~/admin/hg-admin-tools/hgadmin-hgrc .hg/hgrc
   ../../admin/hg-admin-tools/refresh-auth
   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

You can now add other users by putting their keys in an appropriate
subdirectory of the "keys" directory, and control their access by
editing hg-ssh-access.conf.  Changes will take effect as soon as you
push them to the remote repository.

HG-SSH-ACCESS.CONF

Each line of hg-ssh-access.conf has the following syntax:

<rule> <keypattern> <repositorypattern>

The "rule" is either "init", "allow", or "deny".  "keypattern" is a
glob pattern matched against the name of the key used - for example,
in our initial setup "admin/myname" matches "admin/*".
"repositorypattern" is a pattern matched againt the repository name -
so "hgadmin" matches "*".  Only boring characters are allowed in
patterns and key and repository names - see the source for details.
Blank lines and lines that start with "#" are ignored.  The first rule
to match both the key and the repository applies: "deny" will deny all
matching requests, "allow" allows read/write access to existing
repositories, and "init" allows that and creation of new repositories.