[core]
packedGitLimit = 200 m
[cache]
directory = /var/cache/gerrit2
[cache "diff"]
diskbuffer = 10 m
The optional file $site_path/gerrit.config is a Git-style config file that controls many host specific settings for Gerrit.
|
Note
|
The contents of the gerrit.config file are cached at startup by Gerrit. If you modify any propeties in this file, Gerrit needs to be restarted before it will use the new values. |
Sample gerrit.config:
[core]
packedGitLimit = 200 m
[cache]
directory = /var/cache/gerrit2
[cache "diff"]
diskbuffer = 10 m
See also SSO configuration.
Type of user authentication employed by Gerrit. The supported values are:
OpenID
The default setting. Gerrit uses any valid OpenID provider chosen by the end-user. For more information see openid.net.
HTTP
Gerrit relies upon data presented in the HTTP request. This includes HTTP basic authentication, or some types of commerical single-sign-on solutions. With this setting enabled the authentication must take place in the web server or servlet container, and not from within Gerrit.
HTTP_LDAP
Exactly like HTTP (above), but additionally Gerrit pre-populates a user's full name and email address based on information obtained from the user's account object in LDAP. The user's group membership is also pulled from LDAP, making any LDAP groups that a user is a member of available as groups in Gerrit.
LDAP
Gerrit prompts the user to enter a username and a password, which it then verifies by performing a simple bind against the configured ldap.server. In this configuration the web server is not involved in the user authentication process.
DEVELOPMENT_BECOME_ANY_ACCOUNT
DO NOT USE. Only for use in a development environment.
When this is the configured authentication method a hyperlink titled Become appears in the top right corner of the page, taking the user to a form where they can enter the username of any existing user account, and immediately login as that account, without any authentication taking place. This form of authentication is only useful for the GWT hosted mode shell, where OpenID authentication redirects might be risky to the developer's host computer, and HTTP authentication is not possible.
By default, OpenID.
List of trusted OpenID providers. Only used if auth.type was set to OpenID (the default).
In order for a user to take advantage of permissions beyond those granted to the Anonymous Users and Registered Users groups, the user account must only have OpenIDs which match at least one pattern from this list.
Patterns may be either a regular expression (start with ^ and end with $) or be a simple prefix (any other string).
By default, the list contains two values, http:// and https://, allowing Gerrit to trust any OpenID it receives.
HTTP header to trust the username from, or unset to select HTTP basic or digest authentication. Only used if auth.type was set to HTTP.
URL to redirect a browser to after the end-user has clicked on the "Sign Out" link in the upper right corner. Organizations using an enterprise single-sign-on solution may want to redirect the browser to the SSO product's sign-out page.
If not set, the redirect returns to the list of all open changes.
Optional format string to construct user email addresses out of user login names. Only used if auth.type is HTTP, HTTP_LDAP or LDAP.
This value can be set to a format string, where {0} is replaced with the login name. E.g. "{0}+gerrit@example.com" with a user login name of "foo" will produce "foo+gerrit@example.com" during the first time user "foo" registers.
If the site is using HTTP_LDAP or LDAP, using this option is discouraged. Setting ldap.accountEmailAddress and importing the email address from the LDAP directory is generally preferred.
Controls whether or not the contributor agreement features are enabled for the Gerrit site. If enabled a user must complete a contributor agreement before they can upload changes.
If enabled, the admin must also insert one or more rows into contributor_agreements and create agreement files under $site_path/static, so users can actually complete one or more agreements.
By default this is false (no agreements are used).
Allows Google Account users to automatically update their Gerrit account when/if their Google Account OpenID identity token changes. Identity tokens can change if the server changes hostnames, or for other reasons known only to Google. The upgrade path works by matching users by email address if the identity is not present, and then changing the identity.
This setting also permits old Gerrit 1.x users to seamlessly upgrade from Google Accounts on Google App Engine to OpenID authentication.
Having this enabled incurs an extra database query when Google Account users register with the Gerrit2 server.
By default, unset/false.
Path to a local directory where Gerrit can write cached entities for future lookup. This local disk cache is used to retain potentially expensive to compute information across restarts. If the location does not exist, Gerrit will try to create it.
If not absolute, the path is resolved relative to $site_path.
Default is unset, no disk cache.
Maximum age to keep an entry in the cache. If an entry has not been accessed in this period of time, it is removed from the cache. Values should use common unit suffixes to express their setting:
s, sec, second, seconds
m, min, minute, minutes
h, hr, hour, hours
d, day, days
w, week, weeks (1 week is treated as 7 days)
mon, month, months (1 month is treated as 30 days)
y, year, years (1 year is treated as 365 days)
If a unit suffix is not specified, minutes is assumed. If 0 is supplied, the maximum age is infinite and items are never purged except when the cache is full.
Default is 90 days for most caches, except:
"ldap_groups": default is 1 hour
"openid": default is 5 minutes
"web_sessions": default is 12 hours
Maximum number of cache items to retain in memory. Keep in mind this is total number of items, not bytes of heap used.
Default is 1024 for most caches, except:
"diff": default is 128
"openid": default is 64
Maximum number of cache items to retain on disk, if this cache supports storing its items to disk. Like memoryLimit, this is total number of items, not bytes of disk used. If 0, disk storage for this cache is disabled.
Default is 16384.
Number of bytes to buffer in memory before writing less frequently accessed cache items to disk, if this cache supports storing its items to disk.
Default is 5 MiB.
Common unit suffixes of k, m, or g are supported.
Cache entries contain important details of an active user, including their display name, preferences, known email addresses, and group memberships. Entry information is obtained from the following database tables:
accounts
account_group_members
account_external_ids
If direct updates are made to any of these database tables, this cache should be flushed.
Caches account identities keyed by email address, which is scanned from the account_external_ids database table. If updates are made to this table, this cache should be flushed.
Each item caches the differences between two commits, at both the directory and file levels. Gerrit uses this cache to accelerate the display of affected file names, as well as file contents.
Entries in this cache are relatively large, so the memory limit should not be set incredibly high. Administrators should try to target cache.diff.memoryLimit to be roughly the number of changes which their users will process in a 1 or 2 day span.
Keeping entries for 90 days gives sufficient time for most changes to be submitted or abandoned before their relevant difference items expire out.
Caches the basic group information from the account_groups table, including the group owner, name, and description.
Gerrit group membership obtained from the account_group_members table is cached under the "accounts" cache, above. External group membership obtained from LDAP is cached under "ldap_groups".
Caches the LDAP groups that a user belongs to, if LDAP has been configured on this server. This cache should be configured with a low maxAge setting, to ensure LDAP modifications are picked up in a timely fashion.
Caches a mapping of LDAP username to Gerrit account identity. The cache automatically updates when a user first creates their account within Gerrit, so the cache expire time is largely irrelevant.
If OpenID authentication is enabled, caches the OpenID discovery response by URL, for up to 5 minutes. This can reduce the time required for OpenID authentication through very common providers, such as Google Accounts.
Caches the project description records, from the projects table in the database. If a project record is updated or deleted, this cache should be flushed. Newly inserted projects do not require a cache flush, as they will be read upon first reference.
Caches unpacked versions of user SSH keys, so the internal SSH daemon can match against them during authentication. The unit of storage is per-user, so 1024 items translates to 1024 unique user accounts. As each individual user account may configure multiple SSH keys, the total number of keys may be larger than the item count.
This cache is based off the account_ssh_keys table and the accounts.ssh_user_name column in the database. If either is modified directly, this cache should be flushed.
Tracks the live user sessions coming in over HTTP. Flushing this cache would cause all users to be signed out immediately, forcing them to sign-in again. To avoid breaking active users, this cache is not flushed automatically by gerrit flush-caches —all, but instead must be explicitly requested.
If no disk cache is configured (or cache.web_sessions.diskLimit is set to 0) a server restart will force all users to sign-out, and need to sign-in again after the restart, as the cache was unable to persist the session information. Enabling a disk cache is strongly recommended.
Session storage is relatively inexpensive, the average entry in this cache is approximately 248 bytes, depending on the JVM.
See also gerrit flush-caches.
URL of the web based contact store Gerrit will send any offline contact information to when it collects the data from users as part of a contributor agreement.
See Contact Information.
Shared secret of the web based contact store.
Number of bytes of a pack file to load into memory in a single read operation. This is the "page size" of the JGit buffer cache, used for all pack access operations. All disk IO occurs as single window reads. Setting this too large may cause the process to load more data than is required; setting this too small may increase the frequency of read() system calls.
Default on JGit is 8 KiB on all platforms.
Common unit suffixes of k, m, or g are supported.
Maximum number of bytes to load and cache in memory from pack files. If JGit needs to access more than this many bytes it will unload less frequently used windows to reclaim memory space within the process. As this buffer must be shared with the rest of the JVM heap, it should be a fraction of the total memory available.
Default on JGit is 10 MiB on all platforms.
Common unit suffixes of k, m, or g are supported.
Maximum number of bytes to reserve for caching base objects that multiple deltafied objects reference. By storing the entire decompressed base object in a cache Git is able to avoid unpacking and decompressing frequently used base objects multiple times.
Default on JGit is 10 MiB on all platforms. You probably do not need to adjust this value.
Common unit suffixes of k, m, or g are supported.
Maximum number of pack files to have open at once. A pack file must be opened in order for any of its data to be available in a cached window.
If you increase this to a larger setting you may need to also adjust the ulimit on file descriptors for the host JVM, as Gerrit needs additional file descriptors available for network sockets and other repository data manipulation.
Default on JGit is 128 file descriptors on all platforms.
When true, JGit will use mmap() rather than malloc()+read() to load data from pack files. The use of mmap can be problematic on some JVMs as the garbage collector must deduce that a memory mapped segment is no longer in use before a call to munmap() can be made by the JVM native code.
In server applications (such as Gerrit) that need to access many pack files, setting this to true risks artifically running out of virtual address space, as the garbage collector cannot reclaim unused mapped spaces fast enough.
Default on JGit is false. Although potentially slower, it yields much more predictable behavior.
Local filesystem directory holding all Git repositories that Gerrit knows about and can process changes for. A project entity in Gerrit maps to a local Git repository by creating the path string "${basePath}/${project_name}.git".
If relative, the path is resolved relative to $site_path.
The default URL for Gerrit to be accessed through.
Typically this would be set to "http://review.example.com/" or "http://example.com/gerrit/" so Gerrit can output links that point back to itself.
Setting this is highly recommended, as its necessary for the upload code invoked by "git push" or "repo upload" to output hyperlinks to the newly uploaded changes.
Optional base URL for repositories available over the anonymous git protocol. For example, set this to git://mirror.example.com/base/ to have Gerrit display patch set download URLs in the UI. Gerrit automatically appends the project name onto the end of the URL.
By default unset, as the git daemon must be configured externally by the system administrator, and might not even be running on the same host as Gerrit.
See also Gitweb Integration.
Optional URL of an affiliated gitweb service. Defines the web location where a gitweb.cgi is installed to browse gerrit.basePath and the repositories it contains.
Gerrit appends any necessary query arguments onto the end of this URL. For example, "?p=$project.git;h=$commit".
LDAP integration is only enabled if auth.type was set to HTTP_LDAP or LDAP. See above for a detailed description of the auth.type settings and their implications.
An example LDAP configuration follows, and then discussion of the parameters introduced here. Suitable defaults for most parameters are automatically guessed based on the type of server detected during startup. The guessed defaults support both RFC 2307 and Active Directory.
[ldap]
server = ldap://ldap.example.com
#
accountBase = ou=people,dc=example,dc=com
accountPattern = (&(objectClass=person)(uid=${username}))
accountFullName = displayName
accountEmailAddress = mail
#
groupBase = ou=groups,dc=example,dc=com
groupMemberPattern = (&(objectClass=group)(member=${dn}))
URL of the organization's LDAP server to query for user information and group membership from. Must be of the form ldap://host or ldaps://host to bind with either a plaintext or SSL connection.
If auth.type is LDAP this setting should use ldaps:// to ensure the end user's plaintext password is transmitted only over an encrypted connection.
If false and ldap.server is an ldaps:// style URL, Gerrit will not verify the server certificate when it connects to perform a query.
By default, true, requiring the certificate to be verified.
(Optional) Username to bind to the LDAP server with. If not set, an anonymous connection to the LDAP server is attempted.
(Optional) Password for the user identified by ldap.username. If not set, an anonymous (or passwordless) connection to the LDAP server is attempted.
Root of the tree containing all user accounts. This is typically of the form ou=people,dc=example,dc=com.
Scope of the search performed for accounts. Must be one of:
one: Search only one level below accountBase, but not recursive
sub or subtree: Search recursively below accountBase
base or object: Search exactly accountBase; probably not desired
Default is subtree as many directories have several levels.
Query pattern to use when searching for a user account. This may be any valid LDAP query expression, including the standard (&…) and (|…) operators. If auth.type is HTTP_LDAP then the variable ${username} is replaced with a parameter set to the username that was supplied by the HTTP server. If auth.type is LDAP then the variable ${username} is replaced by the string entered by the end user.
This pattern is used to search the objects contained directly under the ldap.accountBase tree. A typical setting for this parameter is (uid=${username}) or (cn=${username}), but the proper setting depends on the LDAP schema used by the directory server.
Default is (uid=${username}) for RFC 2307 servers, for Active Directory.
(Optional) Name of an attribute on the user account object which contains the initial value for the user's full name field in Gerrit. Typically this is the displayName property in LDAP, but could also be legalName or cn.
Attribute values may be concatenated with literal strings, for example to join given name and surname together use the pattern ${givenName} ${SN}.
If set, users will be unable to modify their full name field, as Gerrit will populate it only from the LDAP data.
Default is displayName for RFC 2307 servers,
(Optional) Name of an attribute on the user account object which contains the user's Internet email address, as defined by this LDAP server.
Attribute values may be concatenated with literal strings, for example to set the email address to the lowercase form of sAMAccountName followed by a constant domain name, use ${sAMAccountName.toLowerCase}@example.com.
If set, the preferred email address will be prefilled from LDAP, but users may still be able to register additional email address, and select a different preferred email address.
Default is mail.
(Optional) Name of an attribute on the user account object which contains the initial value for the user's SSH username field in Gerrit. Typically this is the uid property in LDAP, but could also be cn. Administrators should prefer to match the attribute corresponding to the user's workstation username, as this is what SSH clients will default to.
Attribute values may also be forced to lowercase, or to uppercase in an expression. For example, ${sAMAccountName.toLowerCase} will force the value of sAMAccountName, if defined, to be all lowercase. The suffix .toUpperCase can be used for the other direction. The suffix .localPart can be used to split attribute values of the form user@example.com and return only the left hand side, for example ${userPrincipalName.localPart} would provide only user.
If set, users will be unable to modify their SSH username field, as Gerrit will populate it only from the LDAP data.
Default is uid for RFC 2307 servers, and ${sAMAccountName.toLowerCase} for Active Directory.
(Optional) Name of an attribute on the user account object which contains the groups the user is part of. Typically used for Active Directory servers.
Default is unset for RFC 2307 servers (disabled) and memberOf for Active Directory.
Root of the tree containing all group objects. This is typically of the form ou=groups,dc=example,dc=com.
Scope of the search performed for group objects. Must be one of:
one: Search only one level below groupBase, but not recursive
sub or subtree: Search recursively below groupBase
base or object: Search exactly groupBase; probably not desired
Default is subtree as many directories have several levels.
Query pattern used when searching for an LDAP group to connect to a Gerrit group. This may be any valid LDAP query expression, including the standard (&…) and (|…) operators. The variable ${groupname} is replaced with the search term supplied by the group owner.
Default is (cn=${groupname}) for RFC 2307, and (&(objectClass=group)(cn=${groupname})) for Active Directory.
Query pattern to use when searching for the groups that a user account is currently a member of. This may be any valid LDAP query expression, including the standard (&…) and (|…) operators.
If auth.type is HTTP_LDAP then the variable ${username} is replaced with a parameter set to the username that was supplied by the HTTP server. Other variables appearing in the pattern, such as ${fooBarAttribute}, are replaced with the value of the corresponding attribute (in this case, fooBarAttribute) as read from the user's account object matched under ldap.accountBase. Attributes such as ${dn} or ${uidNumber} may be useful.
Default is (memberUid=${username}) for RFC 2307, and unset (disabled) for Active Directory.
If set to true, files with the MIME type <name> will be sent as direct downloads to the user's browser, rather than being wrapped up inside of zipped archives. The type name may be a complete type name, e.g. image/gif, a generic media type, e.g. image/*, or the wildcard */* to match all types.
By default, false for all MIME types.
Common examples:
[mimetype "image/*"] safe = true [mimetype "application/pdf"] safe = true [mimetype "application/msword"] safe = true [mimetype "application/vnd.ms-excel"] safe = true
If set to true, Gerrit advertises patch set downloads with the repo download command, assuming that all projects managed by this instance are generally worked on with the repo multi-repository tool.
By default, false, as not all instances will deploy repo.
If false Gerrit will not send email messages, for any reason, and all other properties of section sendemail are ignored.
By default, true, allowing notifications to be sent.
Designates what name and address Gerrit will place in the From field of any generated email messages. The supported values are:
USER
Gerrit will set the From header to use the current user's Full Name and Preferred Email. This may cause messsages to be classified as spam if the user's domain has SPF or DKIM enabled and sendemail.smtpServer is not a trusted relay for that domain.
MIXED
Shorthand for ${user} (Code Review) <review@example.com> where review@example.com is the same as user.email. See below for a description of how the replacement is handled.
SERVER
Gerrit will set the From header to the same name and address it records in any commits Gerrit creates. This is set by user.name and user.email, or guessed from the local operating system.
Code Review <review@example.com>
If set to a name and email address in brackets, Gerrit will use this name and email address for any messages, overriding the name that may have been selected for commits by user.name and user.email. Optionally, the name portion may contain the placeholder ${user}, which is replaced by the Full Name of the current user.
By default, MIXED.
Hostname (or IP address) of a SMTP server that will relay messages generated by Gerrit to end users.
By default, 127.0.0.1 (aka localhost).
Port number of the SMTP server in sendemail.smtpserver.
By default, 25, or 465 if smtpEncryption is ssl.
Specify the encryption to use, either ssl or tls.
By default, none, indicating no encryption is used.
If false and sendemail.smtpEncryption is ssl or tls, Gerrit will not verify the server certificate when it connects to send an email message.
By default, true, requiring the certificate to be verified.
User name to authenticate with, if required for relay.
Password for the account named by sendemail.smtpUser.
If present, each value adds one entry to the whitelist of email addresses that Gerrit can send email to. If set to a complete email address, that one address is added to the white list. If set to a domain name, any address at that domain can receive email from Gerrit.
By default, unset, permitting delivery to any email address.
Specifies the local addresses the internal SSHD should listen for connections on. The following forms may be used to specify an address. In any form, :port may be omitted to use the default of 29418.
hostname:port (for example review.example.com:29418)
IPv4:port (for example 10.0.0.1:29418)
[IPv6]:port (for example [ff02::1]:29418)
*:port (for example *:29418)
If multiple values are supplied, the daemon will listen on all of them.
By default, *:29418.
If true, permits the daemon to bind to the port even if the port is already in use. If false, the daemon ensures the port is not in use before starting. Busy sites may need to set this to true to permit fast restarts.
By default, true.
If true, enables TCP keepalive messages to the other side, so the daemon can terminate connections if the peer disappears.
By default, true.
Available ciphers. To permit multiple ciphers, specify multiple sshd.cipher keys in the configuration file, one cipher name per key. Cipher names starting with + are enabled in addition to the default ciphers, cipher names starting with - are removed from the default cipher set.
Supported ciphers: aes128-cbc, aes128-cbc, aes256-cbc, blowfish-cbc, 3des-cbc, none.
By default, all supported ciphers except none are available.
Available MAC (message authentication code) algorithms. To permit multiple algorithms, specify multiple sshd.mac keys in the configuration file, one MAC per key. MAC names starting with + are enabled in addition to the default MACs, MAC names starting with - are removed from the default MACs.
Supported MACs: hmac-md5, hmac-md5-96, hmac-sha1, hmac-sha1-96.
By default, all supported MACs are available.
Name that Gerrit calls itself in Git when it creates a new Git commit, such as a merge during change submission.
By default this is "Gerrit Code Review".
Email address that Gerrit refers to itself as when it creates a new Git commit, such as a merge commit during change submission.
If not set, Gerrit generates this as "gerrit@hostname", where hostname is the hostname of the system Gerrit is running on.
By default, not set, generating the value at startup.
The optional file $site_path/replication.config controls how Gerrit automatically replicates changes it makes to any of the Git repositories under its control.
Several columns in the system_config table within the metadata database may be set to control how Gerrit behaves.
|
Note
|
The contents of the system_config table are cached at startup by Gerrit. If you modify any columns in this table, Gerrit needs to be restarted before it will use the new values. |
Local filesystem directory holding the site customization assets. Placing this directory under version control and/or backup is a good idea.
SSH key files (ssh_host_rsa_key and ssh_host_dsa_key or ssh_host_key) in this directory provide the host keys for the internal SSH daemon.
Other files support site customization.
These fields generally shouldn't be modified.
Private key used to sign the links emailed to users when they request to register a new email address on their user account. When the link is activated, the private key authenticates the link was created and sent by this Gerrit server, proving that the user can receive email at the address they are registering.
This column is automatically generated when the database is initialized. Changing it to a new value would cause all current links to be invalidated.
Changing it is not recommended.
Unique identity of the group with full privileges. Any user who is a member of this group may manage any other group, any project, and other system settings over the web.
This is initialized by Gerrit to be the "Administrators" group.
Changing it is not recommended.
Unique identity of the group for anonymous (not authenticated) users.
All users are a member of this group, whether or not they are actually signed in to Gerrit. Any access rights assigned to this group are inherited by all users.
This is initialized by Gerrit to be the "Anonymous Users" group.
Changing it is not recommended.
Unique identity of the group for all authenticated users.
All signed-in users are a member of this group. Any access rights assigned to this group are inherited by all users once they have authenticated to Gerrit.
Since account registration is open and fairly easy to obtain, moving from the "Anonymous Users" group to this group is not very difficult. Caution should be taken when assigning any permissions to this group.
This is initialized by Gerrit to be the "Registered Users" group.
Changing it is not recommended.
Part of Gerrit Code Review