doc/manual.docbook
changeset 263 9f7ad3a71c90
parent 252 75acaf1b1216
child 311 3cbde66305e4
equal deleted inserted replaced
262:675474f5be32 263:9f7ad3a71c90
     2 <article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en"
     2 <article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en"
     3   xmlns:xlink="http://www.w3.org/1999/xlink">
     3   xmlns:xlink="http://www.w3.org/1999/xlink">
     4 <info>
     4 <info>
     5   <title>Sharing Mercurial repositories with mercurial-server</title>
     5   <title>Sharing Mercurial repositories with mercurial-server</title>
     6   <author><firstname>Paul</firstname><surname>Crowley</surname></author>
     6   <author><firstname>Paul</firstname><surname>Crowley</surname></author>
     7   <copyright><year>2009</year><holder>Paul Crowley, LShift Ltd</holder></copyright>
     7   <copyright><year>2008-2010</year><holder>Paul Crowley, LShift Ltd</holder></copyright>
     8 </info>
     8 </info>
     9 <section>
     9 <section>
    10 <title>About mercurial-server</title>
    10 <title>About mercurial-server</title>
    11 <para>
    11 <para>
    12 Home page: <link xlink:href="http://www.lshift.net/mercurial-server.html"/>
    12 Home page: <link xlink:href="http://www.lshift.net/mercurial-server.html"/>
   418 </listitem>
   418 </listitem>
   419 </itemizedlist>
   419 </itemizedlist>
   420 </section>
   420 </section>
   421 </section>
   421 </section>
   422 <section>
   422 <section>
   423 <title>Logging</title>
   423 <title>In detail</title>
   424 <para>
       
   425 Every successful access is logged in a file called
       
   426 <filename>~hg/repos/<replaceable>repository</replaceable>/.hg/servelog</filename>. The log records the time as a
       
   427 UTC ISO 8601 time, the operation ("push" or "pull"), the path to the key as
       
   428 used in the access rules, and the hex changeset ID.
       
   429 </para>
       
   430 </section>
       
   431 <section>
   424 <section>
   432 <title>How mercurial-server works</title>
   425 <title>How mercurial-server works</title>
   433 <para>
   426 <para>
   434 All of the repositories controlled by mercurial-server are owned by a
   427 All of the repositories controlled by mercurial-server are owned by a
   435 single user, the <systemitem
   428 single user, the <systemitem
   457 class='directory'>hgadmin</filename> repository, creating an entry in
   450 class='directory'>hgadmin</filename> repository, creating an entry in
   458 <filename>~hg/.ssh/authorized_keys</filename> for each one. This is redone
   451 <filename>~hg/.ssh/authorized_keys</filename> for each one. This is redone
   459 automatically whenever a change is pushed to <filename
   452 automatically whenever a change is pushed to <filename
   460 class='directory'>hgadmin</filename>.
   453 class='directory'>hgadmin</filename>.
   461 </para>
   454 </para>
       
   455 </section>
   462 <section>
   456 <section>
   463 <title>Security</title>
   457 <title>Security</title>
   464 <para>
   458 <para>
   465 mercurial-server relies entirely on <command>sshd</command> to grant access to remote users.
   459 mercurial-server relies entirely on <command>sshd</command> to grant access to remote users.
   466 As a result, it runs no daemons, installs no setuid programs, and no part
   460 As a result, it runs no daemons, installs no setuid programs, and no part
   481 operation.
   475 operation.
   482 </para>
   476 </para>
   483 <para>
   477 <para>
   484 However, while the first paragraph holds no matter what bugs
   478 However, while the first paragraph holds no matter what bugs
   485 mercurial-server contains, the second depends on the relevant code being
   479 mercurial-server contains, the second depends on the relevant code being
   486 correct; though the entire codebase is short, mercurial-server is a fairly
   480 correct; though the entire codebase is short, like all software mercurial-server may harbour bugs. Backups are essential!
   487 new program and may harbour bugs. Backups are essential!
   481 </para>
   488 </para>
   482 </section>
   489 </section>
   483 <section>
   490 </section>
   484 <title>Logging</title>
   491 <section>
   485 <para>
   492 <title>License and thanks</title>
   486 Every successful access is logged in a file called
       
   487 <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
       
   488 UTC ISO 8601 time, the operation ("push" or "pull"), the path to the key as
       
   489 used in the access rules, the SSH connection information (including the source IP address), and the hex changeset IDs.
       
   490 </para>
       
   491 </section>
       
   492 <section>
       
   493 <title>Paths and configuration</title>
       
   494 <para>
       
   495 For security reasons, all mercurial-server code runs as the <systemitem
       
   496 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>.
       
   497 </para>
       
   498 <para>
       
   499 By creating such a file with suitable entries, you can run mercurial-server as a user other than <systemitem
       
   500 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.
       
   501 </para>
       
   502 </section>
       
   503 <section>
       
   504 <title>License</title>
   493 <para>
   505 <para>
   494 This program is free software; you can redistribute it and/or modify it
   506 This program is free software; you can redistribute it and/or modify it
   495 under the terms of the GNU General Public License as published by the Free
   507 under the terms of the GNU General Public License as published by the Free
   496 Software Foundation; either version 2 of the License, or (at your option)
   508 Software Foundation; either version 2 of the License, or (at your option)
   497 any later version.
   509 any later version.
   505 <para>
   517 <para>
   506 You should have received a copy of the GNU General Public License along
   518 You should have received a copy of the GNU General Public License along
   507 with this program; if not, write to the Free Software Foundation, Inc., 51
   519 with this program; if not, write to the Free Software Foundation, Inc., 51
   508 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
   520 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
   509 </para>
   521 </para>
       
   522 </section>
       
   523 <section>
       
   524 <title>Thanks</title>
   510 <para>
   525 <para>
   511 Thanks for reading this far. If you use mercurial-server, please tell me about
   526 Thanks for reading this far. If you use mercurial-server, please tell me about
   512 it.
   527 it.
   513 </para>
   528 </para>
   514 <para>
   529 <para>
   515 Paul Crowley, <email>paul@lshift.net</email>, 2009
   530 Paul Crowley, <email>paul@lshift.net</email>, 2010
   516 </para>
   531 </para>
       
   532 </section>
   517 </section>
   533 </section>
   518 </article>
   534 </article>
   519 
   535