1.1 --- a/README Tue Apr 22 13:51:19 2008 +0100
1.2 +++ b/README Thu Apr 24 08:27:30 2008 +0100
1.3 @@ -20,8 +20,6 @@
1.4 developers who have access, and a file "hg-ssh-access.conf" which
1.5 gives a set of rules defining who can do what to what.
1.6
1.7 -HOW IT WORKS
1.8 -
1.9 All of the repositories controlled by these tools are owned by a
1.10 single user (the "hg" user in what follows), but many remote users can
1.11 act on them. We don't use file permissions to achieve that - instead,
1.12 @@ -29,75 +27,23 @@
1.13 host using ssh, using ssh URLs of the form
1.14 "ssh://hg@repository-host/repository-name". A restricted shell
1.15 prevents them from using this access for unauthorized purposes.
1.16 +Developers are authenticated only using SSH keys; no other form of
1.17 +authentication is supported.
1.18
1.19 -Developers are authenticated only using SSH keys; no other form of
1.20 -authentication is supported. When a developer attempts to connect to
1.21 -a repository via ssh, the SSH daemon searches for a match for that
1.22 -user's key in ~hg/.ssh/authorized_keys. If the developer is
1.23 -authorised to connect to the repository they will have an entry in
1.24 -this file. The entry includes a "command" prefix which specifies that
1.25 -the restricted shell should be used; this shell is passed an argument
1.26 -identifying the developer. The shell parses the command the developer
1.27 -is trying to execute, and consults a rules file to see if that
1.28 -developer is allowed to perform that action on that repository. The
1.29 -bulk of the work of the restricted shell is done by the Python program
1.30 -"hg-ssh", but the shell script "hg-ssh-wrapper" sets up some
1.31 -configuration so that you can change it to suit your local
1.32 -installation.
1.33 +QUICK START
1.34
1.35 -The file ~hg/.ssh/authorized_keys is generated by "refresh-auth",
1.36 -which recurses through a directory of files containing SSH keys and
1.37 -generates an entry in authorized_keys for each one, using the name of
1.38 -the key file as the identifier for the developer. These keys will
1.39 -live in the "keys" subdirectory of a repository called "hgadmin". A
1.40 -hook in this repository re-runs "refresh-auth" on the most recent
1.41 -version after every push.
1.42 +You will need
1.43
1.44 -Finally, a hook in an extension is run for each changeset that is
1.45 -remotely committed, which uses the rules file to determine whether to
1.46 -allow the changeset.
1.47 +- "sudo" installed
1.48 +- "sudo" root privileges
1.49 +- an ssh-key set up with ssh-agent
1.50
1.51 -GETTING STARTED
1.52 -
1.53 -This is only one setup - it can be tweaked in many ways, and is as
1.54 -specific as it is only in the interests of brevity.
1.55 -
1.56 -You, and all users of this repository host, will need SSH public key
1.57 -authentication set up, preferably working with ssh-agent so you don't
1.58 -have to type in your passphrase all the time. I assume you've done
1.59 -that in what follows, so if you've done something different you'll
1.60 -need to change it appropriately.
1.61 -
1.62 -Issue these commands to get the repository host started. These are
1.63 -written out here rather than encapsulated in a script because many of
1.64 -them may need to be different for your local setup. You will need
1.65 -root access on the repository host, because you need to create a new
1.66 -user.
1.67 -
1.68 - ssh -A repository-host
1.69 - ssh-add -L >> /tmp/my-ssh-public-key
1.70 - sudo adduser --system --shell /bin/sh --group --disabled-password \
1.71 - --gecos "Mercurial repositories" hg
1.72 - sudo -u hg -H -s
1.73 - cd
1.74 - mkdir -p admin repos/hgadmin/keys/admin .ssh
1.75 - cd admin
1.76 - hg clone http://hg.opensource.lshift.net/hg-admin-tools
1.77 - cp hg-admin-tools/hg-ssh-wrapper hg-admin-tools/remote-hgrc ~
1.78 - cd ../repos/hgadmin
1.79 - hg init .
1.80 - echo "init user=admin/*" > hg-ssh-access.conf
1.81 - cp /tmp/my-ssh-public-key keys/admin/myname
1.82 - hg add
1.83 - hg commit -m "initial commit"
1.84 - cp ~/admin/hg-admin-tools/hgadmin-hgrc .hg/hgrc
1.85 - ../../admin/hg-admin-tools/refresh-auth ./hg-ssh-wrapper
1.86 - exit
1.87 - exit
1.88 -
1.89 -You are now the sole user able to change and create repositories on
1.90 -this repository host. To administer these controls (and test your
1.91 -access), check out hgadmin:
1.92 +Ensure there is no user called "hg" on the repository host, and run
1.93 +"./install" to create them. You are now the sole user able to change
1.94 +and create repositories on this repository host. To give access to
1.95 +others, check out hgadmin - as yourself, and on whichever host is most
1.96 +convenient, but using the ssh-key with which you set up the
1.97 +repository:
1.98
1.99 mkdir ~/hg
1.100 cd ~/hg
1.101 @@ -190,6 +136,33 @@
1.102 write user=docs/* file=docs/*
1.103 read user=docs/*
1.104
1.105 +HOW IT WORKS
1.106 +
1.107 +When a developer attempts to connect to a repository via ssh, the SSH
1.108 +daemon searches for a match for that user's key in
1.109 +~hg/.ssh/authorized_keys. If the developer is authorised to connect
1.110 +to the repository they will have an entry in this file. The entry
1.111 +includes a "command" prefix which specifies that the restricted shell
1.112 +should be used; this shell is passed an argument identifying the
1.113 +developer. The shell parses the command the developer is trying to
1.114 +execute, and consults a rules file to see if that developer is allowed
1.115 +to perform that action on that repository. The bulk of the work of
1.116 +the restricted shell is done by the Python program "hg-ssh", but the
1.117 +shell script "hg-ssh-wrapper" sets up some configuration so that you
1.118 +can change it to suit your local installation.
1.119 +
1.120 +The file ~hg/.ssh/authorized_keys is generated by "refresh-auth",
1.121 +which recurses through a directory of files containing SSH keys and
1.122 +generates an entry in authorized_keys for each one, using the name of
1.123 +the key file as the identifier for the developer. These keys will
1.124 +live in the "keys" subdirectory of a repository called "hgadmin". A
1.125 +hook in this repository re-runs "refresh-auth" on the most recent
1.126 +version after every push.
1.127 +
1.128 +Finally, a hook in an extension is run for each changeset that is
1.129 +remotely committed, which uses the rules file to determine whether to
1.130 +allow the changeset.
1.131 +
1.132 LOCKING YOURSELF OUT
1.133
1.134 If you find yourself "locked out" - that is, that you no longer have