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 |