README
author Paul Crowley <paul@lshift.net>
Fri, 06 Mar 2009 09:22:33 +0000
changeset 68 a88134f77486
parent 66 2f0ea1163b9e
child 81 f23736ad66bc
permissions -rw-r--r--
Add __init__.py
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
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
     3
mercurial-server makes a group of repositories available to the developers
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
     4
you choose, identified by ssh keys, with easy key and access management
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
     5
based on hg.
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     6
50
77d97aa18f29 update dates and copyright notices
Paul Crowley <paul@lshift.net>
parents: 49
diff changeset
     7
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
     8
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     9
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
    10
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
    11
60
909f3801ee44 Add link to source website
Paul Crowley <paul@lshift.net>
parents: 57
diff changeset
    12
http://hg.opensource.lshift.net/mercurial-server/
909f3801ee44 Add link to source website
Paul Crowley <paul@lshift.net>
parents: 57
diff changeset
    13
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    14
All of the repositories controlled by mercurial-server are owned by a
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    15
single user (the "hg" user in what follows), but many remote users can act
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    16
on them, and different users can have different permissions. We don't use
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    17
file permissions to achieve that - instead, developers log in as the "hg"
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    18
user when they connect to the repository host using ssh, using ssh URLs of
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    19
the form "ssh://hg@repository-host/repository-name". A restricted shell
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    20
prevents them from using this access for unauthorized purposes. Developers
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    21
are authenticated only using SSH keys; no other form of authentication is
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    22
supported. 
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    23
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    24
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
    25
appropriately-named subdirectory of "/etc/mercurial-server/keys" and run
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    26
"/etc/mercurial-server/refresh-auth". You can then control what access they
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    27
have to what repositories by editing the control file
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    28
"/etc/mercurial-server/access.conf", which can match the names of these
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    29
keys against a glob pattern. 
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    30
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    31
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
    32
privileges) make changes to a special repository called "hgadmin", which
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    33
contains its own "access.conf" file and "keys" directory. Changes pushed to
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    34
this repository take effect immediately. The two "access.conf" files are
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    35
concatenated, and the keys directories merged.
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    36
28
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
    37
QUICK START
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    38
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    39
You and all developers using this system will need an SSH public key, and
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    40
will almost certainly want to be running ssh-agent (or its equivalent, eg
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    41
Pageant under Windows). If you're not familiar with ssh-agent, you should
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    42
learn about that before using this.
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    43
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    44
In what follows, certain operations (eg installing mercurial-server itself)
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    45
have to be done on the repository server (which we call "repository-host"),
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    46
but any operation that involves checking in or out of Mercurial can be done
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    47
wherever is most convenient to you; the most usual arrangment would be that
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    48
you'd do these things at the machine you sit at, and on which you run
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    49
ssh-agent, which is what authenticates you when you talk to the repository
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    50
server.
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    51
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    52
Ensure there is no user called "hg" on the repository host, and run
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    53
"./install". This installs the mercurial-server files and control files, and
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    54
creates and sets up the "hg" user.
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    55
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    56
Place your SSH public key in the directory "/etc/mercurial-server/keys/root".
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    57
I suggest creating yourself a directory and naming the key after your hostname
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    58
(ie the file is called something like
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    59
"/etc/mercurial-server/keys/root/yourname/yourhostname") so that you can
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    60
easily manage users who have a different key on each host they use. Then run
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    61
"/etc/mercurial-server/refresh-auth".
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    62
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    63
The repository is now ready to use, and you are now the sole user able to
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    64
change and create repositories on this repository host.  
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    65
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    66
CREATING REPOSITORIES
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    67
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    68
To create a new repository, you clone a local repository onto the remote
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    69
server. So if you want a new empty repository called "myproject", you can do
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    70
(as yourself):
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    71
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    72
    hg init myproject
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    73
    hg clone myproject ssh://hg@repository-host/myproject
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    74
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    75
ADDING OTHER USERS
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    76
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    77
Because your key is in the "keys/root" subdirectory, you have the equivalent
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
    78
of "root privileges" over mercurial-server (not the whole computer, just
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    79
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
    80
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
    81
"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
    82
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
    83
repositories. As always, when you change "/etc/mercurial-server/keys" you need
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    84
to re-run "/etc/mercurial-server/refresh-auth".
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    85
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
    86
LOGGING
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
    87
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
    88
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
    89
each repository.
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
    90
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    91
USING HGADMIN
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    92
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    93
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
    94
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
    95
privileges. This is where mercurial-server shines :-) Suppose you have another
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
    96
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
    97
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
    98
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
    99
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   100
    hg clone ssh://hg@repository-server/hgadmin
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   101
    cd hgadmin
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   102
    mkdir keys/user/thatuser
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   103
    cp /tmp/theirkey keys/user/thatuser/theirhostname
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   104
    hg add
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   105
    hg commit -m "Added key for thatuser"
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   106
    hg push
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
   107
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   108
In other words, hgadmin is a version controlled version of
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   109
"/etc/mercurial-server/keys", and changes to it take effect immediately. Only
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   110
"keys/root" users can act on "hgadmin" - those with keys in "keys/users" are
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   111
locked out. Multiple admins can use Mercurial's version control to cooperate
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   112
on controlling access to the repository server in a natural way. You can also
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   113
add "root" users by putting their key in the "keys/root" directory in just the
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   114
same way - these users will now be able to control hgadmin and create new
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   115
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
   116
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   117
Once you're working with "hgadmin", it can be convenient to remove all the
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   118
keys in "/etc/mercurial-server/keys" and all the entries in
61
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   119
"/etc/mercurial-server/access.conf" and use hgadmin to control everything. If
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   120
you find yourself locked out, you can get back in again by restoring some of
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   121
the entries you removed from these files - remember,
61
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   122
"/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
   123
