doc/manual.docbook
author Paul Crowley <paul@lshift.net>
Thu, 15 Oct 2009 11:53:14 +0100
changeset 154 45dac87ae794
parent 153 aa57f48c7585
child 155 3bff97f72a33
permissions -rw-r--r--
Repository names are directories
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>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
     7
  <copyright><year>2009</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.
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    19
</para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    20
<para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    21
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
    22
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
    23
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
    24
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
    25
</para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    26
</section>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    27
<section>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    28
<title>Step by step</title>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    29
<para>
134
525976d2827c Change the way we link to SSH tutorial
Paul Crowley <paul@lshift.net>
parents: 133
diff changeset
    30
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
    31
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
    32
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
    33
equivalents such as the Windows program <link
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    34
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
    35
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
    36
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
    37
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
    38
Key Authentication tutorial</link> may be helpful.
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    39
</para>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    40
<section>
131
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
    41
<title>Installing mercurial-server</title>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    42
<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
    43
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
    44
class="username">jay</systemitem>, that you usually sit at a machine called
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    45
<systemitem class="systemname">my-workstation</systemitem> and you wish to
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    46
install mercurial-server on <systemitem
131
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
    47
class="systemname">repository-host</systemitem>. 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
134
525976d2827c Change the way we link to SSH tutorial
Paul Crowley <paul@lshift.net>
parents: 133
diff changeset
    48
class="systemname">repository-host</systemitem>.  
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    49
</para>
131
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
    50
<para>First install mercurial-server on <systemitem
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
    51
class="systemname">repository-host</systemitem>:</para>
142
fb64f9ac44c5 Remove blank lines before screen output
Paul Crowley <paul@lshift.net>
parents: 141
diff changeset
    52
<screen><computeroutput>jay@my-workstation:~$ </computeroutput><userinput>scp mercurial-server_0.6.1_amd64.deb repository-host:</userinput>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    53
<computeroutput>mercurial-server_0.6.1_amd64.deb 100%
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
    54
jay@my-workstation:~$ </computeroutput><userinput>ssh -A repository-host</userinput>
138
44ee9dc3bba9 Remove cut/paste error in commands
Paul Crowley <paul@lshift.net>
parents: 137
diff changeset
    55
<computeroutput>jay@repository-host:~$ </computeroutput><userinput>sudo dpkg -i mercurial-server_0.6.1_amd64.deb</userinput>
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
    56
<computeroutput>[sudo] password for jay: 
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    57
Selecting previously deselected package mercurial-server.
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    58
(Reading database ... 144805 files and directories currently installed.)
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    59
Unpacking mercurial-server (from .../mercurial-server_0.6.1_amd64.deb) ...
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    60
Setting up mercurial-server (0.6.1) ...
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
    61
jay@repository-host:~$ </computeroutput></screen>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    62
<para>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    63
mercurial-server is now installed on the repository host.  Next, we need to give you permission to access its repositories.
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    64
</para>
142
fb64f9ac44c5 Remove blank lines before screen output
Paul Crowley <paul@lshift.net>
parents: 141
diff changeset
    65
<screen><computeroutput>jay@repository-host:~$ </computeroutput><userinput>ssh-add -L > my-key</userinput>
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
    66
<computeroutput>jay@repository-host:~$ </computeroutput><userinput>sudo mkdir -p /etc/mercurial-server/keys/root/jay</userinput>
05b676684c7e Call the user jay rather than user, and use pat instead of other-user
Paul Crowley <paul@lshift.net>
parents: 121
diff changeset
    67
<computeroutput>jay@repository-host:~$ </computeroutput><userinput>sudo cp my-key /etc/mercurial-server/keys/root/jay/my-workstation</userinput>
05b676684c7e Call the user jay rather than user, and use pat instead of other-user
Paul Crowley <paul@lshift.net>
parents: 121
diff changeset
    68
<computeroutput>jay@repository-host:~$ </computeroutput><userinput>sudo -u hg /usr/share/mercurial-server/refresh-auth</userinput>
05b676684c7e Call the user jay rather than user, and use pat instead of other-user
Paul Crowley <paul@lshift.net>
parents: 121
diff changeset
    69
