README
author Paul Crowley <paul@lshift.net>
Tue, 24 Feb 2009 10:31:29 +0000
changeset 64 60c557a63810
parent 63 b75177d307e5
child 66 2f0ea1163b9e
permissions -rw-r--r--
Ignore more
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
36
b3237aabd0fe Change the name to mercurial-server
Paul Crowley <paul@lshift.net>
parents: 30
diff changeset
     1
mercurial-server
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     3
A set of tools for managing authorization and access control for
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
     4
ssh-based Mercurial repositories
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     5
50
77d97aa18f29 update dates and copyright notices
Paul Crowley <paul@lshift.net>
parents: 49
diff changeset
     6
Paul Crowley, paul@lshift.net, 2008-2009
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     7
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     8
This software may be used and distributed according to the terms
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     9
of the GNU General Public License, incorporated herein by reference.
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    10
60
909f3801ee44 Add link to source website
Paul Crowley <paul@lshift.net>
parents: 57
diff changeset
    11
http://hg.opensource.lshift.net/mercurial-server/
909f3801ee44 Add link to source website
Paul Crowley <paul@lshift.net>
parents: 57
diff changeset
    12
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    13
WHAT IT GIVES YOU
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    14
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    15
These tools make it easier to provide a centralized repository host
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    16
with read/write access to many repositories for many developers.
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    17
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    18
All of the repositories controlled by these tools are owned by a single user
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    19
(the "hg" user in what follows), but many remote users can act on them, and
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    20
different users can have different permissions. We don't use file permissions to
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    21
achieve that - instead, developers log in as the "hg" user when they connect to
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    22
the repository host using ssh, using ssh URLs of the form
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    23
"ssh://hg@repository-host/repository-name". A restricted shell prevents them
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    24
from using this access for unauthorized purposes. Developers are authenticated
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    25
only using SSH keys; no other form of authentication is supported. 
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    26
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    27
To give a user access to the repository, place their key in an
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    28
appropriately-named subdirectory of "/etc/mercurial-server/keys" and run
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    29
"/etc/mercurial-server/refresh-auth". You can then control what access they have
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    30
to what repositories by editing the control file
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    31
"/etc/mercurial-server/access.conf", which can match the names of these keys
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    32
against a glob pattern. 
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    33
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    34
For convenient remote control of access, you can instead (if you have the
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    35
privileges) make changes to a special repository called "hgadmin", which
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    36
contains its own "access.conf" file and "keys" directory. Changes pushed to this
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    37
repository take effect immediately. The two "access.conf" files are
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    38
concatenated, and the keys directories merged.
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    39
28
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
    40
QUICK START
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    41
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    42
You and all developers using this system will need an SSH public key, and will
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    43
almost certainly want to be running ssh-agent (or its equivalent, eg Pageant
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    44
under Windows). If you're not familiar with ssh-agent, you should learn about
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    45
that before using this.
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    46
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    47
In what follows, certain operations (eg installing mercurial-server itself) have
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    48
to be done on the repository server (which we call "repository-host"), but any
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    49
operation that involves checking in or out of Mercurial can be done wherever is
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    50
most convenient to you; the most usual arrangment would be that you'd do these
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    51
things at the machine you sit at, and on which you run ssh-agent, which is what
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    52
authenticates you when you talk to the repository server.
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    53
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    54
Ensure there is no user called "hg" on the repository host, and run "./install".
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    55
This installs the mercurial-server files and control files, and creates and sets
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    56
up the "hg" user.
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    57
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    58
Place your SSH public key in the directory "/etc/mercurial-server/keys/root". I
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    59
suggest creating yourself a directory and naming the key after your hostname (ie
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    60
the file is called something like
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    61
"/etc/mercurial-server/keys/root/yourname/yourhostname") so that you can easily
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    62
manage users who have a different key on each host they use. Then run
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    63
"/etc/mercurial-server/refresh-auth".
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    64
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    65
The repository is now ready to use, and you are now the sole user able to change
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    66
and create repositories on this repository host.  
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    67
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    68
CREATING REPOSITORIES
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    69
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    70
To create a new repository, you clone a local repository onto the remote server.
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    71
So if you want a new empty repository called "myproject", you can do (as
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    72
yourself):
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    73
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    74
    hg init myproject
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    75
    hg clone myproject ssh://hg@repository-host/myproject
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    76
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    77
ADDING OTHER USERS
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    78
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    79
Because your key is in the "keys/root" subdirectory, you have the equivalent of
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    80
"root privileges" over mercurial-server (not the whole computer, just
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    81
mercurial-server). You can add other root users by putting their keys next to
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    82
yours, or you can make less privileged users by putting their keys in the
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    83
"keys/users" subdirectory - these users will be able to read and write to any
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    84
repository (except one - see below) but will not be able to create new
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    85
repositories. As always, when you change "/etc/mercurial-server/keys" you need
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    86
to re-run "/etc/mercurial-server/refresh-auth".
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    87
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
    88
