# HG changeset patch
# User Paul Crowley <paul@lshift.net>
# Date 1317138535 -3600
# Node ID f06d9816272dd68a320d30debeb1b652302ae57e
# Parent  e8c4f88126c19c952a6a10505bf5d07b6129ac92
Documentation update
- make it clear that you have to have an existing repo to clone
- don't try to put the same key in different directories
- explain the .mercurial-server file.

diff -r e8c4f88126c1 -r f06d9816272d doc/manual.docbook
--- a/doc/manual.docbook	Wed Sep 14 13:11:25 2011 +0100
+++ b/doc/manual.docbook	Tue Sep 27 16:48:55 2011 +0100
@@ -4,7 +4,7 @@
 <info>
   <title>Sharing Mercurial repositories with mercurial-server</title>
   <author><firstname>Paul</firstname><surname>Crowley</surname></author>
-  <copyright><year>2008-2010</year><holder>Paul Crowley, LShift Ltd</holder></copyright>
+  <copyright><year>2008-2011</year><holder>Paul Crowley, LShift Ltd</holder></copyright>
 </info>
 <section>
 <title>About mercurial-server</title>
@@ -65,19 +65,24 @@
 <para>
 To store a repository on the server, clone it over.
 </para>
-<screen><computeroutput>jay@spoon:~$ </computeroutput><userinput>cd myproj</userinput>
+<screen><computeroutput>jay@spoon:~$ </computeroutput><userinput>hg init myproj</userinput>
+<computeroutput>jay@spoon:~$ </computeroutput><userinput>cd myproj</userinput>
+<computeroutput>jay@spoon:~/myproj$ </computeroutput><userinput>editor program.c</userinput> <lineannotation>...create project files here...</lineannotation>
+<computeroutput>jay@spoon:~/myproj$ </computeroutput><userinput>hg add</userinput>
+<computeroutput>adding program.c
+jay@spoon:~/myproj$ </computeroutput><userinput>hg commit -m "Initial checkin"</userinput>
 <computeroutput>jay@spoon:~/myproj$ </computeroutput><userinput>hg clone . ssh://hg@jeeves/jays/project</userinput>
 <computeroutput>searching for changes
 remote: adding changesets
 remote: adding manifests
 remote: adding file changes
-remote: added 119 changesets with 284 changes to 61 files
+remote: added 1 changesets with 1 changes to 1 files
 jay@spoon:~/myproj$ </computeroutput><userinput>hg pull ssh://hg@jeeves/jays/project</userinput>
 <computeroutput>pulling from ssh://hg@jeeves/jays/project
 searching for changes
 no changes found
-<computeroutput>jay@spoon:~/myproj$ </computeroutput><userinput>cd ..</userinput>
-jay@spoon:~$ </computeroutput></screen>
+jay@spoon:~/myproj$ </computeroutput><userinput>cd ..</userinput>
+<computeroutput>jay@spoon:~$ </computeroutput></screen>
 </section>
 <section>
 <title>Adding other users</title>
@@ -154,6 +159,13 @@
 class='directory'>widget</filename> repository as soon as we add, commit, and push these files.
 </para>
 <para>
+Placing the same key in multiple directories will <emphasis>not</emphasis>
+grant that user multiple powers.  One of the locations will be used for
+all permission checks, while any others will be ignored.  Instead, put each
+key under the keys directory only once, and use
+<filename>access.conf</filename> to give permissions to the key.
+</para>
+<para>
 Each line of <filename>access.conf</filename> has the following syntax:
 </para>
 <programlisting><replaceable>rule</replaceable> <replaceable>condition</replaceable> <replaceable>condition...</replaceable>
@@ -499,6 +511,81 @@
 By creating such a file with suitable entries, you can run mercurial-server as a user other than <systemitem
 class="username">hg</systemitem>, or install it without root privileges; however I strongly recommend that if you need to do this, you use a user account that is used for no other purpose, and take the time to thoroughly understand how mercurial-server works before you attempt it.
 </para>
+<para>
+At install time the following <filename>~hg/.mercurial-server</filename> file is used:
+</para>
+<programlisting># WARNING: a .mercurial-server file in your home directory means
+# that refresh-auth can and will trash your ~/.ssh/authorized_keys file.
+
+[paths]
+repos = ~/repos
+authorized_keys = ~/.ssh/authorized_keys
+keys = /etc/mercurial-server/keys:~/repos/hgadmin/keys
+access = /etc/mercurial-server/access.conf:~/repos/hgadmin/access.conf
+
+[exceptions]
+# Allow the creation of mq repositories by default
+allowdots = .hg/patches
+
+[env]
+# Use a different hgrc for remote pulls - this way you can set
+# up access.py for everything at once without affecting local operations
+
+HGRCPATH = /etc/mercurial-server/remote-hgrc.d
+</programlisting>
+<para>
+The meaning of the entries are:
+</para>
+<itemizedlist>
+<listitem>
+<para><literal>[paths]</literal></para>
+<itemizedlist>
+<listitem>
+<para><literal>repos</literal>: directory under which all repositories are
+found. No remote user can reference any repo not under this directory.
+Here and throughout this section, where a path begins with
+<literal>~/</literal> the home directory is substituted - ie the
+directory in which the <filename>.mercurial-server</filename> file
+was found.</para>
+</listitem>
+<listitem>
+<para><literal>authorized_keys</literal>: this is the file that will be rewritten
+by refresh-auth, or whenever a checkin to the <literal>hgadmin</literal> repository is pushed.</para>
+</listitem>
+<listitem>
+<para><literal>keys</literal>: directories to scan for keys when rewriting
+<filename>authorized_keys</filename>.</para>
+</listitem>
+<listitem>
+<para><literal>access</literal>: files to read to determine the access rules.
+The files are effectively concatenated together in the order given.</para>
+</listitem>
+</itemizedlist>
+</listitem>
+<listitem>
+<para><literal>[exceptions]</literal></para>
+<itemizedlist>
+<listitem>
+<para><literal>allowdots</literal>: paths to allow even though they
+begin with dots.  Dots at the start of a pathname component are
+disallowed unless they exactly match one of the tails given in this
+colon-separated list.  The given exception allows MQ repositories
+to be pushed.</para>
+</listitem>
+</itemizedlist>
+</listitem>
+<listitem>
+<para><literal>[env]</literal>: all entries in here are added to the Unix environment
+when users connect.  The keys are converted to all-upper-case. </para>
+<itemizedlist>
+<listitem>
+<para><literal>HGRCPATH</literal>: set the path that Mercurial uses to search for
+configuration files.  At install time config files are placed on this path
+which set up access control and logging.</para>
+</listitem>
+</itemizedlist>
+</listitem>
+</itemizedlist>
 </section>
 <section>
 <title>License</title>
@@ -527,7 +614,7 @@
 it.
 </para>
 <para>
-Paul Crowley, <email>paul@lshift.net</email>, 2010
+Paul Crowley, <email>paul@lshift.net</email>, 2011
 </para>
 </section>
 </section>