"hgadmin".
964ac53280cb Security of mercurial-server
Paul Crowley <paul@lshift.net>
parents: 60
diff changeset
   124
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   125
ACCESS.CONF
13
1206ed37090a more README fixes
Paul Crowley <paul@ciphergoth.org>
parents: 12
diff changeset
   126
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   127
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
   128
"keys/root" and those in "keys/users". However, you can change this by editing
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   129
"access.conf". There are two "access.conf" files, one in
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   130
"/etc/mercurial-server" and one in "hgadmin"; the two are simply concatenated
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   131
before being read.
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   132
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   133
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
   134
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   135
<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
   136
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   137
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
   138
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   139
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
   140
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
   141
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
   142
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
   143
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   144
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
   145
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   146
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
   147
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
   148
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
   149
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
   150
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   151
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
   152
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
   153
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   154
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
   155
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
   156
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
   157
including "/".
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   158
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   159
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
   160
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   161
FILE CONDITIONS
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   162
49
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   163
mercurial-server supports file and branch conditions, which restrict an
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   164
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
   165
However, the way these conditions work is subtle and can be counterintuitive -
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   166
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
   167
things are likely to work the way you would expect.
a886ed5fec05 New README
Paul Crowley <paul@lshift.net>
parents: 36
diff changeset
   168
20
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
   169
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
   170
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   171
- 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
   172
- 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
   173
- 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
   174
- 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
   175
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   176
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
   177
what files might be changed, and so all file conditions automatically succeed
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   178
for the purpose of such decisions. This means that doing tricky things with
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   179
file 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
   180
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   181
- You cannot limit read access to a subset of a repository with a "read" rule
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   182
and a file condition: any user who has access to a repository can read all of
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   183
it and its full history. Such a rule can only have the effect of masking a
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   184
later "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
   185
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   186
   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
   187
   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
   188
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   189
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
   190
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
   191
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   192
- 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
   193
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   194
- Don't try to deny write access to a particular file on a particular branch -
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   195
a developer can write to the file on another branch and then merge it in.
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   196
Either deny all writes to the branch from that user, or allow them to write to
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   197
all the files they can write to on any branch. In other words, something like
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   198
this will have the intended effect:
26
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   199
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   200
  write user=docs/* branch=docs file=docs/*
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   201
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   202
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
   203
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
   204
first:
26
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   205
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   206
  write user=docs/* branch=docs
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   207
  write user=docs/* file=docs/*
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   208
  read user=docs/*
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   209
28
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   210
HOW IT WORKS
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   211
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   212
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
   213
searches for a match for that user's key in ~hg/.ssh/authorized_keys. If the
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   214
developer is authorised to connect to the repository they will have an entry
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   215
in this file. The entry includes a "command" prefix which specifies that the
57
fdf8f5f0c283 re-wrap paras to be consistent; briefly document logging
Paul Crowley <paul@lshift.net>
parents: 50
diff changeset
   216
restricted shell should be used; this shell is passed an argument identifying
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   217
the developer. The shell parses the command the developer is trying to
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   218
execute, and consults a rules file to see if that developer is allowed to
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   219
perform that action on that repository. The bulk of the work of the restricted
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   220
shell is done by the Python program "hg-ssh", but the shell script
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   221
"hg-ssh-wrapper" sets up some configuration so that you can change it to suit
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   222
your local installation.
28
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   223
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   224
The file ~hg/.ssh/authorized_keys is generated by "refresh-auth", which
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   225
recurses through two directories of files containing SSH keys and generates an
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   226
entry in authorized_keys for each one, using the name of the key file as the
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   227
identifier for the developer. These keys will live in the "keys" subdirectory
57
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
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   239
result, it runs no daemons, installs no setuid programs, and no part of it
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   240
runs as root except the install process: all programs run as the user hg. And
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   241
any attack on mercurial-server can only be started if the Bad Guys already
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   242
have a public key in ~hg/.ssh/authorized_keys, otherwise sshd will bar the
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   243
way. No matter what command the user tries to run on the remote system via
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   244
ssh, 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
66
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   248
and add to history within repositories; they cannot run any other hg command.
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   249
In addition, every push and pull is logged with a datestamp, changeset ID and
2f0ea1163b9e Change intro to README and linewrap at column 75
Paul Crowley <paul@lshift.net>
parents: 63
diff changeset
   250
the key that performed the operation.
61
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