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

HOW IT WORKS

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

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

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.

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.

   ssh-add -L >> /tmp/my-ssh-public-key

   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

   mkdir ~/hg

   cd ~/hg

   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

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.