--- a/README Sat Mar 07 08:58:30 2009 +0000
+++ b/README Sat Mar 07 09:31:06 2009 +0000
@@ -116,158 +116,35 @@
hg clone ssh://hg@repository-server/hgadmin
cd hgadmin
- mkdir keys/user/thatuser
- cp /tmp/theirkey keys/user/thatuser/theirhostname
+ 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/keys", and changes to it take effect immediately. Only
-"keys/root" users can act on "hgadmin" - those with keys in "keys/users" are
-locked out. Multiple admins can use Mercurial's version control to cooperate
-on controlling access to the repository server in a natural way. You can also
-add "root" users by putting their key in the "keys/root" directory in just the
-same way - these users will now be able to control hgadmin and create new
-repositories just as you can.
+"/etc/mercurial-server", and changes to it take effect immediately -
+"refresh-auth" is run after every push.
-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
+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 - remember,
-"/etc/mercurial-server/access.conf" takes precedence over the "access.conf" in
-"hgadmin".
-
-ACCESS.CONF
-
-Out of the box, there are just two kinds of users: the ones with keys in
-"keys/root" and those in "keys/users". However, you can change this by editing
-"access.conf". There are two "access.conf" files, one in
-"/etc/mercurial-server" and one in "hgadmin"; the two are simply concatenated
-before being read.
-
-Each line of access.conf has the following syntax:
-
-<rule> <condition> <condition> ...
-
-Rule is one of
-
-init - allow any operation, including the creation of new repositories
-write - allow reads and writes to this file in this repository
-read - allow the repo to be read but reject matching writes
-deny - deny all requests
-
-A condition is a globpattern matched against a relative path, one of:
-
-user=<globpattern> - user's key
-repo=<globpattern> - repo (as the user supplies it)
-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.
-
-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.
-
-FILE CONDITIONS
-
-mercurial-server supports file and branch conditions, which restrict an
-operation depending on what files it modifies and what branch the work is on.
-However, the way these conditions work is subtle and can be counterintuitive -
-if you want to keep things simple, stick to user and repo conditions, and then
-things are likely to work the way you would expect.
-
-The rules file is used to make four decisions:
-
-- Whether to allow a repository to be created
-- Whether to allow access to a repository
-- 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:
-
-- 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:
+the entries you removed from these files.
- 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.
-
-- 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:
-
- 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:
-
- write user=docs/* branch=docs
- write user=docs/* file=docs/*
- read user=docs/*
-
-HOW IT WORKS
+MORE INFORMATION
-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 "/usr/local/lib/mercurial-server/hg-ssh" 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 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, 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.
-
-SECURITY OF MERCURIAL-SERVER
-
-mercurial-server relies entirely on sshd to grant access to remote users. As a
-result, it runs no daemons, installs no setuid programs, and no part of it
-runs as root except the install process: all programs run as the user hg. And
-any attack on mercurial-server can only be started if the Bad Guys already
-have a public key in ~hg/.ssh/authorized_keys, otherwise sshd will bar the
-way. No matter what command the user tries to run on the remote system via
-ssh, mercurial-server is run.
-
-It parses the command line the user asked for, and interprets and runs the
-corresponding hg operation itself if access is allowed, so users can only read
-and add to history within repositories; they cannot run any other hg command.
-In addition, every push and pull is logged with a datestamp, changeset ID and
-the key that performed the operation.
-
-However, while the first paragraph holds no matter what bugs mercurial-server
-contains, the second depends on the relevant code being correct; though the
-entire codebase is currently only about twice as long as this README,
-mercurial-server is a fairly new program and may harbour bugs. Backups are
-essential!
+For more on how to use mercurial-server and configure access, see the files in
+the doc directory.
THANKS