added notes on how to do more things via admin push

doc/2-admin.mkd

@@ -10,7 +10,7 @@ In this document:
       * moving pre-existing repos into gitolite
       * specifying gitweb and daemon access
       * custom hooks
-      * when you need your own "update" hook
+      * hook chaining
       * custom git config
 
 ### administer
@@ -99,30 +99,37 @@ for the special usernames or remove the description line.
 
 #### custom hooks
 
-If you want to put in your own, custom, hooks every time a new repo is created
-by gitolite, put a **tested** hook script in `hooks/common` of your gitolite
-clone before running easy-install.  As distributed, there are only two files
-there, but everything (*everything*) in that directory will get copied to the
-`hooks/` subdirectory of every *new* repo created.
+You can supply your own, custom, hook scripts if you wish.  Just put a
+**tested** hook script in `hooks/common` of your gitolite clone (as
+distributed, there are only two files there).  For each file in that
+directory, a symlink pointing to it will be placed in the `hooks/`
+subdirectory of every *new* repo created.
 
-In order to push a new or updated hook script to *existing* repos as well,
-just run easy install once again; it'll do it to existing repos also.
+If you added any new hooks and wish to propagate them to *existing* repos as
+well, just run gl-easy-install (or gl-setup, if you installed directly on the
+server) once.
 
 **VERY IMPORTANT SECURITY NOTE:  the `update` hook in `hooks/common` is what
 implements all the branch-level permissions in gitolite.  If you fiddle with
 the hooks directory, please make sure you do not mess with this file
 accidentally, or all your fancy per-branch permissions will stop working.**
 
-#### when you need your own "update" hook
+#### hook chaining
 
 Gitolite basically takes over the update hook for all repos, but some setups
 really need the update hook functionality for their own purposes too.  In
 order to allow this, Gitolite now exec's a hook called `update.secondary` when
 it's own "update" hook is done and everything is ready to go.
 
-You can create this `update.secondary` hook selectively on some repos on the
-server, or use the mechanism in the previous section to make gitolite install
-it on *all* your repos.
+You can create this `update.secondary` hook manually on selected repos on the
+server, or use the mechanism in the previous section to make gitolite put it
+on *all* your repos.
+
+Similarly, gitolite also takes over the post-update hook for the special
+"gitolite-admin" repo.  This hook will also chain to a `post-update.secondary`
+if such a hook exists.  People wishing to do exotic things on the server side
+when the admin repo is pushed should see doc/shell-games.notes for how to
+exploit this :-)
 
 #### custom git config
 

doc/shell-games.mkd

@@ -0,0 +1,71 @@
+# avoiding the shell on the server
+
+Gitolite now tries to prevent gitolite-admin push privileges from being used
+to obtain a shell on the server.  This was not always the case (older gitolite
+did not make this distinction), but I've been moving towards this for a while
+now, and, while there could still be holes in that separation, they will be
+fixed as and when found.
+
+Thus, settings that have security implications can be set only from the rc
+file, which needs to be edited directly on the server.  And adding a new hook
+requires adding it to the *gitolite* clone and running easy install again, or
+gl-setup, if you used the server-side install method, both of which require
+shell access.
+
+While this is great for my main target (corporate environments), some people
+don't like it.  They want to do all of this from the *gitolite-admin* repo,
+because the security concern mentioned above does not bother them.  They don't
+want to log on to the server to make a change in the rc file or don't want to
+run easy install to propagate a new set of hooks.  In addition, they may want
+all of these animals versioned in the "gitolite-admin" repo itself, which
+certainly makes sense.
+
+So here's how you might do that.
+
+First, arrange to have all your special files added to the gitolite-admin
+repo.  The best option is to keep all of this in a single subdirectory (let's
+call it "local" in our example).  So your `~/.gitolite.rc` might go into
+`local/gitolite.rc`, and all your local hooks into `local/hooks` etc.  Add
+them, commit, and push.
+
+Note: do not create any top level directory called "conf", "contrib", "doc",
+"hooks", or "src" -- those names are used by gitolite itself.
+
+Second, create a `post-update.secondary` hook and place it in the *gitolite*
+clone's `hooks/common` directory, containing the following code:
+
+    #!/bin/bash
+
+    GL_ADMINDIR=` cd;perl -e 'do ".gitolite.rc"; print $GL_ADMINDIR'`
+
+    cp    $GL_ADMINDIR/local/gitolite.rc    $HOME/.gitolite.rc
+    cp -a $GL_ADMINDIR/local/hooks/*        $GL_ADMINDIR/hooks/common
+    $HOME/gitolite-install/src/gl-install -q
+
+Now run easy-install (or gl-setup) once, and you're done.
+
+All future changes to the rc file can be done via local/gitolite.rc in the
+admin repo, and hooks can be added to local/hooks.
+
+**Warning**: Nothing in gitolite *removes* hooks, so if you delete (or even
+rename) a script, it still stays on the server -- you'll have to delete them
+manually from the server.
+
+----
+
+So what's this actually doing?
+
+Well, first, note that `$GL_ADMINDIR` contains files from both gitolite
+itself, as well as from the gitolite-admin repo.  "conf/VERSION", "src",
+"doc", and "hooks" come from gitolite itself, while the other 2 files in
+"conf", and all of "keydir" come from the gitolite-admin repo.  ("logs"
+doesn't come from anywhere).
+
+In addition, any other files in the "master" branch of the gitolite-admin repo
+get checked out here, which in this case would mean the entire "local/"
+hierarchy you created above.
+
+Now, since the "hooks/common" directory is coming from gitolite itself,
+clearly this is where the internal "install" routine expects to find new or
+updated hooks to propagate.  So you just copy your local hooks (in the
+"local/hooks" directory) to "hooks/common" and run the installer again.  Done!