doc/6: rename the file, change focus completely

doc/6-complex-ssh-setups.mkd → doc/6-ssh-troubleshooting.mkd

@@ -1,15 +1,17 @@
-# more complex ssh setups
+# ssh troubleshooting
 
-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!
+Ssh has always been the biggest troublespot in all this.  While gitolite makes
+it as easy as possible, you might still run into trouble sometimes.
 
 In this document:
 
-  * files on client
-  * files on the server
-  * sanity checks
-  * two gitolite servers to manage?
+  * ssh sanity checks
+  * explanation
+      * files on the server
+      * files on client
+  * more complex ssh setups
+      * two gitolite servers to manage?
+  * further reading
 
 ----
 
@@ -18,31 +20,61 @@ In this document:
 >   shell and gitolite access, so he has **two** pubkeys in play.
 
 >   Normal users have only one pubkey, since they are only allowed to access
->   gitolite itself.  They do not need to worry about any of this
->   `~/.ssh/config` stuff, and their repo urls are very simple, like:
->   `git@my.git.server:reponame.git`.
+>   gitolite itself.  They do not need to worry about any of this stuff, and
+>   their repo urls are very simple, like: `git@my.git.server:reponame.git`.
 
 ----
 
-### files on client
+### ssh sanity checks
 
-  * 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!
+There are two quick sanity checks you can run:
 
-        ~/.ssh/id_rsa
-        ~/.ssh/id_rsa.pub
+  * running `ssh gitolite` should get you a list of repos you have rights to
+    access, as described [here][myrights]
 
-  * 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
+[myrights]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#myrights
 
-        ~/.ssh/sitaram
-        ~/.ssh/sitaram.pub
+  * conversely, `ssh git@server` should get you a command line
+
+If one or both of these does not work as expected, do this:
+
+  * first, check that your `~/.ssh` has two public keys, like below:
+
+        $ ls -al ~/.ssh/*.pub
+        -rw-r--r-- 1 sitaram sitaram 409 2008-04-21 17:42 /home/sitaram/.ssh/id_rsa.pub
+        -rw-r--r-- 1 sitaram sitaram 409 2009-10-15 16:25 /home/sitaram/.ssh/sitaram.pub
+
+    If it doesn't you have either lost your keys or you're on the wrong
+    machine.  As long as you have password access to the server you can alweys
+    recover; just pretend you're installing from scratch and start over.
+
+  * next, try running `ssh-add -l`.  On my desktop the output looks like this:
+
+        2048 63:ea:ab:10:d2:4f:88:f4:85:cb:d3:7d:3a:83:37:9a /home/sitaram/.ssh/id_rsa (RSA)
+        2048 d7:23:89:12:5f:22:4f:ad:54:7d:7e:f8:f5:2a:e9:13 /home/sitaram/.ssh/sitaram (RSA)
+
+    If you get only one line (typically the top one), you should ssh-add the
+    other one, using (in my case) `ssh-add ~/.ssh/sitaram`.
+
+    If you get no output, add both of them and check `ssh-add -l` again.
+
+    If this error keeps happening please consider installing [keychain][kch]
+    or something similar, or add these commands to your bash startup scripts.
+
+[kch]: http://www.gentoo.org/proj/en/keychain/
+
+  * Finally, make sure your `~/.ssh/config` has the required `host gitolite`
+    para (see below for more on this).
+
+Once these sanity checks have passed, things should be fine.  However, if you
+still have problems, make sure that the "origin" URL in any clones looks like
+`gitolite:reponame.git`, not `git@server:reponame.git`.
 
-### files on the server
+### explanation
+
+Here's how it all hangs together.
+
+#### 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.
@@ -72,12 +104,30 @@ In this document:
     argument `sitaram`.  This is how gitolite is invoked, (and is told the
     user logging in is "sitaram").
 
+#### 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
+
   * 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:
+    To understand why we need that, let's step back a bit.  Normally, you
+    might expect to access gitolite repos like this:
 
         ssh://git@server/reponame.git
 
@@ -87,7 +137,7 @@ In this document:
     control will work.
 
     You need to force ssh to use the *other* keypair when performing a git
-    operation.  With just ssh, that would be
+    operation.  With normal ssh, that would be
 
         ssh -i ~/.ssh/sitaram git@server
 
@@ -103,8 +153,8 @@ In this document:
              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
+    (The "gitolite" can be anything you want of course; it's like a group name
+    for all the stuff below it).  This ensures that typing
 
         ssh gitolite
 
@@ -119,17 +169,12 @@ In this document:
     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
+### more complex ssh setups
 
-  * 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
+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)?
 
-### two gitolite servers to manage?
+#### two gitolite servers to manage?
 
   * they can have the same key; no harm there (example, sitaram.pub)
 
@@ -146,3 +191,13 @@ In this document:
              hostname server2
              identityfile ~/.ssh/sitaram
 
+  * now access one server's repos as `gitolite:reponame.git` and the other
+    server's repos as `gitolite2:reponame.git`.
+
+### further reading
+
+While this focused mostly on the client side ssh, you may also want to read
+[this][glb] for a much more detailed explanation of the ssh magic on the
+server side.
+
+[glb]: http://sitaramc.github.com/0-installing/9-gitolite-basics.html#IMPORTANT_overview_of_ssh

src/00-easy-install.sh

@@ -446,7 +446,7 @@ CONFIG FILE FORMAT: see comments in conf/example.conf in the gitolite source.
 
 SSH MAGIC: Remember you (the admin) now have *two* keys to access the server
 hosting your gitolite setup -- one to get you a command line, and one to get
-you gitolite access; see doc/6-complex-ssh-setups.mkd.  If you're not using
+you gitolite access; see doc/6-ssh-troubleshooting.mkd.  If you're not using
 keychain or some such software, you may have to run this each time you log in:
 
     ssh-add ~/.ssh/$admin_name