gitolite/doc/wildcard-repositories.mkd

348 lines
13 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
custom perm categories in setperms (WARNING: PLEASE READ FULL COMMIT MESSAGE) 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.
2010-11-06 06:16:17 +01:00
created it, allowing him/her to hand out 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
----
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>
custom perm categories in setperms (WARNING: PLEASE READ FULL COMMIT MESSAGE) 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.
2010-11-06 06:16:17 +01:00
* <a href="#_side_note_valid_regexes">side-note: valid regexes</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>
custom perm categories in setperms (WARNING: PLEASE READ FULL COMMIT MESSAGE) 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.
2010-11-06 06:16:17 +01:00
* <a href="#_admin_adding_other_categories_than_READERS_and_WRITERS">(admin) adding other categories than READERS and WRITERS</a>
* <a href="#_IMPORTANT_WARNING_ABOUT_THIS_FEATURE_">**IMPORTANT WARNING ABOUT THIS FEATURE**</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>
----
2009-12-06 07:11:02 +01:00
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>
2010-04-29 10:58:03 +02:00
### 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.
2009-12-06 07:11:02 +01:00
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.
2009-12-06 07:11:02 +01:00
<a name="_wildcard_repos_with_creator_name_in_them"></a>
#### wildcard repos with creator name in them
2009-12-06 07:11:02 +01:00
Here's an example snippet:
@prof = u1
@TAs = u2 u3
@students = u4 u5 u6
repo assignments/CREATOR/a[0-9][0-9]
2009-12-06 07:11:02 +01:00
C = @students
RW+ = CREATOR
2009-12-06 07:11:02 +01:00
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 ;-)
2009-12-06 07:11:02 +01:00
<a name="_wildcard_repos_without_creator_name_in_them"></a>
#### wildcard repos without creator name in them
2009-12-06 07:11:02 +01:00
Here's how the same example would look if you did not want the CREATOR's name
2009-12-06 07:11:02 +01:00
to be part of the actual repo name.
repo assignments/a[0-9][0-9]
C = @students
RW+ = CREATOR
2009-12-06 07:11:02 +01:00
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
custom perm categories in setperms (WARNING: PLEASE READ FULL COMMIT MESSAGE) 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.
2010-11-06 06:16:17 +01:00
<a name="_side_note_valid_regexes"></a>
2010-11-05 11:34:58 +01:00
### side-note: valid regexes
Due to projects like `gtk+`, the `+` character is now considered a valid
character for an *ordinary* repo. Therefore, a pattern like `foo/.+` does not
look like a regex to gitolite. Use `foo/..*` if you want that.
Also, `..*` by itself is not considered a valid repo pattern. Try
`[a-zA-Z0-9].*`.
custom perm categories in setperms (WARNING: PLEASE READ FULL COMMIT MESSAGE) 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.
2010-11-06 06:16:17 +01:00
<a name="_side_note_line_anchored_regexes"></a>
### side-note: line-anchored regexes
2009-12-06 07:11:02 +01:00
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
2009-12-06 07:11:02 +01:00
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.
2009-12-06 07:11:02 +01:00
<a name="_handing_out_rights_to_wildcard_matched_repos"></a>
### 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 creator to take ad hoc sets of
2009-12-06 07:11:02 +01:00
users from among the actual users in the system, and place them into one of
custom perm categories in setperms (WARNING: PLEASE READ FULL COMMIT MESSAGE) 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.
2010-11-06 06:16:17 +01:00
two categories (in this example, READERS and WRITERS 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.
2009-12-06 07:11:02 +01:00
Create a small text file that contains the permissions you desire:
$ cat > myperms
custom perm categories in setperms (WARNING: PLEASE READ FULL COMMIT MESSAGE) 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.
2010-11-06 06:16:17 +01:00
READERS u5
WRITERS 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:
custom perm categories in setperms (WARNING: PLEASE READ FULL COMMIT MESSAGE) 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.
2010-11-06 06:16:17 +01:00
READERS u5
WRITERS 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
custom perm categories in setperms (WARNING: PLEASE READ FULL COMMIT MESSAGE) 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.
2010-11-06 06:16:17 +01:00
READERS u5
WRITERS 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
custom perm categories in setperms (WARNING: PLEASE READ FULL COMMIT MESSAGE) 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.
2010-11-06 06:16:17 +01:00
`:` like in a repo URL. The first space-separated word is READERS or
WRITERS, and the rest are simple usernames.
<a name="_admin_adding_other_categories_than_READERS_and_WRITERS"></a>
### (admin) adding other categories than READERS and WRITERS
Let's say your needs are more complex and you need more categories of users.
For example, you might like to have a setup where only a tester can update
tags, and only a manager can delete branches:
repo foo/..*
C = u1
RW refs/tags/ = TESTERS
- refs/tags/ = @all
RW+ = WRITERS
RW = INTERNS
R = READERS
RW+D = MANAGERS
2009-12-06 07:11:02 +01:00
custom perm categories in setperms (WARNING: PLEASE READ FULL COMMIT MESSAGE) 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.
2010-11-06 06:16:17 +01:00
As you can see, someone pre-creates the repo and assigns rights to various
people, say by sending something like this to `setperms`:
READERS wally
WRITERS dilbert alice
MANAGERS phb
INTERNS ashok
TESTERS ashok
You can enable do this by setting the `GL_WILDREPOS_PERM_CATS` variable in the
rc file. The example rc file (`conf/example.gitolite.rc`) explains how to do
this, with sample code.
<a name="_IMPORTANT_WARNING_ABOUT_THIS_FEATURE_"></a>
#### **IMPORTANT WARNING ABOUT THIS FEATURE**
Please make sure that none of the category names conflict with any of the
**usernames** in the system. For example, if you have a user called "foo",
make sure you do not include "foo" as a valid category in
`$GL_WILDREPOS_PERM_CATS`.
You can keep things sane by using UPPERCASE names for categories, while
keeping all your usernames lowercase; then you don't have to worry about this
problem.
2009-12-06 07:11:02 +01:00
<a name="_setting_a_gitweb_description_for_a_wildcard_matched_repo"></a>
### setting a gitweb description for a wildcard-matched repo
2010-09-03 05:22:14 +02:00
Similar to the getperms/setperms commands, there are the getdesc/setdesc
commands, thanks to Teemu.
<a name="_reporting"></a>
### reporting
2009-12-06 07:11:02 +01:00
In order to see what repositories were created from a wildcard, use the
"expand" command, described briefly in [doc/report-output.mkd][repout].
2009-12-06 07:11:02 +01:00
2010-12-24 06:31:28 +01:00
### deleting a wild repo
See [repo deletion][rmr] for more on this. Note that this requires you to
install/setup "adc"s (admin defined commands). See
[doc/admin-defined-commands.mkd][adc] for how to do that.
[adc]: http://github.com/sitaramc/gitolite/blob/pu/doc/admin-defined-commands.mkd
[rmr]: http://github.com/sitaramc/gitolite/blob/pu/contrib/adc/repo-deletion.README
<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.
custom perm categories in setperms (WARNING: PLEASE READ FULL COMMIT MESSAGE) 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.
2010-11-06 06:16:17 +01:00
If the invoking user has been put in the "WRITERS" category using `setperms`, all
permissions for the the user WRITERS are given to the invoking username (and
similarly for 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
custom perm categories in setperms (WARNING: PLEASE READ FULL COMMIT MESSAGE) 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.
2010-11-06 06:16:17 +01:00
`assignments/u4/a23`, this is what the effective ruleset looks like:
repo assignments/u4/a23
C = @students
RW+ = u4
RW = @TAs
R = @prof
custom perm categories in setperms (WARNING: PLEASE READ FULL COMMIT MESSAGE) 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.
2010-11-06 06:16:17 +01:00
If u4 puts u5 in the "WRITERS" category 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.
2009-12-06 07:11:02 +01:00
----
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