mercurial-server

mercurial-server makes a group of repositories available to the developers

you choose, identified by ssh keys, with easy key and access management

based on hg.

http://www.lshift.net/mercurial-server.html

Copyright (C) 2008-2009 LShift Ltd.

    This program is free software; you can redistribute it and/or modify

    it under the terms of the GNU General Public License as published by

    the Free Software Foundation; either version 2 of the License, or

    (at your option) any later version.

    This program is distributed in the hope that it will be useful,

    but WITHOUT ANY WARRANTY; without even the implied warranty of

    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License along

    with this program; if not, write to the Free Software Foundation, Inc.,

    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

SUMMARY

mercurial-server makes a group of repositories available to the developers

you choose, identified by ssh keys, with easy key and access management

based on hg.

All of the repositories controlled by mercurial-server are owned by a

single user (the "hg" user in what follows), but many remote users can act

on them, and different users can have different permissions. We don't use

file permissions to achieve that - instead, developers log in as the "hg"

user when they connect to the repository host using ssh, using ssh URLs of

the form "ssh://hg@repository-host/repository-name". A restricted shell

prevents them from using this access for unauthorized purposes. Developers

are authenticated only using SSH keys; no other form of authentication is

supported. 

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

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

"/usr/local/share/mercurial-server/refresh-auth". You can then control what

access they have to what repositories by editing the control file

"/etc/mercurial-server/access.conf", which can match the names of these keys

against a glob pattern. 

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

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

contains its own "access.conf" file and "keys" directory. Changes pushed to

this repository take effect immediately. The two "access.conf" files are

concatenated, and the keys directories merged.

QUICK START

You and all developers using this system will need an SSH public key, and

will almost certainly want to be running ssh-agent (or its equivalent, eg

Pageant under Windows). If you're not familiar with ssh-agent, you should

learn about that before using this.

In what follows, certain operations (eg installing mercurial-server itself)

have to be done on the repository server (which we call "repository-host"),

but any operation that involves checking in or out of Mercurial can be done

wherever is most convenient to you; the most usual arrangment would be that

you'd do these things at the machine you sit at, and on which you run

ssh-agent, which is what authenticates you when you talk to the repository

server.

Ensure there is no user called "hg" on the repository host, and run

"./install". This installs the mercurial-server files and control files, and

creates and sets up the "hg" user.

Place your SSH public key in the directory "/etc/mercurial-server/keys/root".

I suggest creating yourself a directory and naming the key after your hostname

(ie the file is called something like

"/etc/mercurial-server/keys/root/yourname/yourhostname") so that you can

easily manage users who have a different key on each host they use. Then run

"/usr/local/share/mercurial-server/refresh-auth".

The repository is now ready to use, and you are now the sole user able to

change and create repositories on this repository host.  

CREATING REPOSITORIES

To create a new repository, you clone a local repository onto the remote

server. So if you want a new empty repository called "myproject", you can do

(as yourself):

    hg init myproject

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

ADDING OTHER USERS

Because your key is in the "keys/root" subdirectory, you have the equivalent

of "root privileges" over mercurial-server (not the whole computer, just

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 "/usr/local/share/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/users/thatuser

    cp /tmp/theirkey keys/users/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", and changes to it take effect immediately -

"refresh-auth" is run after every push. 

With the default access.conf file (see doc/configuring-access for more

details) only users in "keys/root" can act on "hgadmin" - those with keys in

"keys/users" cannot even read this repository. So multiple admins can use

Mercurial's version control to cooperate on controlling access to the

repository server in a natural way.

You can also create an "access.conf" file in hgadmin, and this is appended to

/etc/mercurial-server/access.conf whenever this is read - in other words,

rules in the latter take precedence over those in the former. So once you're

working with "hgadmin", it can be convenient to remove all the keys in

"/etc/mercurial-server/keys" and all the entries in

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

you find yourself locked out, you can get back in again by restoring some of

the entries you removed from these files.

MORE INFORMATION

For more on how to use mercurial-server and configure access, see the files in

the doc directory.

THANKS

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

it.

Paul Crowley, paul@lshift.net, 2009