diff -r f0cb7ad9e4ab -r a886ed5fec05 README --- a/README Fri Feb 20 11:38:19 2009 +0000 +++ b/README Fri Feb 20 12:44:16 2009 +0000 @@ -12,57 +12,111 @@ These tools make it easier to provide a centralized repository host with read/write access to many repositories for many developers. -Access control is managed with a special repository on the server -called "hgadmin"; pushes to this repository immediately change the -rules that are in effect. -Inside "hgadmin" is a "keys" directory containing the SSH keys of all -developers who have access, and a file "hg-ssh-access.conf" which -gives a set of rules defining who can do what to what. +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. -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. 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 will need +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. -- "sudo" installed -- "sudo" root privileges -- an ssh-key set up with ssh-agent +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. -Ensure there is no user called "hg" on the repository host, and run -"./install" to create them. You are now the sole user able to change -and create repositories on this repository host. To give access to -others, check out hgadmin - as yourself, and on whichever host is most -convenient, but using the ssh-key with which you set up the -repository: +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 - mkdir ~/hg - cd ~/hg - hg clone ssh://hg@repository-host/hgadmin - cd hgadmin +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: -You can now add other users by putting their keys in an appropriate -subdirectory of the "keys" directory, and control their access by -editing hg-ssh-access.conf. Changes will take effect as soon as you -push them to "ssh://hg@repository-host/hgadmin". + 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 -Users authorized to do so can now also create new repositories on this -host with "clone": +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. - hg clone . ssh://hg@repository-host/my-project-name +ACCESS.CONF -HG-SSH-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 hg-ssh-access.conf has the following syntax: +Each line of access.conf has the following syntax: ... @@ -92,6 +146,12 @@ 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 @@ -163,19 +223,15 @@ remotely committed, which uses the rules file to determine whether to allow the changeset. -LOCKING YOURSELF OUT +LOCKED OUT? -If you find yourself "locked out" - that is, that you no longer have -the permissions needed in hgadmin - you can break back in again if -you're able to become the "hg" user on the repository host. Once you -are that user, delete ~hg/.ssh/authorized_keys (to stop any user who -might have access but shouldn't from using the repository while you -fix things). Then go into ~hg/repos/hgadmin, do an "hg update", edit -things to your satisfaction, and commit the change. Finally, run - -~hg/admin/mercurial-server/refresh-auth ~hg/.ssh/authorized_keys ./hg-ssh-wrapper - -to regenerate ~hg/.ssh/authorized_keys. +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