doc/manual.docbook
author Cédric Krier <ced@b2ck.com>
Sun, 14 Dec 2014 20:30:25 +0100
changeset 374 7a1d6b228af6
parent 372 80f78674c56e
permissions -rw-r--r--
Set user as login name using a configuration index of the key path.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     1
<?xml version="1.0" encoding="utf-8"?>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
     2
<article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en"
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
     3
  xmlns:xlink="http://www.w3.org/1999/xlink">
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     4
<info>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     5
  <title>Sharing Mercurial repositories with mercurial-server</title>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     6
  <author><firstname>Paul</firstname><surname>Crowley</surname></author>
359
a14142919eb3 Bump year in manual
Paul Crowley <paul@lshift.net>
parents: 358
diff changeset
     7
  <copyright><year>2008-2012</year><holder>Paul Crowley, LShift Ltd</holder></copyright>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     8
</info>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     9
<section>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    10
<title>About mercurial-server</title>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    11
<para>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    12
Home page: <link xlink:href="http://www.lshift.net/mercurial-server.html"/>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    13
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    14
<para>
133
a99ab5be891a Let next para do the work of discussing what OS it runs on
Paul Crowley <paul@lshift.net>
parents: 132
diff changeset
    15
mercurial-server gives your developers remote read/write access to
a99ab5be891a Let next para do the work of discussing what OS it runs on
Paul Crowley <paul@lshift.net>
parents: 132
diff changeset
    16
centralized <link xlink:href="http://hg-scm.org/">Mercurial</link>
a99ab5be891a Let next para do the work of discussing what OS it runs on
Paul Crowley <paul@lshift.net>
parents: 132
diff changeset
    17
repositories using SSH public key authentication; it provides convenient
a99ab5be891a Let next para do the work of discussing what OS it runs on
Paul Crowley <paul@lshift.net>
parents: 132
diff changeset
    18
and fine-grained key management and access control.
372
80f78674c56e Add support for phases
David Douard <david.douard@logilab.fr>
parents: 359
diff changeset
    19
It provides access control for <link xlink:href="http://mercurial.selenic.com/wiki/Phases">phases</link>
80f78674c56e Add support for phases
David Douard <david.douard@logilab.fr>
parents: 359
diff changeset
    20
move (from "draft" to "public").
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    21
</para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    22
<para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    23
Though mercurial-server is currently targeted at Debian-based systems such
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    24
as Ubuntu, other users have reported success getting it running on other
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    25
Unix-based systems such as Red Hat. Running it on a non-Unix system such as
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    26
Windows is not supported. You will need root privileges to install it.
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    27
</para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    28
</section>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    29
<section>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    30
<title>Step by step</title>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    31
<para>
134
525976d2827c Change the way we link to SSH tutorial
Paul Crowley <paul@lshift.net>
parents: 133
diff changeset
    32
mercurial-server authenticates users not using passwords but using SSH
525976d2827c Change the way we link to SSH tutorial
Paul Crowley <paul@lshift.net>
parents: 133
diff changeset
    33
public keys; everyone who wants access to a mercurial-server repository
131
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
    34
will need such a key. In combination with <command>ssh-agent</command> (or
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    35
equivalents such as the Windows program <link
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    36
xlink:href="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">Pageant</link>),
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    37
this means that users will not need to type in a password to access the
134
525976d2827c Change the way we link to SSH tutorial
Paul Crowley <paul@lshift.net>
parents: 133
diff changeset
    38
repository. If you're not familiar with SSH public keys, the <link
525976d2827c Change the way we link to SSH tutorial
Paul Crowley <paul@lshift.net>
parents: 133
diff changeset
    39
xlink:href="http://sial.org/howto/openssh/publickey-auth/">OpenSSH Public
525976d2827c Change the way we link to SSH tutorial
Paul Crowley <paul@lshift.net>
parents: 133
diff changeset
    40
Key Authentication tutorial</link> may be helpful.
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    41
</para>
358
924bf9d4dbc0 Added a para warning that an hg account will be created, as suggested in email
Paul Crowley <paul@lshift.net>
parents: 345
diff changeset
    42
<para>
924bf9d4dbc0 Added a para warning that an hg account will be created, as suggested in email
Paul Crowley <paul@lshift.net>
parents: 345
diff changeset
    43
When mercurial-server is installed, a new user account called <systemitem
924bf9d4dbc0 Added a para warning that an hg account will be created, as suggested in email
Paul Crowley <paul@lshift.net>
parents: 345
diff changeset
    44
class="username">hg</systemitem> will be created; this user's home directory will be where all repositories will be stored, so you should ensure that it has enough space and suchlike.</para>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    45
<section>
185
f8f8b4018381 Remove all installation talk from docbook
Paul Crowley <paul@lshift.net>
parents: 179
diff changeset
    46
<title>Initial access to mercurial-server</title>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    47
<para>
122
05b676684c7e Call the user jay rather than user, and use pat instead of other-user
Paul Crowley <paul@lshift.net>
parents: 121
diff changeset
    48
In what follows, we assume that your username is <systemitem
05b676684c7e Call the user jay rather than user, and use pat instead of other-user
Paul Crowley <paul@lshift.net>
parents: 121
diff changeset
    49
class="username">jay</systemitem>, that you usually sit at a machine called
185
f8f8b4018381 Remove all installation talk from docbook
Paul Crowley <paul@lshift.net>
parents: 179
diff changeset
    50
<systemitem class="systemname">spoon</systemitem> and you have
f8f8b4018381 Remove all installation talk from docbook
Paul Crowley <paul@lshift.net>
parents: 179
diff changeset
    51
installed mercurial-server on <systemitem
f8f8b4018381 Remove all installation talk from docbook
Paul Crowley <paul@lshift.net>
parents: 179
diff changeset
    52
class="systemname">jeeves</systemitem> using the package management system (see the README for more on installation). We assume that you have created your SSH public key, set up your SSH agent with this key, and that this key gives you access to <systemitem
311
3cbde66305e4 Fix white space
Paul Crowley <paul@lshift.net>
parents: 263
diff changeset
    53
class="systemname">jeeves</systemitem>.
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    54
</para>
185
f8f8b4018381 Remove all installation talk from docbook
Paul Crowley <paul@lshift.net>
parents: 179
diff changeset
    55
