deac/gitolite
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity
gitolite/doc/gitolite.rc.mkd
Sitaram Chamarty e5c3b0e5dc (projects.list changes) allow escaping the names... 
requires setting GITWEB_URI_ESCAPE in the rc file
2011-10-06 19:55:46 +05:30

393 lines
17 KiB
Markdown
Raw Blame History

# 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.
* `$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" category: `$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.
* mirroring setup
These two variables enable mirroring support; see
[doc/mirroring.mkd][mirr] for details. The two variables are
`$GL_SLAVE_MODE`, (boolean, default undef), and `$ENV{GL_SLAVES}`,
(environment variable, string, default undef)
Note on the second variable above: you must use single quotes to give it
its value, not double quotes, (like `$ENV{GL_SLAVES} = 'gitolite@server2
gitolite@server3';`). Also note that this is an environment variable, not
a regular perl variable, so mind the syntax if you're not a perl guy :-)
* `$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 categories as she wishes (example:
MANAGERS, TESTERS, etc).
This variable is a space-separated list of the allowed categories.
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 categories 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
Reference in a new issue View git blame Copy permalink