diff --git a/doc/6-complex-ssh-setups.mkd b/doc/6-ssh-troubleshooting.mkd similarity index 57% rename from doc/6-complex-ssh-setups.mkd rename to doc/6-ssh-troubleshooting.mkd index f2292fa..efd5f2b 100644 --- a/doc/6-complex-ssh-setups.mkd +++ b/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 -### files on the server +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`. + +### 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 +### more complex ssh setups - * `ssh gitolite` should get you the `SSH_ORIGINAL_COMMAND` error. If you - get a command line, something is wrong +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)? - * 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? +#### 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 diff --git a/src/00-easy-install.sh b/src/00-easy-install.sh index b8ad9fe..4cc6ff1 100755 --- a/src/00-easy-install.sh +++ b/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