diff -r 675474f5be32 -r 9f7ad3a71c90 doc/manual.docbook --- a/doc/manual.docbook Fri Dec 17 14:39:25 2010 +0000 +++ b/doc/manual.docbook Fri Dec 17 15:08:23 2010 +0000 @@ -4,7 +4,7 @@ <info> <title>Sharing Mercurial repositories with mercurial-server</title> <author><firstname>Paul</firstname><surname>Crowley</surname></author> - <copyright><year>2009</year><holder>Paul Crowley, LShift Ltd</holder></copyright> + <copyright><year>2008-2010</year><holder>Paul Crowley, LShift Ltd</holder></copyright> </info> <section> <title>About mercurial-server</title> @@ -420,14 +420,7 @@ </section> </section> <section> -<title>Logging</title> -<para> -Every successful access is logged in a file called -<filename>~hg/repos/<replaceable>repository</replaceable>/.hg/servelog</filename>. The log records the time as a -UTC ISO 8601 time, the operation ("push" or "pull"), the path to the key as -used in the access rules, and the hex changeset ID. -</para> -</section> +<title>In detail</title> <section> <title>How mercurial-server works</title> <para> @@ -459,6 +452,7 @@ automatically whenever a change is pushed to <filename class='directory'>hgadmin</filename>. </para> +</section> <section> <title>Security</title> <para> @@ -483,13 +477,31 @@ <para> 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 short, mercurial-server is a fairly -new program and may harbour bugs. Backups are essential! +correct; though the entire codebase is short, like all software mercurial-server may harbour bugs. Backups are essential! +</para> +</section> +<section> +<title>Logging</title> +<para> +Every successful access is logged in a file called +<filename>~hg/repos/<replaceable>repository</replaceable>/.hg/mercurial-server.log</filename>. This file is in YAML format for easy parsing, but if you don't like YAML, simply treat each line as a JSON data structure prepended with <code>- </code>. The log records the time as a +UTC ISO 8601 time, the operation ("push" or "pull"), the path to the key as +used in the access rules, the SSH connection information (including the source IP address), and the hex changeset IDs. </para> </section> +<section> +<title>Paths and configuration</title> +<para> +For security reasons, all mercurial-server code runs as the <systemitem +class="username">hg</systemitem> user. The first thing this code reads when it starts is <filename>~hg/.mercurial-server</filename>; if this file is absent or corrupt the code won't run. This file specifies all of the file paths that mercurial-server uses. In particular, it specifies that mercurial-server always uses <code>HGRCPATH = /etc/mercurial-server/remote-hgrc.d</code> for remote operations, overriding any system <code>HGRCPATH</code>. +</para> +<para> +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> </section> <section> -<title>License and thanks</title> +<title>License</title> <para> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free @@ -507,13 +519,17 @@ with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. </para> +</section> +<section> +<title>Thanks</title> <para> Thanks for reading this far. If you use mercurial-server, please tell me about it. </para> <para> -Paul Crowley, <email>paul@lshift.net</email>, 2009 +Paul Crowley, <email>paul@lshift.net</email>, 2010 </para> </section> +</section> </article>