gitolite/doc/4-wildcard-repositories.mkd

217 lines
7.7 KiB
Markdown
Raw Normal View History

2009-12-06 07:11:02 +01:00
# 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.
2009-12-06 07:11:02 +01:00
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.
2009-12-06 07:11:02 +01:00
----
In this document:
* wildcard repos
* wildcard repos with creater name in them
* wildcard repos without creater 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
2009-12-06 07:11:02 +01:00
* reporting
* other issues and discussion
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 creater name in them
Here's an example snippet:
@prof = u1
@TAs = u2 u3
@students = u4 u5 u6
repo assignments/CREATER/a[0-9][0-9]
C = @students
RW+ = CREATER
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 ;-) Now
make some changes and push, and after that, that specific repo
(`assignments/u4/a12`) behaves as if the access control looked like this:
# effective config
repo assignments/u4/a12
RW+ = u4
RW = WRITERS @TAs
R = READERS @prof
#### Wildcard repos without creater name in them
Here's how the same example would look if you did not want the CREATER's name
to be part of the actual repo name.
repo assignments/a[0-9][0-9]
C = @students
RW+ = CREATER
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.
2009-12-06 16:10:23 +01:00
In either case, they could then use the `setperms` feature to specify which
users are "READERS" and which are "WRITERS". See later for details.
2009-12-06 07:11:02 +01:00
### 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.
Those "refexes" are *not* anchored; a pattern like `refs/heads/master`
actually matches `foo/refs/heads/master01/bar` as well, even if no one will
actually push such a branch! You can anchor it if you really care, by using
`master$` instead of `master`, but anchoring is *not* the default for
refexes.]
### Handing out rights to wildcard-matched repos
2009-12-06 07:11:02 +01:00
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 creater 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
wildrepos: expanded access reporting This feature has *no* warranty, and so no documentation. Not more than this transcript anyway. config file: @prof = u1 @TAs = u2 u3 @students = u4 u5 u6 repo assignments/CREATER/a[0-9][0-9] C = @students RW+ = CREATER RW = WRITERS @TAs R = READERS @prof session: as user "u4": # check your permissions $ ssh git@server PTY allocation request failed on channel 0 hello u4, the gitolite version here is v0.95-31-gbcb14ca you have the following permissions: C assignments/CREATER/a[0-9][0-9] @ @ testing Connection to localhost closed. # autovivify repos for assignment 12 and 24 $ git clone git@server:assignments/u4/a12 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. $ git clone git@server:assignments/u4/a24 a24 Initialized empty Git repository in /home/sitaram/t/a24/.git/ Initialized empty Git repository in /home/gitolite/repositories/assignments/u4/a24.git/ warning: You appear to have cloned an empty repository. # check what repos you autovivified $ ssh git@server expand assignments/u4/a[0-9][0-9] (u4) assignments/u4/a12 (u4) assignments/u4/a24 as user "u5": # check your basic permissions $ ssh git@server PTY allocation request failed on channel 0 hello u5, the gitolite version here is v0.95-31-gbcb14ca you have the following permissions: C assignments/CREATER/a[0-9][0-9] @ @ testing Connection to localhost closed. # see if you have access to any of u4's repos $ ssh git@server expand assignments/u4/a[0-9][0-9] # (no output produced) as user "u4": # allow "u5" read access to assignment 12 # note you type in "R u5", hit enter, then hit Ctrl-D. Gitolite # then produces a confirmation message starting "New perms are:" $ ssh git@server setperms assignments/u4/a12 R u5 New perms are: R u5 as user "u5": # again see if you have access to any u4 repos $ ssh git@server expand assignments/u4/a[0-9][0-9] (u4) assignments/u4/a12 as user "u4": # check what permissions you gave to assignment 12 $ ssh git@server getperms assignments/u4/a12 R u5 # add RW access to "u6" to assignment 12 # again, type 'em in, then hit Ctrl-D; and note each time you run # this you're starting from scratch -- you can't "add to" the # permissions. Deal with it... $ ssh git@server setperms assignments/u4/a12 R u5 RW u6 New perms are: R u5 RW u6 as user "u6": # check what u4 stuff you have access to $ ssh git@server expand assignments/u4/a[0-9][0-9] (u4) assignments/u4/a12
2009-12-06 10:56:53 +01:00
R u5
RW u6
2009-12-06 07:11:02 +01:00
(hit ctrl-d here)
2010-01-08 01:50:19 +01:00
...and use the new "setperms" command to set permissions for your repo:
2009-12-06 07:11:02 +01:00
wildrepos: expanded access reporting This feature has *no* warranty, and so no documentation. Not more than this transcript anyway. config file: @prof = u1 @TAs = u2 u3 @students = u4 u5 u6 repo assignments/CREATER/a[0-9][0-9] C = @students RW+ = CREATER RW = WRITERS @TAs R = READERS @prof session: as user "u4": # check your permissions $ ssh git@server PTY allocation request failed on channel 0 hello u4, the gitolite version here is v0.95-31-gbcb14ca you have the following permissions: C assignments/CREATER/a[0-9][0-9] @ @ testing Connection to localhost closed. # autovivify repos for assignment 12 and 24 $ git clone git@server:assignments/u4/a12 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. $ git clone git@server:assignments/u4/a24 a24 Initialized empty Git repository in /home/sitaram/t/a24/.git/ Initialized empty Git repository in /home/gitolite/repositories/assignments/u4/a24.git/ warning: You appear to have cloned an empty repository. # check what repos you autovivified $ ssh git@server expand assignments/u4/a[0-9][0-9] (u4) assignments/u4/a12 (u4) assignments/u4/a24 as user "u5": # check your basic permissions $ ssh git@server PTY allocation request failed on channel 0 hello u5, the gitolite version here is v0.95-31-gbcb14ca you have the following permissions: C assignments/CREATER/a[0-9][0-9] @ @ testing Connection to localhost closed. # see if you have access to any of u4's repos $ ssh git@server expand assignments/u4/a[0-9][0-9] # (no output produced) as user "u4": # allow "u5" read access to assignment 12 # note you type in "R u5", hit enter, then hit Ctrl-D. Gitolite # then produces a confirmation message starting "New perms are:" $ ssh git@server setperms assignments/u4/a12 R u5 New perms are: R u5 as user "u5": # again see if you have access to any u4 repos $ ssh git@server expand assignments/u4/a[0-9][0-9] (u4) assignments/u4/a12 as user "u4": # check what permissions you gave to assignment 12 $ ssh git@server getperms assignments/u4/a12 R u5 # add RW access to "u6" to assignment 12 # again, type 'em in, then hit Ctrl-D; and note each time you run # this you're starting from scratch -- you can't "add to" the # permissions. Deal with it... $ ssh git@server setperms assignments/u4/a12 R u5 RW u6 New perms are: R u5 RW u6 as user "u6": # check what u4 stuff you have access to $ ssh git@server expand assignments/u4/a[0-9][0-9] (u4) assignments/u4/a12
2009-12-06 10:56:53 +01:00
$ ssh git@server setperms assignments/u4/a12 < myperms
2009-12-06 07:11:02 +01:00
New perms are:
wildrepos: expanded access reporting This feature has *no* warranty, and so no documentation. Not more than this transcript anyway. config file: @prof = u1 @TAs = u2 u3 @students = u4 u5 u6 repo assignments/CREATER/a[0-9][0-9] C = @students RW+ = CREATER RW = WRITERS @TAs R = READERS @prof session: as user "u4": # check your permissions $ ssh git@server PTY allocation request failed on channel 0 hello u4, the gitolite version here is v0.95-31-gbcb14ca you have the following permissions: C assignments/CREATER/a[0-9][0-9] @ @ testing Connection to localhost closed. # autovivify repos for assignment 12 and 24 $ git clone git@server:assignments/u4/a12 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. $ git clone git@server:assignments/u4/a24 a24 Initialized empty Git repository in /home/sitaram/t/a24/.git/ Initialized empty Git repository in /home/gitolite/repositories/assignments/u4/a24.git/ warning: You appear to have cloned an empty repository. # check what repos you autovivified $ ssh git@server expand assignments/u4/a[0-9][0-9] (u4) assignments/u4/a12 (u4) assignments/u4/a24 as user "u5": # check your basic permissions $ ssh git@server PTY allocation request failed on channel 0 hello u5, the gitolite version here is v0.95-31-gbcb14ca you have the following permissions: C assignments/CREATER/a[0-9][0-9] @ @ testing Connection to localhost closed. # see if you have access to any of u4's repos $ ssh git@server expand assignments/u4/a[0-9][0-9] # (no output produced) as user "u4": # allow "u5" read access to assignment 12 # note you type in "R u5", hit enter, then hit Ctrl-D. Gitolite # then produces a confirmation message starting "New perms are:" $ ssh git@server setperms assignments/u4/a12 R u5 New perms are: R u5 as user "u5": # again see if you have access to any u4 repos $ ssh git@server expand assignments/u4/a[0-9][0-9] (u4) assignments/u4/a12 as user "u4": # check what permissions you gave to assignment 12 $ ssh git@server getperms assignments/u4/a12 R u5 # add RW access to "u6" to assignment 12 # again, type 'em in, then hit Ctrl-D; and note each time you run # this you're starting from scratch -- you can't "add to" the # permissions. Deal with it... $ ssh git@server setperms assignments/u4/a12 R u5 RW u6 New perms are: R u5 RW u6 as user "u6": # check what u4 stuff you have access to $ ssh git@server expand assignments/u4/a[0-9][0-9] (u4) assignments/u4/a12
2009-12-06 10:56:53 +01:00
R u5
RW u6
2009-12-06 07:11:02 +01:00
'setperms' will helpfully print what the new permissions are but you can also
use 'getperms' to check:
wildrepos: expanded access reporting This feature has *no* warranty, and so no documentation. Not more than this transcript anyway. config file: @prof = u1 @TAs = u2 u3 @students = u4 u5 u6 repo assignments/CREATER/a[0-9][0-9] C = @students RW+ = CREATER RW = WRITERS @TAs R = READERS @prof session: as user "u4": # check your permissions $ ssh git@server PTY allocation request failed on channel 0 hello u4, the gitolite version here is v0.95-31-gbcb14ca you have the following permissions: C assignments/CREATER/a[0-9][0-9] @ @ testing Connection to localhost closed. # autovivify repos for assignment 12 and 24 $ git clone git@server:assignments/u4/a12 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. $ git clone git@server:assignments/u4/a24 a24 Initialized empty Git repository in /home/sitaram/t/a24/.git/ Initialized empty Git repository in /home/gitolite/repositories/assignments/u4/a24.git/ warning: You appear to have cloned an empty repository. # check what repos you autovivified $ ssh git@server expand assignments/u4/a[0-9][0-9] (u4) assignments/u4/a12 (u4) assignments/u4/a24 as user "u5": # check your basic permissions $ ssh git@server PTY allocation request failed on channel 0 hello u5, the gitolite version here is v0.95-31-gbcb14ca you have the following permissions: C assignments/CREATER/a[0-9][0-9] @ @ testing Connection to localhost closed. # see if you have access to any of u4's repos $ ssh git@server expand assignments/u4/a[0-9][0-9] # (no output produced) as user "u4": # allow "u5" read access to assignment 12 # note you type in "R u5", hit enter, then hit Ctrl-D. Gitolite # then produces a confirmation message starting "New perms are:" $ ssh git@server setperms assignments/u4/a12 R u5 New perms are: R u5 as user "u5": # again see if you have access to any u4 repos $ ssh git@server expand assignments/u4/a[0-9][0-9] (u4) assignments/u4/a12 as user "u4": # check what permissions you gave to assignment 12 $ ssh git@server getperms assignments/u4/a12 R u5 # add RW access to "u6" to assignment 12 # again, type 'em in, then hit Ctrl-D; and note each time you run # this you're starting from scratch -- you can't "add to" the # permissions. Deal with it... $ ssh git@server setperms assignments/u4/a12 R u5 RW u6 New perms are: R u5 RW u6 as user "u6": # check what u4 stuff you have access to $ ssh git@server expand assignments/u4/a[0-9][0-9] (u4) assignments/u4/a12
2009-12-06 10:56:53 +01:00
$ ssh git@server getperms assignments/u4/a12
R u5
RW u6
2009-12-06 07:11:02 +01:00
The following points are important:
2010-02-26 21:11:38 +01:00
* note the syntax of the commands; it's not a "git" command, and there's no
2009-12-06 07:11:02 +01:00
`:` 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
2009-12-06 07:11:02 +01:00
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.
### other issues and discussion
2009-12-06 07:11:02 +01:00
* *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.
----
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