new doc on gitolite without ssh, plus some minor docfixes

doc/gitolite-without-ssh.mkd

@@ -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_

doc/gitolite.conf.mkd

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

doc/who-uses-it.mkd

@@ -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
 [bc]: http://sitaramc.github.com/gitolite/doc/big-config.html
 
-The **KDE project** is currently [testing][kdet] gitolite to see if it will
-suit their needs (in combination with redmine for issue tracking and
-reviewboard for code review), after an initial [review of alternatives][kdera]
-by a core group.  Apart from the usual access control, the KDE folks will be
-using many of the "ad hoc repo creation" features enabled by wildrepos and the
-accompanying commands.  Some of the changes to the "admin defined commands"
-were inspired by KDE's needs.
+The **KDE project** [uses][kde] gitolite (in combination with redmine for
+issue tracking and reviewboard for code review).  Apart from the usual access
+control, the KDE folks are heavy users of the "ad hoc repo creation" features
+enabled by wildrepos and the accompanying commands.  Several of the changes to
+the "admin defined commands" were also inspired by KDE's needs.  See [section
+5][s5] and [section 6][s6] of the above linked page for details.
 
-[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
 
 **Prof. Hiren Patel** of the University of Waterloo is responsible for the
 existence of the fairly popular "[wildrepos][wild]" feature.  The
 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
 been for this feature, he might not have used git itself -- which is a pretty

src/gl-setup-authkeys

@@ -2,12 +2,7 @@
 
 # documentation for this program is right here, please read
 
-# IMPORTANT NOTES:
-
-# - 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!
+# IMPORTANT: also see usage notes below
 
 # BACKGROUND/PURPOSE:
 
@@ -48,13 +43,28 @@ GetOptions('batch' => \$batch);
 unless ($batch) {
     print STDERR "
     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;
 }