gitolite/doc/deleg.mkd
Sitaram Chamarty de40461d9a document overhaul
- explicit 'list' gives way to mindmap, ...
  - 'fm2mt.pl' to produce master-toc.mkd from the mindmap
  - mkdoc no longer ignores master-toc.mkd, calls fm2mt.pl itself

and LOTS of changes to the actual docs
2012-04-05 21:42:22 +05:30

115 lines
4 KiB
Markdown

# delegating access control responsibilities
Delegation allows you to divide up a large conf file into smaller groups of
repos (called **subconf**s) and hand over responsibility to manage them to
**sub-admin**s. Gitolite can prevent one sub-admin from being able to set
access rules for any other sub-admin's repos.
Delegation is achieved by combining two gitolite features: [subconf][] and the
[NAME VREF][NAME].
To understand delegation, read both those links then come back to this
example.
## example
@webbrowsers = firefox lynx browsers/..*
@webservers = apache nginx servers/..*
@malwares = conficker storm ms/..*
# side note: if anyone objects, we claim ms stands for "metasploit" ;-)
# the admin repo access was probably like this to start with:
repo gitolite-admin
RW+ = sitaram
# now add these lines to the config for the admin repo
RW = alice bob mallory
RW VREF/NAME/conf/subs/webbrowsers = alice
RW VREF/NAME/conf/subs/webservers = bob
RW VREF/NAME/conf/subs/malwares = mallory
- VREF/NAME/ = alice bob mallory
Finally, you tell gitolite to pull in these files using the "subconf" command
subconf "subs/*.conf"
And that's it.
## #subconf the subconf command
Subconf is exactly like the include command in syntax:
subconf "foo/bar.conf"
but while reading the included file, it sets a "subconf name" of "foo".
When a subconf name is in effect, there are some restrictions on what repos
can be managed.
For example, in the include file in the above example, you can only have
"repo" lines for:
* a repo called "foo"
* a group called "@foo" defined outside the include file
* a member of a group called "@foo" (again, defined outside)
* a repo that matches a member of a group called "@foo" if that member is a
regular expression pattern
Here's an example. If the main conf file contains
@foo = aa bb cc/..*
then the subconf can only accept repo statements that refer to 'foo', '@foo',
'aa', 'bb', or any repo whose name starts with 'cc/'.
### how the "subconf name" is derived
For subconf lines that look just like include statements, i.e.,
subconf "foo/bar.conf"
subconf "frob/*.conf"
# assume frob has files aa.conf, bb.conf
the subconf name as each file is being processed is the base name of the file.
This means it would be "bar" for the first line, "aa" when processing
"frob/aa.conf", and "bb" when processing "frob/bb.conf".
A variation of subconf exists that can explicitly state the subconf name:
subconf foo "frob/*.conf"
In this variation, regardless of what file in "frob/" is being read, the
subconf name in effect is "foo".
## security notes
### group names
You can use "@group"s defined in the main config file but do not attempt to
redefine or extend them in your own subconf file. If you must extend a group
(say `@foo`) defined in the main config file, do this:
@myfoo = @foo
# now do whatever you want with @myfoo
Group names you define in your subconf will not clash even if the exact same
name is used in another subconf file, so you need not worry about that.
### delegating pubkeys
Short answer: not gonna happen.
The delegation feature is meant only for access control rules, not pubkeys.
Adding/removing pubkeys is a much more significant event than changing branch
level permissions for people already on staff, and only the main admin should
be allowed to do it.
Gitolite's "userids" all live in the same namespace. This is unlikely to
change, so please don't ask -- it gets real complicated to do otherwise.
Allowing sub-admins to add users means username collisions, which also means
security problems (admin-A creates a pubkey for Admin-B, thus gaining access
to all of Admin-B's stuff).
If you feel the need to delegate even that, please just go the whole hog and
give them separate gitolite instances (i.e., running under different gitolite
hosting users)!