<computeroutput>jay@repository-host:~$ </computeroutput><userinput>exit</userinput>
141
e326e29b48ab fix output that should read "repository-host"
Paul Crowley <paul@lshift.net>
parents: 138
diff changeset
    70
<computeroutput>Connection to repository-host closed.
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
    71
jay@my-workstation:~$ </computeroutput></screen>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    72
<para>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    73
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
    74
read-write access to all of them.
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    75
</para>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    76
</section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    77
<section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    78
<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
    79
<para>
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
    80
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
    81
</para>
142
fb64f9ac44c5 Remove blank lines before screen output
Paul Crowley <paul@lshift.net>
parents: 141
diff changeset
    82
<screen><computeroutput>jay@my-workstation:~$ </computeroutput><userinput>cd my-mercurial-project</userinput>
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
    83
<computeroutput>jay@my-workstation:~/my-mercurial-project$ </computeroutput><userinput>hg clone . ssh://hg@repository-host/repository/name</userinput>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    84
<computeroutput>searching for changes
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    85
remote: adding changesets
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    86
remote: adding manifests
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    87
remote: adding file changes
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    88
remote: added 119 changesets with 284 changes to 61 files
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
    89
jay@my-workstation:~/my-mercurial-project$ </computeroutput><userinput>hg pull ssh://hg@repository-host/repository/name</userinput>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    90
<computeroutput>pulling from ssh://hg@repository-host/repository/name
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    91
searching for changes
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    92
no changes found
136
492bc9e536e1 Move the cd up one section
Paul Crowley <paul@lshift.net>
parents: 135
diff changeset
    93
<computeroutput>jay@my-workstation:~/my-mercurial-project$ </computeroutput><userinput>cd ..</userinput>
492bc9e536e1 Move the cd up one section
Paul Crowley <paul@lshift.net>
parents: 135
diff changeset
    94
jay@my-workstation:~$ </computeroutput></screen>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    95
</section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    96
<section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    97
<title>Adding other users</title>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    98
<para>
145
bc2b93fa662d tiny reword
Paul Crowley <paul@lshift.net>
parents: 144
diff changeset
    99
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
   100
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
   101
copy of their SSH public key; we'll assume you have that key in
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   102
<filename>~/sam-key.pub</filename>.  To manage access, you make changes to the special <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   103
class='directory'>hgadmin</filename> repository.
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   104
</para>
142
fb64f9ac44c5 Remove blank lines before screen output
Paul Crowley <paul@lshift.net>
parents: 141
diff changeset
   105
<screen><computeroutput>jay@my-workstation:~$ </computeroutput><userinput>hg clone ssh://hg@repository-host/hgadmin</userinput>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   106
<computeroutput>destination directory: hgadmin
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   107
no changes found
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   108
updating working directory
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   109
0 files updated, 0 files merged, 0 files removed, 0 files unresolved
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
   110
jay@my-workstation:~$ </computeroutput><userinput>cd hgadmin</userinput>
123
20b54500a618 Call the other user "Sam"
Paul Crowley <paul@lshift.net>
parents: 122
diff changeset
   111
<computeroutput>jay@my-workstation:~/hgadmin$ </computeroutput><userinput>mkdir -p keys/users/sam</userinput>
135
298c6ea6295c Missed something in change to sam
Paul Crowley <paul@lshift.net>
parents: 134
diff changeset
   112
<computeroutput>jay@my-workstation:~/hgadmin$ </computeroutput><userinput>cp ~/sam-key.pub keys/users/sam/their-workstation</userinput>
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
   113
<computeroutput>jay@my-workstation:~/hgadmin$ </computeroutput><userinput>hg add</userinput>
123
20b54500a618 Call the other user "Sam"
Paul Crowley <paul@lshift.net>
parents: 122
diff changeset
   114
<computeroutput>adding keys/users/sam/their-workstation
20b54500a618 Call the other user "Sam"
Paul Crowley <paul@lshift.net>
parents: 122
diff changeset
   115
jay@my-workstation:~/hgadmin$ </computeroutput><userinput>hg commit -m "Add Sam's key'"</userinput>
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
   116
