new doc on gitolite without ssh, plus some minor docfixes

This commit is contained in:
Sitaram Chamarty 2011-03-28 18:54:32 +05:30
parent 12ab89abc6
commit 0f377a7679
4 changed files with 110 additions and 21 deletions

View file

@ -0,0 +1,75 @@
# gitolite without ssh
Gitolite does not actually need ssh. If you managed to read
[doc/gitolite-and-ssh.mkd][gas], you may have realised that the crux of
gitolite is that it be eventually invoked as
/full/path/to/gl-auth-command some-authenticated-gitolite-username
(where the "gitolite username" is a "virtual" username; it does not have to
be, and usually *isn't*, an actual *unix* username).
[gas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html
### sidebar: authentication versus authorisation
> Just for completeness, I'd like to loosely define these two animals.
> **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.
### what does gitolite actually do
With that background, here's the truth about gitolite:
> ***Gitolite does not do authentication. It only does authorisation.***
Yes, the default mode of using gitolite does use ssh keys, but all it's doing
is helping you **setup** ssh-based authentication **as a convenience to you**.
But nothing forces you to use it. The best example: there are no ssh keys
involved if you setup [smart http][sh] mode.
[sh]: http://sitaramc.github.com/gitolite/doc/http-backend.html
In other words, authentication is the job of `sshd` or `httpd`, not gitolite.
### using other authentication systems with gitolite
The bottom line in terms of how to invoke gitolite has been described up at
the top, 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.
[Side note: it also expects that the environment variable
`SSH_ORIGINAL_COMMAND` contain the command that the client sent (typically a
git-receive-pack or git-upload-pack command), or in some CGI variables when
using [smart http][sh] mode.]
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
unauthenticated, and `file://` doesn't really apply to this discussion, so
we're ignoring those).
One common example is LDAP. 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:password@git.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.
Finally, gitolite allows you to store *group* information externally too. See
[here][ldap] for more on this.
[ldap]: http://sitaramc.github.com/gitolite/doc/big-config.html#_storing_usergroup_information_outside_gitolite_like_in_LDAP_

View file

@ -231,12 +231,14 @@ have 6 names in it.
##### the special `@all` group ##### the special `@all` group
There's a special group called `@all` that includes all authenticated users; There's a special group called `@all` that includes all authenticated users
you've seen examples of it earlier. when used as a username; you've seen examples of it earlier.
[Advanced users: also see the entry for `GL_ALL_INCLUDES_SPECIAL` in [Advanced users: also see the entry for `GL_ALL_INCLUDES_SPECIAL` in
[doc/gitolite.rc.mkd][rcdoc].] [doc/gitolite.rc.mkd][rcdoc].]
When used as a reponame, it includes all repos.
<a name="_advanced_access_control"></a> <a name="_advanced_access_control"></a>
### advanced access control ### advanced access control

View file

@ -14,21 +14,23 @@ gitolite would just run out of memory and die!).
[fedora]: http://lists.fedoraproject.org/pipermail/devel-announce/2010-July/000647.html [fedora]: http://lists.fedoraproject.org/pipermail/devel-announce/2010-July/000647.html
[bc]: http://sitaramc.github.com/gitolite/doc/big-config.html [bc]: http://sitaramc.github.com/gitolite/doc/big-config.html
The **KDE project** is currently [testing][kdet] gitolite to see if it will The **KDE project** [uses][kde] gitolite (in combination with redmine for
suit their needs (in combination with redmine for issue tracking and issue tracking and reviewboard for code review). Apart from the usual access
reviewboard for code review), after an initial [review of alternatives][kdera] control, the KDE folks are heavy users of the "ad hoc repo creation" features
by a core group. Apart from the usual access control, the KDE folks will be enabled by wildrepos and the accompanying commands. Several of the changes to
using many of the "ad hoc repo creation" features enabled by wildrepos and the the "admin defined commands" were also inspired by KDE's needs. See [section
accompanying commands. Some of the changes to the "admin defined commands" 5][s5] and [section 6][s6] of the above linked page for details.
were inspired by KDE's needs.
[kdet]: http://www.omat.nl/2010/07/07/move-to-git-the-progress-so-far/ [kde]: http://community.kde.org/Sysadmin/GitKdeOrgManual
[s5]: http://community.kde.org/Sysadmin/GitKdeOrgManual#Server-side_commands
[s6]: http://community.kde.org/Sysadmin/GitKdeOrgManual#Personal_repositories
[kdera]: http://permalink.gmane.org/gmane.comp.kde.scm-interest/1437 [kdera]: http://permalink.gmane.org/gmane.comp.kde.scm-interest/1437
**Prof. Hiren Patel** of the University of Waterloo is responsible for the **Prof. Hiren Patel** of the University of Waterloo is responsible for the
existence of the fairly popular "[wildrepos][wild]" feature. The existence of the fairly popular "[wildrepos][wild]" feature. The
documentation was pretty much written with his use case in mind, but of course documentation was pretty much written with his use case in mind, but of course
it turns out to be useful for a lot of people. it turns out to be useful for a lot of people, as you can see from the
previous para on KDE's use of gitolite.
In fact, he surprised the heck out of me recently by saying that if it hadn't In fact, he surprised the heck out of me recently by saying that if it hadn't
been for this feature, he might not have used git itself -- which is a pretty been for this feature, he might not have used git itself -- which is a pretty

View file

@ -2,12 +2,7 @@
# documentation for this program is right here, please read # documentation for this program is right here, please read
# IMPORTANT NOTES: # IMPORTANT: also see usage notes below
# - this program MUST be placed in the same directory as the rest of the
# programs that come with gitolite
# - this program MUST be run by supplying its full path!
# BACKGROUND/PURPOSE: # BACKGROUND/PURPOSE:
@ -48,13 +43,28 @@ GetOptions('batch' => \$batch);
unless ($batch) { unless ($batch) {
print STDERR " print STDERR "
This is a cronnable, batchable, program to rewrite ~/.ssh/authorized_keys This is a cronnable, batchable, program to rewrite ~/.ssh/authorized_keys
using public keys in a given directory. using public keys in a given directory. It MUST be run by supplying its
full path, and the rest of the gitolite scripts must be in the same
directory. Here's how to run it:
If you are ABSOLUTELY sure you know what you're doing, here's how: /full/path/to/gl-setup-authkeys -batch keydir
$0 -batch keydir where 'keydir' contains a bunch of '*.pub' files.
where 'keydir' contains a bunch of '*.pub' files\n\n"; If you're not sure what the full path to the script should be, look in
~/.ssh/authorized_keys for the path to the gl-auth-command script.
If you managed to lose that file (how careless of you!) then, depending on
what install mode you used, it's either \$HOME/.gitolite/src or \$HOME/bin
or /usr/local/bin or whatever your package maintainer decided. I leave it
to you to figure out which method gets you which PATH ;-) In this case
you'll also have to set GL_BINDIR to that same path *and* export it, so
something like this should do:
export GL_BINDIR=/that/full/path/you/just/found
\$GL_BINDIR/gl-setup-authkeys -batch keydir
The keydir can be found from the value of \$GL_KEYDIR in ~/.gitolite.rc\n\n";
exit 1; exit 1;
} }