LOGGING
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
    89
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
    90
Every push and pull is logged with the key used: see the file .hg/serve-log in
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
    91
each repository.
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
    92
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    93
USING HGADMIN
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    94
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    95
It can be inconvenient to log on to the repository server, become root, copy
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    96
keys around, and run "refresh-auth" every time you want to change user
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    97
privileges. This is where mercurial-server shines :-) Suppose you have another
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    98
user's SSH public key in the file "/tmp/theirkey" (on the machine you sit at,
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    99
not necessarily the repository server) and you want to give them user-level
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   100
access to the repository server. Run these commands:
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   101
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   102
    hg clone ssh://hg@repository-server/hgadmin
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   103
    cd hgadmin
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   104
    mkdir keys/user/thatuser
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   105
    cp /tmp/theirkey keys/user/thatuser/theirhostname
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   106
    hg add
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   107
    hg commit -m "Added key for thatuser"
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   108
    hg push
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
   109
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   110
In other words, hgadmin is a version controlled version of
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   111
"/etc/mercurial-server/keys", and changes to it take effect immediately. Only
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   112
"keys/root" users can act on "hgadmin" - those with keys in "keys/users" are
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   113
locked out. Multiple admins can use Mercurial's version control to cooperate on
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   114
controlling access to the repository server in a natural way. You can also add
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   115
"root" users by putting their key in the "keys/root" directory in just the same
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   116
way - these users will now be able to control hgadmin and create new
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   117
repositories just as you can.
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
   118
61
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   119
Once you're working with "hgadmin", it can be convenient to remove all the keys
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   120
in "/etc/mercurial-server/keys" and all the entries in
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   121
"/etc/mercurial-server/access.conf" and use hgadmin to control everything. If
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   122
you find yourself locked out, you can get back in again by restoring some of the
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   123
entries you removed from these files - remember,
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   124
"/etc/mercurial-server/access.conf" takes precedence over the "access.conf" in
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   125
"hgadmin".
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   126
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   127
ACCESS.CONF
13
1206ed37090a more README fixes
Paul Crowley <paul@ciphergoth.org>
parents: 12
diff changeset
   128
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   129
Out of the box, there are just two kinds of users: the ones with keys in
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   130
"keys/root" and those in "keys/users". However, you can change this by editing
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   131
"access.conf". There are two "access.conf" files, one in "/etc/mercurial-server"
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   132
and one in "hgadmin"; the two are simply concatenated before being read.
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   133
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   134
Each line of access.conf has the following syntax:
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   135
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   136
<rule> <condition> <condition> ...
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   137
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   138
Rule is one of
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   139
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   140
init - allow any operation, including the creation of new repositories
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   141
write - allow reads and writes to this file in this repository
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   142
read - allow the repo to be read but reject matching writes
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   143
deny - deny all requests
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   144
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   145
A condition is a globpattern matched against a relative path, one of:
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   146
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   147
user=<globpattern> - user's key
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   148
repo=<globpattern> - repo (as the user supplies it)
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   149
file=<globpattern> - file in the repo
20
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
   150
branch=<globpattern> - name of the branch
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   151
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   152
The first rule in the file which has all its conditions satisfied is used to
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   153
determine whether an action is allowed.
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   154
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   155
Paths cannot contain any special characters except "/"; glob patterns cannot
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   156
contain any special characters except "/" and "*". "*" matches zero or more
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   157
characters not including "/" while "**" matches zero or more characters
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   158
including "/".
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   159
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   160
Blank lines and lines that start with "#" are ignored.
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   161
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   162
FILE CONDITIONS
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   163
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   164
mercurial-server supports file and branch conditions, which restrict an
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   165
operation depending on what files it modifies and what branch the work is on.
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   166
However, the way these conditions work is subtle and can be counterintuitive -
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   167
if you want to keep things simple, stick to user and repo conditions, and then
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   168
things are likely to work the way you would expect.
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   169
20
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
   170
The rules file is used to make four decisions:
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   171
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   172
- Whether to allow a repository to be created
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   173
- Whether to allow access to a repository
20
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
   174
