3f57f18ee2
-79f0a5f("(big one!) more than one wildcard may match a repo...") makes some of the dire warnings about this irrelevant -d1d2c3eandad64f99("git config settings in wild repos: part 1" and "...part 2") makes this caveat also useless While we were about it, we added a quick intro and tried to make some other details a little clearer.
289 lines
11 KiB
Markdown
289 lines
11 KiB
Markdown
# repositories named with wildcards
|
|
|
|
***IMPORTANT NOTE***:
|
|
|
|
This feature may be somewhat "brittle" in terms of security. Creating
|
|
repositories based on wild cards, giving "ownership" to the specific user who
|
|
created it, allowing him/her to hand out R and RW permissions to other users
|
|
to collaborate, all these are possible. And any of these could have a bug in
|
|
it. I haven't found any yet, but that doesn't mean there aren't any.
|
|
|
|
----
|
|
|
|
In this document:
|
|
|
|
* <a href="#_quick_introduction">quick introduction</a>
|
|
* <a href="#_rc_file_setting_required">rc file setting required</a>
|
|
* <a href="#_examples_of_wildcard_repos">examples of wildcard repos</a>
|
|
* <a href="#_wildcard_repos_with_creator_name_in_them">wildcard repos with creator name in them</a>
|
|
* <a href="#_wildcard_repos_without_creator_name_in_them">wildcard repos without creator name in them</a>
|
|
* <a href="#_side_note_line_anchored_regexes">side-note: line-anchored regexes</a>
|
|
* <a href="#_contrast_with_refexes">contrast with refexes</a>
|
|
* <a href="#_handing_out_rights_to_wildcard_matched_repos">handing out rights to wildcard-matched repos</a>
|
|
* <a href="#_setting_a_gitweb_description_for_a_wildcard_matched_repo">setting a gitweb description for a wildcard-matched repo</a>
|
|
* <a href="#_reporting">reporting</a>
|
|
* <a href="#_how_it_actually_works">how it actually works</a>
|
|
|
|
----
|
|
|
|
This document is mostly "by example".
|
|
|
|
----
|
|
|
|
<a name="_quick_introduction"></a>
|
|
|
|
### quick introduction
|
|
|
|
The wildrepos feature allows you to specify access control rules using regular
|
|
expression patterns, so you can have many actual repos being served by a
|
|
single set of rules in the config file. The regex pattern can also include
|
|
the word `CREATOR` in it, allowing you to parametrise the name of the user
|
|
creating the repo. The examples below will make this clearer.
|
|
|
|
<a name="_rc_file_setting_required"></a>
|
|
|
|
### rc file setting required
|
|
|
|
This feature requires that you set `$GL_WILDREPOS` to "1" in `~/.gitolite.rc`
|
|
on the server. Please search for that variable and see comments around it in
|
|
`conf/example.gitolite.rc` for more information on this.
|
|
|
|
<a name="_examples_of_wildcard_repos"></a>
|
|
|
|
### examples of wildcard repos
|
|
|
|
As the introduction said, you can include the word `CREATOR` in the regex
|
|
pattern, though it is not mandatory. We'll look at examples of both types of
|
|
usage.
|
|
|
|
Which of these alternatives you choose depends on your needs, and the social
|
|
aspects of your environment. Including the creator name in the pattern keeps
|
|
users rigidly separated from each others repos, and is good for a largely
|
|
autonomous collection of users with a high probability of repo name clashes.
|
|
|
|
Omitting the creator name from the pattern puts the repos in a common
|
|
namespace, and is suitable for environments where it is not very important to
|
|
keep track of who actually created the repo (except for granting access), but
|
|
needs more communication / co-operation among the users to avoid repo name
|
|
clashes.
|
|
|
|
<a name="_wildcard_repos_with_creator_name_in_them"></a>
|
|
|
|
#### wildcard repos with creator name in them
|
|
|
|
Here's an example snippet:
|
|
|
|
@prof = u1
|
|
@TAs = u2 u3
|
|
@students = u4 u5 u6
|
|
|
|
repo assignments/CREATOR/a[0-9][0-9]
|
|
C = @students
|
|
RW+ = CREATOR
|
|
RW = WRITERS @TAs
|
|
R = READERS @prof
|
|
|
|
For now, ignore the special usernames READERS and WRITERS, and just create a
|
|
new repo, as user "u4" (a student):
|
|
|
|
$ git clone git@server:assignments/u4/a12
|
|
Initialized empty Git repository in /home/sitaram/t/a12/.git/
|
|
Initialized empty Git repository in /home/gitolite/repositories/assignments/u4/a12.git/
|
|
warning: You appear to have cloned an empty repository.
|
|
|
|
Notice the *two* empty repo inits, and the order in which they occur ;-)
|
|
|
|
<a name="_wildcard_repos_without_creator_name_in_them"></a>
|
|
|
|
#### wildcard repos without creator name in them
|
|
|
|
Here's how the same example would look if you did not want the CREATOR's name
|
|
to be part of the actual repo name.
|
|
|
|
repo assignments/a[0-9][0-9]
|
|
C = @students
|
|
RW+ = CREATOR
|
|
RW = WRITERS @TAs
|
|
R = READERS @prof
|
|
|
|
We haven't changed anything except the repo name pattern. This means that the
|
|
first student that creates, say, `assignments/a12` becomes the owner.
|
|
Mistakes (such as claiming a12 instead of a13) need to be rectified by an
|
|
admin logging on to the back end, though it's not too difficult.
|
|
|
|
You could also repace the C line like this:
|
|
|
|
C = @TAs
|
|
|
|
and have a TA create the repos in advance.
|
|
|
|
In either case, they could then use the `setperms` feature to specify which
|
|
users are "READERS" and which are "WRITERS". See later for details.
|
|
|
|
<a name="_side_note_line_anchored_regexes"></a>
|
|
|
|
### side-note: line-anchored regexes
|
|
|
|
A regex like
|
|
|
|
repo assignments/S[0-9]+/A[0-9]+
|
|
|
|
would match `assignments/S02/A37`. It will not match `assignments/S02/ABC`,
|
|
or `assignments/S02/a37`, obviously.
|
|
|
|
But you may be surprised to find that it does not match even
|
|
`assignments/S02/A37/B99`. This is because internally, gitolite
|
|
*line-anchors* the given regex; so that regex actually becomes
|
|
`^assignments/S[0-9]+/A[0-9]+$` -- notice the line beginning and ending
|
|
metacharacters.
|
|
|
|
<a name="_contrast_with_refexes"></a>
|
|
|
|
#### contrast with refexes
|
|
|
|
Just for interest, note that this is in contrast to the refexes for the normal
|
|
"branch" permissions, as described in `conf/example.conf` and elsewhere.
|
|
These "refexes" are only anchored at the start; a pattern like
|
|
`refs/heads/master` actually can match `refs/heads/master01/bar` as well, even
|
|
if no one will actually push such a branch! You can anchor both sides if you
|
|
really care, by using `master$` instead of `master`, but that is *not* the
|
|
default for refexes.
|
|
|
|
<a name="_handing_out_rights_to_wildcard_matched_repos"></a>
|
|
|
|
### handing out rights to wildcard-matched repos
|
|
|
|
In the examples above, we saw two special "user" names: READERS and WRITERS.
|
|
The permissions they have are controlled by the config file, but ***who is
|
|
part of this list*** is controlled by the person who created the repository.
|
|
|
|
The use case is that, although our toy example has only 3 students, in reality
|
|
there will be a few dozen, but each assignment will be worked on only by a
|
|
handful from among those. This allows the creator to take ad hoc sets of
|
|
users from among the actual users in the system, and place them into one of
|
|
two categories (whose permissions are, in this example, R and RW
|
|
respectively). In theory you could do the same thing by creating lots of
|
|
little "assignment-NN" groups in the config file but that may be a little too
|
|
cumbersome for non-secret environments.
|
|
|
|
Create a small text file that contains the permissions you desire:
|
|
|
|
$ cat > myperms
|
|
R u5
|
|
RW u6
|
|
(hit ctrl-d here)
|
|
|
|
...and use the new "setperms" command to set permissions for your repo:
|
|
|
|
$ ssh git@server setperms assignments/u4/a12 < myperms
|
|
New perms are:
|
|
R u5
|
|
RW u6
|
|
|
|
'setperms' will helpfully print what the new permissions are but you can also
|
|
use 'getperms' to check:
|
|
|
|
$ ssh git@server getperms assignments/u4/a12
|
|
R u5
|
|
RW u6
|
|
|
|
The following points are important:
|
|
|
|
* note the syntax of the commands; it's not a "git" command, and there's no
|
|
`:` like in a repo URL. The first space-separated word is R or RW, and
|
|
the rest are simple usernames.
|
|
|
|
* whoever you specify as "R" will match the special user READERS. "RW" will
|
|
match WRITERS.
|
|
|
|
<a name="_setting_a_gitweb_description_for_a_wildcard_matched_repo"></a>
|
|
|
|
### setting a gitweb description for a wildcard-matched repo
|
|
|
|
Similar to the getperms/setperms commands, there are the getdesc/setdesc
|
|
commands, thanks to Teemu.
|
|
|
|
<a name="_reporting"></a>
|
|
|
|
### reporting
|
|
|
|
In order to see what repositories were created from a wildcard, use the
|
|
"expand" command, described briefly in [doc/report-output.mkd][repout].
|
|
|
|
<a name="_how_it_actually_works"></a>
|
|
|
|
### how it actually works
|
|
|
|
This section tells you what is happening inside gitolite so you can understand
|
|
this feature better. Let's use the config example at the beginning of this
|
|
document:
|
|
|
|
repo assignments/CREATOR/a[0-9][0-9]
|
|
C = @students
|
|
RW+ = CREATOR
|
|
RW = WRITERS @TAs
|
|
R = READERS @prof
|
|
|
|
First we find the set of rules to apply. This involves replacing the special
|
|
words CREATOR, WRITERS, and READERS with appropriate usernames to derive an
|
|
"effective" ruleset for the repo in question.
|
|
|
|
For a **new** repo, replace the word CREATOR in all repo patterns and rules
|
|
with the name of the invoking user.
|
|
|
|
> (Note: this is why you should never use `C = CREATOR`; it becomes `C =
|
|
> invoking_user`! Unless you really want to allow *all* users to create
|
|
> repos, you should restrict "C" perms to an actual user or set of users,
|
|
> like in the examples in this document).
|
|
|
|
For an **existing** repo, do the same but replace with the name of the user
|
|
who actually *created* the repo (this name is recorded in a special file in
|
|
the repo directory when the repo is first created, so it is available).
|
|
|
|
Now find a repo pattern that matches the actual reponame being pushed -- this
|
|
tells you which set of rules to apply. There can be multiple matches; if so,
|
|
they will all be applied in the sequence they appear in the config file.
|
|
|
|
If the invoking user has been given "RW" permissions using `setperms`, all
|
|
occurrences of the word WRITERS are replaced by the invoking username.
|
|
Otherwise -- and this includes the "new repo" case, since you couldn't have
|
|
run `setperms` on a non-existant repo -- they are replaced by "NOBODY".
|
|
|
|
(The same thing is done with "R" access and the word "READERS".)
|
|
|
|
At this point we have an effective ruleset, and the normal access rules (R,
|
|
RW, etc) apply, with the addition that the invoking user needs "C" access to
|
|
be able to create a repo.
|
|
|
|
> (Note: "C" rights do not automatically give the CREATOR any other rights;
|
|
> they must be specifically given. `RW+ = CREATOR` is recommended in most
|
|
> situations, as you can see in our example).
|
|
|
|
Assuming user "u4" trying to push-create a new repo called
|
|
`assignments/u4/a23`, this is what the effective ruleset looks like (we're
|
|
ignoring the "NOBODY" business):
|
|
|
|
repo assignments/u4/a23
|
|
C = @students
|
|
RW+ = u4
|
|
RW = @TAs
|
|
R = @prof
|
|
|
|
If u4 gives "RW" perms to u5 using `setperms`, and u5 tries to access that
|
|
repo, the ruleset looks like:
|
|
|
|
repo assignments/u4/a23
|
|
C = @students
|
|
RW+ = u4
|
|
RW = u5 @TAs
|
|
R = @prof
|
|
|
|
I hope that helps.
|
|
|
|
----
|
|
|
|
Enjoy, and please use with care. This is pretty powerful stuff. As they say:
|
|
if you break it, you get to keep both pieces :)
|
|
|
|
[repout]: http://github.com/sitaramc/gitolite/blob/pu/doc/report-output.mkd
|