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

These tools make it easier to provide a centralized repository host
with read/write access to many repositories for many developers.
Access control is managed with a special repository on the server
called "hgadmin"; pushes to this repository immediately change the
rules that are in effect.

Inside "hgadmin" is a "keys" directory containing the SSH keys of all
developers who have access, and a file "hg-ssh-access.conf" which
gives a set of rules defining who can do what to what.

HOW IT WORKS

All of the repositories controlled by these tools are owned by a
single user (the "hg" user in what follows), but many remote users can
act on them.  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 called "hgadmin".  A
hook in this repository re-runs "refresh-auth" on the most recent
version after every push.

Finally, a hook in an extension is run for each changeset that is
remotely committed, which uses the rules file to determine whether to
allow the changeset.

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 this repository host, 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.

Issue these commands to get the repository host started.  These are
written out here rather than encapsulated in a script because many of
them may need to be different for your local setup.  You will need
root access on the repository host, because you need to create a new
user.

   ssh -A repository-host
   ssh-add -L >> /tmp/my-ssh-public-key
   sudo adduser --system --shell /bin/sh --group --disabled-password \
     --gecos "Mercurial repositories" hg
   sudo -u hg -H -s
   cd
   mkdir -p admin repos/hgadmin/keys/admin .ssh
   cd admin
   hg clone http://hg.opensource.lshift.net/hg-admin-tools
   cp hg-admin-tools/hg-ssh-wrapper hg-admin-tools/remote-hgrc ~
   cd ../repos/hgadmin
   hg init .
   echo "init user=admin/*" > hg-ssh-access.conf
   cp /tmp/my-ssh-public-key keys/admin/myname
   hg add
   hg commit -m "initial commit"
   cp ~/admin/hg-admin-tools/hgadmin-hgrc .hg/hgrc
   ../../admin/hg-admin-tools/refresh-auth ./hg-ssh-wrapper
   exit
   exit

You are now the sole user able to change and create repositories on
this repository host.  To administer these controls (and test your
access), check out hgadmin:

   mkdir ~/hg
   cd ~/hg
   hg clone ssh://hg@repository-host/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 "ssh://hg@repository-host/hgadmin".

Users authorized to do so can now also create new repositories on this
host with "clone":

  hg clone . ssh://hg@repository-host/my-project-name

HG-SSH-ACCESS.CONF

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

<rule> <condition> <condition> ...

Rule is one of

init - allow any operation, including the creation of new repositories
write - allow reads and writes to this file in this repository
read - allow the repo to be read but reject matching writes
deny - deny all requests

A condition is a globpattern matched against a relative path, one of:

user=<globpattern> - user's key
repo=<globpattern> - repo (as the user supplies it)
file=<globpattern> - file in the repo
branch=<globpattern> - name of the branch

The first rule in the file which has all its conditions satisfied is
used to determine whether an action is allowed.

Paths cannot contain any special characters except "/"; glob patterns
cannot contain any special characters except "/" and "*".  "*" matches
zero or more characters not including "/" while "**" matches zero or
more characters including "/".

Blank lines and lines that start with "#" are ignored.

FILE CONDITIONS

The rules file is used to make four decisions:

- Whether to allow a repository to be created
- Whether to allow access to a repository
- Whether to allow a changeset on a particular branch at all
- Whether to allow a changeset to change a particular file

When the first two of these decisions are being made, nothing is known
about what files might be changed, and so all file conditions
automatically succeed for the purpose of such decisions.  This means
that doing tricky things with file conditions can have
counterintuitive consequences:

- You cannot limit read access to a subset of a repository with a
"read" rule and a file condition: any user who has access to a
repository can read all of it and its full history.  Such a rule can
only have the effect of masking a later "write" rule, as in this
example:

   read repo=specialrepo file=dontwritethis
   write repo=specialrepo

allows all users to read specialrepo, and to write to all files
*except* that any changeset which writes to "dontwritethis" will be
rejected.

- For similar reasons, don't give "init" rules file conditions.

- Don't try to deny write access to a particular file on a particular
branch - a developer can write to the file on another branch and then
merge it in.  Either deny all writes to the branch from that user, or
allow them to write to all the files they can write to on any branch.
In other words, something like this will have the intended effect

  write user=docs/* branch=docs file=docs/*

But something like this will not have the intended effect; it will
effectively allow these users to write to any file on any branch, by
writing it to "docs" first:

  write user=docs/* branch=docs
  write user=docs/* file=docs/*
  read user=docs/*

LOCKING YOURSELF OUT

If you find yourself "locked out" - that is, that you no longer have
the permissions needed in hgadmin - you can break back in again if
you're able to become the "hg" user on the repository host.  Once you
are that user, delete ~hg/.ssh/authorized_keys (to stop any user who
might have access but shouldn't from using the repository while you
fix things).  Then go into ~hg/repos/hgadmin, do an "hg update", edit
things to your satisfaction, and commit the change.  Finally, run
~/admin/hg-admin-tools/refresh-auth to regenerate
~hg/.ssh/authorized_keys. 

THANKS

Thanks for reading this far.  If you use hg-admin-tools, please tell
me about it.

Paul Crowley, 2008