# password access to gitolite

## (a.k.a: turning real users into gitolite users)

<a name="_problems"></a>

### problems

*Problem 1*: Here's one type of problem some admins have:

  * Some of your users already have a real (unix) userid on the *same server*
    as the gitolite hosting user.
  * They don't all use ssh keys; some may still be using passwords and don't
    want to change.
  * They want to use this existing userid to access the gitolite served repos.

This document has a solution to this problem!

*Problem 2*: And here's a somewhat different one:

  * Some of your users are not willing to use ssh keys; they're only
    comfortable with passwords.
  * But gitolite *requires* ssh key-based access; it can't work if you use a
    password to get access (because then there is no way to distinguish one
    user from another).

Well, as the math folks say, "reduce it to a known problem".  Give them all
Unix userids on the same server as gitolite, with password access, so that
problem 2 reduces to problem 1 ;-)

<font color="gray">If you created these Unix accounts *only* to solve this
pesky password problem, and do not wish them to actually have shell access or
be able to do anything else on the server, don't worry -- that's easy to
handle too.</font>

<a name="_solution"></a>

### solution

Briefly, the Unix userid is made to act like a "gitolite proxy".

Here's a more detailed explanation.

Normal gitolite flow, for a user called Alice, is like this:

                                ssh key
        alice     ---------------------------------------->    git
    (workstation)              (REQUIRED)                    (server)

However, if Alice has her own real (unix) userid on the server, and the admin
sets things up according to this document, then Alice can do this:

                      password
        alice     ------ OR ----->  alice
    (workstation)     ssh key      (server)

The **important** thing to note here is that she doesn't need ssh keys; she
can use passwords if she wants to.

Behind the scenes, the gitolite/git conversation is being transparently
forwarded to the gitolite hosting user, so it is *actually* like this:

                      password                  ssh key
        alice     ------ OR ----->  alice   - - - - - - - >    git
    (workstation)     ssh key      (server)    (REQUIRED)  (localhost)

The second connection is transparent to Alice; she still thinks she is talking
to her own userid.  In git URL terms, she simply uses `alice@server:reponame`,
without realising that behind the scenes this is getting forwarded to
`git@server:reponame`.

This second connection *does* require ssh keys, but since they're all on the
server, it's scriptable and automatable so the user doesn't have to deal with
these pesky ssh keys.

<a name="_some_hints_notes_and_caveats"></a>

### some hints, notes and caveats

  * This doesn't mean all your users have to be like this.  You can have
    normal users also.  In fact, you can have users who give you a pub key
    from their workstation the normal way, as well as use this method.

  * Special commands and ADCs will NOT work from the workstation for such
    users; they have to log on to their own userid on the server and run the
    appropriate command (such as `ssh git@localhost info`) from there.  <font
    color="gray">We could have handled the known special commands (info,
    expand, setperms, etc.), but considering that an ADC could be called
    *anything*, a general solution is impossible.</font>

  * If you server's host key changes, you may have to manually fix up all the
    host keys in all the user's `~/.ssh/known_hosts` files.  Not too difficult
    if you're sure they all have just the one host key, but if they have
    multiple, you have to carefully delete and replace just the one line that
    pertains to localhost.  Scripts to do this cleanly are welcome...

<a name="_what_the_2_scripts_actually_do"></a>

### what the 2 scripts actually do

  * `gl-shell` will become the new login shell for these users.  This shell
    will forward git clone/fetch/push requests to the gitolite server.

    This redirection is so transparent that I had to explicitly code a message
    ("forwarding to git@server") to make troubleshooting easier.

  * `gl-shell-setup` is run by root, once for each user.  (You can run it
    multiple times; it's designed to be idempotent).  As root, it changes the
    user's shell to `gl-shell` (full path), then sets up an RSA key for the
    user if one is not already present.  Then it runs as `git` (or whatever
    the hosting user is) and takes the pubkey and adds it as (to continue our
    example) `alice@localhost.pub` in keydir of the admin repo, which is then
    pushed.

    Notice the use of [this trick][oumk] to allow Alice to allow users to have
    other (gitolite normal) keys as well, such as perhaps from a laptop.

<a name="_setting_it_up"></a>

### setting it up

Here's how to set this up.  First, the **one-time** tasks:

  * Install gitolite as normal, if not already installed.  This will require
    you to use ssh keys for your (admin's) own access, but I assume that's ok.

  * As root, copy the program `contrib/real-users/gl-shell` to
    `/usr/local/bin`.

  * As root, customise the program `/usr/local/bin/gl-shell`.  You will need
    to change only 2 variables at the top in a section clearly marked as
    'site-local changes'.

  * As root, copy `contrib/real-users/gl-shell-setup` to some place on root's
    `$PATH` and customise it similarly to gl-shell.  Note that there are many
    more configurable values in this script.  **NOTE** also that this includes
    fixing the `chsh` command, which may be OS/distro dependent.  The supplied
    command is good for Fedora.

Now, for each user 'alice' that has her own real (unix) userid, and also needs
to access gitolite *via* her own id, run the command `gl-shell-setup alice`.

And that's really all there is to it.

[oumk]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_one_user_many_keys