diff -r f3c73c9fc0ff -r 834426fcbada README --- a/README Thu Apr 17 16:50:17 2008 +0100 +++ b/README Thu Apr 17 17:34:07 2008 +0100 @@ -1,14 +1,56 @@ hg-admin-tools version 0.1 A set of tools for managing authorization and access control for -ssh-based Hg repositories +ssh-based Mercurial repositories -Paul Crowley, paul@lshift.net, 2008-04-15 +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. -INSTRUCTIONS FOR USE: +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. + +INSTRUCTIONS FOR USE 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. @@ -25,46 +67,31 @@ sudo adduser --system --shell /bin/sh --group --disabled-password \ --gecos "Mercural repository" hg -Now create a basic access control setup. - - cd - mkdir hg - cd hg - hg clone ssh://hg.opensource.lshift.net/hg-admin-tools hg-admin-tools - mkdir -p hgadmin/keys/admin - cd hgadmin - ssh-add -L > keys/admin/myname - echo "init admin/* *" > hg-ssh-access.conf - hg init . - hg add - hg commit -m "Initial configuration" - -You can use whatever you want in place of "myname" and indeed "admin". -The files in ~/hg must be readable by the hg user. Issue these -commands to become the hg user and set up the repository +Issue these commands to become the hg user and set up the repository. +Use your own name in place of "myname". sudo -u hg -s cd ~hg - mkdir admin repos - hg clone ~/hg/hg-admin-tools admin/hg-admin-tools - hg clone ~/hg/hgadmin repos/hgadmin - cp admin/hg-admin-tools/hgadmin-hgrc repos/hgadmin/.hg/hgrc - cp admin/hg-admin-tools/hg-ssh-wrapper hg-ssh-wrapper - cd repos/hgadmin + mkdir -p admin repos/hgadmin/keys/admin + cd admin + tar xvzf /tmp/hg-admin-tools.tar.gz + mv hg-admin-tools* 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 + cp ~/admin/hg-admin-tools/hgadmin-hgrc .hg/hgrc ../../admin/hg-admin-tools/refresh-auth - exit + exit -You should now have SSH access to this repository and full control, -which you can test like so: +You should now have SSH access to this repository and full control. +To administer these controls (and test your access), check out hgadmin: - cd ~/hg/hgadmin - echo "[paths]" >> .hg/hgrc - echo "default = ssh://hg@localhost/hgadmin" >> .hg/hgrc - hg pull - hg push - -These attempts to push and pull should report no new changes but -otherwise work. + 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 @@ -83,4 +110,3 @@ patterns and key and repository names - see the source for details. Blank lines and lines that start with "#" are ignored. -