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 |