doc/manual.docbook
author Paul Crowley <paul@lshift.net>
Wed, 14 Oct 2009 15:22:29 +0100
changeset 123 20b54500a618
parent 122 05b676684c7e
child 124 6836769f5134
permissions -rw-r--r--
Call the other user "Sam"
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>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    15
mercurial-server is software for Debian and Ubuntu systems which gives your
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    16
developers remote read/write access to <link
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    17
xlink:href="http://hg-scm.org/">Mercurial</link> repositories using SSH public
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    18
key authentication; it provides convenient and fine-grained key management
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    19
and access control.
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
<para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    22
mercurial-server is the easiest and most secure way for several developers
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    23
to have read/write access to a central repository, but that's not the only
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    24
way for several people to work on the same project using Mercurial; you
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    25
should be familiar with the <link
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    26
xlink:href="http://mercurial.selenic.com/wiki/MultipleCommitters">other ways of
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    27
handling multiple commiters</link> before deciding to use this.
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    28
</para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    29
<para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    30
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
    31
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
    32
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
    33
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
    34
</para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    35
<section>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    36
<title>Legalese</title>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    37
<para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    38
This program is free software; you can redistribute it and/or modify it
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    39
under the terms of the GNU General Public License as published by the Free
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    40
Software Foundation; either version 2 of the License, or (at your option)
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    41
any later version.
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    42
</para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    43
<para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    44
This program is distributed in the hope that it will be useful, but
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    45
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    46
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    47
more details.
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    48
</para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    49
<para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    50
You should have received a copy of the GNU General Public License along
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    51
with this program; if not, write to the Free Software Foundation, Inc., 51
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    52
Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    53
</para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    54
</section>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    55
</section>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    56
<section>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    57
<title>Step by step</title>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    58
<para>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    59
mercurial-server authenticates users not using passwords but using <link
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    60
xlink:href="http://sial.org/howto/openssh/publickey-auth/">SSH public
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    61
keys</link>; everyone who wants access to a mercurial-server repository
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    62
will need such a key, so you'll need to familiarize yourself with them
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    63
before proceeding. In combination with <command>ssh-agent</command> (or
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    64
equivalents such as the Windows program <link
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    65
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
    66
this means that users will not need to type in a password to access the
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    67
repository.
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    68
</para>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    69
<section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    70
<title>Creating a repository host</title>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    71
<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
    72
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
    73
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
    74
<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
    75
install mercurial-server on <systemitem
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    76
class="systemname">repository-host</systemitem>. First, you'll need to
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    77
create an SSH public key if you haven't already. You should consult your
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    78
system documentation on how to do this, but it should look something like
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
    79
this.
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    80
</para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    81
<screen>
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
    82
<computeroutput>jay@my-workstation:~$ </computeroutput><userinput>ssh-keygen</userinput>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    83
<computeroutput>Generating public/private rsa key pair.
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    84
Enter passphrase (empty for no passphrase): 
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    85
Enter same passphrase again: 
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
    86
Your identification has been saved in /home/jay/.ssh/id_rsa.
05b676684c7e Call the user jay rather than user, and use pat instead of other-user
Paul Crowley <paul@lshift.net>
parents: 121
diff changeset
    87
Your public key has been saved in /home/jay/.ssh/id_rsa.pub.
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    88
The key fingerprint is:
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
8b:aa:0a:98:fe:e7:84:48:a3:fe:5f:31:4b:16:e6:0b jay@my-workstation
05b676684c7e Call the user jay rather than user, and use pat instead of other-user
Paul Crowley <paul@lshift.net>
parents: 121
diff changeset
    90
jay@my-workstation:~$ </computeroutput><userinput>ssh-add</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
    91
<computeroutput>Enter passphrase for /home/jay/.ssh/id_rsa: 
05b676684c7e Call the user jay rather than user, and use pat instead of other-user
Paul Crowley <paul@lshift.net>
parents: 121
diff changeset
    92
Identity added: /home/jay/.ssh/id_rsa (/home/jay/.ssh/id_rsa)
05b676684c7e Call the user jay rather than user, and use pat instead of other-user
Paul Crowley <paul@lshift.net>
parents: 121
diff changeset
    93
jay@my-workstation:~$ </computeroutput></screen>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    94
<para>Now copy the files you're going to need over to your target system, and install mercurial-server</para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    95
<screen>
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
    96
<computeroutput>jay@my-workstation:~$ </computeroutput><userinput>ssh-copy-id repository-host</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
    97
<computeroutput>jay@repository-host's password:
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    98
Now try logging into the machine, with "ssh 'repository-host'", and check in:
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    99
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   100
  .ssh/authorized_keys
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   101
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   102
to make sure we haven't added extra keys that you weren't expecting.
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
   103
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
   104
<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
   105
jay@my-workstation:~$ </computeroutput><userinput>ssh -A repository-host</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
   106
<computeroutput>jay@repository-host:~$ </computeroutput><userinput>sudo dpkg -i ../mercurial-server_0.6.1_amd64.deb</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
   107
<computeroutput>[sudo] password for jay: 
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   108
Selecting previously deselected package mercurial-server.
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   109
(Reading database ... 144805 files and directories currently installed.)
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   110
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
   111
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
   112
jay@repository-host:~$ </computeroutput></screen>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   113
<para>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   114
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
   115
</para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   116
<screen>
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
   117
<computeroutput>jay@repository-host:~$ </computeroutput><userinput>ssh-add -L > my-key</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
   118
<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
   119
<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
   120
<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
   121
<computeroutput>jay@repository-host:~$ </computeroutput><userinput>exit</userinput>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   122
<computeroutput>Connection to shell 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
   123
jay@my-workstation:~$ </computeroutput></screen>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   124
<para>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   125
You can now create repositories on the remote machine and have complete
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   126
read-write access to all of them; you need never log on to <systemitem
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   127
class="systemname">repository-host</systemitem> again.
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   128
</para>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   129
</section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   130
<section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   131
<title>Creating repositories</title>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   132
<screen>
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
   133
<computeroutput>jay@my-workstation:~$ </computeroutput><userinput>cd my-mercurial-project</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
   134
<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
   135
<computeroutput>searching for changes
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   136
remote: adding changesets
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   137
remote: adding manifests
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   138
remote: adding file changes
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   139
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
   140
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
   141
<computeroutput>pulling from ssh://hg@repository-host/repository/name
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   142
searching for changes
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   143
no changes found
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
   144
jay@my-workstation:~/my-mercurial-project$ </computeroutput></screen>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   145
</section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   146
<section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   147
<title>Adding other users</title>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   148
<para>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   149
As things stand, no-one but you has any access to any repositories you
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   150
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
   151
copy of their SSH public key; we'll assume you have that key in
123
20b54500a618 Call the other user "Sam"
Paul Crowley <paul@lshift.net>
parents: 122
diff changeset
   152
<filename>~/sam-key.pub</filename>. You could give them access by
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   153
logging into <systemitem class="systemname">repository-host</systemitem>,
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   154
putting the key in the right place under <filename
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   155
class='directory'>/etc/mercurial-server/keys</filename>, and re-running
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   156
<userinput>sudo -u hg /usr/share/mercurial-server/refresh-auth</userinput>.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   157
However, there's a more convenient way.
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   158
</para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   159
<screen>
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
   160
<computeroutput>jay@my-workstation:~/my-mercurial-project$ </computeroutput><userinput>cd ..</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
   161
<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
   162
<computeroutput>destination directory: hgadmin
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   163
no changes found
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   164
updating working directory
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   165
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
   166
jay@my-workstation:~$ </computeroutput><userinput>cd hgadmin</userinput>
123
20b54500a618 Call the other user "Sam"
Paul Crowley <paul@lshift.net>
parents: 122
diff changeset
   167
<computeroutput>jay@my-workstation:~/hgadmin$ </computeroutput><userinput>mkdir -p keys/users/sam</userinput>
20b54500a618 Call the other user "Sam"
Paul Crowley <paul@lshift.net>
parents: 122
diff changeset
   168
<computeroutput>jay@my-workstation:~/hgadmin$ </computeroutput><userinput>cp ~/other-users-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
   169
<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
   170
<computeroutput>adding keys/users/sam/their-workstation
20b54500a618 Call the other user "Sam"
Paul Crowley <paul@lshift.net>
parents: 122
diff changeset
   171
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
   172
<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
   173
<computeroutput>pushing to ssh://hg@repository-host/hgadmin
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   174
searching for changes
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   175
remote: adding changesets
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   176
remote: adding manifests
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   177
remote: adding file changes
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   178
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
   179
jay@my-workstation:~/hgadmin$ </computeroutput></screen>
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   180
<para>
123
20b54500a618 Call the other user "Sam"
Paul Crowley <paul@lshift.net>
parents: 122
diff changeset
   181
Sam can now read and write to your
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   182
<literal>ssh://hg@repository-host/repository/name</literal> repository.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   183
Most other changes to access control can be made simply by making and
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   184
pushing changes to <literal>hgadmin</literal>, and you can use Mercurial to
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   185
cooperate with other root users in the normal way.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   186
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   187
</section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   188
<section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   189
<title>Basic access control</title>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   190
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   191
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
   192
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   193
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   194
Root users can edit <literal>hgadmin</literal>, create new repositories and read and write to existing ones.  Normal users cannot access <literal>hgadmin</literal> or create new repositories, but they can read and write to any other repository.  This is only the default configuration; for more advanced configuration read <xref linkend="accesscontrol"/>.
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
</section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   197
</section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   198
<section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   199
<title>How mercurial-server works</title>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   200
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   201
All of the repositories controlled by mercurial-server are owned by a
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   202
single user, the <literal>hg</literal> user, which is why all URLs for
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   203
mercurial-server repositories start with <literal>ssh://hg@...</literal>.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   204
Each SSH key that has access to the repository has an entry in
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   205
<filename>~hg/.ssh/authorized_keys</filename>; this is how the SSH daemon
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   206
knows to give that key access. When the user connects over SSH, their
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   207
commands are run in a specially crafted restricted shell; this shell knows
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   208
which key was used to connect, determines what the user is trying to do,
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   209
and checks the access rules to decide whether to allow it.  
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
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   212
This restricted shell also ensures that certain Mercurial extensions are
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   213
loaded when the user acts on a repository; these extensions check the
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   214
access control rules for any changeset that the user tries to commit, and
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   215
log all pushes and pulls into a per-repository access log.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   216
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   217
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   218
<command>refresh-auth</command> recurses through the <filename
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   219
class='directory'>/etc/mercurial-server/keys</filename> and the <filename
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   220
class='directory'>keys</filename> directory in the
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   221
<literal>hgadmin</literal> repository, creating an entry in
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   222
<filename>~hg/.ssh/authorized_keys</filename> for each one. This is redone
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   223
automatically whenever a change is pushed to <literal>hgadmin</literal>.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   224
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   225
</section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   226
<section id="accesscontrol">
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   227
<title>Access control</title>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   228
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   229
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 <literal>widget</literal> repository, but no other.  We first copy Pat's SSH public key into the <filename
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   230
class='directory'>keys/widget/pat</filename> directory in <literal>hgadmin</literal>.  Now mercurial-server knows about Pat's key, but will give Pat no access to anything because the key is not under either <filename
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   231
class='directory'>keys/root</filename> or <filename
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   232
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 <literal>hgadmin</literal> called <filename>access.conf</filename>, with the following contents:</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   233
<programlisting>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   234
    write repo=widget user=widget/**
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   235
</programlisting>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   236
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   237
Pat will have read and write access as soon as we add, commit, and push these files.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   238
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   239
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   240
Each line of access.conf has the following syntax:
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   241
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   242
<programlisting>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   243
<replaceable>rule</replaceable> <replaceable>condition</replaceable> <replaceable>condition...</replaceable>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   244
</programlisting>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   245
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   246
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
   247
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   248
<itemizedlist>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   249
<listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   250
<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
   251
</listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   252
<listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   253
<literal>write</literal>: allow reads and writes
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   254
</listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   255
<listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   256
<literal>read</literal>: allow only read operations
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   257
</listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   258
<listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   259
<literal>deny</literal>: deny all requests
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   260
</listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   261
</itemizedlist>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   262
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   263
When considering a request, mercurial-server steps through all the rules in <filename>/etc/mercurial-server/access.conf</filename> and then all the rules in <filename>access.conf</filename> in <literal>hgadmin</literal> looking for a rule which matches on every condition.  If it does not find such a rule, it denies the request; otherwise it checks whether the rule grants sufficient privilege to allow it.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   264
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   265
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   266
By default, <filename>/etc/mercurial-server/access.conf</filename> has the following rules:
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   267
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   268
<programlisting>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   269
    init user=root/**
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   270
    deny repo=hgadmin
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   271
    write user=users/**
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   272
</programlisting>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   273
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   274
These rules ensure that root users can do any operation on any repository, that no other users can access the <literal>hgadmin</literal> repository, and that those with keys in <filename class='directory'>keys/users</filename> can read or write to any repository but not create repositories.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   275
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   276
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   277
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
   278
important conditions are
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   279
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   280
<itemizedlist>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   281
<listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   282
<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
   283
</listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   284
<listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   285
<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
   286
</listitem>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   287
</itemizedlist>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   288
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   289
"*" 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
   290
want. More precisely, "*" matches zero or more characters not including "/"
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   291
while "**" matches zero or more characters including "/".
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   292
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   293
<section>
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   294
<title>File and branch conditions</title>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   295
<para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   296
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
   297
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
   298
on. </para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   299
<caution>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   300
The way these conditions work is subtle and can be counterintuitive - if
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   301
you want to keep things simple, stick to user and repo conditions, and then
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   302
things are likely to work the way you would expect.
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   303
</caution>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   304
<para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   305
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
   306
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
   307
</para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   308
<itemizedlist>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   309
<listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   310
<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
   311
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   312
<listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   313
<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
   314
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   315
</itemizedlist>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   316
<para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   317
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
   318
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
   319
</para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   320
<para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   321
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
   322
</para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   323
<itemizedlist>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   324
<listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   325
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
   326
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   327
<listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   328
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
   329
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   330
<listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   331
Whether to allow a changeset, which is on a some branch
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   332
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   333
<listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   334
Whether to allow a changeset which changes a particular file
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   335
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   336
</itemizedlist>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   337
<para>
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   338
When the first two of these decisions are being made, nothing is known
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   339
about what files might be changed, and so all file and branch conditions
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   340
automatically succeed for the purpose of such decisions. This means that
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   341
doing tricky things with file conditions can have counterintuitive
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   342
consequences:
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   343
</para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   344
<itemizedlist>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   345
<listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   346
<para>You cannot limit read access to a subset of a repository with a "read"
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   347
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
   348
all of it and its full history. Such a rule can only have the effect of
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   349
masking a later "write" rule, as in this example:</para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   350
<programlisting>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   351
   read repo=specialrepo file=dontwritethis
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   352
   write repo=specialrepo
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   353
</programlisting>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   354
<para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   355
allows all users to read specialrepo, and to write to all files
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   356
<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
   357
<filename>dontwritethis</filename> will be rejected.
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   358
</para>
121
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   359
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   360
<listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   361
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
   362
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   363
<listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   364
<para>Don't try to deny write access to a particular file on a particular
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   365
branch - a developer can write to the file on another branch and then merge
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   366
it in. Either deny all writes to the branch from that user, or allow them
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   367
to write to all the files they can write to on any branch. In other words,
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   368
something like this will have the intended effect:
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   369
</para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   370
<programlisting>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   371
   write user=docs/* branch=docs file=docs/*
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   372
</programlisting>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   373
<para>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   374
But something like this will not have the intended effect; it will
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   375
effectively allow these users to write to any file on any branch, by
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   376
writing it to "docs" first:
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
<programlisting>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   379
  write user=docs/* branch=docs
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   380
  write user=docs/* file=docs/*
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   381
  read user=docs/*
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   382
</programlisting>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   383
</listitem>
62185dc7d0c9 Document file and branch conditions in Docbook
Paul Crowley <paul@lshift.net>
parents: 120
diff changeset
   384
</itemizedlist>
120
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   385
</section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   386
</section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   387
<section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   388
<title>Security</title>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   389
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   390
mercurial-server relies entirely on sshd to grant access to remote users.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   391
As a result, it runs no daemons, installs no setuid programs, and no part
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   392
of it runs as root except the install process: all programs run as the user
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   393
hg. And any attack on mercurial-server can only be started if the Bad Guys
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   394
already have a public key in <filename>~hg/.ssh/authorized_keys</filename>,
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   395
otherwise sshd will bar the way.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   396
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   397
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   398
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
   399
mercurial-server is run. It parses the command line the user asked for, and
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   400
interprets and runs the corresponding hg operation itself if access is
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   401
allowed, so users can only read and add to history within repositories;
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   402
they cannot run any other hg command. In addition, every push and pull is
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   403
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
   404
operation.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   405
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   406
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   407
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
   408
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
   409
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
   410
new program and may harbour bugs. Backups are essential!
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   411
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   412
</section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   413
<section>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   414
<title>Thanks</title>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   415
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   416
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
   417
it.
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   418
</para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   419
<para>
16056a9015f3 Huge update to docbook docs
Paul Crowley <paul@lshift.net>
parents: 119
diff changeset
   420
Paul Crowley, <email>paul@lshift.net</email>, 2009
119
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   421
</para>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   422
</section>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   423
</article>
40a287c95661 Start work on a docbook manual
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   424