gitolite/doc/gitolite.rc.mkd

F=rc 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.

[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].

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.

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 [this][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.

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 [this][bc] if you need details.

  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 [this][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][limitoutput] for details.

#rcsecurity 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 the [gitolite.conf][conf] documentation 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, this 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):

  $GL_GITCONFIG_KEYS = 'core\.logAllRefUpdates core\..*compression';
  

  Each pattern should match the whole key (in other words, there is an implicit ^ at the start of each pattern, and a $ at the end).

  Note: if you don't know regex syntax, please learn, but briefly, a literal period must be escaped with a backslash, as you can see in the example above. In addition, if you use double quotes instead of single quotes, you will need to escape the backslash itself, like "foo\\..*".

  It's probably simplest to stick to single quotes.

  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 = '.*';

• $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 the docs for [linking gitweb authorisation with gitolite][gitwebauth] 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 the [admin defined commands][ADCs] document 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 the [big config][bc] doc 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 the [mob branches][mob]), this variable -- combined with appropriate setup described in [doc/http-backend.mkd][http] -- 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!

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 read the [warning][rolenamewarn] in the [wild][] document before using this feature. 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";
  

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").

  Note that %d is also available if you want.

• $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.

  See the previous variable (GL_LOGT) for template related info.

• $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][disable] to gitolite, move ~/repositories/*, change this variable, then re-enable writes.

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.