people will NOT read documentation, especially the bloody install documentation. I'm about ready to throw in the towel and declare gitolite unsupported, take-it-or-leave-it. But I'm making one last attempt to refocus the install doc to better suit the "I know I'm very smart and I dont have to read docs so it's clearly your fault that I am not able to install gitolite" crowd. As a bonus, though, I ended up making proper, hyper-linked, TOCs for most of the docs, and moved a whole bunch of stuff around. Also finally got some of the ssh stuff over from my git-notes repo because it really belongs here.
225 lines
5.8 KiB
Markdown
225 lines
5.8 KiB
Markdown
# what is a "big-config"
|
|
|
|
In this document:
|
|
|
|
* <a href="#A1">when/why do we need it?</a>
|
|
* <a href="#A2">how do we use it?</a>
|
|
* <a href="#A3">summary of settings in RC file</a>
|
|
* <a href="#A4">what are the downsides?</a>
|
|
* <a href="#A5">(extra coolness) usergroups and LDAP/similar tools</a>
|
|
|
|
<a name="A1"></a>
|
|
|
|
### when/why do we need it?
|
|
|
|
A "big config" is anything that has a few thousand users and a few thousand
|
|
repos, organised into groups that are much smaller in number (like maybe a few
|
|
hundreds of repogroups and a few dozens of usergroups).
|
|
|
|
So let's say you have
|
|
|
|
@wbr = lynx firefox
|
|
@devs = alice bob
|
|
|
|
repo @wbr
|
|
RW+ next = @devs
|
|
RW master = @devs
|
|
|
|
Gitolite internally translates this to
|
|
|
|
repo lynx firefox
|
|
RW+ next = alice bob
|
|
RW master = alice bob
|
|
|
|
Not just that -- it now generates the actual config rules once for each
|
|
user-repo-ref combination (there are 8 combinations above; the compiled config
|
|
file looks partly like this:
|
|
|
|
%repos = (
|
|
'firefox' => {
|
|
'R' => {
|
|
'alice' => 1,
|
|
'bob' => 1
|
|
},
|
|
'W' => {
|
|
'alice' => 1,
|
|
'bob' => 1
|
|
},
|
|
'alice' => [
|
|
{
|
|
'refs/heads/next' => 'RW+'
|
|
},
|
|
{
|
|
'refs/heads/master' => 'RW'
|
|
}
|
|
],
|
|
'bob' => [
|
|
{
|
|
'refs/heads/next' => 'RW+'
|
|
},
|
|
{
|
|
'refs/heads/master' => 'RW'
|
|
}
|
|
]
|
|
},
|
|
'lynx' => {
|
|
'R' => {
|
|
'alice' => 1,
|
|
'bob' => 1
|
|
},
|
|
'W' => {
|
|
'alice' => 1,
|
|
'bob' => 1
|
|
},
|
|
'alice' => [
|
|
{
|
|
'refs/heads/next' => 'RW+'
|
|
},
|
|
{
|
|
'refs/heads/master' => 'RW'
|
|
}
|
|
],
|
|
'bob' => [
|
|
{
|
|
'refs/heads/next' => 'RW+'
|
|
},
|
|
{
|
|
'refs/heads/master' => 'RW'
|
|
}
|
|
]
|
|
}
|
|
);
|
|
|
|
Phew!
|
|
|
|
You can imagine what that does when you have 10,000 users and 10,000 repos.
|
|
Let's just say it's not pretty :)
|
|
|
|
<a name="A2"></a>
|
|
|
|
### how do we use it?
|
|
|
|
Now, if you had all those 10,000 users and repos explicitly listed (no
|
|
groups), then there is no help. But if, like the above example, you had
|
|
groups like we used above, there is hope.
|
|
|
|
Just set
|
|
|
|
$GL_BIG_CONFIG = 1;
|
|
|
|
in the `~/.gitolite.rc` file on the server. When you do that, and push this
|
|
configuration, the compiled file looks like this:
|
|
|
|
%repos = (
|
|
'@wbr' => {
|
|
'@devs' => [
|
|
{
|
|
'refs/heads/next' => 'RW+'
|
|
},
|
|
{
|
|
'refs/heads/master' => 'RW'
|
|
}
|
|
],
|
|
'R' => {
|
|
'@devs' => 1
|
|
},
|
|
'W' => {
|
|
'@devs' => 1
|
|
}
|
|
},
|
|
);
|
|
%groups = (
|
|
'@devs' => {
|
|
'alice' => 'master',
|
|
'bob' => 'master'
|
|
},
|
|
'@wbr' => {
|
|
'firefox' => 'master',
|
|
'lynx' => 'master'
|
|
}
|
|
);
|
|
|
|
That's a lot smaller, and allows orders of magintude more repos and groups to
|
|
be supported.
|
|
|
|
<a name="A3"></a>
|
|
|
|
### summary of settings in RC file
|
|
|
|
The default RC file contains the following lines:
|
|
|
|
$GL_BIG_CONFIG = 0;
|
|
$GL_NO_DAEMON_NO_GITWEB = 0;
|
|
|
|
The first setting means that by default, big-config is off; you can change it
|
|
to 1 to enable it.
|
|
|
|
The second is a very useful optimisation that you *must* enable if you *do*
|
|
have a large number of repositories, and do *not* use gitolite's support for
|
|
gitweb or git-daemon access (see "[easier to specify gitweb description and
|
|
gitweb/daemon access][gw]" for details). This will save a lot of time when
|
|
you push the gitolite-admin repo with changes.
|
|
|
|
[gw]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#gitweb
|
|
|
|
<a name="A4"></a>
|
|
|
|
### what are the downsides?
|
|
|
|
There is one minor issue.
|
|
|
|
If you use the delegation feature, you can no longer define or extend
|
|
@groups in a fragment, for security reasons. It will also not let you use any
|
|
group other than the @fragname itself (specifically, groups which contained a
|
|
subset of the allowed @fragname, which would work normally, do not work now).
|
|
|
|
(If you didn't understand all that, you're probably not using delegation, so
|
|
feel free to ignore it!)
|
|
|
|
<a name="A5"></a>
|
|
|
|
### (extra coolness) usergroups and LDAP/similar tools
|
|
|
|
[Please NOTE: this is all about *user* groups, not *repo* groups]
|
|
|
|
Gitolite now allows usergroup information to be passed in from outside. The
|
|
`gl-auth-commmand` can now take an optional list of usergroup names after the
|
|
first argument (which is the username).
|
|
|
|
To understand why this is useful, consider the following:
|
|
|
|
Some people have an LDAP-backed ssh daemon (or some other similar mechanism
|
|
that can speak "ssh" to the client), with pubkeys stored in LDAP, etc., and
|
|
some way (not using `~/.ssh/authorized_keys`) of invoking gitolite.
|
|
|
|
Such setups also have "usergroups", and a way to tell, for each user, what
|
|
groups he/she is a member of. So let's say "alice" works on projects "foo"
|
|
and "bar", while "bob" is works on project "bar" and is a member of the
|
|
`L3_support` team.
|
|
|
|
You can use those group names in the gitolite config file for access control
|
|
as "@foo", "@bar", `@L3_support`, etc.; please note the "@" prefix because
|
|
gitolite requires it.
|
|
|
|
However, that still leaves a wee little inconvenience. You still have to add
|
|
lines like this to the gitolite config file:
|
|
|
|
@foo = alice
|
|
@bar = alice bob
|
|
@L3_support = bob
|
|
|
|
You don't need to do that anymore now. Tell your authentication system that,
|
|
after authenticating alice, instead of running:
|
|
|
|
/some/path/to/gl-auth-command alice
|
|
|
|
it should first find the groups that alice is a member of, and then run:
|
|
|
|
/some/path/to/gl-auth-command alice foo bar
|
|
|
|
That's it. Internally, gitolite will behave as if the config file had also
|
|
specified:
|
|
|
|
@foo = alice
|
|
@bar = alice
|