diff -r 1c0bc7d33648 -r 8d73bcd75243 README --- a/README Thu Oct 15 12:28:08 2009 +0100 +++ b/README Thu Oct 15 12:47:39 2009 +0100 @@ -1,8 +1,8 @@ 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. +mercurial-server gives your developers remote read/write access to +centralized Mercurial repositories using SSH public key authentication; it +provides convenient and fine-grained key management and access control. http://www.lshift.net/mercurial-server.html @@ -22,134 +22,7 @@ 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. +For details on how to install and use mercurial-server, see doc/manual.docbook. Paul Crowley, paul@lshift.net, 2009