mercurial-server

Paul Crowley, paul@lshift.net, 2008-2009

This software may be used and distributed according to the terms

of the GNU General Public License, incorporated herein by reference.

http://hg.opensource.lshift.net/mercurial-server/

To give a user access to the repository, place their key in an

appropriately-named subdirectory of "/etc/mercurial-server/keys" and run

For convenient remote control of access, you can instead (if you have the

privileges) make changes to a special repository called "hgadmin", which

concatenated, and the keys directories merged.

QUICK START

"/etc/mercurial-server/refresh-auth".

CREATING REPOSITORIES

    hg init myproject

    hg clone myproject ssh://hg@repository-host/myproject

ADDING OTHER USERS

mercurial-server). You can add other root users by putting their keys next to

yours, or you can make less privileged users by putting their keys in the

"keys/users" subdirectory - these users will be able to read and write to any

repository (except one - see below) but will not be able to create new

repositories. As always, when you change "/etc/mercurial-server/keys" you need

to re-run "/etc/mercurial-server/refresh-auth".

LOGGING

Every push and pull is logged with the key used: see the file .hg/serve-log in

each repository.

USING HGADMIN

It can be inconvenient to log on to the repository server, become root, copy

keys around, and run "refresh-auth" every time you want to change user

privileges. This is where mercurial-server shines :-) Suppose you have another

user's SSH public key in the file "/tmp/theirkey" (on the machine you sit at,

not necessarily the repository server) and you want to give them user-level

access to the repository server. Run these commands:

    hg clone ssh://hg@repository-server/hgadmin

    cd hgadmin

    mkdir keys/user/thatuser

    cp /tmp/theirkey keys/user/thatuser/theirhostname

    hg add

    hg commit -m "Added key for thatuser"

    hg push

In other words, hgadmin is a version controlled version of

"/etc/mercurial-server/keys", and changes to it take effect immediately. Only

"keys/root" users can act on "hgadmin" - those with keys in "keys/users" are

repositories just as you can.

"/etc/mercurial-server/access.conf" and use hgadmin to control everything. If

"/etc/mercurial-server/access.conf" takes precedence over the "access.conf" in

"hgadmin".

ACCESS.CONF

Out of the box, there are just two kinds of users: the ones with keys in

"keys/root" and those in "keys/users". However, you can change this by editing

Each line of access.conf has the following syntax:

<rule> <condition> <condition> ...

Rule is one of

init - allow any operation, including the creation of new repositories

write - allow reads and writes to this file in this repository

read - allow the repo to be read but reject matching writes

deny - deny all requests

A condition is a globpattern matched against a relative path, one of:

user=<globpattern> - user's key

repo=<globpattern> - repo (as the user supplies it)

file=<globpattern> - file in the repo

branch=<globpattern> - name of the branch

The first rule in the file which has all its conditions satisfied is used to

determine whether an action is allowed.

Paths cannot contain any special characters except "/"; glob patterns cannot

contain any special characters except "/" and "*". "*" matches zero or more

characters not including "/" while "**" matches zero or more characters

including "/".

Blank lines and lines that start with "#" are ignored.

FILE CONDITIONS

mercurial-server supports file and branch conditions, which restrict an

operation depending on what files it modifies and what branch the work is on.

However, the way these conditions work is subtle and can be counterintuitive -

if you want to keep things simple, stick to user and repo conditions, and then

things are likely to work the way you would expect.

The rules file is used to make four decisions:

- Whether to allow a repository to be created

- Whether to allow access to a repository

- Whether to allow a changeset on a particular branch at all

- Whether to allow a changeset to change a particular file

When the first two of these decisions are being made, nothing is known about

what files might be changed, and so all file conditions automatically succeed

- You cannot limit read access to a subset of a repository with a "read" rule

   read repo=specialrepo file=dontwritethis

   write repo=specialrepo

allows all users to read specialrepo, and to write to all files *except* that

any changeset which writes to "dontwritethis" will be rejected.

- For similar reasons, don't give "init" rules file conditions.

  write user=docs/* branch=docs file=docs/*

But something like this will not have the intended effect; it will effectively

allow these users to write to any file on any branch, by writing it to "docs"

first:

  write user=docs/* branch=docs

  write user=docs/* file=docs/*

  read user=docs/*

HOW IT WORKS

When a developer attempts to connect to a repository via ssh, the SSH daemon

searches for a match for that user's key in ~hg/.ssh/authorized_keys. If the

restricted shell should be used; this shell is passed an argument identifying

"/etc/mercurial-server" and the "keys" subdirectory of a repository called

"hgadmin". A hook in this repository re-runs "refresh-auth" on the most recent

version after every push.

Finally, hook in an extension is run for each changeset that is remotely

committed, which uses the rules file to determine whether to allow the

changeset.

SECURITY OF MERCURIAL-SERVER

mercurial-server relies entirely on sshd to grant access to remote users. As a

It parses the command line the user asked for, and interprets and runs the

corresponding hg operation itself if access is allowed, so users can only read

However, while the first paragraph holds no matter what bugs mercurial-server

contains, the second depends on the relevant code being correct; though the

entire codebase is currently only about twice as long as this README,

mercurial-server is a fairly new program and may harbour bugs. Backups are

essential!

THANKS

Thanks for reading this far. If you use mercurial-server, please tell me about

it.

Paul Crowley, 2009