added doc/6: more complex ssh setups

doc/6-complex-ssh-setups.mkd

@@ -0,0 +1,135 @@
+# more complex ssh setups
+
+What do you need to know in order to create more complex ssh setups (for
+instance if you have *two* gitolite servers you are administering)?  Once more
+unto the breach, here's more ssh magic!
+
+In this document:
+
+  * files on client
+  * files on the server
+  * sanity checks
+  * two gitolite servers to manage?
+
+### files on client
+
+  * default keypair; used to get shell access to servers.  You would have
+    copied this pubkey to the gitolite server in order to log in without a
+    password.  (On Linux systems you may have used `ssh-copy-id` to do that).
+    You would have done this *before* you ran the easy install script, because
+    otherwise easy install won't run!
+
+        ~/.ssh/id_rsa
+        ~/.ssh/id_rsa.pub
+
+  * gitolite keypair; the "sitaram" in this is the 3rd argument to the
+    `src/00-easy-install.sh` command you ran; the easy install script does the
+    rest
+
+        ~/.ssh/sitaram
+        ~/.ssh/sitaram.pub
+
+### files on the server
+
+  * the authkeys file; this contains one line containing the pubkey of each
+    user who is permitted to login without a password.
+
+    Pubkey lines that give shell access look like this:
+
+        ssh-rsa AAAAB3NzaC[snip]uPjrUiAUew== /home/sitaram/.ssh/id_rsa
+
+    On a typical server there will be only one or two of these lines.
+
+    Note that the last bit (`/home/sitaram/.ssh/id_rsa`) is purely a *comment*
+    field and can be anything.  Also, the actual lines are much longer, about
+    400 characters; I snipped 'em in the middle, as you can see.
+
+    In contrast, pubkey lines that give access to git repos hosted by gitolite
+    looks like this:
+
+        command="[some path]src/gl-auth-command sitaram",[some restrictions] ssh-rsa AAAAB3NzaC[snip]s18OnB42oQ== sitaram@sita-lt
+
+    You will have many more of these lines -- one for every pubkey file in
+    `keydir/` of your gitolite-admin repo, with the corresponding username in
+    place of "sitaram" in the example above.
+
+    The "command=" at the beginning ensures that when someone with the
+    corresponding private key logs in, they don't get a shell.  Instead, the
+    `gl-auth-command` program is run, and (in this example) is given the
+    argument `sitaram`.  This is how gitolite is invoked, (and is told the
+    user logging in is "sitaram").
+
+  * config file; this file has an entry for gitolite access:
+
+        ~/.ssh/config
+
+    Let's step back a bit.  Normally, you might expect to access gitolite
+    repos like this:
+
+        ssh://git@server/reponame.git
+
+    But this won't work, because this ends up using the *default* keypair
+    (normally), which gives you a command line.  Which means it won't invoke
+    the `gl-auth-command` program at all, and so none of gitolite's access
+    control will work.
+
+    You need to force ssh to use the *other* keypair when performing a git
+    operation.  With just ssh, that would be
+
+        ssh -i ~/.ssh/sitaram git@server
+
+    but git does not support putting an alternate keypair in the URL.
+
+    Luckily, ssh has a very convenient way of capturing all the mundane
+    information (username, hostname, port number (if it's not the default 22),
+    and keypair to be used) in one "paragraph".  This is what the para looks
+    like for us (the easy install script puts it there the first time):
+
+        host gitolite
+             user git
+             hostname server
+             identityfile ~/.ssh/sitaram
+
+    (The "gitolite" can be anything you want of course; it's like an alias for
+    all the stuff below it).  This ensures that typing
+
+        ssh gitolite
+
+    is equivalent to
+
+        ssh -i ~/.ssh/sitaram git@server
+
+    and therefore this:
+
+        git clone gitolite:reponame.git
+
+    now works as expected, invoking the special keypair instead of the default
+    one.
+
+### sanity checks
+
+  * `ssh gitolite` should get you the `SSH_ORIGINAL_COMMAND` error.  If you
+    get a command line, something is wrong
+
+  * conversely, `ssh git@server` should get you a command line
+
+  * the "origin" URL in any clones should look like `gitolite:reponame.git`
+    instead of something more complex
+
+### two gitolite servers to manage?
+
+  * they can have the same key; no harm there (example, sitaram.pub)
+
+  * instead of just one ssh/config para, you now have two (assuming that the
+    remote user on both machines is called "git"):
+
+        host gitolite
+             user git
+             hostname server
+             identityfile ~/.ssh/sitaram
+
+        host gitolite2
+             user git
+             hostname server2
+             identityfile ~/.ssh/sitaram
+