diff --git a/doc/6-complex-ssh-setups.mkd b/doc/6-complex-ssh-setups.mkd index c274a73..fa69abf 100644 --- a/doc/6-complex-ssh-setups.mkd +++ b/doc/6-complex-ssh-setups.mkd @@ -1,135 +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 - +# 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 +