+
−mercurial-server
+
−
+
−A set of tools for managing authorization and access control for
+
−ssh-based Mercurial repositories
+
−
+
−Paul Crowley, paul@lshift.net, 2008
+
−
+
−This software may be used and distributed according to the terms
+
−of the GNU General Public License, incorporated herein by reference.
+
−
+
−WHAT IT GIVES YOU
+
−
+
−These tools make it easier to provide a centralized repository host
+
−with read/write access to many repositories for many developers.
+
−
+
−All of the repositories controlled by these tools 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
+
−"/etc/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
+
−"/etc/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 "/etc/mercurial-server/refresh-auth".
+
−
+
−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.
+
−
+
−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
+
−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 bulk of the work of
+
−the restricted shell is done by the Python program "hg-ssh", but the
+
−shell script "hg-ssh-wrapper" sets up some configuration so that you
+
−can change it to suit your local installation.
+
−
+
−The file ~hg/.ssh/authorized_keys is generated by "refresh-auth",
+
−which recurses through a directory 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 of a repository called "hgadmin".  A
+
−hook in this repository re-runs "refresh-auth" on the most recent
+
−version after every push.
+
−
+
−Finally, a 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.
+
−
+
−LOCKED OUT?
+
−
+
−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".
+
−
+
−THANKS
+
−
+
−Thanks for reading this far.  If you use mercurial-server, please tell
+
−me about it.
+
−
+
−Paul Crowley, 2008