# HG changeset patch
# User Paul Crowley <paul@lshift.net>
# Date 1255602218 -3600
# Node ID f4688940fe15e288d849cba50cc67b7948388888
# Parent  5758cf47ff43c9a99ef45cc88d294e5aa0c87cb6
Improvements to access.conf documentation

diff -r 5758cf47ff43 -r f4688940fe15 doc/manual.docbook
--- a/doc/manual.docbook	Thu Oct 15 11:05:14 2009 +0100
+++ b/doc/manual.docbook	Thu Oct 15 11:23:38 2009 +0100
@@ -195,21 +195,75 @@
 <para>
 "*" only matches one directory level, where "**" matches as many as you
 want. More precisely, "*" matches zero or more characters not including "/"
-while "**" matches zero or more characters including "/".
+while "**" matches zero or more characters including "/". So
+<code>projects/*</code> matches <filename
+class='directory'>projects/foo</filename> but not <filename
+class='directory'>projects/foo/bar</filename>, while
+<code>projects/**</code> matches both.
 </para>
 <para>
-When considering a request, mercurial-server steps through all the rules in <filename>/etc/mercurial-server/access.conf</filename> and then all the rules in <filename>access.conf</filename> in <literal>hgadmin</literal> looking for a rule which matches on every condition.  If it does not find such a rule, it denies the request; otherwise it checks whether the rule grants sufficient privilege to allow it.
+When considering a request, mercurial-server steps through all the rules in
+<filename>/etc/mercurial-server/access.conf</filename> and then all the
+rules in <filename>access.conf</filename> in <literal>hgadmin</literal>
+looking for a rule which matches on every condition. The first match
+determines whether the request will be allowed; if there is no match in
+either file, the request will be denied.
 </para>
 <para>
-By default, <filename>/etc/mercurial-server/access.conf</filename> has the following rules:
+By default, <filename>/etc/mercurial-server/access.conf</filename> has the
+following rules:
 </para>
 <programlisting>init user=root/**
 deny repo=hgadmin
 write user=users/**
 </programlisting>
 <para>
-These rules ensure that root users can do any operation on any repository, that no other users can access the <literal>hgadmin</literal> repository, and that those with keys in <filename class='directory'>keys/users</filename> can read or write to any repository but not create repositories.
+These rules ensure that root users can do any operation on any repository,
+that no other users can access the <literal>hgadmin</literal> repository,
+and that those with keys in <filename
+class='directory'>keys/users</filename> can read or write to any repository
+but not create repositories. If these are the only rules in effect, they
+have the following consequences:
 </para>
+<itemizedlist>
+<listitem>
+Any request from a user with a key under <filename
+class='directory'>keys/root</filename> will match the first rule; since
+this rule is <literal>init</literal> the request will always be allowed.
+</listitem>
+<listitem>
+Any request to access the <literal>hgadmin</literal> by any other user will
+not match the first rule, but will match the second rule, and so will be
+denied.
+</listitem>
+<listitem>
+Any request to create a repository from a user with a key in <filename
+class='directory'>keys/users</filename> will not match the first or second
+rules, but will match the third rule. This is a <literal>write</literal>
+rule, which doesn't grant the privilege to create repositories, so the
+request will be denied.
+</listitem>
+<listitem>
+Any request to access an existing repository from a user with a key in
+<filename class='directory'>keys/users</filename> will not match the first
+or second rules, but will match the third rule, which grants
+<literal>write</literal> privilege, so the request will be allowed.
+</listitem>
+<listitem>
+Any request from any user whose key is in neither <filename
+class='directory'>keys/root</filename> nor <filename
+class='directory'>keys/users</filename> will not match any rule and so will
+be denied. Unless it matches the second rule, in which case it will still
+be denied.  Changes to the <filename>access.conf</filename> in <literal>hgadmin</literal> will change that, as the example at the start of this section shows.
+</listitem>
+<listitem>
+Any request from a user whose key not under the <filename
+class='directory'>keys</filename> directory at all will always be denied,
+no matter what rules are in effect; because of the way SSH authentication
+works, they will be prompted to enter a password, but no password will
+work. This can't be changed.
+</listitem>
+</itemizedlist>
 </section>
 <section>
 <title>/etc/mercurial-server and hgadmin</title>