gitolite/doc/6-complex-ssh-setups.mkd

# 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