+
−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.