--- a/README Fri Feb 20 15:33:49 2009 +0000
+++ b/README Fri Feb 20 15:41:44 2009 +0000
@@ -83,6 +83,11 @@
repositories. As always, when you change "/etc/mercurial-server/keys" you need
to re-run "/etc/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
@@ -134,13 +139,13 @@
file=<globpattern> - file in the repo
branch=<globpattern> - name of the branch
-The first rule in the file which has all its conditions satisfied is
-used to determine whether an action is allowed.
+The first rule in the file which has all its conditions satisfied is used to
+determine whether an action is allowed.
-Paths cannot contain any special characters except "/"; glob patterns
-cannot contain any special characters except "/" and "*". "*" matches
-zero or more characters not including "/" while "**" matches zero or
-more characters including "/".
+Paths cannot contain any special characters except "/"; glob patterns cannot
+contain any special characters except "/" and "*". "*" matches zero or more
+characters not including "/" while "**" matches zero or more characters
+including "/".
Blank lines and lines that start with "#" are ignored.
@@ -159,38 +164,35 @@
- Whether to allow a changeset on a particular branch at all
- Whether to allow a changeset to change a particular file
-When the first two of these decisions are being made, nothing is known
-about what files might be changed, and so all file conditions
-automatically succeed for the purpose of such decisions. This means
-that doing tricky things with file conditions can have
-counterintuitive consequences:
+When the first two of these decisions are being made, nothing is known about
+what files might be changed, and so all file conditions automatically succeed
+for the purpose of such decisions. This means that doing tricky things with file
+conditions can have counterintuitive consequences:
-- You cannot limit read access to a subset of a repository with a
-"read" rule and a file condition: any user who has access to a
-repository can read all of it and its full history. Such a rule can
-only have the effect of masking a later "write" rule, as in this
-example:
+- You cannot limit read access to a subset of a repository with a "read" rule
+and a file condition: any user who has access to a repository can read all of it
+and its full history. Such a rule can only have the effect of masking a later
+"write" rule, as in this example:
read repo=specialrepo file=dontwritethis
write repo=specialrepo
-allows all users to read specialrepo, and to write to all files
-*except* that any changeset which writes to "dontwritethis" will be
-rejected.
+allows all users to read specialrepo, and to write to all files *except* that
+any changeset which writes to "dontwritethis" will be rejected.
- For similar reasons, don't give "init" rules file conditions.
-- Don't try to deny write access to a particular file on a particular
-branch - a developer can write to the file on another branch and then
-merge it in. Either deny all writes to the branch from that user, or
-allow them to write to all the files they can write to on any branch.
-In other words, something like this will have the intended effect
+- Don't try to deny write access to a particular file on a particular branch - a
+developer can write to the file on another branch and then merge it in. Either
+deny all writes to the branch from that user, or allow them to write to all the
+files they can write to on any branch. In other words, something like this will
+have the intended effect:
write user=docs/* branch=docs file=docs/*
-But something like this will not have the intended effect; it will
-effectively allow these users to write to any file on any branch, by
-writing it to "docs" first:
+But something like this will not have the intended effect; it will effectively
+allow these users to write to any file on any branch, by writing it to "docs"
+first:
write user=docs/* branch=docs
write user=docs/* file=docs/*
@@ -198,30 +200,28 @@
HOW IT WORKS
-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.
+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
+The file ~hg/.ssh/authorized_keys is generated by "refresh-auth", which recurses
+through two directories 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
+"/etc/mercurial-server" and 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.
-Finally, a hook in an extension is run for each changeset that is
-remotely committed, which uses the rules file to determine whether to
-allow the changeset.
+Finally, hook in an extension is run for each changeset that is remotely
+committed, which uses the rules file to determine whether to allow the
+changeset.
LOCKED OUT?
@@ -235,8 +235,8 @@
THANKS
-Thanks for reading this far. If you use mercurial-server, please tell
-me about it.
+Thanks for reading this far. If you use mercurial-server, please tell me about
+it.
Paul Crowley, 2009