<screen><computeroutput>jay@spoon:~$ </computeroutput><userinput>ssh -A jeeves</userinput>
f8f8b4018381 Remove all installation talk from docbook
Paul Crowley <paul@lshift.net>
parents: 179
diff changeset
    56
<computeroutput>jay@jeeves:~$ </computeroutput><userinput>ssh-add -L > my-key</userinput>
158
713c6cccbc2f Use short meaningless hostnames
Paul Crowley <paul@lshift.net>
parents: 157
diff changeset
    57
<computeroutput>jay@jeeves:~$ </computeroutput><userinput>sudo mkdir -p /etc/mercurial-server/keys/root/jay</userinput>
713c6cccbc2f Use short meaningless hostnames
Paul Crowley <paul@lshift.net>
parents: 157
diff changeset
    58
<computeroutput>jay@jeeves:~$ </computeroutput><userinput>sudo cp my-key /etc/mercurial-server/keys/root/jay/spoon</userinput>
713c6cccbc2f Use short meaningless hostnames
Paul Crowley <paul@lshift.net>
parents: 157
diff changeset
    59
<computeroutput>jay@jeeves:~$ </computeroutput><userinput>sudo -u hg /usr/share/mercurial-server/refresh-auth</userinput>
713c6cccbc2f Use short meaningless hostnames
Paul Crowley <paul@lshift.net>
parents: 157
diff changeset
    60
<computeroutput>jay@jeeves:~$ </computeroutput><userinput>exit</userinput>
713c6cccbc2f Use short meaningless hostnames
Paul Crowley <paul@lshift.net>
parents: 157
diff changeset
    61
<computeroutput>Connection to jeeves closed.
713c6cccbc2f Use short meaningless hostnames
Paul Crowley <paul@lshift.net>
parents: 157
diff changeset
    62
jay@spoon:~$ </computeroutput></screen>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    63
<para>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    64
You can now create repositories on the remote machine and have complete
131
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
    65
read-write access to all of them.
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    66
</para>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    67
</section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    68
<section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    69
<title>Creating repositories</title>
131
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
    70
<para>
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
    71
To store a repository on the server, clone it over.
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
    72
</para>
345
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
    73
<screen><computeroutput>jay@spoon:~$ </computeroutput><userinput>hg init myproj</userinput>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
    74
<computeroutput>jay@spoon:~$ </computeroutput><userinput>cd myproj</userinput>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
    75
<computeroutput>jay@spoon:~/myproj$ </computeroutput><userinput>editor program.c</userinput> <lineannotation>...create project files here...</lineannotation>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
    76
<computeroutput>jay@spoon:~/myproj$ </computeroutput><userinput>hg add</userinput>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
    77
<computeroutput>adding program.c
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
    78
jay@spoon:~/myproj$ </computeroutput><userinput>hg commit -m "Initial checkin"</userinput>
160
72cb7a42650a Use shorter remote repo name
Paul Crowley <paul@lshift.net>
parents: 159
diff changeset
    79
<computeroutput>jay@spoon:~/myproj$ </computeroutput><userinput>hg clone . ssh://hg@jeeves/jays/project</userinput>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    80
<computeroutput>searching for changes
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    81
remote: adding changesets
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    82
remote: adding manifests
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    83
remote: adding file changes
345
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
    84
remote: added 1 changesets with 1 changes to 1 files
160
72cb7a42650a Use shorter remote repo name
Paul Crowley <paul@lshift.net>
parents: 159
diff changeset
    85
jay@spoon:~/myproj$ </computeroutput><userinput>hg pull ssh://hg@jeeves/jays/project</userinput>
72cb7a42650a Use shorter remote repo name
Paul Crowley <paul@lshift.net>
parents: 159
diff changeset
    86
<computeroutput>pulling from ssh://hg@jeeves/jays/project
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    87
searching for changes
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    88
no changes found
345
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
    89
jay@spoon:~/myproj$ </computeroutput><userinput>cd ..</userinput>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
    90
<computeroutput>jay@spoon:~$ </computeroutput></screen>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    91
</section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    92
<section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    93
<title>Adding other users</title>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    94
<para>
145
bc2b93fa662d tiny reword
Paul Crowley <paul@lshift.net>
parents: 144
diff changeset
    95
At this stage, no-one but you has any access to any repositories you
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    96
create on this system. In order to give anyone else access, you'll need a
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    97
copy of their SSH public key; we'll assume you have that key in
161
475a05ed5f0e Sam's machine is called saucer
Paul Crowley <paul@lshift.net>
parents: 160
diff changeset
    98
<filename>~/sam-saucer-key.pub</filename>.  To manage access, you make changes to the special <filename
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
    99
class='directory'>hgadmin</filename> repository.
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   100
</para>
158
713c6cccbc2f Use short meaningless hostnames
Paul Crowley <paul@lshift.net>
parents: 157
diff changeset
   101
<screen><computeroutput>jay@spoon:~$ </computeroutput><userinput>hg clone ssh://hg@jeeves/hgadmin</userinput>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   102
<computeroutput>destination directory: hgadmin
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   103
no changes found
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   104
updating working directory
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   105
0 files updated, 0 files merged, 0 files removed, 0 files unresolved
158
713c6cccbc2f Use short meaningless hostnames
Paul Crowley <paul@lshift.net>
parents: 157
diff changeset
   106
jay@spoon:~$ </computeroutput><userinput>cd hgadmin</userinput>
713c6cccbc2f Use short meaningless hostnames
Paul Crowley <paul@lshift.net>
parents: 157
diff changeset
   107
<computeroutput>jay@spoon:~/hgadmin$ </computeroutput><userinput>mkdir -p keys/users/sam</userinput>
161
475a05ed5f0e Sam's machine is called saucer
Paul Crowley <paul@lshift.net>
parents: 160
diff changeset
   108
<computeroutput>jay@spoon:~/hgadmin$ </computeroutput><userinput>cp ~/sam-saucer-key.pub keys/users/sam/saucer</userinput>
158
713c6cccbc2f Use short meaningless hostnames
Paul Crowley <paul@lshift.net>
parents: 157
diff changeset
   109
