gitolite/doc/gitolite.rc.mkd

# 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