master TOC | main page | single-page | license
This is for gitolite "g3"; for older (v2.x) documentation click here
This document will explain why an "ssh issue" is almost never a "gitolite issue", and, indirectly, why I dont get too excited about the former.
Note: for actual ssh troubleshooting see this.
Here is a fundamental point: Gitolite does not do authentication. It only does authorisation.
So first, let's loosely define these words:
Authentication is the process of verifying that you are who you claim to be. An authentication system will establish that I am the user "sitaram" on my work system. The one behind gmail will similarly establish that I am "sitaramc". And so on...
Authorisation is the process of asking what you want to do and deciding if you're allowed to do it or not.
Now, if you managed to read about gitolite and ssh, you know that gitolite is meant to be invoked as:
(where the "gitolite username" is a "virtual" username; it does not have to be, and usually isn't, an actual unix username).
As you can see, authentication happens before gitolite is called.
No I don't. Not in "core" gitolite from g3 onwards :-)
The default setup does use ssh keys, but it's only helping you setup ssh-based authentication as a convenience to you. But in fact it is a completely separate program that you can disable (in the rc file) or replace with something else of your choice.
For example, in both smart http and ldap-backed sshd, gitolite has no role to play in creating users, setting up their passwords/keys, etc.
(where "X" is some ssh related behaviour change or feature)
Well, if it's not a security issue I won't. But since it's no longer part of "core" gitolite, I can be much more relaxed about taking patches, or even alternative implementations.
While we're on the subject, locking someone out is not a security issue. Even if you lost the admin key, the docs tell you how to recover from such errors. You do need some password based method to get a shell command line on the server, of course.
The bottom line in terms of how to invoke gitolite has been described above, and as long as you manage to do that gitolite won't even know how the authentication was done. Which in turn means you can use whatever authentication scheme you want.
It also expects the
SSH_ORIGINAL_COMMAND environment variable to contain the
full command (typically starting with git-receive-pack or git-upload-pack)
that the client sent. Also, when using smart http, things are somewhat
different: gitolite uses certain environment variables that it expects httpd
to have set up. Even the user name comes from the
variable instead of as a command line argument in this case.
However, it has to be an authentication system that is compatible with sshd or
httpd in some form. Why? Because the git client accessing the server only
knows those 2 protocols to "speak git". (Well, the
git:// protocol is
file:// doesn't really apply to this discussion, so
we're ignoring those).
For example, let's say you have an LDAP-based authentication system somewhere.
It is possible to make apache use that to authenticate users, so when a user
accesses a git url using
http://sitaram:email@example.com/repo, it is
LDAP that does the actual authentication. [I wouldn't know how to do it but I
know it is possible. Patches to this doc explaining how are welcome!]
There are also ssh daemons that use LDAP to store the authorised keys (instead
of putting them all in
~/.ssh/authorized_keys). The clients will still need
to generate keypairs and send them to the admin, but they can be more
centrally stored and perhaps used by other programs or tools simultaneously,
which can be useful.
Gitolite's groups are pretty convenient, but some organisations already have similar (or sufficient) information in their LDAP store.
Gitolite can tap into that information, with a little help. Write a program
which, given a username, queries your LDAP store and returns a space-separated
list of groups that the user is a member of. Then put the full path to this
program in an rc variable called
GROUPLIST_PGM, like so:
GROUPLIST_PGM => '/home/git/bin/ldap-query-groups',
Now you can use those groupnames in access rules in gitolite, because the user is a member of those groups as well as any normal gitolite groups you may have added him to in the conf file.
Caution: your program must do its own logging if you want the audit trail of "why/how did this user get access to this repo at this time?" to resolve properly. Gitolite does not do any logging of the results of the queries because for people who don't need it that would be a huge waste.