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