<computeroutput>jay@my-workstation:~/hgadmin$ </computeroutput><userinput>hg push</userinput>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   117
<computeroutput>pushing to ssh://hg@repository-host/hgadmin
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   118
searching for changes
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   119
remote: adding changesets
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   120
remote: adding manifests
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   121
remote: adding file changes
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   122
remote: added 1 changesets with 1 changes to 1 files
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
   123
jay@my-workstation:~/hgadmin$ </computeroutput></screen>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   124
<para>
123
20b54500a618 Call the other user "Sam"
Paul Crowley <paul@lshift.net>
parents: 122
diff changeset
   125
Sam can now read and write to your
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   126
<literal>ssh://hg@repository-host/repository/name</literal> repository.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   127
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
   128
pushing changes to <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   129
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
   130
cooperate with other root users in the normal way.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   131
</para>
131
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
   132
<para>
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
   133
If you prefer, you could give them access by
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
   134
logging into <systemitem class="systemname">repository-host</systemitem>,
e8bf13d06582 Assume they have SSH set up; talk about hgadmin first
Paul Crowley <paul@lshift.net>
parents: 130
diff changeset
   135
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
   136
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
   137
<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
   138
However, using <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   139
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
   140
</para>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   141
</section>
132
a5850a63390f Move basic access control to the start of access control
Paul Crowley <paul@lshift.net>
parents: 131
diff changeset
   142
</section>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   143
<section>
132
a5850a63390f Move basic access control to the start of access control
Paul Crowley <paul@lshift.net>
parents: 131
diff changeset
   144
<title>Access control</title>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   145
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   146
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
   147
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   148
<para>
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   149
Root users can edit <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   150
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
   151
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
   152
</para>
132
a5850a63390f Move basic access control to the start of access control
Paul Crowley <paul@lshift.net>
parents: 131
diff changeset
   153
<section>
a5850a63390f Move basic access control to the start of access control
Paul Crowley <paul@lshift.net>
parents: 131
diff changeset
   154
<title>Using access.conf</title>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   155
<para>
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   156
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
   157
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
   158
class='directory'>keys/pat</filename> directory in <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   159
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
   160
class='directory'>keys/root</filename> or <filename
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   161
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
   162
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
   163
<programlisting># Give Pat access to the "widget" repository
04e74d4b3822 Simplify Pat story
Paul Crowley <paul@lshift.net>
parents: 145
diff changeset
   164
write repo=widget user=pat
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   165
</programlisting>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   166
<para>
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   167
Pat will have read and write access to the <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   168
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
   169
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   170
<para>
124
6836769f5134 Forgot a filename tag
Paul Crowley <paul@lshift.net>
parents: 123
diff changeset
   171
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
   172
</para>
144
2dbaddde1fd5 programlisting also needs no initial blank lines
Paul Crowley <paul@lshift.net>
parents: 143
diff changeset
   173
<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
   174
</programlisting>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   175
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   176
Blank lines and lines that start with <literal>#</literal> are ignored. Rule is one of
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   177
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   178
<itemizedlist>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   179
<listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   180
<literal>init</literal>: allow reads, writes, and the creation of new repositories
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   181
</listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   182
<listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   183
<literal>write</literal>: allow reads and writes
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   184
</listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   185
<listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   186
<literal>read</literal>: allow only read operations
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   187
</listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   188
<listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   189
<literal>deny</literal>: deny all requests
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   190
</listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   191
</itemizedlist>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   192
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   193
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
   194
