doc/manual.docbook
changeset 345 f06d9816272d
parent 311 3cbde66305e4
child 358 924bf9d4dbc0
equal deleted inserted replaced
344:e8c4f88126c1 345:f06d9816272d
     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>2008-2010</year><holder>Paul Crowley, LShift Ltd</holder></copyright>
     7   <copyright><year>2008-2011</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"/>
    63 <section>
    63 <section>
    64 <title>Creating repositories</title>
    64 <title>Creating repositories</title>
    65 <para>
    65 <para>
    66 To store a repository on the server, clone it over.
    66 To store a repository on the server, clone it over.
    67 </para>
    67 </para>
    68 <screen><computeroutput>jay@spoon:~$ </computeroutput><userinput>cd myproj</userinput>
    68 <screen><computeroutput>jay@spoon:~$ </computeroutput><userinput>hg init myproj</userinput>
       
    69 <computeroutput>jay@spoon:~$ </computeroutput><userinput>cd myproj</userinput>
       
    70 <computeroutput>jay@spoon:~/myproj$ </computeroutput><userinput>editor program.c</userinput> <lineannotation>...create project files here...</lineannotation>
       
    71 <computeroutput>jay@spoon:~/myproj$ </computeroutput><userinput>hg add</userinput>
       
    72 <computeroutput>adding program.c
       
    73 jay@spoon:~/myproj$ </computeroutput><userinput>hg commit -m "Initial checkin"</userinput>
    69 <computeroutput>jay@spoon:~/myproj$ </computeroutput><userinput>hg clone . ssh://hg@jeeves/jays/project</userinput>
    74 <computeroutput>jay@spoon:~/myproj$ </computeroutput><userinput>hg clone . ssh://hg@jeeves/jays/project</userinput>
    70 <computeroutput>searching for changes
    75 <computeroutput>searching for changes
    71 remote: adding changesets
    76 remote: adding changesets
    72 remote: adding manifests
    77 remote: adding manifests
    73 remote: adding file changes
    78 remote: adding file changes
    74 remote: added 119 changesets with 284 changes to 61 files
    79 remote: added 1 changesets with 1 changes to 1 files
    75 jay@spoon:~/myproj$ </computeroutput><userinput>hg pull ssh://hg@jeeves/jays/project</userinput>
    80 jay@spoon:~/myproj$ </computeroutput><userinput>hg pull ssh://hg@jeeves/jays/project</userinput>
    76 <computeroutput>pulling from ssh://hg@jeeves/jays/project
    81 <computeroutput>pulling from ssh://hg@jeeves/jays/project
    77 searching for changes
    82 searching for changes
    78 no changes found
    83 no changes found
    79 <computeroutput>jay@spoon:~/myproj$ </computeroutput><userinput>cd ..</userinput>
    84 jay@spoon:~/myproj$ </computeroutput><userinput>cd ..</userinput>
    80 jay@spoon:~$ </computeroutput></screen>
    85 <computeroutput>jay@spoon:~$ </computeroutput></screen>
    81 </section>
    86 </section>
    82 <section>
    87 <section>
    83 <title>Adding other users</title>
    88 <title>Adding other users</title>
    84 <para>
    89 <para>
    85 At this stage, no-one but you has any access to any repositories you
    90 At this stage, no-one but you has any access to any repositories you
   152 <para>
   157 <para>
   153 Pat will have read and write access to the <filename
   158 Pat will have read and write access to the <filename
   154 class='directory'>widget</filename> repository as soon as we add, commit, and push these files.
   159 class='directory'>widget</filename> repository as soon as we add, commit, and push these files.
   155 </para>
   160 </para>
   156 <para>
   161 <para>
       
   162 Placing the same key in multiple directories will <emphasis>not</emphasis>
       
   163 grant that user multiple powers.  One of the locations will be used for
       
   164 all permission checks, while any others will be ignored.  Instead, put each
       
   165 key under the keys directory only once, and use
       
   166 <filename>access.conf</filename> to give permissions to the key.
       
   167 </para>
       
   168 <para>
   157 Each line of <filename>access.conf</filename> has the following syntax:
   169 Each line of <filename>access.conf</filename> has the following syntax:
   158 </para>
   170 </para>
   159 <programlisting><replaceable>rule</replaceable> <replaceable>condition</replaceable> <replaceable>condition...</replaceable>
   171 <programlisting><replaceable>rule</replaceable> <replaceable>condition</replaceable> <replaceable>condition...</replaceable>
   160 </programlisting>
   172 </programlisting>
   161 <para>
   173 <para>
   497 </para>
   509 </para>
   498 <para>
   510 <para>
   499 By creating such a file with suitable entries, you can run mercurial-server as a user other than <systemitem
   511 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.
   512 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>
   513 </para>
       
   514 <para>
       
   515 At install time the following <filename>~hg/.mercurial-server</filename> file is used:
       
   516 </para>
       
   517 <programlisting># WARNING: a .mercurial-server file in your home directory means
       
   518 # that refresh-auth can and will trash your ~/.ssh/authorized_keys file.
       
   519 
       
   520 [paths]
       
   521 repos = ~/repos
       
   522 authorized_keys = ~/.ssh/authorized_keys
       
   523 keys = /etc/mercurial-server/keys:~/repos/hgadmin/keys
       
   524 access = /etc/mercurial-server/access.conf:~/repos/hgadmin/access.conf
       
   525 
       
   526 [exceptions]
       
   527 # Allow the creation of mq repositories by default
       
   528 allowdots = .hg/patches
       
   529 
       
   530 [env]
       
   531 # Use a different hgrc for remote pulls - this way you can set
       
   532 # up access.py for everything at once without affecting local operations
       
   533 
       
   534 HGRCPATH = /etc/mercurial-server/remote-hgrc.d
       
   535 </programlisting>
       
   536 <para>
       
   537 The meaning of the entries are:
       
   538 </para>
       
   539 <itemizedlist>
       
   540 <listitem>
       
   541 <para><literal>[paths]</literal></para>
       
   542 <itemizedlist>
       
   543 <listitem>
       
   544 <para><literal>repos</literal>: directory under which all repositories are
       
   545 found. No remote user can reference any repo not under this directory.
       
   546 Here and throughout this section, where a path begins with
       
   547 <literal>~/</literal> the home directory is substituted - ie the
       
   548 directory in which the <filename>.mercurial-server</filename> file
       
   549 was found.</para>
       
   550 </listitem>
       
   551 <listitem>
       
   552 <para><literal>authorized_keys</literal>: this is the file that will be rewritten
       
   553 by refresh-auth, or whenever a checkin to the <literal>hgadmin</literal> repository is pushed.</para>
       
   554 </listitem>
       
   555 <listitem>
       
   556 <para><literal>keys</literal>: directories to scan for keys when rewriting
       
   557 <filename>authorized_keys</filename>.</para>
       
   558 </listitem>
       
   559 <listitem>
       
   560 <para><literal>access</literal>: files to read to determine the access rules.
       
   561 The files are effectively concatenated together in the order given.</para>
       
   562 </listitem>
       
   563 </itemizedlist>
       
   564 </listitem>
       
   565 <listitem>
       
   566 <para><literal>[exceptions]</literal></para>
       
   567 <itemizedlist>
       
   568 <listitem>
       
   569 <para><literal>allowdots</literal>: paths to allow even though they
       
   570 begin with dots.  Dots at the start of a pathname component are
       
   571 disallowed unless they exactly match one of the tails given in this
       
   572 colon-separated list.  The given exception allows MQ repositories
       
   573 to be pushed.</para>
       
   574 </listitem>
       
   575 </itemizedlist>
       
   576 </listitem>
       
   577 <listitem>
       
   578 <para><literal>[env]</literal>: all entries in here are added to the Unix environment
       
   579 when users connect.  The keys are converted to all-upper-case. </para>
       
   580 <itemizedlist>
       
   581 <listitem>
       
   582 <para><literal>HGRCPATH</literal>: set the path that Mercurial uses to search for
       
   583 configuration files.  At install time config files are placed on this path
       
   584 which set up access control and logging.</para>
       
   585 </listitem>
       
   586 </itemizedlist>
       
   587 </listitem>
       
   588 </itemizedlist>
   502 </section>
   589 </section>
   503 <section>
   590 <section>
   504 <title>License</title>
   591 <title>License</title>
   505 <para>
   592 <para>
   506 This program is free software; you can redistribute it and/or modify it
   593 This program is free software; you can redistribute it and/or modify it
   525 <para>
   612 <para>
   526 Thanks for reading this far. If you use mercurial-server, please tell me about
   613 Thanks for reading this far. If you use mercurial-server, please tell me about
   527 it.
   614 it.
   528 </para>
   615 </para>
   529 <para>
   616 <para>
   530 Paul Crowley, <email>paul@lshift.net</email>, 2010
   617 Paul Crowley, <email>paul@lshift.net</email>, 2011
   531 </para>
   618 </para>
   532 </section>
   619 </section>
   533 </section>
   620 </section>
   534 </article>
   621 </article>