--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/how-it-works	Sat Mar 07 09:31:06 2009 +0000
@@ -0,0 +1,22 @@
+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.