--- a/README Thu Oct 15 12:28:08 2009 +0100
+++ b/README Thu Oct 15 12:47:39 2009 +0100
@@ -1,8 +1,8 @@
mercurial-server
-mercurial-server makes a group of repositories available to the developers
-you choose, identified by ssh keys, with easy key and access management
-based on hg.
+mercurial-server gives your developers remote read/write access to
+centralized Mercurial repositories using SSH public key authentication; it
+provides convenient and fine-grained key management and access control.
http://www.lshift.net/mercurial-server.html
@@ -22,134 +22,7 @@
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-SUMMARY
-
-mercurial-server makes a group of repositories available to the developers
-you choose, identified by ssh keys, with easy key and access management
-based on hg.
-
-All of the repositories controlled by mercurial-server are owned by a
-single user (the "hg" user in what follows), but many remote users can act
-on them, and different users can have different permissions. 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.
-
-To give a user access to the repository, place their key in an
-appropriately-named subdirectory of "/etc/mercurial-server/keys" and run
-"/usr/local/share/mercurial-server/refresh-auth". You can then control what
-access they have to what repositories by editing the control file
-"/etc/mercurial-server/access.conf", which can match the names of these keys
-against a glob pattern.
-
-For convenient remote control of access, you can instead (if you have the
-privileges) make changes to a special repository called "hgadmin", which
-contains its own "access.conf" file and "keys" directory. Changes pushed to
-this repository take effect immediately. The two "access.conf" files are
-concatenated, and the keys directories merged.
-
-QUICK START
-
-You and all developers using this system will need an SSH public key, and
-will almost certainly want to be running ssh-agent (or its equivalent, eg
-Pageant under Windows). If you're not familiar with ssh-agent, you should
-learn about that before using this.
-
-In what follows, certain operations (eg installing mercurial-server itself)
-have to be done on the repository server (which we call "repository-host"),
-but any operation that involves checking in or out of Mercurial can be done
-wherever is most convenient to you; the most usual arrangment would be that
-you'd do these things at the machine you sit at, and on which you run
-ssh-agent, which is what authenticates you when you talk to the repository
-server.
-
-Ensure there is no user called "hg" on the repository host, and run
-"./install". This installs the mercurial-server files and control files, and
-creates and sets up the "hg" user.
-
-Place your SSH public key in the directory "/etc/mercurial-server/keys/root".
-I suggest creating yourself a directory and naming the key after your hostname
-(ie the file is called something like
-"/etc/mercurial-server/keys/root/yourname/yourhostname") so that you can
-easily manage users who have a different key on each host they use. Then run
-"/usr/local/share/mercurial-server/refresh-auth".
-
-The repository is now ready to use, and you are now the sole user able to
-change and create repositories on this repository host.
-
-CREATING REPOSITORIES
-
-To create a new repository, you clone a local repository onto the remote
-server. So if you want a new empty repository called "myproject", you can do
-(as yourself):
-
- hg init myproject
- hg clone myproject ssh://hg@repository-host/myproject
-
-ADDING OTHER USERS
-
-Because your key is in the "keys/root" subdirectory, you have the equivalent
-of "root privileges" over mercurial-server (not the whole computer, just
-mercurial-server). You can add other root users by putting their keys next to
-yours, or you can make less privileged users by putting their keys in the
-"keys/users" subdirectory - these users will be able to read and write to any
-repository (except one - see below) but will not be able to create new
-repositories. As always, when you change "/etc/mercurial-server/keys" you need
-to re-run "/usr/local/share/mercurial-server/refresh-auth".
-
-LOGGING
-
-Every push and pull is logged with the key used: see the file .hg/serve-log in
-each repository.
-
-USING HGADMIN
-
-It can be inconvenient to log on to the repository server, become root, copy
-keys around, and run "refresh-auth" every time you want to change user
-privileges. This is where mercurial-server shines :-) Suppose you have another
-user's SSH public key in the file "/tmp/theirkey" (on the machine you sit at,
-not necessarily the repository server) and you want to give them user-level
-access to the repository server. Run these commands:
-
- hg clone ssh://hg@repository-server/hgadmin
- cd hgadmin
- mkdir keys/users/thatuser
- cp /tmp/theirkey keys/users/thatuser/theirhostname
- hg add
- hg commit -m "Added key for thatuser"
- hg push
-
-In other words, hgadmin is a version controlled version of
-"/etc/mercurial-server", and changes to it take effect immediately -
-"refresh-auth" is run after every push.
-
-With the default access.conf file (see doc/configuring-access for more
-details) only users in "keys/root" can act on "hgadmin" - those with keys in
-"keys/users" cannot even read this repository. So multiple admins can use
-Mercurial's version control to cooperate on controlling access to the
-repository server in a natural way.
-
-You can also create an "access.conf" file in hgadmin, and this is appended to
-/etc/mercurial-server/access.conf whenever this is read - in other words,
-rules in the latter take precedence over those in the former. So once you're
-working with "hgadmin", it can be convenient to remove all the keys in
-"/etc/mercurial-server/keys" and all the entries in
-"/etc/mercurial-server/access.conf" and use hgadmin to control everything. If
-you find yourself locked out, you can get back in again by restoring some of
-the entries you removed from these files.
-
-MORE INFORMATION
-
-For more on how to use mercurial-server and configure access, see the files in
-the doc directory.
-
-THANKS
-
-Thanks for reading this far. If you use mercurial-server, please tell me about
-it.
+For details on how to install and use mercurial-server, see doc/manual.docbook.
Paul Crowley, paul@lshift.net, 2009