- Whether to allow a changeset on a particular branch at all
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   175
- Whether to allow a changeset to change a particular file
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   176
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   177
When the first two of these decisions are being made, nothing is known about
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   178
what files might be changed, and so all file conditions automatically succeed
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   179
for the purpose of such decisions. This means that doing tricky things with file
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   180
conditions can have counterintuitive consequences:
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   181
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   182
- You cannot limit read access to a subset of a repository with a "read" rule
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   183
and a file condition: any user who has access to a repository can read all of it
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   184
and its full history. Such a rule can only have the effect of masking a later
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   185
"write" rule, as in this example:
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   186
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   187
   read repo=specialrepo file=dontwritethis
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   188
   write repo=specialrepo
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   189
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   190
allows all users to read specialrepo, and to write to all files *except* that
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   191
any changeset which writes to "dontwritethis" will be rejected.
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   192
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   193
- For similar reasons, don't give "init" rules file conditions.
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   194
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   195
- Don't try to deny write access to a particular file on a particular branch - a
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   196
developer can write to the file on another branch and then merge it in. Either
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   197
deny all writes to the branch from that user, or allow them to write to all the
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   198
files they can write to on any branch. In other words, something like this will
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   199
have the intended effect:
26
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   200
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   201
  write user=docs/* branch=docs file=docs/*
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   202
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   203
But something like this will not have the intended effect; it will effectively
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   204
allow these users to write to any file on any branch, by writing it to "docs"
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   205
first:
26
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   206
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   207
  write user=docs/* branch=docs
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   208
  write user=docs/* file=docs/*
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   209
  read user=docs/*
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   210
28
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   211
HOW IT WORKS
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   212
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   213
When a developer attempts to connect to a repository via ssh, the SSH daemon
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   214
searches for a match for that user's key in ~hg/.ssh/authorized_keys. If the
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   215
developer is authorised to connect to the repository they will have an entry in
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   216
this file. The entry includes a "command" prefix which specifies that the
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   217
restricted shell should be used; this shell is passed an argument identifying
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   218
the developer. The shell parses the command the developer is trying to execute,
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   219
and consults a rules file to see if that developer is allowed to perform that
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   220
action on that repository. The bulk of the work of the restricted shell is done
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   221
by the Python program "hg-ssh", but the shell script "hg-ssh-wrapper" sets up
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   222
some configuration so that you can change it to suit your local installation.
28
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   223
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   224
The file ~hg/.ssh/authorized_keys is generated by "refresh-auth", which recurses
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   225
through two directories of files containing SSH keys and generates an entry in
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   226
authorized_keys for each one, using the name of the key file as the identifier
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   227
for the developer. These keys will live in the "keys" subdirectory
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   228
"/etc/mercurial-server" and the "keys" subdirectory of a repository called
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   229
"hgadmin". A hook in this repository re-runs "refresh-auth" on the most recent
28
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   230
version after every push.
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   231
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   232
Finally, hook in an extension is run for each changeset that is remotely
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   233
committed, which uses the rules file to determine whether to allow the
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   234
changeset.
28
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   235
61
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   236
SECURITY OF MERCURIAL-SERVER
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   237
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   238
mercurial-server relies entirely on sshd to grant access to remote users. As a
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   239
result, it runs no daemons, installs no setuid programs, and no part of it runs
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   240
as root except the install process: all programs run as the user hg. And any
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   241
attack on mercurial-server can only be started if the Bad Guys already have a
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   242
public key in ~hg/.ssh/authorized_keys, otherwise sshd will bar the way. No
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   243
matter what command the user tries to run on the remote system via ssh,
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   244
mercurial-server is run. 
20
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
   245
61
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   246
It parses the command line the user asked for, and interprets and runs the
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   247
corresponding hg operation itself if access is allowed, so users can only read
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   248
and add to history within repositories; they cannot run any other hg command. In
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   249
addition, every push and pull is logged with a datestamp, changeset ID and the
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   250
key that performed the operation.
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   251
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   252
However, while the first paragraph holds no matter what bugs mercurial-server
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   253
contains, the second depends on the relevant code being correct; though the
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   254
entire codebase is currently only about twice as long as this README,
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   255
mercurial-server is a fairly new program and may harbour bugs. Backups are
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   256
essential!
20
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
   257
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   258
THANKS
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   259
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   260
Thanks for reading this far. If you use mercurial-server, please tell me about
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   261
it.
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   262
50
77d97aa18f29 update dates and copyright notices
Paul Crowley <paul@lshift.net>
parents: 49
diff changeset
   263
Paul Crowley, 2009