<computeroutput>jay@spoon:~/hgadmin$ </computeroutput><userinput>hg add</userinput>
161
475a05ed5f0e Sam's machine is called saucer
Paul Crowley <paul@lshift.net>
parents: 160
diff changeset
   110
<computeroutput>adding keys/users/sam/saucer
162
1c0bc7d33648 Remove stray apostrophe
Paul Crowley <paul@lshift.net>
parents: 161
diff changeset
   111
jay@spoon:~/hgadmin$ </computeroutput><userinput>hg commit -m "Add Sam's key"</userinput>
158
713c6cccbc2f Use short meaningless hostnames
Paul Crowley <paul@lshift.net>
parents: 157
diff changeset
   112
<computeroutput>jay@spoon:~/hgadmin$ </computeroutput><userinput>hg push</userinput>
713c6cccbc2f Use short meaningless hostnames
Paul Crowley <paul@lshift.net>
parents: 157
diff changeset
   113
<computeroutput>pushing to ssh://hg@jeeves/hgadmin
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   114
searching for changes
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   115
remote: adding changesets
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   116
remote: adding manifests
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   117
remote: adding file changes
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   118
remote: added 1 changesets with 1 changes to 1 files
158
713c6cccbc2f Use short meaningless hostnames
Paul Crowley <paul@lshift.net>
parents: 157
diff changeset
   119
jay@spoon:~/hgadmin$ </computeroutput></screen>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   120
<para>
123
20b54500a618 Call the other user "Sam"
Paul Crowley <paul@lshift.net>
parents: 122
diff changeset
   121
Sam can now read and write to your
160
72cb7a42650a Use shorter remote repo name
Paul Crowley <paul@lshift.net>
parents: 159
diff changeset
   122
<uri>ssh://hg@jeeves/jays/project</uri> repository.
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   123
Most other changes to access control can be made simply by making and
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   124
pushing changes to <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   125
class='directory'>hgadmin</filename>, and you can use Mercurial to
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   126
cooperate with other root users in the normal way.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   127
</para>
131
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
   128
<para>
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
   129
If you prefer, you could give them access by
158
713c6cccbc2f Use short meaningless hostnames
Paul Crowley <paul@lshift.net>
parents: 157
diff changeset
   130
logging into <systemitem class="systemname">jeeves</systemitem>,
131
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
   131
putting the key in the right place under <filename
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
   132
class='directory'>/etc/mercurial-server/keys</filename>, and re-running
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
   133
<userinput>sudo -u hg /usr/share/mercurial-server/refresh-auth</userinput>.
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   134
However, using <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   135
class='directory'>hgadmin</filename> is usually more convenient if you need to make more than a very few changes; it also makes it easier to share administration with others and provides a log of all changes.
131
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
   136
</para>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   137
</section>
132
a5850a63390f Move basic access control to the start of access control
Paul Crowley <paul@lshift.net>
parents: 131
diff changeset
   138
</section>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   139
<section>
132
a5850a63390f Move basic access control to the start of access control
Paul Crowley <paul@lshift.net>
parents: 131
diff changeset
   140
<title>Access control</title>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   141
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   142
Out of the box, mercurial-server supports two kinds of users: "root" users and normal users.  If you followed the steps above, you are a "root" user because your key is under <filename class='directory'>keys/root</filename>, while the other user you gave access to is a normal user since their key is under <filename class='directory'>keys/users</filename>.  Keys that are not in either of these directories will by default have no access to anything.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   143
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   144
<para>
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   145
Root users can edit <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   146
class='directory'>hgadmin</filename>, create new repositories and read and write to existing ones.  Normal users cannot access <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   147
class='directory'>hgadmin</filename> or create new repositories, but they can read and write to any other repository.
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   148
</para>
132
a5850a63390f Move basic access control to the start of access control
Paul Crowley <paul@lshift.net>
parents: 131
diff changeset
   149
<section>
a5850a63390f Move basic access control to the start of access control
Paul Crowley <paul@lshift.net>
parents: 131
diff changeset
   150
<title>Using access.conf</title>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   151
<para>
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   152
mercurial-server offers much more fine-grained access control than this division into two classes of users.  Let's suppose you wish to give Pat access to the <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   153
class='directory'>widget</filename> repository, but no other.  We first copy Pat's SSH public key into the <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   154
class='directory'>keys/pat</filename> directory in <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   155
class='directory'>hgadmin</filename>.  This tells mercurial-server about Pat's key, but gives Pat no access to anything because the key is not under either <filename
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   156
class='directory'>keys/root</filename> or <filename
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   157
class='directory'>keys/users</filename>.  To grant this key access, we must give mercurial-server a new access rule, so we create a file in <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   158
class='directory'>hgadmin</filename> called <filename>access.conf</filename>, with the following contents:</para>
146
04e74d4b3822 Simplify Pat story
Paul Crowley <paul@lshift.net>
parents: 145
diff changeset
   159
<programlisting># Give Pat access to the "widget" repository
238
4747f2920666 Use wildcard in rule to match instructions
Paul Crowley <paul@lshift.net>
parents: 221
diff changeset
   160
