877c6625dc
typos, minor clarifications, removing outdated stuff that got missed, adding some emphasis here and there, re-phrasing some places, etc.
384 lines
16 KiB
Markdown
384 lines
16 KiB
Markdown
# configuring gitolite's advanced features -- the `.gitolite.rc` file
|
|
|
|
This is the documentation for the contents of the "rc" file
|
|
(`$HOME/.gitolite.rc`) on the server. Until now this documentation was
|
|
inline, within the rc file itself, but it has grown too large, too unwieldy,
|
|
and too difficult to grok for people new to gitolite.
|
|
|
|
The documentation follows approximately the same order as the sample variables
|
|
in the (now reorganised) example "rc" file.
|
|
|
|
In this document:
|
|
|
|
* <a href="#_variables_that_should_not_be_touched_at_all">variables that should not be touched at all</a>
|
|
* <a href="#_most_often_used_changed_variables">most often used/changed variables</a>
|
|
* <a href="#_variables_with_an_efficiency_performance_impact">variables with an efficiency/performance impact</a>
|
|
* <a href="#_variables_with_a_security_impact">variables with a security impact</a>
|
|
* <a href="#_less_used_changed_variables">less used/changed variables</a>
|
|
* <a href="#_rarely_changed_variables">rarely changed variables</a>
|
|
* <a href="#_constants_that_aren_t_">constants that aren't!</a>
|
|
|
|
[Note: in perl, there is no actual boolean. The undefined value, the number
|
|
'0', and the empty string, are all 'false'. Everything else is 'true'. It is
|
|
thus common to use just 0/1 for false/true].
|
|
|
|
<a name="_variables_that_should_not_be_touched_at_all"></a>
|
|
|
|
### variables that should not be touched at all
|
|
|
|
The first section does not need too much elaboration. Let's just say bad
|
|
things happen if you change them.
|
|
|
|
<a name="_most_often_used_changed_variables"></a>
|
|
|
|
### most often used/changed variables
|
|
|
|
* `$GL_WILDREPOS`, boolean, default 0
|
|
|
|
Setting this variable lets your users create repositories based on wild
|
|
cards, hand out R and RW permissions to other users to collaborate, etc.
|
|
|
|
See [doc/wildcard-repositories.mkd][wild] for lots of info on this.
|
|
|
|
* `$PROJECTS_LIST`, filename, default `~/projects.list`
|
|
|
|
This is for gitweb users only. Gitweb setup has a variable called
|
|
`$projects_list` (please see gitweb docs for more on this). Set this to
|
|
the same value as that one.
|
|
|
|
* `$GITWEB_URI_ESCAPE`, boolean, default undef
|
|
|
|
Apparently gitweb expects project names to be URI-escaped (but seems to
|
|
work fine even if you don't). If you need strict compatibility with
|
|
gitweb, add/uncomment this variable and set it to 1.
|
|
|
|
* `$REPO_UMASK`, octal, default `0077`
|
|
|
|
The default UMASK that gitolite uses makes all the repos and their
|
|
contents have `rwx------` permissions. People who want to run gitweb
|
|
realise that this will not do.
|
|
|
|
The correct way to deal with this is to give this variable a value like
|
|
`0027` (note the syntax: the leading 0 is required), and then make the
|
|
user running the webserver (apache, www-data, whatever) a member of the
|
|
'git' group.
|
|
|
|
If you've already installed gitolite then existing files will have to be
|
|
fixed up manually (for a umask or 0027, that would be `chmod -R g+rX`).
|
|
This is because umask only affects permissions on newly created files, not
|
|
existing ones.
|
|
|
|
<a name="_variables_with_an_efficiency_performance_impact"></a>
|
|
|
|
### variables with an efficiency/performance impact
|
|
|
|
* `$GL_BIG_CONFIG`, boolean, default 0
|
|
|
|
This is the most common setting for efficiency in handling large repo/user
|
|
groups. This is a very powerful setting; please read
|
|
[doc/big-config.mkd][bc] for all the details you might need.
|
|
|
|
There are 3 other settings related to big configs. They are changed only
|
|
in rare cases, however, so are described later.
|
|
|
|
* `$GL_NO_DAEMON_NO_GITWEB`, boolean, default 0
|
|
|
|
If you have *lots* of repos, and you're *not* using gitweb or daemon, you
|
|
should probably set this on for efficiency. Despite the name, it also
|
|
blocks repo config settings. Please read [doc/big-config.mkd][bc] for
|
|
more details.
|
|
|
|
**WARNING**: if your description files are maintained by some other means
|
|
than via the gitolite config file, make sure you set this variable to 1.
|
|
|
|
* `$GL_NICE_VALUE`, boolean, default undef
|
|
|
|
The nice value to run under. Applicable only if it is greater than 0.
|
|
Please do NOT set it if your bits/resource.h does not define PRIO_PROCESS
|
|
is 0. For Linux this is true...
|
|
|
|
* `$BIG_INFO_CAP`, number, default 20
|
|
|
|
See [using patterns to limit output][limit] for details.
|
|
|
|
<a name="_variables_with_a_security_impact"></a>
|
|
|
|
### variables with a security impact
|
|
|
|
**IMPORTANT NOTE**
|
|
|
|
This section describes variables that, if not carefully used, can cause
|
|
security issues. It also includes variables which I personally do not use and
|
|
do not have the ability to test thoroughly
|
|
|
|
Using non-default value for these variables voids the security reward in the
|
|
README. This does *not* mean they are less important or that I will ignore
|
|
problems; it just means *my* ability to catch problems may be limited by my
|
|
test suite, my actual production use, my time, and sometimes (LDAP comes to
|
|
mind) even my skill or resources available to me, and that therefore I depend
|
|
on feedback from my users to find or fix issues.
|
|
|
|
* `$GL_ALL_READ_ALL`, boolean, default undef
|
|
|
|
Eliminates the access control check for read access. Makes things much
|
|
(**much**!) faster when you have 10,000 projects and the compiled conf
|
|
file is more than 20MB in size! **Double check with your boss or have a
|
|
new job lined up before setting this on!**
|
|
|
|
* `$GIT_PATH`, string, default empty
|
|
|
|
If git on your server is on a standard path (that is `ssh git@server git
|
|
--version` works), leave this setting as is. Otherwise, find out where it
|
|
is and use that value here, for example `GIT_PATH="/opt/bin/";`
|
|
|
|
* `$GL_GITCONFIG_KEYS`, string, default empty
|
|
|
|
This setting allows the repo admin to define acceptable gitconfig keys.
|
|
|
|
Gitolite allows you to set git repo options using the "config" keyword;
|
|
see the section on "repo specific git config commands" in
|
|
[doc/gitolite.conf.mkd][gitconf] for details and syntax.
|
|
|
|
However, if you are in an installation where the repo admin does not (and
|
|
should not) have shell access to the server, then allowing him to set
|
|
arbitrary repo config options *may* be a security risk -- some config
|
|
settings allow executing arbitrary commands!
|
|
|
|
You have 3 choices. By default `$GL_GITCONFIG_KEYS` is left empty, which
|
|
completely disables this feature (meaning you cannot set git configs via
|
|
the repo config).
|
|
|
|
The second choice is to give it a space separated list of settings you
|
|
consider safe. (These are actually treated as a set of perl regular
|
|
expression patterns, and any one of them must match). For example:
|
|
`$GL_GITCONFIG_KEYS = "core\\.logAllRefUpdates core\\..*compression";`
|
|
allows repo admins to set one of those 3 config keys (yes, that second
|
|
pattern matches two settings from "man git-config", if you look).
|
|
|
|
The third choice (which you may have guessed already if you're familiar
|
|
with regular expressions) is to allow anything and everything:
|
|
`$GL_GITCONFIG_KEYS = ".*";`
|
|
|
|
NOTE that due to some quoting and interpolation issues I have not been
|
|
able to look at, a literal "." needs to be specified in this string as
|
|
`\\.` (two backslashes and a dot). So this is how you'd allow any keys in
|
|
the "foo" section: `$GL_GITCONFIG_KEYS = "foo\\..*";`
|
|
|
|
* `$GL_NO_CREATE_REPOS`, boolean, default 0
|
|
|
|
DO NOT CHANGE THIS unless you have other means to create repos and
|
|
correctly populate them with the required hooks. No hooks, no access
|
|
control; you have been warned!
|
|
|
|
* `$GL_NO_SETUP_AUTHKEYS`, boolean, default 0
|
|
|
|
DO NOT CHANGE THIS unless you have other means to setup the authkeys file
|
|
(`~/.ssh/authorized_keys`). In an extreme case, if you switch this on
|
|
without also fixing up the authkeys file, users who you think you deleted
|
|
may still have access. All in all, please be careful, as with any change
|
|
that affects ssh.
|
|
|
|
* `$GL_WILDREPOS_DEFPERMS`, string, default undef
|
|
|
|
This sets default wildcard permissions for newly created wildcard repos.
|
|
|
|
If set, this value will be used as the default user-level permission rule
|
|
of new wildcard repositories. The user can change this value with the
|
|
setperms command as desired after repository creation; it is only a
|
|
default.
|
|
|
|
Example: `$GL_WILDREPOS_DEFPERMS = 'R @all';`
|
|
|
|
* `$HTPASSWD_FILE`, string, default empty
|
|
|
|
Gitolite can help users run the htpasswd command in a secure manner (since
|
|
gitolite has already identified them by an ssh key). If you want to
|
|
enable this, give the variable the absolute path to whatever file apache
|
|
(etc) expect to find the passwords in.
|
|
|
|
Look in [doc/3-faq-tips-etc.mkd][faq] ("easier to link gitweb
|
|
authorisation with gitolite" section) for more details on using this
|
|
feature.
|
|
|
|
* `$RSYNC_BASE`, string, default empty
|
|
|
|
Gitolite can be used to allow fine grained control of the rsync command.
|
|
|
|
This setting enables the rsync external command helper, by specifying the
|
|
base path of all the files that are accessible via rsync. It must be an
|
|
absolute path, like `$RSYNC_BASE = "/home/git/up-down";`. Leave it
|
|
undefined or set to the empty string to disable the rsync helper.
|
|
|
|
When enabled, it runs rsync with specific arguments, all presumably filled
|
|
in correctly by the client-side rsync. However, I am not an expert on how
|
|
rsync may be abused, so if it breaks, you get to keep both pieces!
|
|
|
|
* `$SVNSERVE`, string, default empty
|
|
|
|
Gitolite can also be used to gate access (though not at a fine grained
|
|
level) to SVN if needed, passing authentication information on to
|
|
`svnserve`. This setting allows launching svnserve when requested by the
|
|
ssh client. This allows using the same SSH setup for both SVN and git
|
|
access. Leave it undefined or set to the empty string to disable svnserve
|
|
access.
|
|
|
|
The setting will look something like (where the %u is substituted with the
|
|
username):
|
|
|
|
$SVNSERVE = "/usr/bin/svnserve -r /var/svn/ -t --tunnel-user=%u";
|
|
|
|
* hook chaining
|
|
|
|
* `$UPDATE_CHAINS_TO`, string, default "hooks/update.secondary"
|
|
* `$ADMIN_POST_UPDATE_CHAINS_TO`, string, default
|
|
"hooks/post-update.secondary"
|
|
|
|
By default, the update hook in every repo chains to "update.secondary".
|
|
Similarly, the post-update hook in the admin repo chains to
|
|
"post-update.secondary". If you're fine with the defaults, there's no
|
|
need to do anything here. However, if you want to use different names or
|
|
paths, change these variables.
|
|
|
|
* `$GL_ADC_PATH`, string, default undef
|
|
|
|
This setting enables admin defined commands.
|
|
|
|
**WARNING**: Use this feature only if (a) you really know what you're
|
|
doing and (b) you really, **really**, know what you're doing! Please read
|
|
[doc/admin-defined-commands.mkd][adc] for details. This is an extremely
|
|
powerful and flexible feature, and naturally anything that flexible can be
|
|
a security risk!
|
|
|
|
* `$GL_GET_MEMBERSHIPS_PGM`, string, default undef
|
|
|
|
Some sites would like to store group membership outside gitolite, because
|
|
they already have it in (usually) their LDAP server, and it doesn't make
|
|
sense to be forced to duplicate this information.
|
|
|
|
Set the following variable to the name of a script that, given a username
|
|
as argument, will return a list of groups that she is a member of. See
|
|
[doc/big-config.mkd][bc] for more details.
|
|
|
|
Example: `$GL_GET_MEMBERSHIPS_PGM = "/usr/local/bin/expand-ldap-user-to-groups"`
|
|
|
|
* `$GL_HTTP_ANON_USER`, string, default undef
|
|
|
|
Analogous to running mob branches over ssh (as described in
|
|
[doc/mob-branches.mkd][mob], this variable -- combined with appropriate
|
|
setup described in [doc/http-backend.mkd][smart] -- lets you pretend to
|
|
gitolite that unauthenticated HTTP users are actually authenticated as
|
|
this user.
|
|
|
|
* `$GL_REF_OR_FILENAME_PATT`, string
|
|
|
|
Set of allowed characters in refnames (and, if you have `NAME/` rules, in
|
|
filenames as well). The default pattern is almost the same as
|
|
`$REPONAME_PATT` with some additions.
|
|
|
|
Although the current code is not at risk in any way even if we let in
|
|
names containing strings like `$(command)`, and although I intend to make
|
|
sure things stay that way, it's probably a good idea to trap weird
|
|
filenames early. Just to be safe.
|
|
|
|
You ought to be able to loosen the pattern by adding other characters to
|
|
it, if you really need to. If you do, at least avoid backquotes and the
|
|
dollar sign!
|
|
|
|
<a name="_less_used_changed_variables"></a>
|
|
|
|
### less used/changed variables
|
|
|
|
* `$GL_ALL_INCLUDES_SPECIAL`, boolean, default undef
|
|
|
|
Giving access to @all users (as in `R = @all`) in the config normally
|
|
does *not* include the special users "gitweb" and "daemon". If you want
|
|
@all to include these two users, set this variable.
|
|
|
|
* `$GL_WILDREPOS_PERM_CATS`, string, default "READERS WRITERS"
|
|
|
|
Originally, we only allowed "R" and "RW" in the setperms command. Now we
|
|
allow the admin to define other roles as she wishes (example: MANAGERS,
|
|
TESTERS, etc).
|
|
|
|
This variable is a space-separated list of the allowed roles.
|
|
|
|
PLEASE, *PLEASE*, read the section in
|
|
[doc/wildcard-repositories.mkd][wild] for caveats and warnings. This is a
|
|
VERY powerful feature and if you're not careful you could mess up the ACLs
|
|
nicely.
|
|
|
|
This is the internal default if you don't set it (like if you didn't
|
|
update your ~/.gitolite.rc with new variables when you upgraded gitolite):
|
|
|
|
$GL_WILDREPOS_PERM_CATS = "READERS WRITERS";
|
|
|
|
You can use your own roles in addition to the standard ones; I suggest you
|
|
include READERS and WRITERS for backward compatbility though:
|
|
|
|
$GL_WILDREPOS_PERM_CATS = "READERS WRITERS MANAGERS TESTERS";
|
|
|
|
<a name="_rarely_changed_variables"></a>
|
|
|
|
### rarely changed variables
|
|
|
|
* `$GL_LOGT`, string, default `$GL_ADMINDIR/logs/gitolite-%y-%m.log`
|
|
|
|
This is the template for location of the log files and format of their
|
|
names.
|
|
|
|
The default produces files like `~/.gitolite/logs/gitolite-2009-09.log`.
|
|
If you make up your own templates, **PLEASE MAKE SURE** the directory
|
|
exists and is writable; gitolite won't do that for you unless it is the
|
|
default, ("$GL_ADMINDIR/logs")
|
|
|
|
* `$GL_PERFLOGT`, string, default undef
|
|
|
|
This gives the location of the performance log files. Uncomment and set
|
|
this variable if you want performance logging. Performance log files are
|
|
kept separate from access log files because they store different, usually
|
|
much shorter term, information.
|
|
|
|
* `$GL_SITE_INFO`, string, default undef
|
|
|
|
Some installations would like to give their users customised information
|
|
(like a link to their own websites, for example) so that users have a
|
|
quick way to find some links or information.
|
|
|
|
If this variable is defined, the "info" command will print it at the end
|
|
of the listing.
|
|
|
|
* `$REPO_BASE`, string, default "repositories"
|
|
|
|
This is where all the repos go. If it's not an absolute path, it is
|
|
considered to be relative to $HOME. Moving all the repositories after the
|
|
install has completed is doable: just [disable writes][dwr] to gitolite,
|
|
move `~/repositories/*`, change this variable, then re-enable writes.
|
|
|
|
<a name="_constants_that_aren_t_"></a>
|
|
|
|
### constants that aren't!
|
|
|
|
The source file `src/gitolite_rc.pm` defines a few "constants", for example:
|
|
|
|
$R_COMMANDS=qr/^(git[ -]upload-pack|git[ -]upload-archive)$/;
|
|
|
|
Let's say you want to disallow the archive feature, you would need to change
|
|
this constant.
|
|
|
|
As of this version, you can now change these "constants" also, simply by
|
|
defining a new value for any or all of them in your `~/.gitolite.rc` file.
|
|
|
|
If you use this to relax some of the patterns involved (for example, the value
|
|
of `ADC_CMD_ARGS_PATT`), please be sure you know what you're doing.
|
|
|
|
[wild]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html
|
|
[bc]: http://sitaramc.github.com/gitolite/doc/big-config.html
|
|
[faq]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html
|
|
[adc]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html
|
|
[mirr]: http://sitaramc.github.com/gitolite/doc/mirroring.html
|
|
[mob]: http://sitaramc.github.com/gitolite/doc/mob-branches.html
|
|
[smart]: http://sitaramc.github.com/gitolite/doc/http-backend.html
|
|
[dwr]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_disabling_write_access_to_take_backups
|
|
[limit]: http://sitaramc.github.com/gitolite/doc/report-output.html#_using_patterns_to_limit_output
|
|
[gitconf]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_repo_specific_git_config_commands
|