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