important conditions are
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   195
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   196
<itemizedlist>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   197
<listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   198
<code><literal>user=</literal><replaceable>globpattern</replaceable></code>: path to the user's key
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   199
</listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   200
<listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   201
<code><literal>repo=</literal><replaceable>globpattern</replaceable></code>: path to the repository
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   202
</listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   203
</itemizedlist>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   204
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   205
"*" only matches one directory level, where "**" matches as many as you
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   206
want. More precisely, "*" matches zero or more characters not including "/"
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   207
while "**" matches zero or more characters including "/". So
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   208
<code>projects/*</code> matches <filename
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   209
class='directory'>projects/foo</filename> but not <filename
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   210
class='directory'>projects/foo/bar</filename>, while
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   211
<code>projects/**</code> matches both.
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   212
</para>
147
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   213
<para>
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   214
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
   215
<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
   216
rules in <filename>access.conf</filename> in <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   217
class='directory'>hgadmin</filename>
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   218
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
   219
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
   220
either file, the request will be denied.
147
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   221
</para>
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   222
<para>
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   223
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
   224
following rules:
147
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   225
</para>
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   226
<programlisting>init user=root/**
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   227
deny repo=hgadmin
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   228
write user=users/**
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   229
</programlisting>
b29a7088b132 Move conditions next to rules
Paul Crowley <paul@lshift.net>
parents: 146
diff changeset
   230
<para>
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   231
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
   232
that no other users can access the <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   233
class='directory'>hgadmin</filename> repository,
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   234
and that those with keys in <filename
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   235
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
   236
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
   237
</para>
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   238
<itemizedlist>
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   239
<listitem>
153
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   240
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
   241
<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
   242
rule and so will be allowed.
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   243
</listitem>
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   244
<listitem>
153
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   245
User <filename class='directory'>root/jay</filename> changes repository
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   246
<filename class='directory'>hgadmin</filename>. Again, this matches the
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   247
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
   248
</listitem>
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   249
<listitem>
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   250
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
   251
repository <filename class='directory'>hgadmin</filename>. This does not
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   252
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
   253
</listitem>
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   254
<listitem>
153
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   255
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
   256
repository <filename class='directory'>sams-project</filename>. This does
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   257
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
   258
<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
   259
repositories, so the request will be denied.
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   260
</listitem>
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   261
<listitem>
153
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   262
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
   263
repository <filename class='directory'>projects/main</filename>. Again,
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   264
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
   265
</listitem>
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   266
<listitem>
153
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   267
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
   268
repository <filename class='directory'>widget</filename>. Until we change
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   269
the <filename>access.conf</filename> file in <filename
aa57f48c7585 replace generalities with specific examples
Paul Crowley <paul@lshift.net>
parents: 152
diff changeset
   270
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
   271
be denied.
152
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   272
</listitem>
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   273
<listitem>
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   274
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
   275
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
   276
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
   277
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
   278
work. This can't be changed.
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   279
</listitem>
f4688940fe15 Improvements to access.conf documentation
Paul Crowley <paul@lshift.net>
parents: 151
diff changeset
   280
</itemizedlist>
132
a5850a63390f Move basic access control to the start of access control
Paul Crowley <paul@lshift.net>
parents: 131
diff changeset
   281
</section>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   282
<section>
125
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   283
<title>/etc/mercurial-server and hgadmin</title>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   284
<para>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   285
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
   286
class='directory'>/etc/mercurial-server</filename> and its own <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   287
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
   288
</para>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   289
<itemizedlist>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   290
<listitem>
148
5da43b596bac Fixes to /etc/mercurial-server discussion
Paul Crowley <paul@lshift.net>
parents: 147
diff changeset
   291
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
   292
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
   293
</listitem>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   294
<listitem>
148
5da43b596bac Fixes to /etc/mercurial-server discussion
Paul Crowley <paul@lshift.net>
parents: 147
diff changeset
   295
<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
   296
for management with tools such as <link
125
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   297
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
   298
</listitem>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   299
<listitem>
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   300
If a change to <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   301
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
   302
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
   303
</listitem>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   304
<listitem>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   305
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
   306
</listitem>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   307
</itemizedlist>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   308
<para>
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   309
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
   310
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
   311
class='directory'>hgadmin</filename> changes.
125
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   312
</para>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   313
<para>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   314
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
   315
working you will usually want to use <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   316
class='directory'>hgadmin</filename> for most
125
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   317
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
   318
<filename>access.conf</filename> set up in <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   319
class='directory'>hgadmin</filename>, you
125
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   320
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
   321
of <filename class='directory'>/etc/mercurial-server/keys</filename>,
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   322
turning control entirely over to <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   323
class='directory'>hgadmin</filename>.
125
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   324
</para>
127
3262c0a53b59 Talk about remote-hgrc
Paul Crowley <paul@lshift.net>
parents: 126
diff changeset
   325
<para>
3262c0a53b59 Talk about remote-hgrc
Paul Crowley <paul@lshift.net>
parents: 126
diff changeset
   326
<filename>/etc/mercurial-server/remote-hgrc</filename> is in the
3262c0a53b59 Talk about remote-hgrc
Paul Crowley <paul@lshift.net>
parents: 126
diff changeset
   327
<systemitem>HGRCPATH</systemitem> for all remote access to mercurial-server
3262c0a53b59 Talk about remote-hgrc
Paul Crowley <paul@lshift.net>
parents: 126
diff changeset
   328
repositories. This file contains the hooks that mercurial-server uses for
3262c0a53b59 Talk about remote-hgrc
Paul Crowley <paul@lshift.net>
parents: 126
diff changeset
   329
access control and logging. You can add hooks to this file, but obviously
3262c0a53b59 Talk about remote-hgrc
Paul Crowley <paul@lshift.net>
parents: 126
diff changeset
   330
breaking the existing hooks will disable the relevant functionality and
3262c0a53b59 Talk about remote-hgrc
Paul Crowley <paul@lshift.net>
parents: 126
diff changeset
   331
isn't advisable.
3262c0a53b59 Talk about remote-hgrc
Paul Crowley <paul@lshift.net>
parents: 126
diff changeset
   332
</para>
125
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   333
</section>
fc5b8fc1040e Explain why we configure access twice
Paul Crowley <paul@lshift.net>
parents: 124
diff changeset
   334
<section>
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   335
<title>File and branch conditions</title>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   336
<para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   337
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
   338
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
   339
on. </para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   340
<caution>
128
b1610de4b6b1 Reword caution
Paul Crowley <paul@lshift.net>
parents: 127
diff changeset
   341
The way these conditions work is subtle and can be counterintuitive. Unless
b1610de4b6b1 Reword caution
Paul Crowley <paul@lshift.net>
parents: 127
diff changeset
   342
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
   343
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
   344
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
   345
</caution>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   346
<para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   347
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
   348
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
   349
</para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   350
<itemizedlist>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   351
<listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   352
<code><literal>file=</literal><replaceable>globpattern</replaceable></code>: file within the repo
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   353
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   354
<listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   355
<code><literal>branch=</literal><replaceable>globpattern</replaceable></code>: Mercurial branch name
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   356
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   357
</itemizedlist>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   358
<para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   359
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
   360
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
   361
</para>
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
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
   364
</para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   365
<itemizedlist>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   366
<listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   367
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
   368
</listitem>
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
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
   371
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   372
<listitem>
139
b7e78f9705e6 There are only three decisions, honest
Paul Crowley <paul@lshift.net>
parents: 138
diff changeset
   373
Whether to allow a changeset
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   374
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   375
</itemizedlist>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   376
<para>
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   377
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
   378
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
   379
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
   380
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
   381
<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
   382
to be allowed.
b7e78f9705e6 There are only three decisions, honest
Paul Crowley <paul@lshift.net>
parents: 138
diff changeset
   383
</para>
b7e78f9705e6 There are only three decisions, honest
Paul Crowley <paul@lshift.net>
parents: 138
diff changeset
   384
<para>
b7e78f9705e6 There are only three decisions, honest
Paul Crowley <paul@lshift.net>
parents: 138
diff changeset
   385
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
   386
counterintuitive consequences:
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   387
</para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   388
<itemizedlist>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   389
<listitem>
149
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   390
<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
   391
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
   392
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
   393
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
   394
<programlisting>read repo=specialrepo file=dontwritethis
2dbaddde1fd5 programlisting also needs no initial blank lines
Paul Crowley <paul@lshift.net>
parents: 143
diff changeset
   395
write repo=specialrepo
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   396
</programlisting>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   397
<para>
149
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   398
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
   399
<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
   400
<filename>dontwritethis</filename> will be rejected.
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   401
</para>
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   402
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   403
<listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   404
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
   405
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   406
<listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   407
<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
   408
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
   409
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
   410
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
   411
</para>
144
2dbaddde1fd5 programlisting also needs no initial blank lines
Paul Crowley <paul@lshift.net>
parents: 143
diff changeset
   412
<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
   413
</programlisting>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   414
<para>
149
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   415
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
   416
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
   417
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
   418
<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
   419
under the <filename class='directory'>docs</filename> directory. However,
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   420
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
   421
</para>
144
2dbaddde1fd5 programlisting also needs no initial blank lines
Paul Crowley <paul@lshift.net>
parents: 143
diff changeset
   422
<programlisting>write user=docs/* branch=docs
2dbaddde1fd5 programlisting also needs no initial blank lines
Paul Crowley <paul@lshift.net>
parents: 143
diff changeset
   423
write user=docs/* file=docs/*
2dbaddde1fd5 programlisting also needs no initial blank lines
Paul Crowley <paul@lshift.net>
parents: 143
diff changeset
   424
read user=docs/*
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   425
</programlisting>
149
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   426
<para>
dc4ed4edb458 Improvements to file conditions section
Paul Crowley <paul@lshift.net>
parents: 148
diff changeset
   427
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
   428
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
   429
</para>
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   430
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   431
</itemizedlist>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   432
</section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   433
</section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   434
<section>
126
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   435
<title>How mercurial-server works</title>
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   436
<para>
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   437
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
   438
single user, the <systemitem
5758cf47ff43 cleanups to the security section
Paul Crowley <paul@lshift.net>
parents: 150
diff changeset
   439
class="username">hg</systemitem> user, which is why all URLs for
126
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   440
mercurial-server repositories start with <literal>ssh://hg@...</literal>.
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   441
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
   442
<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
   443
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
   444
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
   445
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
   446
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
   447
Mercurial internally, without forking.
126
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   448
</para>
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   449
<para>
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   450
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
   451
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
   452
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
   453
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
   454
</para>
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   455
<para>
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   456
<command>refresh-auth</command> recurses through the <filename
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   457
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
   458
class='directory'>keys</filename> directory in the
154
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   459
<filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   460
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
   461
<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
   462
automatically whenever a change is pushed to <filename
45dac87ae794 Repository names are directories
Paul Crowley <paul@lshift.net>
parents: 153
diff changeset
   463
class='directory'>hgadmin</filename>.
126
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   464
</para>
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   465
</section>
fd7ebe95d8e5 Move how it works section later
Paul Crowley <paul@lshift.net>
parents: 125
diff changeset
   466
<section>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   467
<title>Security</title>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   468
<para>
151
5758cf47ff43 cleanups to the security section
Paul Crowley <paul@lshift.net>
parents: 150
diff changeset
   469
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
   470
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
   471
of it runs as <systemitem
5758cf47ff43 cleanups to the security section
Paul Crowley <paul@lshift.net>
parents: 150
diff changeset
   472
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
   473
<systemitem
5758cf47ff43 cleanups to the security section
Paul Crowley <paul@lshift.net>
parents: 150
diff changeset
   474
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
   475
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
   476
otherwise <command>sshd</command> will bar the way.
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   477
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   478
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   479
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
   480
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
   481
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
   482
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
   483
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
   484
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
   485
operation.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   486
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   487
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   488
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
   489
mercurial-server contains, the second depends on the relevant code being
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   490
correct; though the entire codebase is short, mercurial-server is a fairly
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   491
new program and may harbour bugs. Backups are essential!
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   492
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   493
</section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   494
<section>
129
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   495
<title>Legalese</title>
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   496
<para>
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   497
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
   498
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
   499
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
   500
any later version.
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   501
</para>
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   502
<para>
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   503
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
   504
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
   505
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
   506
more details.
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   507
</para>
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   508
<para>
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   509
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
   510
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
   511
Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   512
</para>
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   513
</section>
4d261ae3ba4f move legalese to the bottom
Paul Crowley <paul@lshift.net>
parents: 128
diff changeset
   514
<section>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   515
<title>Thanks</title>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   516
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   517
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
   518
it.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   519
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   520
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   521
Paul Crowley, <email>paul@lshift.net</email>, 2009
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   522
</para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   523
</section>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   524
</article>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   525