requested by someone who told me it's high time I catered to the experts
too, and saved them some time on the install!
I took the opportunity to streamline the README (especially the "what"
section), and to prioritise the non-root method over the root method in
the install doc.
- caution about wild repos needing to be manually created on the
receiving side (because nothing gets auto-created now)
- caution about the right and wrong way to "delete" a config variable
- a few other minor fixes
We previously said all mirroring features are disabled if GL_HOSTNAME is
not set.
But what if, after mirroring has been setup, and master/slaves defined
for a repo, a slave admin fat-fingers the RC file and accidentally
comments out GL_HOSTNAME? We might end up violating RULE NUMBER ONE!
to my eternal shame (considering how proud I am of my documentation)
this was not mentioned anywhere! I'm getting old...
thanks to Pierre Habouzit for catching this
(also slipped in a few other minor doc changes. I wouldn't mix
unrelated stuff in a commit when doing code changes but it seems ok to
do this for docfixes, for some reason).
"gitolite-without-ssh" doc name was misleading; rename to
"authentication-vs-authorisation"
also restructure the whole thing to answer the main question better, and
fix up links from other places
Initial entry of markdown documentation as generated by pod2markdown.
Note addition of table-of-contents and appropriate anchors
Signed-off-by: Christopher M. Fuhrman <cfuhrman@panix.com>
[some formatting type changes done by Sitaram]
you might wonder why these are different from all the other variables in
the rc file... it's just that I never thought people would want to
change these!
This patch is dedicated to the person who, when referred to [1] for
gitweb access help, assumed we're talking about a Unix userid called
"gitweb" and said it still doesn't work. He looked at the description
examples and wasn't sure what to do with them. Finally, he missed the
sentence "All gitolite does is:" in the document, and assumed *he* was
supposed to do what the next 3 bullets said (in this case, create the
"description" file manually).
He didn't once think of the gitolite.conf file as being the location for
these instructions, or that "give read access" means "R = ..." instead
of a Unix level "chmod ...".
Do things have to be spelled out so goddamn clearly? Can't people think
for a few seconds and see if there is another way before giving up?
I blame the prevalence of Windows and GUI IDEs. People can only
"click". They can't "think" anymore...
[1]: http://sitaramc.github.com/gitolite/doc/2-admin.html#gwd
- allow a mob username to be defined; all unauthenticated access will
look to gitolite like this user (if you setup apache also properly)
- update doc with more details (some repeat stuff from `man
git-http-backend` but it's probably worth having everything in one
place
Fedora's config has over 11,000 repositories and the compiled config
file is over 20 MB in size. Although negligible on a server class
machine, on my laptop just parsing this file takes a good 2.5 seconds.
Even if you use GL_ALL_READ_ALL (see a couple of commits before this
one) to remove the overhead for 'read's, that's still a pretty big
overhead for writes. And GL_ALL_READ_ALL is not really a solution for
most people anyway.
With this commit, using GL_BIG_CONFIG adds another optimisation; see
doc/big-config.mkd for details (look for the word "split config" to find
the section that talks about it).
----
Implementation notes:
- the check for GL_NO_CREATE_REPOS has moved *into* the loop (which it
completely bypassed earlier) so that write_1_compiled_conf can be
called on each item
(we quietly do not document the 'able' adc, which is now the most
"official" adc in the sense that it has a new test, t64-write-able!)
other notes: fix bug in 'able' (not setting $loc)
(thanks to a somewhat heated "discussion" with "abstrakt" on #git)
While I don't agree with everything he said, some improvements are
always possible (always, always!) in docs:
- move the "conventions used" section closer to the action
- add note about RPM/DEB using "gitolite" as the user, not "git"
- de-emphasise multiple gitolite hosting users at the top; refer
advanced users to the already present detailed section later instead
- in that section, add a bit of intro, and hand-wave the inconsistency
between its 2 sub-sections ;-)
----
Unrelated to the "discussion" today, someone else (running Arch? don't
remember) had a system where /usr/local/bin was not in $PATH for a
normal user, so I added a note about that.
THE COMPILED CONFIG FILE FORMAT CHANGES WITH THIS VERSION. PLEASE DO
NOT MIX VERSIONS OR DOWNGRADE. Upgrading using normal gitolite upgrade
means should be fine, though.
Originally, we only allowed "R" and "RW" as categories of users supplied
to the `setperms` command. These map respectively to "READERS" and
"WRITERS" in the access rules.
Now:
- we prefer READERS instead of R and WRITERS instead of RW
- we allow the admin to define other categories as she wishes
(example: MANAGERS, TESTERS, etc). These do not have abbreviations,
however, so they must be supplied in full.
PLEASE, *PLEASE*, read the section in doc/wildcard-repositories.mkd for
more info. This is a VERY powerful feature and if you're not careful
you could mess up the ACLs nicely.
Backward compat note: you can continue to use the "R" and "RW"
categories when running the "setperms" command, and gitolite will
internally convert them to READERS and WRITERS categories.
----
implementation notes:
- new RC var called GL_WILDREPOS_PERM_CATS that is a space-sep list of
the allowed categories in a gl-perms file; defaults to "R RW" if not
specified
- wild_repo_rights no longer returns $c, $r, $wC, where $r = $user if
"R $user", $r = '@all' if "R @all", and similarly with $w and "RW".
Instead it returns $c and a new hash that effectively gives the same
info, but expanded to include any other valid categories (listed in
GL_WILDREPOS_PERM_CATS)
- consequently, the arguments that parse_acl takes also change the
same way
- (side note: R and RW are quietly converted to READERS and WRITERS;
however, new categories that you define yourself do not have
abbreviations)
- setperms validates perms to make sure only allowed categories are
used; however even if someone changed them behind the scenes,
wild_repo_rights will also check. This is necessary in case the
admin tightened up GL_WILDREPOS_PERM_CATS after someone had already
setperms-d his repos.
- as a bonus, we eliminate all the post-Dumper shenanigans, at least
for READERS and WRITERS. Those two now look, to the compile script,
just like any other usernames.
Well from now on they will be called "YourName".
Even better quote from essial on #git (after literally typing in
"sitaram.pub" instead of substituting his name as the instructions [in
bold] tell him to do):
come on you know how ubuntu users are
if they see fixed width fonts inside a box they immediately copy-paste it
UBUNTU USERS: I DIDN'T SAY THAT, SOMEONE ELSE DID! For details see
http://colabti.org/irclogger/irclogger_log/git?date=2010-11-04#l2417
[Although, since you apparently are quite happy to use a system that
default installs mono I doubt these little jibes matter to you
anyway...]
[idea: distribute my own pubkey with gitolite and instantly get access
to every gitolite install that is not behind a firewall, anywhere in the
world. No one will notice or realise what I'm doing - MUAHAHAHAHA!!!]
- get_rights_and_owner normalises its arg1 by stripping .git if
supplied, then sets the variable "repo" to the result as a side
effect
- new "help" adc with some default text but main purpose is to allow
site local help text
- other adc's refer to 'help' adc when appropriate
- 'undelete' renamed to 'restore'; that's what the KDE "trashcan"
program calls that operation
- minor typo in sample script in documentation
- main adc doc points to contrib/adc/repo-deletion.README now
I had someone delete the admin repo on the server, then run gl-setup
again, and complain that included config files did not get restored.
There have been others (see below) before with similar demands, but
those at least had the excuse of being provoked by genuine mistakes.
This guy was intentionally breaking stuff server side.
Wish I could say he was stupid, but actually he was probably smarter
than I. Just that his idea of the limits of gitolite's responsibility
was vastly different from mine.
----
[1] There was this guy who, as root, went on a "chmod go-rwx" spree for
security, which bollixed up gitweb access to all his repos, so he tells
me gitolite should be able to fix all the permissions on the next admin
push at least? (That is, instead of just setting umask as it currently
does, it should go on a chmod spree just like he did).
[2] Then there was the guy who told me gitolite should re-create all the
"gl-creater" files for his wildcard repos because he was restoring from
a git push --mirror backup and that doesn't preserve those files? I
tried to tell him that a git push --mirror doesn't preserve "config" or
"description" or "info/exclude" or any of the other files that git (not
gitolite) maintains, but he didn't care -- losing those did not affect
him (or he never had them), but losing these affected access control,
and it's my fault.
The old method of passing in usergroup info had some problems, which are
now fixed. It is also much easier to use now -- no more "wrapper"
script, plus it should work identially whether you use sshd or httpd.
See doc/big-config.mkd for details on the new method.
----
Notes on problems with the old method:
The old method for passing in usergroup info consisted of tacking them
on as extra arguments to gl-auth-command, after the username.
However, there are some problems with this method.
Some actions in gitolite look for permissions for users other than the
invoking user. Determining permissions for gitweb and daemon is one.
An admin asking for "info" on some other user, is another.
However, the list of groups sent in via the command line
pertains only to the invoking user, so these actions don't work
correctly. They may even pick up the wrong permissions.
What it all boils down to is that we need group information for any user
dynamically, instead of being passed a (static) list just for the
invoking user.
- hardcode 0700 mode for GL_ADMINDIR tree (thanks to ma at
ibitsense.com) for catching this
- honor REPO_UMASK for GL_REPO_BASE_ABS creation
- plus a minor doc update