write repo=widget user=pat/*
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   161
</programlisting>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   162
<para>
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   163
Pat will have read and write access to the <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   164
class='directory'>widget</filename> repository as soon as we add, commit, and push these files.
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   165
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   166
<para>
345
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   167
Placing the same key in multiple directories will <emphasis>not</emphasis>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   168
grant that user multiple powers.  One of the locations will be used for
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   169
all permission checks, while any others will be ignored.  Instead, put each
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   170
key under the keys directory only once, and use
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   171
<filename>access.conf</filename> to give permissions to the key.
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   172
</para>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   173
<para>
124
6836769f5134 Forgot a filename tag
Paul Crowley <paul@lshift.net>
parents: 123
diff changeset
   174
Each line of <filename>access.conf</filename> has the following syntax:
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   175
</para>
144
2dbaddde1fd5 programlisting also needs no initial blank lines
Paul Crowley <paul@lshift.net>
parents: 143
diff changeset
   176
<programlisting><replaceable>rule</replaceable> <replaceable>condition</replaceable> <replaceable>condition...</replaceable>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   177
</programlisting>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   178
<para>
157
bb53f3b9c411 Use markup, not quote marks
Paul Crowley <paul@lshift.net>
parents: 156
diff changeset
   179
Blank lines and lines that start with <code>#</code> are ignored. Rule is
bb53f3b9c411 Use markup, not quote marks
Paul Crowley <paul@lshift.net>
parents: 156
diff changeset
   180
one of
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   181
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   182
<itemizedlist>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   183
<listitem>
372
80f78674c56e Add support for phases
David Douard <david.douard@logilab.fr>
parents: 359
diff changeset
   184
<literal>init</literal>: allow reads, writes, publish (move the phase
80f78674c56e Add support for phases
David Douard <david.douard@logilab.fr>
parents: 359
diff changeset
   185
of a chageset to "public"), and the creation of new repositories
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   186
</listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   187
<listitem>
372
80f78674c56e Add support for phases
David Douard <david.douard@logilab.fr>
parents: 359
diff changeset
   188
<literal>publish</literal>: allow reads, writes and publish changesets
80f78674c56e Add support for phases
David Douard <david.douard@logilab.fr>
parents: 359
diff changeset
   189
</listitem>
80f78674c56e Add support for phases
David Douard <david.douard@logilab.fr>
parents: 359
diff changeset
   190
<listitem>
80f78674c56e Add support for phases
David Douard <david.douard@logilab.fr>
parents: 359
diff changeset
   191
<literal>write</literal>: allow reads and writes (ie. create draft changesets)
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   192
</listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   193
<listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   194
<literal>read</literal>: allow only read operations
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   195
</listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   196
<listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   197
<literal>deny</literal>: deny all requests
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   198
</listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   199
</itemizedlist>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   200
<para>
372
80f78674c56e Add support for phases
David Douard <david.douard@logilab.fr>
parents: 359
diff changeset
   201
  The distinction between "write" and "publish" access levels is only
80f78674c56e Add support for phases
David Douard <david.douard@logilab.fr>
parents: 359
diff changeset
   202
  meaningful for non-publishing repositories, in which case, the
80f78674c56e Add support for phases
David Douard <david.douard@logilab.fr>
parents: 359
diff changeset
   203
  "write" access level allows a user to push "draft" changesets, but
80f78674c56e Add support for phases
David Douard <david.douard@logilab.fr>
parents: 359
diff changeset
   204
  not to change their phase to "public". This latter operation require
80f78674c56e Add support for phases
David Douard <david.douard@logilab.fr>
parents: 359
diff changeset
   205
  the "publish" access level.
80f78674c56e Add support for phases
David Douard <david.douard@logilab.fr>
parents: 359
diff changeset
   206
</para>
80f78674c56e Add support for phases
David Douard <david.douard@logilab.fr>
parents: 359
diff changeset
   207
<para>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   208
A condition is a globpattern matched against a relative path. The two most
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   209
important conditions are
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   210
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   211
<itemizedlist>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   212
<listitem>
156
34925ee06f90 Silly to use literal inside code
Paul Crowley <paul@lshift.net>
parents: 155
diff changeset
   213
<code>user=<replaceable>globpattern</replaceable></code>: path to the user's key
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   214
</listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   215
<listitem>
156
34925ee06f90 Silly to use literal inside code
Paul Crowley <paul@lshift.net>
parents: 155
diff changeset
   216
<code>repo=<replaceable>globpattern</replaceable></code>: path to the repository
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   217
</listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   218
</itemizedlist>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   219
<para>
157
bb53f3b9c411 Use markup, not quote marks
Paul Crowley <paul@lshift.net>
parents: 156
diff changeset
   220
<code>*</code> only matches one directory level, where <code>**</code>
bb53f3b9c411 Use markup, not quote marks
Paul Crowley <paul@lshift.net>
parents: 156
diff changeset
   221
matches as many as you want. More precisely, <code>*</code> matches zero or
bb53f3b9c411 Use markup, not quote marks
Paul Crowley <paul@lshift.net>
parents: 156
diff changeset
   222
more characters not including <code>/</code> while <code>**</code> matches
bb53f3b9c411 Use markup, not quote marks
Paul Crowley <paul@lshift.net>
parents: 156
diff changeset
   223
zero or more characters including <code>/</code>. So
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   224
<code>projects/*</code> matches <filename
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   225
class='directory'>projects/foo</filename> but not <filename
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   226
class='directory'>projects/foo/bar</filename>, while
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   227
<code>projects/**</code> matches both.
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   228
</para>
147
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   229
<para>
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   230
When considering a request, mercurial-server steps through all the rules in
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   231
<filename>/etc/mercurial-server/access.conf</filename> and then all the
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   232
rules in <filename>access.conf</filename> in <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   233
class='directory'>hgadmin</filename>
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   234
looking for a rule which matches on every condition. The first match
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   235
determines whether the request will be allowed; if there is no match in
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   236
either file, the request will be denied.
147
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   237
</para>
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   238
<para>
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   239
By default, <filename>/etc/mercurial-server/access.conf</filename> has the
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   240
following rules:
147
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   241
</para>
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   242
<programlisting>init user=root/**
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   243
deny repo=hgadmin
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   244
write user=users/**
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   245
</programlisting>
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   246
<para>
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   247
These rules ensure that root users can do any operation on any repository,
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   248
that no other users can access the <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   249
class='directory'>hgadmin</filename> repository,
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   250
and that those with keys in <filename
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   251
class='directory'>keys/users</filename> can read or write to any repository
153
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   252
but not create repositories.  Some examples of how these rules work:
147
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   253
</para>
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   254
<itemizedlist>
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   255
<listitem>
153
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   256
User <filename class='directory'>root/jay</filename> creates a repository
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   257
<filename class='directory'>foo/bar/baz</filename>. This matches the first
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   258
rule and so will be allowed.
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   259
</listitem>
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   260
<listitem>
153
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   261
User <filename class='directory'>root/jay</filename> changes repository
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   262
<filename class='directory'>hgadmin</filename>. Again, this matches the
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   263
first rule and so will be allowed; later rules have no effect.
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   264
</listitem>
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   265
<listitem>
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   266
User <filename class='directory'>users/sam</filename> tries to read
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   267
repository <filename class='directory'>hgadmin</filename>. This does not
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   268
match the first rule, but matches the second, and so will be denied.
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   269
</listitem>
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   270
<listitem>
153
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   271
User <filename class='directory'>users/sam</filename> tries to create
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   272
repository <filename class='directory'>sams-project</filename>. This does
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   273
not match the first two rules, but matches the third; this is a
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   274
<literal>write</literal> rule, which doesn't grant the privilege to create
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   275
repositories, so the request will be denied.
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   276
</listitem>
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   277
<listitem>
153
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   278
User <filename class='directory'>users/sam</filename> writes to existing
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   279
repository <filename class='directory'>projects/main</filename>. Again,
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   280
this matches the third rule, which allows the request.
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   281
</listitem>
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   282
<listitem>
153
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   283
User <filename class='directory'>pat</filename> tries to write to existing
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   284
repository <filename class='directory'>widget</filename>. Until we change
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   285
the <filename>access.conf</filename> file in <filename
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   286
class='directory'>hgadmin</filename>, this will match no rule, and so will
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   287
be denied.
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   288
</listitem>
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   289
<listitem>
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   290
Any request from a user whose key not under the <filename
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   291
class='directory'>keys</filename> directory at all will always be denied,
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   292
no matter what rules are in effect; because of the way SSH authentication
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   293
works, they will be prompted to enter a password, but no password will
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   294
work. This can't be changed.
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   295
</listitem>
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   296
</itemizedlist>
132
a5850a63390f Move basic access control to the start of access control
Paul Crowley <paul@lshift.net>
parents: 131
diff changeset
   297
</section>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   298
<section>
125
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   299
<title>/etc/mercurial-server and hgadmin</title>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   300
<para>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   301
mercurial-server consults two distinct locations to collect information about what to allow: <filename
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   302
class='directory'>/etc/mercurial-server</filename> and its own <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   303
class='directory'>hgadmin</filename> repository.  This is useful for several reasons:
125
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   304
</para>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   305
<itemizedlist>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   306
<listitem>
148
5da43b596bac Fixes to /etc/mercurial-server discussion
Paul Crowley <paul@lshift.net>
parents: 147
diff changeset
   307
Some users may not need the convenience of access control via mercurial; for these users updating <filename
125
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   308
class='directory'>/etc/mercurial-server</filename> may offer a simpler route.
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   309
</listitem>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   310
<listitem>
148
5da43b596bac Fixes to /etc/mercurial-server discussion
Paul Crowley <paul@lshift.net>
parents: 147
diff changeset
   311
<filename class='directory'>/etc/mercurial-server</filename> is suitable
5da43b596bac Fixes to /etc/mercurial-server discussion
Paul Crowley <paul@lshift.net>
parents: 147
diff changeset
   312
for management with tools such as <link
125
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   313
xlink:href="http://reductivelabs.com/products/puppet">Puppet</link>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   314
</listitem>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   315
<listitem>
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   316
If a change to <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   317
class='directory'>hgadmin</filename> leaves you "locked out", <filename
125
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   318
class='directory'>/etc/mercurial-server</filename> allows you a way back in.
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   319
</listitem>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   320
<listitem>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   321
At install time, all users are "locked out", and so some mechanism to allow some users in is needed.
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   322
</listitem>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   323
</itemizedlist>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   324
<para>
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   325
Rules in <filename>/etc/mercurial-server/access.conf</filename> are checked before those in <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   326
class='directory'>hgadmin</filename>, and keys in <filename class='directory'>/etc/mercurial-server/keys</filename> will be present no matter how <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   327
class='directory'>hgadmin</filename> changes.
125
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   328
</para>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   329
<para>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   330
We anticipate that once mercurial-server is successfully installed and
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   331
working you will usually want to use <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   332
class='directory'>hgadmin</filename> for most
125
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   333
access control tasks. Once you have the right keys and
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   334
<filename>access.conf</filename> set up in <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   335
class='directory'>hgadmin</filename>, you
125
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   336
can delete <filename>/etc/mercurial-server/access.conf</filename> and all
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   337
of <filename class='directory'>/etc/mercurial-server/keys</filename>,
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   338
turning control entirely over to <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   339
class='directory'>hgadmin</filename>.
125
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   340
</para>
127
3262c0a53b59 Talk about remote-hgrc
Paul Crowley <paul@lshift.net>
parents: 126
diff changeset
   341
<para>
221
c4c3facf5d6b Switch to remote-hgrc.d
Paul Crowley <paul@lshift.net>
parents: 185
diff changeset
   342
<filename>/etc/mercurial-server/remote-hgrc.d</filename> is in the
127
3262c0a53b59 Talk about remote-hgrc
Paul Crowley <paul@lshift.net>
parents: 126
diff changeset
   343
<systemitem>HGRCPATH</systemitem> for all remote access to mercurial-server
221
c4c3facf5d6b Switch to remote-hgrc.d
Paul Crowley <paul@lshift.net>
parents: 185
diff changeset
   344
repositories. This directory contains the hooks that mercurial-server uses for
c4c3facf5d6b Switch to remote-hgrc.d
Paul Crowley <paul@lshift.net>
parents: 185
diff changeset
   345
access control and logging. You can add hooks to this directory, but obviously
127
3262c0a53b59 Talk about remote-hgrc
Paul Crowley <paul@lshift.net>
parents: 126
diff changeset
   346
breaking the existing hooks will disable the relevant functionality and
3262c0a53b59 Talk about remote-hgrc
Paul Crowley <paul@lshift.net>
parents: 126
diff changeset
   347
isn't advisable.
3262c0a53b59 Talk about remote-hgrc
Paul Crowley <paul@lshift.net>
parents: 126
diff changeset
   348
</para>
125
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   349
</section>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   350
<section>
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   351
<title>File and branch conditions</title>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   352
<para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   353
mercurial-server supports file and branch conditions, which restrict an
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   354
operation depending on what files it modifies and what branch the work is
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   355
on. </para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   356
<caution>
128
b1610de4b6b1 Reword caution
Paul Crowley <paul@lshift.net>
parents: 127
diff changeset
   357
The way these conditions work is subtle and can be counterintuitive. Unless
b1610de4b6b1 Reword caution
Paul Crowley <paul@lshift.net>
parents: 127
diff changeset
   358
you need what they provide, ignore this section, stick to user and repo
140
0f79d1bea07e Beef up the caution
Paul Crowley <paul@lshift.net>
parents: 139
diff changeset
   359
conditions, and then things are likely to work the way you would expect. If
0f79d1bea07e Beef up the caution
Paul Crowley <paul@lshift.net>
parents: 139
diff changeset
   360
you do need what they provide, read what follows very carefully.
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   361
</caution>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   362
<para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   363
File and branch conditions are added to the conditions against which a rule
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   364
matches, just like user and repo conditions; they have this form:
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   365
</para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   366
<itemizedlist>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   367
<listitem>
156
34925ee06f90 Silly to use literal inside code
Paul Crowley <paul@lshift.net>
parents: 155
diff changeset
   368
<code>file=<replaceable>globpattern</replaceable></code>: file within the repo
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   369
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   370
<listitem>
156
34925ee06f90 Silly to use literal inside code
Paul Crowley <paul@lshift.net>
parents: 155
diff changeset
   371
<code>branch=<replaceable>globpattern</replaceable></code>: Mercurial branch name
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   372
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   373
</itemizedlist>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   374
<para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   375
However, in order to understand what effect adding these conditions will
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   376
have, it helps to understand how and when these rules are applied.
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   377
</para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   378
<para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   379
The rules file is used to make three decisions:
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   380
</para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   381
<itemizedlist>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   382
<listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   383
Whether to allow a repository to be created
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   384
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   385
<listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   386
Whether to allow any access to a repository
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   387
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   388
<listitem>
139
b7e78f9705e6 There are only three decisions, honest
Paul Crowley <paul@lshift.net>
parents: 138
diff changeset
   389
Whether to allow a changeset
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   390
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   391
</itemizedlist>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   392
<para>
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   393
When the first two of these decisions are being made, nothing is known
139
b7e78f9705e6 There are only three decisions, honest
Paul Crowley <paul@lshift.net>
parents: 138
diff changeset
   394
about any changsets that might be pushed, and so all file and branch
b7e78f9705e6 There are only three decisions, honest
Paul Crowley <paul@lshift.net>
parents: 138
diff changeset
   395
conditions automatically succeed for the purpose of such decisions. For the
b7e78f9705e6 There are only three decisions, honest
Paul Crowley <paul@lshift.net>
parents: 138
diff changeset
   396
third condition, every file changed in the changeset must be allowed by a
b7e78f9705e6 There are only three decisions, honest
Paul Crowley <paul@lshift.net>
parents: 138
diff changeset
   397
<literal>write</literal> or <literal>init</literal> rule for the changeset
b7e78f9705e6 There are only three decisions, honest
Paul Crowley <paul@lshift.net>
parents: 138
diff changeset
   398
to be allowed.
b7e78f9705e6 There are only three decisions, honest
Paul Crowley <paul@lshift.net>
parents: 138
diff changeset
   399
</para>
b7e78f9705e6 There are only three decisions, honest
Paul Crowley <paul@lshift.net>
parents: 138
diff changeset
   400
<para>
b7e78f9705e6 There are only three decisions, honest
Paul Crowley <paul@lshift.net>
parents: 138
diff changeset
   401
This means that doing tricky things with file conditions can have
b7e78f9705e6 There are only three decisions, honest
Paul Crowley <paul@lshift.net>
parents: 138
diff changeset
   402
counterintuitive consequences:
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   403
</para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   404
<itemizedlist>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   405
<listitem>
149
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   406
<para>You cannot limit read access to a subset of a repository with a <literal>read</literal>
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   407
rule and a file condition: any user who has access to a repository can read
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   408
all of it and its full history. Such a rule can only have the effect of
149
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   409
masking a later <literal>write</literal> rule, as in this example:</para>
144
2dbaddde1fd5 programlisting also needs no initial blank lines
Paul Crowley <paul@lshift.net>
parents: 143
diff changeset
   410
<programlisting>read repo=specialrepo file=dontwritethis
2dbaddde1fd5 programlisting also needs no initial blank lines
Paul Crowley <paul@lshift.net>
parents: 143
diff changeset
   411
write repo=specialrepo
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   412
</programlisting>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   413
<para>
149
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   414
allows all users to read <literal>specialrepo</literal>, and to write to all files
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   415
<emphasis>except</emphasis> that any changeset which writes to
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   416
<filename>dontwritethis</filename> will be rejected.
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   417
</para>
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   418
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   419
<listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   420
For similar reasons, don't give <literal>init</literal> rules file conditions.
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   421
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   422
<listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   423
<para>Don't try to deny write access to a particular file on a particular
149
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   424
branch&#x2014;a developer can write to the file on another branch and then merge
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   425
it in. Either deny all writes to the branch from that user, or allow them
149
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   426
to write to all the files they can write to on any branch.
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   427
</para>
144
2dbaddde1fd5 programlisting also needs no initial blank lines
Paul Crowley <paul@lshift.net>
parents: 143
diff changeset
   428
<programlisting>write user=docs/* branch=docs file=docs/*
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   429
</programlisting>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   430
<para>
149
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   431
This rule grants users whose keys are in the <filename
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   432
class='directory'>docs</filename> subdirectory the power to push changesets
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   433
into any repository only if those changesets are on the
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   434
<literal>docs</literal> branch and they affect only those files directly
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   435
under the <filename class='directory'>docs</filename> directory. However,
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   436
the rules below have more counterintuitive consequences.
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   437
</para>
144
2dbaddde1fd5 programlisting also needs no initial blank lines
Paul Crowley <paul@lshift.net>
parents: 143
diff changeset
   438
<programlisting>write user=docs/* branch=docs
2dbaddde1fd5 programlisting also needs no initial blank lines
Paul Crowley <paul@lshift.net>
parents: 143
diff changeset
   439
write user=docs/* file=docs/*
2dbaddde1fd5 programlisting also needs no initial blank lines
Paul Crowley <paul@lshift.net>
parents: 143
diff changeset
   440
read user=docs/*
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   441
</programlisting>
149
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   442
<para>
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   443
These rules grant users whose keys are in the <filename
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   444
class='directory'>docs</filename> subdirectory the power to change any file directly under the <filename class='directory'>docs</filename> directory, or any file at all in the <literal>docs</literal> branch.  Indirectly, however, this adds up to the power to change any file on any branch, simply by making the change on the docs branch and then merging the change into another branch.
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   445
</para>
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   446
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   447
</itemizedlist>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   448
</section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   449
</section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   450
<section>
263
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   451
<title>In detail</title>
252
75acaf1b1216 Add section on logging, merge later sections
Paul Crowley <paul@lshift.net>
parents: 238
diff changeset
   452
<section>
126
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   453
<title>How mercurial-server works</title>
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   454
<para>
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   455
All of the repositories controlled by mercurial-server are owned by a
151
5758cf47ff43 cleanups to the security section
Paul Crowley <paul@lshift.net>
parents: 150
diff changeset
   456
single user, the <systemitem
5758cf47ff43 cleanups to the security section
Paul Crowley <paul@lshift.net>
parents: 150
diff changeset
   457
class="username">hg</systemitem> user, which is why all URLs for
155
3bff97f72a33 ssh:// is the start of a URI
Paul Crowley <paul@lshift.net>
parents: 154
diff changeset
   458
mercurial-server repositories start with <uri>ssh://hg@...</uri>.
126
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   459
Each SSH key that has access to the repository has an entry in
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   460
<filename>~hg/.ssh/authorized_keys</filename>; this is how the SSH daemon
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   461
knows to give that key access. When the user connects over SSH, their
150
02b464a6b433 Improvements to how it works section
Paul Crowley <paul@lshift.net>
parents: 149
diff changeset
   462
commands are run in a custom restricted shell; this shell knows which key
02b464a6b433 Improvements to how it works section
Paul Crowley <paul@lshift.net>
parents: 149
diff changeset
   463
was used to connect, determines what the user is trying to do, checks the
02b464a6b433 Improvements to how it works section
Paul Crowley <paul@lshift.net>
parents: 149
diff changeset
   464
access rules to decide whether to allow it, and if allowed invokes
02b464a6b433 Improvements to how it works section
Paul Crowley <paul@lshift.net>
parents: 149
diff changeset
   465
Mercurial internally, without forking.
126
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   466
</para>
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   467
<para>
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   468
This restricted shell also ensures that certain Mercurial extensions are
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   469
loaded when the user acts on a repository; these extensions check the
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   470
access control rules for any changeset that the user tries to commit, and
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   471
log all pushes and pulls into a per-repository access log.
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   472
</para>
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   473
<para>
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   474
<command>refresh-auth</command> recurses through the <filename
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   475
class='directory'>/etc/mercurial-server/keys</filename> and the <filename
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   476
class='directory'>keys</filename> directory in the
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   477
<filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   478
class='directory'>hgadmin</filename> repository, creating an entry in
126
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   479
<filename>~hg/.ssh/authorized_keys</filename> for each one. This is redone
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   480
automatically whenever a change is pushed to <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   481
class='directory'>hgadmin</filename>.
126
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   482
</para>
263
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   483
</section>
126
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   484
<section>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   485
<title>Security</title>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   486
<para>
151
5758cf47ff43 cleanups to the security section
Paul Crowley <paul@lshift.net>
parents: 150
diff changeset
   487
mercurial-server relies entirely on <command>sshd</command> to grant access to remote users.
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   488
As a result, it runs no daemons, installs no setuid programs, and no part
151
5758cf47ff43 cleanups to the security section
Paul Crowley <paul@lshift.net>
parents: 150
diff changeset
   489
of it runs as <systemitem
5758cf47ff43 cleanups to the security section
Paul Crowley <paul@lshift.net>
parents: 150
diff changeset
   490
class="username">root</systemitem> except the install process: all programs run as the user
5758cf47ff43 cleanups to the security section
Paul Crowley <paul@lshift.net>
parents: 150
diff changeset
   491
<systemitem
5758cf47ff43 cleanups to the security section
Paul Crowley <paul@lshift.net>
parents: 150
diff changeset
   492
class="username">hg</systemitem>. Any attack on mercurial-server can only be started if the attacker
137
5bcd5a5e4220 Tweak security para
Paul Crowley <paul@lshift.net>
parents: 136
diff changeset
   493
already has a public key in <filename>~hg/.ssh/authorized_keys</filename>,
151
5758cf47ff43 cleanups to the security section
Paul Crowley <paul@lshift.net>
parents: 150
diff changeset
   494
otherwise <command>sshd</command> will bar the way.
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   495
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   496
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   497
No matter what command the user tries to run on the remote system via SSH,
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   498
mercurial-server is run. It parses the command line the user asked for, and
151
5758cf47ff43 cleanups to the security section
Paul Crowley <paul@lshift.net>
parents: 150
diff changeset
   499
interprets and runs the corresponding operation itself if access is
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   500
allowed, so users can only read and add to history within repositories;
151
5758cf47ff43 cleanups to the security section
Paul Crowley <paul@lshift.net>
parents: 150
diff changeset
   501
they cannot run any other command. In addition, every push and pull is
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   502
logged with a datestamp, changeset ID and the key that performed the
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   503
operation.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   504
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   505
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   506
However, while the first paragraph holds no matter what bugs
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   507
mercurial-server contains, the second depends on the relevant code being
263
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   508
correct; though the entire codebase is short, like all software mercurial-server may harbour bugs. Backups are essential!
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   509
</para>
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   510
</section>
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   511
<section>
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   512
<title>Logging</title>
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   513
<para>
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   514
Every successful access is logged in a file called
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   515
<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
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   516
UTC ISO 8601 time, the operation ("push" or "pull"), the path to the key as
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   517
used in the access rules, the SSH connection information (including the source IP address), and the hex changeset IDs.
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   518
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   519
</section>
263
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   520
<section>
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   521
<title>Paths and configuration</title>
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   522
<para>
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   523
For security reasons, all mercurial-server code runs as the <systemitem
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   524
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>.
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   525
</para>
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   526
<para>
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   527
By creating such a file with suitable entries, you can run mercurial-server as a user other than <systemitem
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   528
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.
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   529
</para>
345
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   530
<para>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   531
At install time the following <filename>~hg/.mercurial-server</filename> file is used:
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   532
</para>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   533
<programlisting># WARNING: a .mercurial-server file in your home directory means
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   534
# that refresh-auth can and will trash your ~/.ssh/authorized_keys file.
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   535
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   536
[paths]
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   537
repos = ~/repos
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   538
authorized_keys = ~/.ssh/authorized_keys
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   539
keys = /etc/mercurial-server/keys:~/repos/hgadmin/keys
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   540
access = /etc/mercurial-server/access.conf:~/repos/hgadmin/access.conf
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   541
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   542
[exceptions]
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   543
# Allow the creation of mq repositories by default
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   544
allowdots = .hg/patches
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   545
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   546
[env]
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   547
# Use a different hgrc for remote pulls - this way you can set
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   548
# up access.py for everything at once without affecting local operations
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   549
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   550
HGRCPATH = /etc/mercurial-server/remote-hgrc.d
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   551
</programlisting>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   552
<para>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   553
The meaning of the entries are:
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   554
</para>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   555
<itemizedlist>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   556
<listitem>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   557
<para><literal>[paths]</literal></para>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   558
<itemizedlist>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   559
<listitem>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   560
<para><literal>repos</literal>: directory under which all repositories are
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   561
found. No remote user can reference any repo not under this directory.
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   562
Here and throughout this section, where a path begins with
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   563
<literal>~/</literal> the home directory is substituted - ie the
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   564
directory in which the <filename>.mercurial-server</filename> file
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   565
was found.</para>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   566
</listitem>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   567
<listitem>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   568
<para><literal>authorized_keys</literal>: this is the file that will be rewritten
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   569
by refresh-auth, or whenever a checkin to the <literal>hgadmin</literal> repository is pushed.</para>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   570
</listitem>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   571
<listitem>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   572
<para><literal>keys</literal>: directories to scan for keys when rewriting
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   573
<filename>authorized_keys</filename>.</para>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   574
</listitem>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   575
<listitem>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   576
<para><literal>access</literal>: files to read to determine the access rules.
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   577
The files are effectively concatenated together in the order given.</para>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   578
</listitem>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   579
</itemizedlist>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   580
</listitem>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   581
<listitem>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   582
<para><literal>[exceptions]</literal></para>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   583
<itemizedlist>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   584
<listitem>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   585
<para><literal>allowdots</literal>: paths to allow even though they
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   586
begin with dots.  Dots at the start of a pathname component are
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   587
disallowed unless they exactly match one of the tails given in this
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   588
colon-separated list.  The given exception allows MQ repositories
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   589
to be pushed.</para>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   590
</listitem>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   591
</itemizedlist>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   592
</listitem>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   593
<listitem>
374
7a1d6b228af6 Set user as login name
Cédric Krier <ced@b2ck.com>
parents: 372
diff changeset
   594
<para><literal>[users]</literal></para>
7a1d6b228af6 Set user as login name
Cédric Krier <ced@b2ck.com>
parents: 372
diff changeset
   595
<itemizedlist>
7a1d6b228af6 Set user as login name
Cédric Krier <ced@b2ck.com>
parents: 372
diff changeset
   596
<listitem>
7a1d6b228af6 Set user as login name
Cédric Krier <ced@b2ck.com>
parents: 372
diff changeset
   597
<para><literal>index</literal>: the index of the key path that contains the
7a1d6b228af6 Set user as login name
Cédric Krier <ced@b2ck.com>
parents: 372
diff changeset
   598
user login.  If <literal>-1</literal>, the full path is used.</para>
7a1d6b228af6 Set user as login name
Cédric Krier <ced@b2ck.com>
parents: 372
diff changeset
   599
</listitem>
7a1d6b228af6 Set user as login name
Cédric Krier <ced@b2ck.com>
parents: 372
diff changeset
   600
</itemizedlist>
7a1d6b228af6 Set user as login name
Cédric Krier <ced@b2ck.com>
parents: 372
diff changeset
   601
</listitem>
7a1d6b228af6 Set user as login name
Cédric Krier <ced@b2ck.com>
parents: 372
diff changeset
   602
<listitem>
345
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   603
<para><literal>[env]</literal>: all entries in here are added to the Unix environment
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   604
when users connect.  The keys are converted to all-upper-case. </para>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   605
<itemizedlist>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   606
<listitem>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   607
<para><literal>HGRCPATH</literal>: set the path that Mercurial uses to search for
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   608
configuration files.  At install time config files are placed on this path
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   609
which set up access control and logging.</para>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   610
</listitem>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   611
</itemizedlist>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   612
</listitem>
f06d9816272d Documentation update
Paul Crowley <paul@lshift.net>
parents: 311
diff changeset
   613
</itemizedlist>
252
75acaf1b1216 Add section on logging, merge later sections
Paul Crowley <paul@lshift.net>
parents: 238
diff changeset
   614
</section>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   615
<section>
263
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   616
<title>License</title>
129
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   617
<para>
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   618
This program is free software; you can redistribute it and/or modify it
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   619
under the terms of the GNU General Public License as published by the Free
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   620
Software Foundation; either version 2 of the License, or (at your option)
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   621
any later version.
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   622
</para>
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   623
<para>
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   624
This program is distributed in the hope that it will be useful, but
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   625
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   626
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   627
more details.
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   628
</para>
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   629
<para>
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   630
You should have received a copy of the GNU General Public License along
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   631
with this program; if not, write to the Free Software Foundation, Inc., 51
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   632
Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   633
</para>
263
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   634
</section>
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   635
<section>
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   636
<title>Thanks</title>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   637
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   638
Thanks for reading this far. If you use mercurial-server, please tell me about
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   639
it.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   640
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   641
<para>
359
a14142919eb3 Bump year in manual
Paul Crowley <paul@lshift.net>
parents: 358
diff changeset
   642
Paul Crowley, <email>paul@lshift.net</email>, 2012
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   643
</para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   644
</section>
263
9f7ad3a71c90 Bump version number to 1.1; big documentation update; correct dates;
Paul Crowley <paul@lshift.net>
parents: 252
diff changeset
   645
</section>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   646
</article>