GITACLHOOK

NAME
SYNOPSIS
DESCRIPTION
ACL FILE
RULE MATCHING
LDAP
CONFIGURATION SETTINGS
TEST MODE
ENVIRONMENT
SEE ALSO
AUTHOR

---

NAME

gitaclhook - control access to git repositories

SYNOPSIS

gitaclhook refname old-sha1 new-sha1

gitacthook [--debug] --test REPO USER OP REF

gitaclhook --help

DESCRIPTION

This program is intended to be run as an "update" hook by git. It is called by git-receive-pack with arguments: refname old-sha1 new-sha1.

The program reads access control lists from the storage engine specified in the repository’s config file and allows or denies the update depending on their settings. If no storage engine is defined update is allowed unconditionally. If it is defined, but is not available (e.g. the disk file does not exist or the LDAP server cannot be reached, the update is denied.

Two storage engines are supported: File, which reads access control lists from a disk file, and LDAP , which obtains them from LDAP . The engine to use is defined by the hooks.acltype configuration keyword. The default is File.

ACL FILE

The ACL file is used when the File storage engine is requested. The path to the file must be given via the hooks.aclfile configuration keyword. If hooks.aclfile is not defined, update is allowed unconditionally.

The ACL file has the usual line-oriented syntax. Comments are introduced by the # sign and extend to the end of the physical line. Comments and empty lines are ignored.

Non-empty lines introduce ACL rules. The syntax is:

VERB PROJECT USER [ OP REF ]

where brackets denote optional parts. The parts of an ACL are:
VERB

Either allow or deny, to allow or deny the operation, correspondingly.

PROJECT

The name of the project. It is obtained by removing the directory and suffix parts of the repository pathname. Thus, if the repository is located in /var/gitroot/foobar.git, then the corresponding name of the project is foobar.

An asterisk matches any project name.

USER

Name of the user. The word all stands for any user, the word none matches no one at all. Otherwise, if this part begins with a percent sign (%), the rest of characters are treated as the name of the UNIX group to check and the rule matches any user in that group. Otherwise, the literal match is assumed.

The optional parts are:

OP

Requested operation codes. It is a string consisting of one or more of the following letters (case-insensitive):

Opcodes

	C		Create new ref.
	D		Delete existing ref.
	U		Fast-forward existing ref (no commit loss).
	R		Rewind or rebase existing ref (commit loss).
	REF

Affected ref, relative to the git refs/ directory. If it begins with a caret (^), it is treated as a Perl regular expression (with the ^ being its part). If it ends with a /, it is treated as a prefix match, so, e.g., heads/baz/ matches refs/heads/baz and anything below. Otherwise, it must match exactly the affected ref.

RULE MATCHING

The rule applies only if its PROJECT and USER parts match the project which is being updated and the user who requests the update, its OP contains the opcode of the requested operation and REF matches the affected ref. Missing REF and/or OP are treated as a match.

If no rule applies, the operation is allowed.

For example, assume you have the following ACL file:

allow myprog %devel U heads/master
allow myprog %pm CDUR heads/
allow myprog %pm C ^heads/tags/v\\d+$
allow myprog admin CDUR
deny myprog all

Then the users from the devel group will be able to push updates to refs/heads/master, the users from the pm group will be allowed to do anything with refs under refs/heads and to create tags with names beginning with v and containing only digits afterwards, and the user admin will be allowed to do anything he pleases. No other users will be allowed to update that repository.

LDAP

The LDAP storage engine is requested by the following configuration statement:

[hooks]
acltype = LDAP

The URI of the LDAP server to use and other data necessary to access it are read from the file name given in the hooks.aclldapconf variable, or from /etc/ldap.conf, if it is not defined. LDAP access control entries are similar to the plaintext file ACLs. Each entry has the following attrubutes:
gitAclProject [mandatory]

The project this entry applies to.

gitAclVerb [mandatory]

The control verb.

gitAclUser [optional]

The user name or group (% GROUPNAME ) specification.

gitAclOp [optional]

The list of operation codes.

gitAclRef [optional]

Git ref.

gitAclOrder [optional]

Sorting order (see below).

The program first reads all entries with the gitAclProject attribute matching the requested project name. The obtained entries are sorted by the value of gitAclOrder attribute. Entries without this attributes are assumed to have sorting order 0. Entries with the project name all are sorted last. Entries with the same sorting order are sorted by the count of attributes they carry (in the reverse order). Thus, the most specific entries precede the least specific entries in the resulting list.

Each list entry is then matched against the current tuple ( PROJECT , USER , OP , REF ), much the same way as described in RULE MATCHING . Missing attributes always match. The special gitAclProject value all matches all project names.

If no matching entry is found, the update is allowed.

CONFIGURATION SETTINGS

hooks.acltype STRING

Type of the storage engine. Valid values are File (default) and LDAP .

hooks.aclfile STRING

For the File storage engine, name of the ACL file.

hooks.aclldapconf STRING

For the LDAP storage engine, the name of the configuration file to use instead of /etc/ldap.conf.

hooks.acllog STRING

Send log info to this file.

hooks.acldebug NUMBER

Enable debugging. The bigger the number, the more debugging info will be displayed.

hooks.aclquiet BOOL

Suppress diagnostics on stderr.

hooks.httpd-user STRING

Name of the user httpd runs as. Define it if the repository can be accessed via HTTP (S). If gitaclhook is run as this user, it will get the name of the user on behalf of which the update is performed from the environment variable REMOTE_USER .

TEST MODE

The --test (-t) option provides a mechanism for testing access control lists from the command line. The syntax is:

gitacthook [--debug] [-d] --test REPO USER OP REF

REPO is a pathname of the repository to test, USER is the username, OP is the operation code and REF is the reference.

Optional --debug (-d) options increment the debugging level.

ENVIRONMENT

The program uses following environment variables:
GIT_UPDATE_DEBUG

When set to 1, enables debugging mode. The hooks.acldebug configuration variable overrides this setting.

GIT_DIR

Path to the affected repository.

If updates are performed via HTTP or HTTPS and the hooks.httpd-user configuration variable is set, the following two variables are used to determine the identity of the user:
AUTH_TYPE

If this variable is not set or set to an empty value, the program will deny the update.

REMOTE_USER

The authenticated name of the user.

SEE ALSO

git-receive-pack(1).

AUTHOR

Sergey Poznyakoff, <gray@gnu.org>

---