c4cbfabd4c
Ouch! How mortifying :) I'd always thought this was one of the Brit/US differences, but to find out that it really *isn't* a word... hmph! Anyway, in the interest of not breaking existing wild repos, the ownership file is still called "gl-creater". Everything else has been changed. (...thanks to Sverre)
287 lines
10 KiB
Markdown
287 lines
10 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.
|
|
|
|
Also, there are some limitations. For example, you cannot specify gitconfig
|
|
values for a wildcard repo; it only works for actual repos.
|
|
|
|
There may be other such missing features. Sometimes it's just not possible to
|
|
make it work. Or it may be cumbersome enough that unless there are *no*
|
|
workarounds I may not have the time to code it right away.
|
|
|
|
----
|
|
|
|
In this document:
|
|
|
|
* wildcard repos
|
|
* wildcard repos with creator name in them
|
|
* wildcard repos without creator name in them
|
|
* side-note: line-anchored regexes
|
|
* contrast with refexes
|
|
* handing out rights to wildcard-matched repos
|
|
* setting a gitweb description for a wildcard-matched repo
|
|
* reporting
|
|
* other issues and discussion
|
|
* how it actually works
|
|
|
|
This document is mostly "by example".
|
|
|
|
----
|
|
|
|
### Wildcard repos
|
|
|
|
Which of these alternatives you choose depends on your needs, and the social
|
|
aspects of your environment. The first one is a little more rigid, making it
|
|
harder to make mistakes, and the second is more flexible and trusting.
|
|
|
|
#### 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 ;-)
|
|
|
|
#### 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.
|
|
|
|
### 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.
|
|
|
|
#### 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.
|
|
|
|
### 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.
|
|
|
|
### setting a gitweb description for a wildcard-matched repo
|
|
|
|
Similar to the getperm/setperm commands, there are the getdesc/setdesc
|
|
commands, thanks to Teemu.
|
|
|
|
### reporting
|
|
|
|
Remember the cool stuff you see when you just do `ssh git@server` (grep for
|
|
"myrights" in `doc/3-faq-tips-etc.mkd` if you forgot, or go [here][mr]).
|
|
|
|
[mr]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#myrights
|
|
|
|
This still works, except the format is a little more compressed to accommodate
|
|
a new column (at the start) for "C" permissions, which indicate that you are
|
|
allowed to *create* repos matching that pattern.
|
|
|
|
In addition, there is also the "expand" command, which takes any regex pattern
|
|
and returns you a list of all wildcard-created repos that you have access to
|
|
which fit that pattern. And if, as an administrator, you wish to list out
|
|
*every single* repo that your users have created, add this to your config
|
|
file:
|
|
|
|
repo @all
|
|
R = sitaram # or whoever you are
|
|
|
|
Push the config, then try
|
|
|
|
ssh gitolite expand
|
|
|
|
### other issues and discussion
|
|
|
|
* *what if the repo name being pushed matches more than one pattern*?
|
|
|
|
I think it would be very hard to reason about access if we were to do
|
|
something like combine all the access rights in all the matching patterns.
|
|
No matter how you do it, and how carefully you document it, there'll be
|
|
someone who is surprised by the result.
|
|
|
|
And in security, that's a ***Bad Thing***.
|
|
|
|
So we don't combine permissions. At runtime, we die if we find more than
|
|
one match. Let 'em go holler at the admin for creating multiple matching
|
|
repo patterns :-)
|
|
|
|
This can make some repos inaccessible if the patterns changed *after* they
|
|
were created. The administrator should be careful not to do this. Most
|
|
of the time, it won't be difficult; the fixed prefix will usually be
|
|
different anyway so there won't be overlaps.
|
|
|
|
### 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. Only one pattern is allowed to match;
|
|
matching more than one is an error.
|
|
|
|
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 :)
|
|
|
|
[jwzq]: http://regex.info/blog/2006-09-15/247
|
|
|
|
[av]: http://en.wikipedia.org/wiki/Autovivification
|