+
−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://hg.opensource.lshift.net/mercurial-server/
+
−
+
−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/lib/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/lib/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/lib/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
+
−locked out. Multiple admins can use Mercurial's version control to cooperate
+
−on controlling access to the repository server in a natural way. You can also
+
−add "root" users by putting their key in the "keys/root" directory in just the
+
−same way - these users will now be able to control hgadmin and create new
+
−repositories just as you can.
+
−
+
−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 - remember,
+
−"/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
+
−"access.conf". There are two "access.conf" files, one in
+
−"/etc/mercurial-server" and one in "hgadmin"; the two are simply concatenated
+
−before being read.
+
−
+
−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
+
−for the purpose of such decisions. This means that doing tricky things with
+
−file conditions can have counterintuitive consequences:
+
−
+
−- You cannot limit read access to a subset of a repository with a "read" rule
+
−and a file condition: any user who has access to a repository can read all of
+
−it and its full history. Such a rule can only have the effect of masking a
+
−later "write" rule, as in this example:
+
−
+
−   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.
+
−
+
−- Don't try to deny write access to a particular file on a particular branch -
+
−a developer can write to the file on another branch and then merge it in.
+
−Either deny all writes to the branch from that user, or allow them to write to
+
−all the files they can write to on any branch. In other words, something like
+
−this will have the intended effect:
+
−
+
−  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
+
−developer is authorised to connect to the repository they will have an entry
+
−in this file. The entry includes a "command" prefix which specifies that the
+
−restricted shell "/usr/local/lib/mercurial-server/hg-ssh" should be used; this
+
−shell is passed an argument identifying the developer. The shell parses the
+
−command the developer is trying to execute, and consults a rules file to see
+
−if that developer is allowed to perform that action on that repository.
+
−
+
−The file ~hg/.ssh/authorized_keys is generated by "refresh-auth", which
+
−recurses through two directories of files containing SSH keys and generates an
+
−entry in authorized_keys for each one, using the name of the key file as the
+
−identifier for the developer. These keys will live in the "keys" subdirectory
+
−"/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
+
−result, it runs no daemons, installs no setuid programs, and no part of it
+
−runs as root except the install process: all programs run as the user hg. And
+
−any attack on mercurial-server can only be started if the Bad Guys already
+
−have a public key in ~hg/.ssh/authorized_keys, otherwise sshd will bar the
+
−way. No matter what command the user tries to run on the remote system via
+
−ssh, mercurial-server is run. 
+
−
+
−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
+
−and add to history within repositories; they cannot run any other hg command.
+
−In addition, every push and pull is logged with a datestamp, changeset ID and
+
−the key that performed the operation.
+
−
+
−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