| = Gerrit Code Review - Configuration | |
| == File `etc/gerrit.config` | |
| The optional file `'$site_path'/etc/gerrit.config` is a Git-style | |
| config file that controls many host specific settings for Gerrit. | |
| [NOTE] | |
| The contents of the `etc/gerrit.config` file are cached at startup | |
| by Gerrit. For most properties, if they are modified in this file, Gerrit | |
| needs to be restarted before it will use the new values. Some properties | |
| support being link:#reloadConfig[`reloaded`] without restart. | |
| Sample `etc/gerrit.config`: | |
| ---- | |
| [core] | |
| packedGitLimit = 200 m | |
| [cache] | |
| directory = /var/cache/gerrit | |
| ---- | |
| [[reloadConfig]] | |
| === Reload `etc/gerrit.config` | |
| Some properties support being reloaded without restart when a `reload config` | |
| command is issued through link:cmd-reload-config.html[`SSH`] or the | |
| link:rest-api-config.html#reload-config[`REST API`]. If a property supports | |
| this it is specified in the documentation for the property below. | |
| [[accountPatchReviewDb]] | |
| === Section accountPatchReviewDb | |
| The AccountPatchReviewDb is a database used to store the user file reviewed | |
| flags. | |
| [[accountPatchReviewDb.url]]accountPatchReviewDb.url:: | |
| + | |
| The url of accountPatchReviewDb. Supported types are `H2`, `POSTGRESQL`, | |
| `MARIADB`, and `MYSQL`. Drop the driver jar in the lib folder of the site path | |
| if the Jdbc driver of the corresponding Database is not yet in the class path. | |
| + | |
| Default is to create H2 database in the db folder of the site path. | |
| + | |
| Changing this parameter requires to migrate database using the | |
| link:pgm-MigrateAccountPatchReviewDb.html[MigrateAccountPatchReviewDb] program. | |
| Migration cannot be done while the server is running. | |
| + | |
| Also note that the db_name has to be a new db and not reusing an old ReviewDb | |
| database from a former 2.x site, otherwise gerrit's init will remove the table. | |
| ---- | |
| [accountPatchReviewDb] | |
| url = jdbc:postgresql://<host>:<port>/<db_name>?user=<user>&password=<password> | |
| ---- | |
| [[accountPatchReviewDb.poolLimit]]accountPatchReviewDb.poolLimit:: | |
| + | |
| Maximum number of open database connections. If the server needs | |
| more than this number, request processing threads will wait up | |
| to <<accountPatchReviewDb.poolMaxWait, poolMaxWait>> seconds for a | |
| connection to be released before they abort with an exception. | |
| This limit must be several units higher than the total number of | |
| httpd and sshd threads as some request processing code paths may | |
| need multiple connections. | |
| + | |
| Default is <<sshd.threads, sshd.threads>> | |
| + <<httpd.maxThreads, httpd.maxThreads>> + 2. | |
| + | |
| [[accountPatchReviewDb.poolMinIdle]]database.poolMinIdle:: | |
| + | |
| Minimum number of connections to keep idle in the pool. | |
| Default is 4. | |
| + | |
| [[accountPatchReviewDb.poolMaxIdle]]accountPatchReviewDb.poolMaxIdle:: | |
| + | |
| Maximum number of connections to keep idle in the pool. If there | |
| are more idle connections, connections will be closed instead of | |
| being returned back to the pool. | |
| Default is min(<<accountPatchReviewDb.poolLimit, accountPatchReviewDb.poolLimit>>, 16). | |
| + | |
| [[accountPatchReviewDb.poolMaxWait]]accountPatchReviewDb.poolMaxWait:: | |
| + | |
| Maximum amount of time a request processing thread will wait to | |
| acquire a database connection from the pool. If no connection is | |
| released within this time period, the processing thread will abort | |
| its current operations and return an error to the client. | |
| Values should use common unit suffixes to express their setting: | |
| + | |
| * ms, milliseconds | |
| * s, sec, second, seconds | |
| * m, min, minute, minutes | |
| * h, hr, hour, hours | |
| + | |
| If a unit suffix is not specified, `milliseconds` is assumed. | |
| Default is `30 seconds`. | |
| [[accounts]] | |
| === Section accounts | |
| [[accounts.visibility]]accounts.visibility:: | |
| + | |
| Controls visibility of other users' dashboard pages and | |
| completion suggestions to web users. | |
| + | |
| If `ALL`, all users are visible to all other users, even | |
| anonymous users. | |
| + | |
| If `SAME_GROUP`, only users who are also members of a group the | |
| current user is a member of are visible. | |
| + | |
| If `VISIBLE_GROUP`, only users who are members of at least one group | |
| that is visible to the current user are visible. | |
| + | |
| If `NONE`, no users other than the current user are visible. | |
| + | |
| Default is `ALL`. | |
| [[addreviewer]] | |
| === Section addreviewer | |
| [[addreviewer.maxWithoutConfirmation]]addreviewer.maxWithoutConfirmation:: | |
| + | |
| The maximum number of reviewers a user can add at once by adding a | |
| group as reviewer without being asked to confirm the operation. | |
| + | |
| If set to 0, the user will never be asked to confirm adding a group | |
| as reviewer. | |
| + | |
| Default is 10. | |
| + | |
| This setting only applies for adding reviewers in the Gerrit Web UI, | |
| but is ignored when adding reviewers with the | |
| link:cmd-set-reviewers.html[set-reviewers] command. | |
| + | |
| This value supports link:#reloadConfig[configuration reloads]. | |
| [[addreviewer.maxAllowed]]addreviewer.maxAllowed:: | |
| + | |
| The maximum number of reviewers a user can add at once by adding a | |
| group as reviewer. | |
| + | |
| If set to 0, there is no limit for the number of reviewers that can | |
| be added at once by adding a group as reviewer. | |
| + | |
| Default is 20. | |
| + | |
| This value supports link:#reloadConfig[configuration reloads]. | |
| [[addReviewer.baseWeight]]addReviewer.baseWeight:: | |
| + | |
| The weight that will be applied in the default reviewer ranking algorithm. | |
| This can be increased or decreased to give more or less influence to plugins. | |
| If set to zero, the base ranking will not have any effect. Reviewers will then | |
| be ordered as ranked by the plugins (if there are any). | |
| + | |
| By default 1. | |
| [[auth]] | |
| === Section auth | |
| See also link:config-sso.html[SSO configuration]. | |
| [[auth.type]]auth.type:: | |
| + | |
| 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 | |
| http://openid.net/[openid.net]. | |
| + | |
| * `OpenID_SSO` | |
| + | |
| Supports OpenID from a single provider. There is no registration | |
| link, and the "Sign In" link sends the user directly to the provider's | |
| SSO entry point. | |
| + | |
| * `HTTP` | |
| + | |
| Gerrit relies upon data presented in the HTTP request. This includes | |
| HTTP basic authentication, or some types of commercial 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. Hence the `_LDAP` suffix in | |
| the name of this authentication type. Gerrit does NOT authenticate | |
| the user via LDAP. | |
| + | |
| * `CLIENT_SSL_CERT_LDAP` | |
| + | |
| This authentication type is actually kind of SSO. Gerrit will configure | |
| Jetty's SSL channel to request the client's SSL certificate. For this | |
| authentication to work a Gerrit administrator has to import the root | |
| certificate of the trust chain used to issue the client's certificate | |
| into the <review-site>/etc/keystore. | |
| After the authentication is done Gerrit will obtain basic user | |
| registration (name and email) from LDAP, and some group memberships. | |
| Hence the `_LDAP` suffix in the name of this authentication type. | |
| Gerrit does NOT authenticate the user via LDAP. | |
| This authentication type can only be used under hosted daemon mode, and | |
| the httpd.listenUrl must use https:// as the protocol. | |
| Optionally, certificate revocation list file can be used | |
| at <review-site>/etc/crl.pem. For details, see httpd.sslCrl. | |
| + | |
| * `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,ldap.server>>. In this configuration the web server | |
| is not involved in the user authentication process. | |
| + | |
| The actual username used in the LDAP simple bind request is the | |
| account's full DN, which is discovered by first querying the | |
| directory using either an anonymous request, or the configured | |
| <<ldap.username,ldap.username>> identity. Gerrit can also use kerberos if | |
| <<ldap.authentication,ldap.authentication>> is set to `GSSAPI`. | |
| + | |
| If link:#auth.gitBasicAuthPolicy[`auth.gitBasicAuthPolicy`] is set to `HTTP`, | |
| the randomly generated HTTP password is used for authentication. On the other hand, | |
| if link:#auth.gitBasicAuthPolicy[`auth.gitBasicAuthPolicy`] is set to `HTTP_LDAP`, | |
| the password in the request is first checked against the HTTP password and, if | |
| it does not match, it is then validated against the LDAP password. | |
| Service users that only exist in the Gerrit database are authenticated by their | |
| HTTP passwords. | |
| * `LDAP_BIND` | |
| + | |
| 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,ldap.server>>. In this configuration the web server | |
| is not involved in the user authentication process. | |
| + | |
| Unlike `LDAP` above, the username used to perform the LDAP simple bind | |
| request is the exact string supplied in the dialog by the user. | |
| The configured <<ldap.username,ldap.username>> identity is not used to obtain | |
| account information. | |
| + | |
| * `OAUTH` | |
| + | |
| OAuth is a protocol that lets external apps request authorization to private | |
| details in a user's account without getting their password. This is | |
| preferred over Basic Authentication because tokens can be limited to specific | |
| types of data, and can be revoked by users at any time. | |
| + | |
| Site owners have to register their application before getting started. Note | |
| that provider specific plugins must be used with this authentication scheme. | |
| + | |
| Git clients may send OAuth 2 access tokens instead of passwords in the Basic | |
| authentication header. Note that provider specific plugins must be installed to | |
| facilitate this authentication scheme. If multiple OAuth 2 provider plugins are | |
| installed one of them must be selected as default with the | |
| `auth.gitOAuthProvider` option. | |
| + | |
| * `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. | |
| + | |
| By default, OpenID. | |
| [[auth.allowedOpenID]]auth.allowedOpenID:: | |
| + | |
| List of permitted OpenID providers. A user may only authenticate | |
| with an OpenID that matches this list. Only used if `auth.type` | |
| is set to `OpenID` (the default). | |
| + | |
| Patterns may be either a | |
| link:http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html[standard | |
| Java regular expression (java.util.regex)] (start with `^` and | |
| end with `$`) or be a simple prefix (any other string). | |
| + | |
| By default, the list contains two values, `http://` and `https://`, | |
| allowing users to authenticate with any OpenID provider. | |
| [[auth.trustedOpenID]]auth.trustedOpenID:: | |
| + | |
| List of trusted OpenID providers. Only used if `auth.type` is | |
| 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 | |
| link:http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html[standard | |
| Java regular expression (java.util.regex)] (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. | |
| [[auth.openIdDomain]]auth.openIdDomain:: | |
| + | |
| List of allowed OpenID email address domains. Only used if | |
| `auth.type` is set to `OPENID` or `OPENID_SSO`. | |
| + | |
| Domain is case insensitive and must be in the same form as it | |
| appears in the email address, for example, "example.com". | |
| + | |
| By default, any domain is accepted. | |
| [[auth.maxOpenIdSessionAge]]auth.maxOpenIdSessionAge:: | |
| + | |
| Time in seconds before an OpenID provider must force the user | |
| to authenticate themselves again before authentication to this | |
| Gerrit server. Currently this is only a polite request, and users | |
| coming from providers that don't support the PAPE extension will | |
| be accepted anyway. In the future it may be enforced, rejecting | |
| users coming from providers that don't honor the max session age. | |
| + | |
| If set to 0, the provider will always force the user to authenticate | |
| (e.g. supply their password). 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`) | |
| + | |
| Default is -1, permitting infinite time between authentications. | |
| [[auth.registerEmailPrivateKey]]auth.registerEmailPrivateKey:: | |
| + | |
| Private key to use when generating an email verification token. | |
| + | |
| If not set, a random key is generated when running the | |
| link:pgm-init.html[site initialization]. | |
| [[auth.maxRegisterEmailTokenAge]]auth.maxRegisterEmailTokenAge:: | |
| + | |
| Time in seconds before an email verification token sent to a user in | |
| order to validate their email address expires. | |
| + | |
| * 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`) | |
| + | |
| Default is 12 hours. | |
| [[auth.openIdSsoUrl]]auth.openIdSsoUrl:: | |
| + | |
| The SSO entry point URL. Only used if `auth.type` is set to | |
| `OpenID_SSO`. | |
| + | |
| The "Sign In" link will send users directly to this URL. | |
| [[auth.httpHeader]]auth.httpHeader:: | |
| + | |
| HTTP header to trust the username from, or unset to select HTTP basic | |
| authentication. Only used if `auth.type` is set to `HTTP`. | |
| [[auth.httpDisplaynameHeader]]auth.httpDisplaynameHeader:: | |
| + | |
| HTTP header to retrieve the user's display name from. Only used if `auth.type` | |
| is set to `HTTP`. | |
| + | |
| If set, Gerrit trusts and enforces the user's full name using the HTTP header | |
| and disables the ability to manually modify the user's full name | |
| from the contact information page. | |
| [[auth.httpEmailHeader]]auth.httpEmailHeader:: | |
| + | |
| HTTP header to retrieve the user's e-mail from. Only used if `auth.type` | |
| is set to `HTTP`. | |
| + | |
| If set, Gerrit trusts and enforces the user's e-mail using the HTTP header | |
| and disables the ability to manually modify or register other e-mails | |
| from the contact information page. | |
| [[auth.httpExternalIdHeader]]auth.httpExternalIdHeader:: | |
| + | |
| HTTP header to retrieve the user's external identification token. | |
| Only used if `auth.type` is set to `HTTP`. | |
| + | |
| If set, Gerrit adds the value contained in the HTTP header to the | |
| user's identity. Typical use is with a federated identity token from | |
| an external system (e.g. GitHub OAuth 2.0 authentication) where | |
| the user's auth token exchanged during authentication handshake | |
| needs to be used for authenticated communication to the external | |
| system later on. | |
| + | |
| Example: `auth.httpExternalIdHeader: X-GitHub-OTP` | |
| [[auth.loginUrl]]auth.loginUrl:: | |
| + | |
| URL to redirect a browser to after the end-user has clicked on the | |
| login link in the upper right corner. Only used if `auth.type` is set | |
| to `HTTP` or `HTTP_LDAP`. | |
| Organizations using an enterprise single-sign-on solution may want to | |
| redirect the browser to the SSO product's sign-in page for completing the | |
| login process and validate their credentials. | |
| + | |
| If set, Gerrit allows anonymous access until the end-user performs the login | |
| and provides a trusted identity through the HTTP header. | |
| If not set, Gerrit requires the HTTP header with a trusted identity | |
| and returns the error page 'LoginRedirect.html' if such a header is not | |
| present. | |
| [[auth.loginText]]auth.loginText:: | |
| + | |
| Text displayed in the loginUrl link. Only used if `auth.loginUrl` is set. | |
| + | |
| If not set, the "Sign In" text is used. | |
| [[auth.registerPageUrl]]auth.registerPageUrl:: | |
| + | |
| URL of the registration page to use when a new user logs in to Gerrit for | |
| the first time. Used only when `auth.type` is set to `HTTP`. | |
| + | |
| If not set, the standard Gerrit registration page `/#/register/` is displayed. | |
| [[auth.logoutUrl]]auth.logoutUrl:: | |
| + | |
| 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. | |
| [[auth.registerUrl]]auth.registerUrl:: | |
| + | |
| Target for the "Register" link in the upper right corner. Used only | |
| when `auth.type` is `LDAP`, `LDAP_BIND` or `CUSTOM_EXTENSION`. | |
| + | |
| If not set, no "Register" link is displayed. | |
| [[auth.registerText]]auth.registerText:: | |
| + | |
| Text for the "Register" link in the upper right corner. Used only | |
| when `auth.type` is `LDAP`, `LDAP_BIND` or `CUSTOM_EXTENSION`. | |
| + | |
| If not set, defaults to "Register". | |
| [[auth.editFullNameUrl]]auth.editFullNameUrl:: | |
| + | |
| Target for the "Edit" button when the user is allowed to edit their | |
| full name. Used only when `auth.type` is `LDAP`, `LDAP_BIND` or | |
| `CUSTOM_EXTENSION`. | |
| [[auth.httpPasswordUrl]]auth.httpPasswordUrl:: | |
| + | |
| Target for the "Obtain Password" link. Used only when `auth.type` is | |
| `CUSTOM_EXTENSION`. | |
| [[auth.switchAccountUrl]]auth.switchAccountUrl:: | |
| + | |
| URL to switch user identities and login as a different account than | |
| the currently active account. This is disabled by default except when | |
| `auth.type` is `OPENID` and `DEVELOPMENT_BECOME_ANY_ACCOUNT`. If set | |
| the "Switch Account" link is displayed next to "Sign Out". | |
| + | |
| When `auth.type` does not normally enable this URL administrators may | |
| set this to `login/`, allowing users to begin a new web session. This value | |
| is used as an href in PolyGerrit, so absolute URLs like | |
| `https://someotherhost/login` work as well. | |
| + | |
| If a ${path} parameter is included, then PolyGerrit will substitute the | |
| currently viewed path in the link. Be aware that this path will include | |
| a leading slash, so a value like this might be appropriate: `/login${path}`. | |
| [[auth.cookiePath]]auth.cookiePath:: | |
| + | |
| Sets "path" attribute of the authentication cookie. | |
| + | |
| If not set, HTTP request's path is used. | |
| [[auth.cookieDomain]]auth.cookieDomain:: | |
| + | |
| Sets "domain" attribute of the authentication cookie. | |
| + | |
| If not set, HTTP request's domain is used. | |
| [[auth.cookieSecure]]auth.cookieSecure:: | |
| + | |
| Sets "secure" flag of the authentication cookie. If true, cookies | |
| will be transmitted only over HTTPS protocol. | |
| + | |
| By default, false. | |
| [[auth.emailFormat]]auth.emailFormat:: | |
| + | |
| 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. | |
| [[auth.contributorAgreements]]auth.contributorAgreements:: | |
| + | |
| 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 add one or more | |
| link:config-cla.html[contributor-agreement sections] | |
| in project.config 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). | |
| + | |
| To enable the actual usage of contributor agreement the project | |
| specific config option in the `project.config` must be set: | |
| link:config-project-config.html[receive.requireContributorAgreement]. | |
| [[auth.trustContainerAuth]]auth.trustContainerAuth:: | |
| + | |
| If true then it is the responsibility of the container hosting | |
| Gerrit to authenticate users. In this case Gerrit will blindly trust | |
| the container. | |
| + | |
| This parameter only affects git over http traffic. If set to false | |
| then Gerrit will do the authentication (using Basic authentication). | |
| + | |
| By default this is set to false. | |
| [[auth.gitBasicAuthPolicy]]auth.gitBasicAuthPolicy:: | |
| + | |
| When `auth.type` is `LDAP`, `LDAP_BIND` or `OAUTH`, it allows using either the generated | |
| HTTP password, the LDAP or OAUTH password, or a combination of HTTP and LDAP | |
| authentication, to authenticate Git over HTTP and REST API requests. | |
| The supported values are: | |
| + | |
| *`HTTP` | |
| + | |
| Only the HTTP password is accepted when doing Git over HTTP and REST API requests. | |
| + | |
| *`LDAP` | |
| + | |
| Only the `LDAP` password is allowed when doing Git over HTTP and REST API | |
| requests. | |
| + | |
| *`OAUTH` | |
| + | |
| Only the `OAUTH` authentication is allowed when doing Git over HTTP and REST API | |
| requests. | |
| + | |
| *`HTTP_LDAP` | |
| + | |
| The password in the request is first checked against the HTTP password and, if | |
| it does not match, it is then validated against the `LDAP` password. | |
| + | |
| By default this is set to `LDAP` when link:#auth.type[`auth.type`] is `LDAP` | |
| and `OAUTH` when link:#auth.type[`auth.type`] is `OAUTH`. | |
| Otherwise, the default value is `HTTP`. | |
| [[auth.gitOAuthProvider]]auth.gitOAuthProvider:: | |
| + | |
| Selects the OAuth 2 provider to authenticate git over HTTP traffic with. | |
| + | |
| In general there is no way to determine from an access token alone, which | |
| OAuth 2 provider to address to verify that token, and the BasicAuth | |
| scheme does not support amending such details. If multiple OAuth provider | |
| plugins in a system offer support for git over HTTP authentication site | |
| administrators must configure, which one to use as default provider. | |
| In case the provider cannot be determined from a request the access token | |
| will be sent to the default provider for verification. | |
| + | |
| The value of this parameter must be the identifier of an OAuth 2 provider | |
| in the form `plugin-name:provider-name`. Consult the respective plugin | |
| documentation for details. | |
| [[auth.userNameToLowerCase]]auth.userNameToLowerCase:: | |
| + | |
| If set the username that is received to authenticate a git operation | |
| is converted to lower case for looking up the user account in Gerrit. | |
| + | |
| By setting this parameter a case insensitive authentication for the | |
| git operations can be achieved, if it is ensured that the usernames in | |
| Gerrit (scheme `username`) are stored in lower case (e.g. if the | |
| parameter link:#ldap.accountSshUserName[ldap.accountSshUserName] is | |
| set to `${sAMAccountName.toLowerCase}`). It is important that for all | |
| existing accounts this username is already in lower case. It is not | |
| possible to convert the usernames of the existing accounts to lower | |
| case because this would break the access to existing per-user | |
| branches and Gerrit provides no tool to do such a conversion. | |
| + | |
| Setting this parameter to `true` will prevent all users from login that | |
| have a non-lower-case username. | |
| + | |
| This parameter only affects git over http and git over SSH traffic. | |
| + | |
| By default this is set to false. | |
| [[auth.enableRunAs]]auth.enableRunAs:: | |
| + | |
| If true HTTP REST APIs will accept the `X-Gerrit-RunAs` HTTP request | |
| header from any users granted the link:access-control.html#capability_runAs[Run As] | |
| capability. The header and capability permit the authenticated user | |
| to impersonate another account. | |
| + | |
| If false the feature is disabled and cannot be re-enabled without | |
| editing gerrit.config and restarting the server. | |
| + | |
| Default is true. | |
| [[auth.allowRegisterNewEmail]]auth.allowRegisterNewEmail:: | |
| + | |
| Whether users are allowed to register new email addresses. | |
| + | |
| In addition for the HTTP authentication type | |
| link:#auth.httpemailheader[auth.httpemailheader] must *not* be set to | |
| enable registration of new email addresses. | |
| + | |
| By default, true. | |
| [[auth.autoUpdateAccountActiveStatus]]auth.autoUpdateAccountActiveStatus:: | |
| + | |
| Whether to allow automatic synchronization of an account's inactive flag upon login. | |
| If set to true, upon login, if the authentication back-end reports the account as active, | |
| the account's inactive flag in the internal Gerrit database will be updated to be active. | |
| If the authentication back-end reports the account as inactive, the account's flag will be | |
| updated to be inactive and the login attempt will be blocked. Users enabling this feature | |
| should ensure that their authentication back-end is supported. Currently, only | |
| strict 'LDAP' authentication is supported. | |
| + | |
| In addition, if this parameter is not set, or false, the corresponding scheduled | |
| task to deactivate inactive Gerrit accounts will also be disabled. If this | |
| parameter is set to true, users should also consider configuring the | |
| link:#accountDeactivation[accountDeactivation] section appropriately. | |
| + | |
| By default, false. | |
| [[auth.skipFullRefEvaluationIfAllRefsAreVisible]]auth.skipFullRefEvaluationIfAllRefsAreVisible:: | |
| + | |
| Whether to skip the full ref visibility checks as a performance shortcut when all refs are | |
| visible to a user. Full ref filtering would filter out things like pending edits. | |
| + | |
| By default, true. | |
| [[cache]] | |
| === Section cache | |
| [[cache.directory]]cache.directory:: | |
| + | |
| 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. | |
| + | |
| Technically, cached entities are persisted as a set of H2 databases | |
| inside this directory. | |
| + | |
| If not absolute, the path is resolved relative to `$site_path`. | |
| + | |
| Default is unset, no disk cache. | |
| [[cache.h2CacheSize]]cache.h2CacheSize:: | |
| + | |
| The size of the in-memory cache for each opened H2 cache database, in bytes. | |
| + | |
| Some caches of Gerrit are persistent and are backed by an H2 database. | |
| H2 uses memory to cache its database content. The parameter `h2CacheSize` | |
| allows to limit the memory used by H2 and thus prevent out-of-memory | |
| caused by the H2 database using too much memory. | |
| + | |
| Technically the H2 cache size is configured using the CACHE_SIZE parameter in | |
| the H2 JDBC connection URL, as described | |
| link:http://www.h2database.com/html/features.html#cache_settings[here] | |
| + | |
| Default is unset, using up to half of the available memory. | |
| + | |
| H2 will persist this value in the database, so to unset explicitly specify 0. | |
| + | |
| Common unit suffixes of 'k', 'm', or 'g' are supported. | |
| [[cache.h2AutoServer]]cache.h2AutoServer:: | |
| + | |
| If set to true, enable H2 autoserver mode for the H2-backed persistent cache | |
| databases. | |
| + | |
| See link:http://www.h2database.com/html/features.html#auto_mixed_mode[here] | |
| for detail. | |
| + | |
| Default is false. | |
| [[cache.name.maxAge]]cache.<name>.maxAge:: | |
| + | |
| Maximum age to keep an entry in the cache. Entries are removed from | |
| the cache and refreshed from source data every maxAge interval. | |
| 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, `seconds` is assumed. If 0 is | |
| supplied, the maximum age is infinite and items are never purged | |
| except when the cache is full. | |
| Default is `0`, meaning store forever with no expire, except: | |
| * `"adv_bases"`: default is `10 minutes` | |
| * `"ldap_groups"`: default is `1 hour` | |
| * `"web_sessions"`: default is `12 hours` | |
| -- | |
| [[cache.name.memoryLimit]]cache.<name>.memoryLimit:: | |
| + | |
| The total cost of entries to retain in memory. The cost computation | |
| varies by the cache. For most caches where the in-memory size of each | |
| entry is relatively the same, memoryLimit is currently defined to be | |
| the number of entries held by the cache (each entry costs 1). | |
| + | |
| For caches where the size of an entry can vary significantly between | |
| individual entries (notably `"diff"`, `"diff_intraline"`), memoryLimit | |
| is an approximation of the total number of bytes stored by the cache. | |
| Larger entries that represent bigger patch sets or longer source files | |
| will consume a bigger portion of the memoryLimit. For these caches the | |
| memoryLimit should be set to roughly the amount of RAM (in bytes) the | |
| administrator can dedicate to the cache. | |
| + | |
| Default is 1024 for most caches, except: | |
| + | |
| * `"adv_bases"`: default is `4096` | |
| * `"diff"`: default is `10m` (10 MiB of memory) | |
| * `"diff_intraline"`: default is `10m` (10 MiB of memory) | |
| * `"diff_summary"`: default is `10m` (10 MiB of memory) | |
| * `"external_ids_map"`: default is `2` and should not be changed | |
| * `"groups"`: default is unlimited | |
| * `"groups_byname"`: default is unlimited | |
| * `"groups_byuuid"`: default is unlimited | |
| * `"plugin_resources"`: default is 2m (2 MiB of memory) | |
| + | |
| If set to 0 the cache is disabled. Entries are removed immediately | |
| after being stored by the cache. This is primarily useful for testing. | |
| [[cache.name.expireFromMemoryAfterAccess]]cache.<name>.expireFromMemoryAfterAccess:: | |
| + | |
| Time after last access to automatically expire entries from an in-memory | |
| cache. If 0 or not specified, entries are never expired in this manner. | |
| Values may use unit suffixes as in link:#cache.name.maxAge[maxAge]. | |
| + | |
| This option only applies to in-memory caches; persistent cache values are | |
| not expired in this manner, and are only pruned via | |
| link:#cache.name.diskLimit[diskLimit]. | |
| [[cache.name.diskLimit]]cache.<name>.diskLimit:: | |
| + | |
| Total size in bytes of the keys and values stored on disk. Caches that | |
| have grown bigger than this size are scanned daily at 1 AM local | |
| server time to trim the cache. Entries are removed in least recently | |
| accessed order until the cache fits within this limit. Caches may | |
| grow larger than this during the day, as the size check is only | |
| performed once every 24 hours. | |
| + | |
| Default is 128 MiB per cache, except: | |
| + | |
| * `"change_notes"`: disk storage is disabled by default | |
| * `"diff_summary"`: default is `1g` (1 GiB of disk space) | |
| * `"external_ids_map"`: disk storage is disabled by default | |
| + | |
| If 0 or negative, disk storage for the cache is disabled. | |
| ==== [[cache_names]]Standard Caches | |
| cache `"accounts"`:: | |
| + | |
| Cache entries contain important details of an active user, including | |
| their display name, preferences, and known email addresses. Entry | |
| information is obtained from NoteDb data in the `All-Users` repo. | |
| + | |
| If direct updates are made to `All-Users`, this cache should be flushed. | |
| cache `"adv_bases"`:: | |
| + | |
| Used only for push over smart HTTP when branch level access controls | |
| are enabled. The cache entry contains all commits that are available | |
| for the client to use as potential delta bases. Push over smart HTTP | |
| requires two HTTP requests, and this cache tries to carry state from | |
| the first request into the second to ensure it can complete. | |
| cache `"changes"`:: | |
| + | |
| The size of `memoryLimit` determines the number of projects for which | |
| all changes will be cached. If the cache is set to 1024, this means all | |
| changes for up to 1024 projects can be held in the cache. | |
| + | |
| Default value is 0 (disabled). It is disabled by default due to the fact | |
| that change updates are not communicated between Gerrit servers. Hence | |
| this cache should be disabled in an multi-master/multi-replica setup. | |
| + | |
| The cache should be flushed whenever the database changes table is modified | |
| outside of Gerrit. | |
| cache `"diff"`:: | |
| + | |
| 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 memoryLimit is an | |
| estimate in bytes of memory used. Administrators should try to target | |
| cache.diff.memoryLimit to fit all changes users will view in a 1 or 2 | |
| day span. | |
| cache `"diff_intraline"`:: | |
| + | |
| Each item caches the intraline difference of one file, when compared | |
| between two commits. Gerrit uses this cache to accelerate display of | |
| intraline differences when viewing a file. | |
| + | |
| Entries in this cache are relatively large, so memoryLimit is an | |
| estimate in bytes of memory used. Administrators should try to target | |
| cache.diff.memoryLimit to fit all files users will view in a 1 or 2 | |
| day span. | |
| cache `"diff_summary"`:: | |
| + | |
| Each item caches list of file paths which are different between two | |
| commits. Gerrit uses this cache to accelerate computing of the list | |
| of paths of changed files. | |
| + | |
| Ideally, disk limit of this cache is large enough to cover all changes. | |
| This should significantly speed up change reindexing, especially | |
| full offline reindexing. | |
| cache `"external_ids_map"`:: | |
| + | |
| A singleton cache whose sole entry is a map of the parsed representation | |
| of link:config-accounts.html#external-ids[all current external IDs]. The | |
| cache may temporarily contain 2 entries, but the second one is promptly | |
| expired. | |
| + | |
| It is not recommended to change the in-memory attributes of this cache | |
| away from the defaults. The cache may be persisted by setting | |
| `diskLimit`, which is only recommended if cold start performance is | |
| problematic. | |
| + | |
| `external_ids_map` supports computing the new cache value based on a | |
| previously cached state. This applies modifications based on the Git | |
| diff and is almost always faster. | |
| `cache.external_ids_map.enablePartialReloads` turns this behavior on | |
| or off. The default is `true`. | |
| cache `"git_tags"`:: | |
| + | |
| If branch or reference level READ access controls are used, this | |
| cache tracks which tags are reachable from the branch tips of a | |
| repository. Gerrit uses this information to determine the set | |
| of tags that a client may access, derived from which tags are | |
| part of the history of a visible branch. | |
| + | |
| The cache is persisted to disk across server restarts as it can | |
| be expensive to compute (60 or more seconds for a large history | |
| like the Linux kernel repository). | |
| cache `"groups"`:: | |
| + | |
| Caches the basic group information of internal groups by group ID, | |
| including the group owner, name, and description. | |
| + | |
| For this cache it is important to configure a size that is larger than | |
| the number of internal Gerrit groups, otherwise general Gerrit | |
| performance may be poor. This is why by default this cache is | |
| unlimited. | |
| + | |
| External group membership obtained from LDAP is cached under | |
| `"ldap_groups"`. | |
| cache `"groups_byname"`:: | |
| + | |
| Caches the basic group information of internal groups by group name, | |
| including the group owner, name, and description. | |
| + | |
| For this cache it is important to configure a size that is larger than | |
| the number of internal Gerrit groups, otherwise general Gerrit | |
| performance may be poor. This is why by default this cache is | |
| unlimited. | |
| + | |
| External group membership obtained from LDAP is cached under | |
| `"ldap_groups"`. | |
| cache `"groups_byuuid"`:: | |
| + | |
| Caches the basic group information of internal groups by group UUID, | |
| including the group owner, name, and description. | |
| + | |
| For this cache it is important to configure a size that is larger than | |
| the number of internal Gerrit groups, otherwise general Gerrit | |
| performance may be poor. This is why by default this cache is | |
| unlimited. | |
| + | |
| External group membership obtained from LDAP is cached under | |
| `"ldap_groups"`. | |
| cache `"groups_bymember"`:: | |
| + | |
| Caches the groups which contain a specific member (account). If direct | |
| updates are made to the `account_group_members` table, this cache should | |
| be flushed. | |
| cache `"groups_bysubgroups"`:: | |
| + | |
| Caches the parent groups of a subgroup. If direct updates are made | |
| to the `account_group_includes` table, this cache should be flushed. | |
| cache `"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. | |
| cache `"ldap_groups_byinclude"`:: | |
| + | |
| Caches the hierarchical structure of LDAP groups. | |
| cache `"ldap_usernames"`:: | |
| + | |
| 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. | |
| cache `"permission_sort"`:: | |
| + | |
| Caches the order in which access control sections must be applied to a | |
| reference. Sorting the sections can be expensive when regular | |
| expressions are used, so this cache remembers the ordering for | |
| each branch. | |
| cache `"plugin_resources"`:: | |
| + | |
| Caches formatted plugin resources, such as plugin documentation that | |
| has been converted from Markdown to HTML. The memoryLimit refers to | |
| the bytes of memory dedicated to storing the documentation. | |
| cache `"projects"`:: | |
| + | |
| 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. | |
| cache `"prolog_rules"`:: | |
| + | |
| Caches parsed `rules.pl` contents for each project. This cache uses the same | |
| size as the `projects` cache, and cannot be configured independently. | |
| cache `"pure_revert"`:: | |
| + | |
| Result of checking if one change or commit is a pure/clean revert of | |
| another. | |
| cache `"sshkeys"`:: | |
| + | |
| 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. | |
| cache `"web_sessions"`:: | |
| + | |
| 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 346 bytes. | |
| See also link:cmd-flush-caches.html[gerrit flush-caches]. | |
| ==== [[cache_options]]Cache Options | |
| [[cache.diff.timeout]]cache.diff.timeout:: | |
| + | |
| Maximum number of milliseconds to wait for diff data before giving up and | |
| falling back on a simpler diff algorithm that will not be able to break down | |
| modified regions into smaller ones. This is a work around for an infinite loop | |
| bug in the default difference algorithm implementation. | |
| + | |
| Values should use common unit suffixes to express their setting: | |
| + | |
| * ms, milliseconds | |
| * s, sec, second, seconds | |
| * m, min, minute, minutes | |
| * h, hr, hour, hours | |
| + | |
| -- | |
| If a unit suffix is not specified, `milliseconds` is assumed. | |
| Default is 5 seconds. | |
| -- | |
| [[cache.diff_intraline.timeout]]cache.diff_intraline.timeout:: | |
| + | |
| Maximum number of milliseconds to wait for intraline difference data | |
| before giving up and disabling it for a particular file pair. This is | |
| a work around for an infinite loop bug in the intraline difference | |
| implementation. | |
| + | |
| If computation takes longer than the timeout, the worker thread is | |
| terminated, an error message is shown, and no intraline difference is | |
| displayed for the file pair. | |
| + | |
| Values should use common unit suffixes to express their setting: | |
| + | |
| * ms, milliseconds | |
| * s, sec, second, seconds | |
| * m, min, minute, minutes | |
| * h, hr, hour, hours | |
| + | |
| -- | |
| If a unit suffix is not specified, `milliseconds` is assumed. | |
| Default is 5 seconds. | |
| -- | |
| [[cache.diff_intraline.enabled]]cache.diff_intraline.enabled:: | |
| + | |
| Boolean to enable or disable the computation of intraline differences | |
| when populating a diff cache entry. This flag is provided primarily | |
| as a backdoor to disable the intraline difference feature if | |
| necessary. To maintain backwards compatibility with prior versions, | |
| this setting will fallback to `cache.diff.intraline` if not set in the | |
| configuration. | |
| + | |
| Default is true, enabled. | |
| [[cache.projects.checkFrequency]]cache.projects.checkFrequency:: | |
| + | |
| How often project configuration should be checked for update from Git. | |
| Gerrit Code Review caches project access rules and configuration in | |
| memory, checking the refs/meta/config branch every checkFrequency | |
| minutes to see if a new revision should be loaded and used for future | |
| access. Values can be specified using standard time unit abbreviations | |
| ('ms', 'sec', 'min', etc.). | |
| + | |
| If set to 0, checks occur every time, which may slow down operations. | |
| If set to 'disabled' or 'off', no check will ever be done. | |
| Administrators may force the cache to flush with | |
| link:cmd-flush-caches.html[gerrit flush-caches]. | |
| + | |
| Default is 5 minutes. | |
| [[cache.projects.loadOnStartup]]cache.projects.loadOnStartup:: | |
| + | |
| If the project cache should be loaded during server startup. | |
| + | |
| The cache is loaded concurrently. Admins should ensure that the cache | |
| size set under <<cache.name.memoryLimit,cache.projects.memoryLimit>> | |
| is not smaller than the number of repos. | |
| + | |
| Default is false, disabled. | |
| [[cache.projects.loadThreads]]cache.projects.loadThreads:: | |
| + | |
| Only relevant if <<cache.projects.loadOnStartup,cache.projects.loadOnStartup>> | |
| is true. | |
| + | |
| The number of threads to allocate for loading the cache at startup. These | |
| threads will die out after the cache is loaded. | |
| + | |
| Default is the number of CPUs. | |
| [[capability]] | |
| === Section capability | |
| [[capability.administrateServer]]capability.administrateServer:: | |
| + | |
| Names of groups of users that are allowed to exercise the | |
| `administrateServer` capability, in addition to those listed in | |
| All-Projects. Configuring this option can be a useful fail-safe | |
| to recover a server in the event an administrator removed all | |
| groups from the `administrateServer` capability, or to ensure that | |
| specific groups always have administration capabilities. | |
| + | |
| ---- | |
| [capability] | |
| administrateServer = group Fail Safe Admins | |
| ---- | |
| + | |
| The configuration file uses group names, not UUIDs. If a group is | |
| renamed the gerrit.config file must be updated to reflect the new | |
| name. If a group cannot be found for the configured name a warning | |
| is logged and the server will continue normal startup. | |
| + | |
| If not specified (default), only the groups listed by All-Projects | |
| may use the `administrateServer` capability. | |
| [[capability.makeFirstUserAdmin]]capability.makeFirstUserAdmin:: | |
| + | |
| Whether the first user that logs in to the Gerrit server should | |
| automatically be added to the administrator group and hence get the | |
| `administrateServer` capability assigned. This is useful to bootstrap | |
| the authentication database. | |
| + | |
| Default is true. | |
| [[change]] | |
| === Section change | |
| [[change.allowBlame]]change.allowBlame:: | |
| + | |
| Allow blame on side by side diff. If set to false, blame cannot be used. | |
| + | |
| Default is true. | |
| [[change.api.allowedIdentifier]]change.api.allowedIdentifier:: | |
| + | |
| Change identifier(s) that are allowed on the API. See | |
| link:rest-api-changes.html#change-id[Change Id] for more information. | |
| + | |
| Possible values are `ALL`, `TRIPLET`, `NUMERIC_ID`, `I_HASH`, and | |
| `COMMIT_HASH` or any combination of those as a string list. | |
| `PROJECT_NUMERIC_ID` is always allowed and doesn't need to be listed | |
| explicitly. | |
| + | |
| Default is `ALL`. | |
| [[change.api.excludeMergeableInChangeInfo]]change.api.excludeMergeableInChangeInfo:: | |
| + | |
| If true, the mergeability bit in | |
| link:rest-api-changes.html#change-info[ChangeInfo] will never be set. It can | |
| be requested separately through the | |
| link:rest-api-changes.html#get-mergeable[get-mergeable] endpoint. | |
| + | |
| Default is false. | |
| [[change.cacheAutomerge]]change.cacheAutomerge:: | |
| + | |
| When reviewing diff commits, the left-hand side shows the output of the | |
| result of JGit's automatic merge algorithm. This option controls whether | |
| this output is cached in the change repository, or if only the diff is | |
| cached in the persistent `diff` cache. | |
| + | |
| If true, automerge results are stored in the repository under | |
| `refs/cache-automerge/*`; the results of diffing the change against its | |
| automerge base are stored in the diff cache. If false, no extra data is | |
| stored in the repository, only the diff cache. This can result in slight | |
| performance improvements by reducing the number of refs in the repo. | |
| + | |
| Default is true. | |
| [[change.disablePrivateChanges]]change.disablePrivateChanges:: | |
| + | |
| If set to true, users are not allowed to create private changes. | |
| + | |
| The default is false. | |
| [[change.largeChange]]change.largeChange:: | |
| + | |
| Number of changed lines from which on a change is considered as a large | |
| change. The number of changed lines of a change is the sum of the lines | |
| that were inserted and deleted in the change. | |
| + | |
| The specified value is used to visualize the change sizes in the Web UI | |
| in change tables and user dashboards. | |
| + | |
| By default 500. | |
| [[change.maxUpdates]]change.maxUpdates:: | |
| + | |
| Maximum number of updates to a change. Counts only updates to the main NoteDb | |
| meta ref; draft comments, robot comments, stars, etc. do not count towards the | |
| total. | |
| + | |
| Many NoteDb operations require walking the entire change meta ref and loading | |
| its contents into memory, so changes with arbitrarily many updates may cause | |
| high CPU usage, memory pressure, persistent cache bloat, and other problems. | |
| + | |
| The following operations are allowed even when a change is at the limit: | |
| * Abandon | |
| * Submit | |
| * Submit by push with `%submit` | |
| * Auto-close by pushing directly to the branch | |
| * Fix with link:rest-api-changes.html#fix-input[`expect_merged_as`] | |
| + | |
| By default 1000. | |
| [[change.move]]change.move:: | |
| + | |
| Whether the link:rest-api-changes.html#move-change[Move Change] REST | |
| endpoint is enabled. | |
| + | |
| The move change functionality has some corner cases with undesired side | |
| effects. Hence administrators may decide to disable this functionality. | |
| In particular, if a change that has dependencies on other changes is | |
| moved to a new branch, and the moved change gets submitted to the new | |
| branch, the changes on which the change depends are silently merged | |
| into the new branch, although these changes have not been moved to that | |
| branch (see details in | |
| link:https://bugs.chromium.org/p/gerrit/issues/detail?id=9877[issue | |
| 9877]). | |
| + | |
| By default true. | |
| [[change.replyLabel]]change.replyLabel:: | |
| + | |
| Label name for the reply button. In the user interface an ellipsis (…) | |
| is appended. | |
| + | |
| Default is "Reply". In the user interface it becomes "Reply…". | |
| [[change.replyTooltip]]change.replyTooltip:: | |
| + | |
| Tooltip for the reply button. In the user interface a note about the | |
| keyboard shortcut is appended. | |
| + | |
| Default is "Reply and score". In the user interface it becomes "Reply | |
| and score (Shortcut: a)". | |
| [[change.robotCommentSizeLimit]]change.robotCommentSizeLimit:: | |
| + | |
| Maximum allowed size of a robot comment that will be accepted. Robot comments | |
| which exceed the indicated size will be rejected on addition. The specified | |
| value is interpreted as the maximum size in bytes of the JSON representation of | |
| the robot comment. Common unit suffixes of 'k', 'm', or 'g' are supported. | |
| Zero or negative values allow robot comments of unlimited size. | |
| + | |
| The default limit is 1024kB. | |
| [[change.showAssigneeInChangesTable]]change.showAssigneeInChangesTable:: | |
| + | |
| Show assignee field in changes table. If set to false, assignees will | |
| not be visible in changes table. | |
| + | |
| Default is false. | |
| [[change.strictLabels]]change.strictLabels:: | |
| + | |
| Reject invalid label votes: invalid labels or invalid values. This | |
| configuration option is provided for backwards compaitbility and may | |
| be removed in future gerrit versions. | |
| + | |
| Default is false. | |
| [[change.submitLabel]]change.submitLabel:: | |
| + | |
| Label name for the submit button. | |
| + | |
| Default is "Submit". | |
| [[change.submitLabelWithParents]]change.submitLabelWithParents:: | |
| + | |
| Label name for the submit button if the change has parents which will | |
| be submitted together with this change. | |
| + | |
| Default is "Submit including parents". | |
| [[change.submitTooltip]]change.submitTooltip:: | |
| + | |
| Tooltip for the submit button. Variables available for replacement | |
| include `${patchSet}` for the current patch set number (1, 2, 3), | |
| `${branch}` for the branch name ("master") and `${commit}` for the | |
| abbreviated commit SHA-1 (`c9c0edb`). | |
| + | |
| Default is "Submit patch set ${patchSet} into ${branch}". | |
| [[change.submitTooltipAncestors]]change.submitTooltipAncestors:: | |
| + | |
| Tooltip for the submit button if there are ancestors which would | |
| also be submitted by submitting the change. Additionally to the variables | |
| as in link:#change.submitTooltip[change.submitTooltip], there is the | |
| variable `${submitSize}` indicating the number of changes which are | |
| submitted. | |
| + | |
| Default is "Submit all ${topicSize} changes of the same topic (${submitSize} | |
| changes including ancestors and other changes related by topic)". | |
| [[change.submitTopicLabel]]change.submitTopicLabel:: | |
| + | |
| If `change.submitWholeTopic` is set and a change has a topic, | |
| the label name for the submit button is given here instead of | |
| the configuration `change.submitLabel`. | |
| + | |
| Defaults to "Submit whole topic" | |
| [[change.submitTopicTooltip]]change.submitTopicTooltip:: | |
| + | |
| If `change.submitWholeTopic` is configured to true and a change has a | |
| topic, this configuration determines the tooltip for the submit button | |
| instead of `change.submitTooltip`. The variable `${topicSize}` is available | |
| for the number of changes in the same topic to be submitted. The number of | |
| all changes to be submitted is in the variable `${submitSize}`. | |
| + | |
| Defaults to "Submit all ${topicSize} changes of the same topic | |
| (${submitSize} changes including ancestors and other | |
| changes related by topic)". | |
| [[change.submitWholeTopic]]change.submitWholeTopic:: | |
| + | |
| Determines if the submit button submits the whole topic instead of | |
| just the current change. | |
| + | |
| Default is false. | |
| [[change.updateDelay]]change.updateDelay:: | |
| + | |
| How often in seconds the web interface should poll for updates to the | |
| currently open change. The poller relies on the client's browser | |
| cache to use If-Modified-Since and respect `304 Not Modified` HTTP | |
| responses. This allows for fast polls, often under 8 milliseconds. | |
| + | |
| With a configured 30 second delay a server with 4900 active users will | |
| typically need to dedicate 1 CPU to the update check. 4900 users | |
| divided by an average delay of 30 seconds is 163 requests arriving per | |
| second. If requests are served at \~6 ms response time, 1 CPU is | |
| necessary to keep up with the update request traffic. On a smaller | |
| user base of 500 active users, the default 30 second delay is only 17 | |
| requests per second and requires ~10% CPU. | |
| + | |
| If 0 the update polling is disabled. | |
| + | |
| Default is 5 minutes. | |
| [[changeCleanup]] | |
| === Section changeCleanup | |
| This section allows to configure change cleanups and schedules them to | |
| run periodically. | |
| [[changeCleanup.abandonAfter]]changeCleanup.abandonAfter:: | |
| + | |
| Period of inactivity after which open changes should be abandoned | |
| automatically. | |
| + | |
| By default `0`, never abandon open changes. | |
| + | |
| [WARNING] Auto-Abandoning changes may confuse/annoy users. When | |
| enabling this, make sure to choose a reasonably large grace period and | |
| inform users in advance. | |
| + | |
| The following suffixes are supported to define the time unit: | |
| + | |
| * `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`) | |
| [[changeCleanup.abandonIfMergeable]]changeCleanup.abandonIfMergeable:: | |
| + | |
| Whether changes which are mergeable should be auto-abandoned. | |
| + | |
| By default `true`. | |
| [[changeCleanup.cleanupAccountPatchReview]]changeCleanup.cleanupAccountPatchReview:: | |
| + | |
| Whether accountPatchReview data should be also removed when change | |
| gets auto-abandoned. | |
| + | |
| By default `false`. | |
| [[changeCleanup.abandonMessage]]changeCleanup.abandonMessage:: | |
| + | |
| Change message that should be posted when a change is abandoned. | |
| + | |
| '${URL}' can be used as a placeholder for the Gerrit web URL. | |
| + | |
| By default "Auto-Abandoned due to inactivity, see | |
| ${URL}Documentation/user-change-cleanup.html#auto-abandon\n\n | |
| If this change is still wanted it should be restored.". | |
| [[changeCleanup.startTime]]changeCleanup.startTime:: | |
| + | |
| The link:#schedule-configuration-startTime[start time] for running | |
| change cleanups. | |
| [[changeCleanup.interval]]changeCleanup.interval:: | |
| + | |
| The link:#schedule-configuration-interval[interval] for running | |
| change cleanups. | |
| link:#schedule-configuration-examples[Schedule examples] can be found | |
| in the link:#schedule-configuration[Schedule Configuration] section. | |
| [[commentlink]] | |
| === Section commentlink | |
| Comment links are find/replace strings applied to change descriptions, | |
| patch comments, in-line code comments and approval category value descriptions | |
| to turn set strings into hyperlinks. One common use is for linking to | |
| bug-tracking systems. | |
| In the following example configuration the 'changeid' comment link | |
| will match typical Gerrit Change-Id values and create a hyperlink | |
| to changes which reference it. The second configuration 'bugzilla' | |
| will hyperlink terms such as 'bug 42' to an external bug tracker, | |
| supplying the argument record number '42' for display. The third | |
| configuration 'tracker' uses raw HTML to more precisely control | |
| how the replacement is displayed to the user. | |
| commentlinks supports link:#reloadConfig[configuration reloads]. Though a | |
| link:cmd-flush-caches.html[flush-caches] of "projects" is needed for the | |
| commentlinks to be immediately available in the UI. | |
| ---- | |
| [commentlink "changeid"] | |
| match = (I[0-9a-f]{8,40}) | |
| link = "#/q/$1" | |
| [commentlink "bugzilla"] | |
| match = "(bug\\s+#?)(\\d+)" | |
| link = http://bugs.example.com/show_bug.cgi?id=$2 | |
| [commentlink "tracker"] | |
| match = ([Bb]ug:\\s+)(\\d+) | |
| html = $1<a href=\"http://trak.example.com/$2\">$2</a> | |
| ---- | |
| Comment links can also be specified in `project.config` and sections in | |
| children override those in parents. The only restriction is that to | |
| avoid injecting arbitrary user-supplied HTML in the page, comment links | |
| defined in `project.config` may only supply `link`, not `html`. | |
| [[commentlink.name.match]]commentlink.<name>.match:: | |
| + | |
| A JavaScript regular expression to match positions to be replaced | |
| with a hyperlink. Subexpressions of the matched string can be | |
| stored using groups and accessed with `$'n'` syntax, where 'n' | |
| is the group number, starting from 1. | |
| + | |
| The configuration file parser eats one level of backslashes, so the | |
| character class `\s` requires `\\s` in the configuration file. The | |
| parser also terminates the line at the first `#`, so a match | |
| expression containing # must be wrapped in double quotes. | |
| + | |
| To match case insensitive strings, a character class with both the | |
| upper and lower case character for each position must be used. For | |
| example, to match the string `bug` in a case insensitive way the match | |
| pattern `[bB][uU][gG]` needs to be used. | |
| + | |
| The commentlink.name.match regular expressions are applied to the raw, | |
| unformatted and unescaped text form. Regex matching against HTML is not | |
| supported. Comment link patterns that are written in this style should | |
| be updated to match text formats. | |
| + | |
| A common pattern to match is `bug\\s+(\\d+)`. | |
| [[commentlink.name.link]]commentlink.<name>.link:: | |
| + | |
| The URL to direct the user to whenever the regular expression is | |
| matched. Groups in the match expression may be accessed as `$'n'`. | |
| + | |
| The link property is used only when the html property is not present. | |
| [[commentlink.name.html]]commentlink.<name>.html:: | |
| + | |
| HTML to replace the entire matched string with. If present, | |
| this property overrides the link property above. Groups in the | |
| match expression may be accessed as `$'n'`. | |
| + | |
| The configuration file eats double quotes, so escaping them as | |
| `\"` is necessary to protect them from the parser. | |
| [[commentlink.name.enabled]]commentlink.<name>.enabled:: | |
| + | |
| Whether the comment link is enabled. A child project may override a | |
| section in a parent or the site-wide config that is disabled by | |
| specifying `enabled = true`. | |
| + | |
| Disabling sections in `gerrit.config` can be used by site administrators | |
| to create a library of comment links with `html` set that are not | |
| user-supplied and thus can be verified to be XSS-free, but are only | |
| enabled for a subset of projects. | |
| + | |
| By default, true. | |
| + | |
| Note that the names and contents of disabled sections are visible even | |
| to anonymous users via the | |
| link:rest-api-projects.html#get-config[REST API]. | |
| [[container]] | |
| === Section container | |
| These settings are applied only if Gerrit is started as the container | |
| process through Gerrit's 'gerrit.sh' rc.d compatible wrapper script. | |
| [[container.heapLimit]]container.heapLimit:: | |
| + | |
| Maximum heap size of the Java process running Gerrit, in bytes. | |
| This property is translated into the '-Xmx' flag for the JVM. | |
| + | |
| Default is platform and JVM specific. | |
| + | |
| Common unit suffixes of 'k', 'm', or 'g' are supported. | |
| [[container.javaHome]]container.javaHome:: | |
| + | |
| Path of the JRE/JDK installation to run Gerrit with. If not set, the | |
| Gerrit startup script will attempt to search your system and guess | |
| a suitable JRE. Overrides the environment variable 'JAVA_HOME'. | |
| [[container.javaOptions]]container.javaOptions:: | |
| + | |
| Additional options to pass along to the Java runtime. If multiple | |
| values are configured, they are passed in order on the command line, | |
| separated by spaces. These options are appended onto 'JAVA_OPTIONS'. | |
| For example, it is possible to overwrite Gerrit's default log4j | |
| configuration: | |
| ---- | |
| javaOptions = -Dlog4j.configuration=file:///home/gerrit/site/etc/log4j.properties | |
| ---- | |
| [[container.daemonOpt]]container.daemonOpt:: | |
| + | |
| Additional options to pass to the daemon (e.g. '--enable-httpd'). If | |
| multiple values are configured, they are passed in that order to the command | |
| line, separated by spaces. | |
| + | |
| Execute `java -jar gerrit.war daemon --help` to see all possible | |
| options. | |
| [[container.replica]]container.replica:: | |
| + | |
| Used on Gerrit replica installations. If set to true the Gerrit JVM is | |
| called with the '--replica' switch, enabling replica mode. If no value is | |
| set (or any other value), Gerrit defaults to master mode. | |
| [[container.slave]]container.slave:: | |
| + | |
| Backward compatibility for 'container.slave' config setting. | |
| [[container.startupTimeout]]container.startupTimeout:: | |
| + | |
| The maximum time (in seconds) to wait for a gerrit.sh start command | |
| to run a new Gerrit daemon successfully. If not set, defaults to | |
| 90 seconds. | |
| [[container.user]]container.user:: | |
| + | |
| Login name (or UID) of the operating system user the Gerrit JVM | |
| will execute as. If not set, defaults to the user who launched | |
| the 'gerrit.sh' wrapper script. | |
| [[container.war]]container.war:: | |
| + | |
| Path of the JAR file to start daemon execution with. This should | |
| be the path of the local 'gerrit.war' archive. Overrides the | |
| environment variable 'GERRIT_WAR'. | |
| + | |
| If not set, defaults to '$site_path/bin/gerrit.war', or to | |
| '$HOME/gerrit.war'. | |
| [[core]] | |
| === Section core | |
| [NOTE] | |
| The link:#jgitConfig[etc/jgit.config] file supports configuration of all JGit | |
| options. | |
| [[core.packedGitWindowSize]]core.packedGitWindowSize:: | |
| + | |
| 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. | |
| [[core.packedGitLimit]]core.packedGitLimit:: | |
| + | |
| 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. | |
| [[core.deltaBaseCaseLimit]]core.deltaBaseCacheLimit:: | |
| + | |
| 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. | |
| [[core.packedGitOpenFiles]]core.packedGitOpenFiles:: | |
| + | |
| 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. | |
| [[core.streamFileThreshold]]core.streamFileThreshold:: | |
| + | |
| Largest object size, in bytes, that JGit will allocate as a | |
| contiguous byte array. Any file revision larger than this threshold | |
| will have to be streamed, typically requiring the use of temporary | |
| files under '$GIT_DIR/objects' to implement pseudo-random access | |
| during delta decompression. | |
| + | |
| Servers with very high traffic should set this to be larger than | |
| the size of their common big files. For example a server managing | |
| the Android platform typically has to deal with ~10-12 MiB XML | |
| files, so `15 m` would be a reasonable setting in that environment. | |
| Setting this too high may cause the JVM to run out of heap space | |
| when handling very big binary files, such as device firmware or | |
| CD-ROM ISO images. | |
| + | |
| Defaults to 25% of the available JVM heap, limited to 2048m. | |
| + | |
| Common unit suffixes of 'k', 'm', or 'g' are supported. | |
| [[core.packedGitMmap]]core.packedGitMmap:: | |
| + | |
| 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 artificially 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. | |
| [[core.asyncLoggingBufferSize]]core.asyncLoggingBufferSize:: | |
| + | |
| Size of the buffer to store logging events for asynchronous logging. | |
| Putting a larger value can protect threads from stalling when the | |
| AsyncAppender threads are not fast enough to consume the logging events | |
| from the buffer. It also protects from losing log entries in this case. | |
| + | |
| Default is 64 entries. | |
| [[core.useRecursiveMerge]]core.useRecursiveMerge:: | |
| + | |
| Use JGit's recursive merger for three-way merges. This only affects | |
| projects that allow content merges. | |
| + | |
| As explained in this | |
| link:http://codicesoftware.blogspot.com/2011/09/merge-recursive-strategy.html[ | |
| blog], the recursive merge produces better results if the two commits | |
| that are merged have more than one common predecessor. | |
| + | |
| Default is true. | |
| [[core.repositoryCacheCleanupDelay]]core.repositoryCacheCleanupDelay:: | |
| + | |
| Delay between each periodic cleanup of expired repositories. | |
| + | |
| Values can be specified using standard time unit abbreviations (`ms`, `sec`, | |
| `min`, etc.). | |
| + | |
| Set it to 0 in order to switch off cache expiration. If cache expiration is | |
| switched off, the JVM can still evict cache entries when it is running low | |
| on available heap memory. | |
| + | |
| Set it to -1 to automatically derive cleanup delay from | |
| `core.repositoryCacheExpireAfter` (lowest value between 1/10 of | |
| `core.repositoryCacheExpireAfter` and 10 minutes). | |
| + | |
| Default is -1. | |
| [[core.repositoryCacheExpireAfter]]core.repositoryCacheExpireAfter:: | |
| + | |
| Time an unused repository should expire and be evicted from the repository | |
| cache. | |
| + | |
| Values can be specified using standard time unit abbreviations (`ms`, `sec`, | |
| `min`, etc.). | |
| + | |
| Default is 1 hour. | |
| [[download]] | |
| === Section download | |
| ---- | |
| [download] | |
| command = checkout | |
| command = cherry_pick | |
| command = pull | |
| command = format_patch | |
| scheme = ssh | |
| scheme = http | |
| scheme = anon_http | |
| scheme = anon_git | |
| scheme = repo_download | |
| ---- | |
| The download section configures the allowed download methods. | |
| [[download.command]]download.command:: | |
| + | |
| Commands that should be offered to download changes. | |
| + | |
| Multiple commands are supported: | |
| + | |
| * `checkout` | |
| + | |
| Command to fetch and checkout the patch set. | |
| + | |
| * `cherry_pick` | |
| + | |
| Command to fetch the patch set and to cherry-pick it onto the current | |
| commit. | |
| + | |
| * `pull` | |
| + | |
| Command to pull the patch set. | |
| + | |
| * `format_patch` | |
| + | |
| Command to fetch the patch set and to feed it into the `format-patch` | |
| command. | |
| + | |
| If `download.command` is not specified, all download commands are | |
| offered. | |
| [[download.scheme]]download.scheme:: | |
| + | |
| Schemes that should be used to download changes. | |
| + | |
| Multiple schemes are supported: | |
| + | |
| * `http` | |
| + | |
| Authenticated HTTP download is allowed. | |
| + | |
| * `ssh` | |
| + | |
| Authenticated SSH download is allowed. | |
| + | |
| * `anon_http` | |
| + | |
| Anonymous HTTP download is allowed. | |
| + | |
| * `anon_git` | |
| + | |
| Anonymous Git download is allowed. This is not default, it is also | |
| necessary to set <<gerrit.canonicalGitUrl,gerrit.canonicalGitUrl>> | |
| variable. | |
| + | |
| * `repo_download` | |
| + | |
| 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. This is | |
| not default, as not all instances will deploy repo. | |
| + | |
| If `download.scheme` is not specified, SSH, HTTP and Anonymous HTTP | |
| downloads are allowed. | |
| [[download.checkForHiddenChangeRefs]]download.checkForHiddenChangeRefs:: | |
| + | |
| Whether the download commands should be adapted when the change refs | |
| are hidden. | |
| + | |
| Git has a configuration option to hide refs from the initial | |
| advertisement (`uploadpack.hideRefs`). This option can be used to hide | |
| the change refs from the client. As consequence fetching changes by | |
| change ref does not work anymore. However by setting | |
| `uploadpack.allowTipSha1InWant` to `true` fetching changes by commit ID | |
| is possible. If `download.checkForHiddenChangeRefs` is set to `true` | |
| the git download commands use the commit ID instead of the change ref | |
| when a project is configured like this. | |
| + | |
| Example git configuration on a project: | |
| + | |
| ---- | |
| [uploadpack] | |
| hideRefs = refs/changes/ | |
| hideRefs = refs/cache-automerge/ | |
| allowTipSha1InWant = true | |
| ---- | |
| + | |
| By default `false`. | |
| [[download.archive]]download.archive:: | |
| + | |
| Specifies which archive formats, if any, should be offered on the change | |
| screen and supported for `git-upload-archive` operation: | |
| + | |
| ---- | |
| [download] | |
| archive = tar | |
| archive = tbz2 | |
| archive = tgz | |
| archive = txz | |
| archive = zip | |
| ---- | |
| If `download.archive` is not specified defaults to all archive | |
| commands. Set to `off` or empty string to disable. | |
| Zip is not supported because it may be interpreted by a Java plugin as a | |
| valid JAR file, whose code would have access to cookies on the domain. | |
| For this reason `zip` format is always excluded from formats offered | |
| through the `Download` drop down or accessible in the REST API. | |
| [[download.maxBundleSize]]download.maxBundleSize:: | |
| + | |
| Specifies the maximum size of a bundle in bytes that can be downloaded. | |
| As bundles are kept in memory this setting is to protect the server | |
| from a single request consuming too much heap when generating | |
| a bundle and thereby impacting other users. | |
| + | |
| Defaults to 100MB. | |
| [[gc]] | |
| === Section gc | |
| This section allows to configure the git garbage collection and schedules it | |
| to run periodically. It will be triggered and executed sequentially for all | |
| projects. | |
| [[gc.aggressive]]gc.aggressive:: | |
| + | |
| Determines if scheduled garbage collections and garbage collections triggered | |
| through Web-UI should run in aggressive mode or not. Aggressive garbage | |
| collections are more expensive but may lead to significantly smaller | |
| repositories. | |
| + | |
| Valid values are "true" and "false," default is "false". | |
| [[gc.startTime]]gc.startTime:: | |
| + | |
| The link:#schedule-configuration-startTime[start time] for running the | |
| git garbage collection. | |
| [[gc.interval]]gc.interval:: | |
| + | |
| The link:#schedule-configuration-interval[interval] for running the | |
| git garbage collection. | |
| link:#schedule-configuration-examples[Schedule examples] can be found | |
| in the link:#schedule-configuration[Schedule Configuration] section. | |
| [[gerrit]] | |
| === Section gerrit | |
| [[gerrit.basePath]]gerrit.basePath:: | |
| + | |
| 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'`. | |
| [[gerrit.allProjects]]gerrit.allProjects:: | |
| + | |
| Name of the permissions-only project defining global server | |
| access controls and settings. These are inherited into every | |
| other project managed by the running server. The name is | |
| relative to `gerrit.basePath`. | |
| + | |
| Defaults to `All-Projects` if not set. | |
| [[gerrit.allUsers]]gerrit.allUsers:: | |
| + | |
| Name of the project in which meta data of all users is stored. | |
| The name is relative to `gerrit.basePath`. | |
| + | |
| Defaults to `All-Users` if not set. | |
| [[gerrit.canonicalWebUrl]]gerrit.canonicalWebUrl:: | |
| + | |
| The default URL for Gerrit to be accessed through. | |
| + | |
| Typically this would be set to something like "http://review.example.com/" | |
| or "http://example.com:8080/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. | |
| [[gerrit.canonicalGitUrl]]gerrit.canonicalGitUrl:: | |
| + | |
| 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. | |
| [[gerrit.docUrl]]gerrit.docUrl:: | |
| + | |
| Optional base URL for documentation, under which one can find | |
| "index.html", "rest-api.html", etc. Used as the base for the fixed set | |
| of links in the "Documentation" tab. A slash is implicitly appended. | |
| (For finer control over the top menu, consider writing a | |
| link:dev-plugins.html#top-menu-extensions[plugin].) | |
| + | |
| If unset or empty, the documentation tab will only be shown if | |
| `/Documentation/index.html` can be reached by the browser at app load | |
| time. | |
| [[gerrit.editGpgKeys]]gerrit.editGpgKeys:: | |
| + | |
| If enabled and server-side signed push validation is also | |
| link:#receive.enableSignedPush[enabled], enable the | |
| link:rest-api-accounts.html#list-gpg-keys[REST API endpoints] and web UI | |
| for editing GPG keys. If disabled, GPG keys can only be added by | |
| administrators with direct git access to All-Users. | |
| + | |
| Defaults to true. | |
| [[gerrit.installCommitMsgHookCommand]]gerrit.installCommitMsgHookCommand:: | |
| + | |
| Optional command to install the `commit-msg` hook. Typically of the | |
| form: | |
| + | |
| ---- | |
| fetch-cmd some://url/to/commit-msg .git/hooks/commit-msg ; chmod +x .git/hooks/commit-msg | |
| ---- | |
| + | |
| By default unset; falls back to using scp from the canonical SSH host, | |
| or curl from the canonical HTTP URL for the server. Only necessary if a | |
| proxy or other server/network configuration prevents clients from | |
| fetching from the default location. | |
| [[gerrit.gitHttpUrl]]gerrit.gitHttpUrl:: | |
| + | |
| Optional base URL for repositories available over the HTTP | |
| protocol. For example, set this to `http://mirror.example.com/base/` | |
| to have Gerrit display URLs from this server, rather than itself. | |
| + | |
| By default unset, as the HTTP daemon must be configured externally | |
| by the system administrator, and might not even be running on the | |
| same host as Gerrit. | |
| [[gerrit.installDbModule]]gerrit.installDbModule:: | |
| + | |
| Repeatable list of class name of additional Guice modules to load at | |
| Gerrit startup as part of the dbInjector and during the init phases. | |
| Classes are resolved using the primary Gerrit class loader, hence the | |
| class needs to be either declared in Gerrit or an additional JAR | |
| located under the `/lib` directory. | |
| + | |
| By default unset. | |
| [[gerrit.installModule]]gerrit.installModule:: | |
| + | |
| Repeatable list of class name of additional Guice modules to load at | |
| Gerrit startup as part of the sysInjector and during the init phases. | |
| Classes are resolved using the primary Gerrit class loader, hence the | |
| class needs to be either declared in Gerrit or an additional JAR | |
| located under the `/lib` directory. | |
| + | |
| By default unset. | |
| + | |
| Example: | |
| ---- | |
| [gerrit] | |
| installModule = com.googlesource.gerrit.libmodule.MyModule | |
| installModule = com.example.abc.OurSpecialSauceModule | |
| installDbModule = com.example.def.OurCustomProvider | |
| ---- | |
| [[gerrit.listProjectsFromIndex]]gerrit.listProjectsFromIndex:: | |
| + | |
| Enable rendering of project list from the secondary index instead | |
| of purely relying on the in-memory cache. | |
| + | |
| By default false. | |
| + | |
| [NOTE] | |
| The in-memory cache (set to false) rendering provides an **unlimited list** as a result | |
| of the list project API, causing the full list of projects to be | |
| returned as a result of the link:rest-api-projects.html[/projects/] REST API | |
| or the link:cmd-ls-projects.html[gerrit ls-projects] SSH command. | |
| When the rendering from the secondary index (set to true), | |
| the **list is limited** by the global capability | |
| link:access-control.html#capability_queryLimit[queryLimit] | |
| which is defaulted to 500 entries. | |
| [[gerrit.primaryWeblinkName]]gerrit.primaryWeblinkName:: | |
| + | |
| Name of the link:dev-plugins.html#links-to-external-tools[Weblink] that should | |
| be chosen in cases where only one Weblink can be used in the UI, for example in | |
| inline links. | |
| + | |
| By default unset, meaning that the UI is responsible for trying to identify | |
| a weblink to be used in these cases, most likely weblinks that links to code | |
| browsers with known integrations with Gerrit (like Gitiles and Gitweb). | |
| + | |
| Example: | |
| ---- | |
| [gerrit] | |
| primaryWeblinkName = gitiles | |
| ---- | |
| [[gerrit.reportBugUrl]]gerrit.reportBugUrl:: | |
| + | |
| URL to direct users to when they need to report a bug. | |
| + | |
| By default unset, meaning no bug report URL will be displayed. Administrators | |
| should set this to the URL of their issue tracker, if necessary. | |
| [[gerrit.enableReverseDnsLookup]]gerrit.enableReverseDnsLookup:: | |
| + | |
| Enable reverse DNS lookup during computing ref log entry for identified user, | |
| to record the actual hostname of the user's host in the ref log. | |
| + | |
| Enabling reverse DNS lookup can cause performance issues on git push when | |
| the reverse DNS lookup is slow. | |
| + | |
| Defaults to false, reverse DNS lookup is disabled. The user's IP address | |
| will be recorded in the ref log rather than their hostname. | |
| [[gerrit.secureStoreClass]]gerrit.secureStoreClass:: | |
| + | |
| Use the secure store implementation from a specified class. | |
| + | |
| If specified, must be the fully qualified class name of a class that implements | |
| the `com.google.gerrit.server.securestore.SecureStore` interface, and the jar | |
| file containing the class must be placed in the `$site_path/lib` folder. | |
| + | |
| If not specified, the default no-op implementation is used. | |
| [[gerrit.canLoadInIFrame]]gerrit.canLoadInIFrame:: | |
| + | |
| For security reasons Gerrit will always jump out of iframe. | |
| Setting this option to true will prevent this behavior. | |
| + | |
| By default false. | |
| [[gerrit.cdnPath]]gerrit.cdnPath:: | |
| + | |
| Path prefix for PolyGerrit's static resources if using a CDN. | |
| [[gerrit.faviconPath]]gerrit.faviconPath:: | |
| + | |
| Path for PolyGerrit's favicon after link:#gerrit.canonicalWebUrl[default URL], | |
| including icon name and extension (.ico should be used). | |
| [[gerrit.instanceName]]gerrit.instanceName:: | |
| + | |
| Short identifier for this Gerrit instance. | |
| A good name should be short but precise enough so that users can identify the instance among others. | |
| + | |
| Defaults to the full hostname of the Gerrit server. | |
| [[gerrit.serverId]]gerrit.serverId:: | |
| + | |
| Used by NoteDb to, amongst other things, identify author identities from | |
| per-server specific account IDs. | |
| + | |
| If this value is not set on startup it is automatically set to a random UUID. | |
| + | |
| [NOTE] | |
| If this value doesn't match the serverId used when creating an already existing | |
| NoteDb, Gerrit will not be able to use that instance of NoteDb. The serverId | |
| used to create the NoteDb will show in the resulting exception message in case | |
| the value differs. | |
| [[gitweb]] | |
| === Section gitweb | |
| Gerrit can forward requests to either an internally managed gitweb | |
| (which allows Gerrit to enforce some access controls), or to an | |
| externally managed gitweb (where the web server manages access). | |
| See also link:config-gitweb.html[Gitweb Integration]. | |
| [[gitweb.cgi]]gitweb.cgi:: | |
| + | |
| Path to the locally installed `gitweb.cgi` executable. This CGI will | |
| be called by Gerrit Code Review when the URL `/gitweb` is accessed. | |
| Project level access controls are enforced prior to calling the CGI. | |
| + | |
| Defaults to `/usr/lib/cgi-bin/gitweb.cgi` if `gitweb.url` is not set. | |
| [[gitweb.url]]gitweb.url:: | |
| + | |
| 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`. | |
| [[gitweb.type]]gitweb.type:: | |
| + | |
| Optional type of affiliated gitweb service. This allows using | |
| alternatives to gitweb, such as cgit. | |
| + | |
| Valid values are `gitweb`, `cgit`, `disabled` or `custom`. | |
| + | |
| If not set, or set to `disabled`, there is no gitweb hyperlinking | |
| support. | |
| [[gitweb.revision]]gitweb.revision:: | |
| + | |
| Optional pattern to use for constructing the gitweb URL when pointing | |
| at a specific commit when `gitweb.type` is set to `custom`. | |
| + | |
| Valid replacements are `${project}` for the project name in Gerrit | |
| and `${commit}` for the SHA1 hash for the commit. | |
| [[gitweb.project]]gitweb.project:: | |
| + | |
| Optional pattern to use for constructing the gitweb URL when pointing | |
| at a specific project when `gitweb.type` is set to `custom`. | |
| + | |
| Valid replacements are `${project}` for the project name in Gerrit. | |
| [[gitweb.branch]]gitweb.branch:: | |
| + | |
| Optional pattern to use for constructing the gitweb URL when pointing | |
| at a specific branch when `gitweb.type` is set to `custom`. | |
| + | |
| Valid replacements are `${project}` for the project name in Gerrit | |
| and `${branch}` for the name of the branch. | |
| [[gitweb.tag]]gitweb.tag:: | |
| + | |
| Optional pattern to use for constructing the gitweb URL when pointing | |
| at a specific tag when `gitweb.type` is set to `custom`. | |
| + | |
| Valid replacements are `${project}` for the project name in Gerrit | |
| and `${tag}` for the name of the tag. | |
| [[gitweb.roottree]]gitweb.roottree:: | |
| + | |
| Optional pattern to use for constructing the gitweb URL when pointing | |
| at the contents of the root tree in a specific commit when `gitweb.type` | |
| is set to `custom`. | |
| + | |
| Valid replacements are `${project}` for the project name in Gerrit | |
| and `${commit}` for the SHA1 hash for the commit. | |
| [[gitweb.file]]gitweb.file:: | |
| + | |
| Optional pattern to use for constructing the gitweb URL when pointing | |
| at the contents of a file in a specific commit when `gitweb.type` is | |
| set to `custom`. | |
| + | |
| Valid replacements are `${project}` for the project name in Gerrit, | |
| `${file}` for the file name and `${commit}` for the SHA1 hash for | |
| the commit. | |
| [[gitweb.filehistory]]gitweb.filehistory:: | |
| + | |
| Optional pattern to use for constructing the gitweb URL when pointing | |
| at the history of a file in a specific branch when when `gitweb.type` | |
| is set to `custom`. | |
| + | |
| Valid replacements are `${project}` for the project name in Gerrit, | |
| `${file}` for the file name and `${branch}` for the name of the | |
| branch. | |
| [[gitweb.linkname]]gitweb.linkname:: | |
| + | |
| Optional setting for modifying the link name presented to the user | |
| in the Gerrit web-UI. | |
| + | |
| The default linkname for custom type is `gitweb`. | |
| [[gitweb.pathSeparator]]gitweb.pathSeparator:: | |
| + | |
| Optional character to substitute the standard path separator (slash) in | |
| project names and branch names. | |
| + | |
| By default, Gerrit will use hexadecimal encoding for slashes in project and | |
| branch names. Some web servers, such as Tomcat, reject this hexadecimal | |
| encoding in the URL. | |
| + | |
| Some alternative gitweb services, such as link:http://gitblit.com[Gitblit], | |
| allow using an alternative path separator character. In Gitblit, this can be | |
| configured through the property link:http://gitblit.com/properties.html[web.forwardSlashCharacter]. | |
| In Gerrit, the alternative path separator can be configured correspondingly | |
| using the property `gitweb.pathSeparator`. | |
| + | |
| Valid values are the characters `*`, `(` and `)`. | |
| [[gitweb.urlEncode]]gitweb.urlEncode:: | |
| + | |
| Whether or not Gerrit should encode the generated viewer URL. | |
| + | |
| Gerrit composes the viewer URL using information about the project, branch, file | |
| or commit of the target object to be displayed. Typically viewers such as CGit | |
| and gitweb do need those parts to be encoded, including the `/` in project's name, | |
| for being correctly parsed. | |
| However other viewers could instead require an unencoded URL (e.g. GitHub web | |
| based viewer). | |
| + | |
| Valid values are `true` and `false`. The default is `true`. | |
| [[groups]] | |
| === Section groups | |
| [[groups.newGroupsVisibleToAll]]groups.newGroupsVisibleToAll:: | |
| + | |
| Controls whether newly created groups should be by default visible to | |
| all registered users. | |
| + | |
| By default, false. | |
| [[groups.uuid.name]]groups.<uuid>.name:: | |
| + | |
| Display name for group with the given UUID. | |
| + | |
| This option is only supported for system groups (scheme 'global'). | |
| + | |
| E.g. this parameter can be used to configure another name for the | |
| `Anonymous Users` group: | |
| + | |
| ---- | |
| [groups "global:Anonymous-Users"] | |
| name = All Users | |
| ---- | |
| + | |
| When setting this parameter it should be verified that there is no | |
| existing group with the same name (case-insensitive). Configuring an | |
| ambiguous name makes Gerrit fail on startup. Once set Gerrit ensures | |
| that it is not possible to create a group with this name. Gerrit also | |
| keeps the default name reserved so that it cannot be used for new | |
| groups either. This means there is no danger of ambiguous group names | |
| when this parameter is removed and the system group uses the default | |
| name again. | |
| [[http]] | |
| === Section http | |
| [[http.proxy]]http.proxy:: | |
| + | |
| URL of the proxy server when making outgoing HTTP | |
| connections for OpenID login transactions. Syntax | |
| should be `http://`'hostname'`:`'port'. | |
| [[http.proxyUsername]]http.proxyUsername:: | |
| + | |
| Optional username to authenticate to the HTTP proxy with. | |
| This property is honored only if the username does not | |
| appear in the http.proxy property above. | |
| [[http.proxyPassword]]http.proxyPassword:: | |
| + | |
| Optional password to authenticate to the HTTP proxy with. | |
| This property is honored only if the password does not | |
| appear in the http.proxy property above. | |
| [[http.addUserAsRequestAttribute]]http.addUserAsRequestAttribute:: | |
| + | |
| If true, 'User' attribute will be added to the request attributes so it | |
| can be accessed outside the request scope (will be set to username or id | |
| if username not configured). | |
| + | |
| This attribute can be used by the servlet container to log user in the | |
| http access log. | |
| + | |
| When running the embedded servlet container, this attribute is used to | |
| print user in the httpd_log. | |
| + | |
| * `%{User}r` | |
| + | |
| Pattern to print user in Tomcat AccessLog. | |
| + | |
| Default value is true. | |
| [[http.addUserAsResponseHeader]]http.addUserAsResponseHeader:: | |
| + | |
| If true, the header 'User' will be added to the list of response headers so it | |
| can be accessed from a reverse proxy for logging purposes. | |
| + | |
| Default value is false. | |
| [[httpd]] | |
| === Section httpd | |
| The httpd section configures the embedded servlet container. | |
| [[httpd.listenUrl]]httpd.listenUrl:: | |
| + | |
| Configuration for the listening sockets of the internal HTTP daemon. | |
| Each entry of `listenUrl` combines the following options for a | |
| listening socket: protocol, network address, port and context path. | |
| + | |
| _Protocol_ can be either `http://`, `https://`, `proxy-http://` or | |
| `proxy-https://`. The latter two are special forms of `http://` with | |
| awareness of a reverse proxy (see below). _Network address_ selects | |
| the interface and/or scope of the listening socket. For notes | |
| examples, see below. _Port_ is the TCP port number and is optional | |
| (default value depends on the protocol). _Context path_ is the | |
| optional "base URI" for the Gerrit Code Review as application to | |
| serve on. | |
| + | |
| **Protocol** schemes: | |
| + | |
| * `http://` | |
| + | |
| Plain-text HTTP protocol. If port is not supplied, defaults to 80, | |
| the standard HTTP port. | |
| + | |
| * `https://` | |
| + | |
| SSL encrypted HTTP protocol. If port is not supplied, defaults to | |
| 443, the standard HTTPS port. | |
| + | |
| For configuration of the certificate and private key, see | |
| <<httpd.sslKeyStore,httpd.sslKeyStore>>. | |
| + | |
| [NOTE] | |
| SSL/TLS configuration capabilities of Gerrit internal HTTP daemon | |
| are very limited. Externally facing production sites are strongly | |
| encouraged to use a reverse proxy configuration to handle SSL/TLS | |
| and use a `proxy-https://` scheme here (below) for security and | |
| performance reasons. | |
| + | |
| * `proxy-http://` | |
| + | |
| Plain-text HTTP relayed from a reverse proxy. If port is not | |
| supplied, defaults to 8080. | |
| + | |
| Like `http://`, but additional header parsing features are | |
| enabled to honor `X-Forwarded-For`, `X-Forwarded-Host` and | |
| `X-Forwarded-Server`. These headers are typically set by Apache's | |
| link:https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#x-headers[mod_proxy]. | |
| + | |
| [NOTE] | |
| -- | |
| For secruity reasons, make sure to only allow connections from a | |
| trusted reverse proxy in your network, as clients could otherwise | |
| easily spoof these headers and thus spoof their originating IP | |
| address effectively. If the reverse proxy is running on the same | |
| machine as Gerrit daemon, the use of a _loopback_ network address | |
| to bind to (see below) is strongly recommended to mitigate this. | |
| If not using Apache's mod_proxy, validate that your reverse proxy | |
| sets these headers on all requests. If not, either configure it to | |
| sanitize them from the origin, or use the `http://` scheme instead. | |
| -- | |
| + | |
| * `proxy-https://` | |
| + | |
| Plain-text HTTP relayed from a reverse proxy that has already | |
| handled the SSL encryption/decryption. If port is not supplied, | |
| defaults to 8080. | |
| + | |
| Behaves exactly like `proxy-http://`, but also sets the scheme to | |
| assume `https://` is the proper URL back to the server. | |
| + | |
| -- | |
| **Network address** forms: | |
| * Loopback (localhost): `127.0.0.1` (IPv4) or `[::1]` (IPv6). | |
| * All (unspecified): `0.0.0.0` (IPv4), `[::]` (IPv6) or `*` | |
| (IPv4 and IPv6) | |
| * Interface IP address, e.g. `1.2.3.4` (IPv4) or | |
| `[2001:db8::a00:20ff:fea7:ccea]` (IPv6) | |
| * Hostname, resolved at startup time to an address. | |
| **Context path** is the local part of the URL to be used to access | |
| Gerrit on ('base URL'). E.g. `/gerrit/` to serve Gerrit on that URI | |
| as base. If set, consider to align this with the | |
| <<gerrit.canonicalWebUrl,gerrit.canonicalWebUrl>> setting. Correct | |
| settings may depend on the reverse proxy configuration as well. By | |
| default, this is `/` so that Gerrit serves requests on the root. | |
| If multiple values are supplied, the daemon will listen on all | |
| of them. | |
| Examples: | |
| ---- | |
| [httpd] | |
| listenUrl = proxy-https://127.0.0.1:9999/gerrit/ | |
| [gerrit] | |
| # Reverse proxy is configured to serve with SSL/TLS on | |
| # example.com and to relay requests on /gerrit/ onto | |
| # http://127.0.0.1:9999/gerrit/ | |
| canonicalWebUrl = https://example.com/gerrit/ | |
| ---- | |
| ---- | |
| [httpd] | |
| # Listen on specific external interface with plaintext | |
| # HTTP on IPv6. | |
| listenUrl = http://[2001:db8::a00:20ff:fea7:ccea] | |
| # Also listen on specific internal interface for use with | |
| # reverse proxy run on another host. | |
| listenUrl = proxy-https://192.168.100.123 | |
| ---- | |
| See also the page on link:config-reverseproxy.html[reverse proxy] | |
| configuration. | |
| By default, `\http://*:8080`. | |
| -- | |
| [[httpd.reuseAddress]]httpd.reuseAddress:: | |
| + | |
| 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. | |
| [[httpd.gracefulStopTimeout]]httpd.gracefulStopTimeout:: | |
| + | |
| Set a graceful stop time. If set, the daemon ensures that all incoming | |
| calls are preserved for a maximum period of time, before starting | |
| the graceful shutdown process. Sites behind a workload balancer such as | |
| HAProxy would need this to be set for avoiding serving errors during | |
| rolling restarts. | |
| + | |
| Values should use common unit suffixes to express their setting: | |
| + | |
| * s, sec, second, seconds | |
| * m, min, minute, minutes | |
| + | |
| By default, 0 seconds (immediate shutdown). | |
| [[httpd.inheritChannel]]httpd.inheritChannel:: | |
| + | |
| If true, permits the daemon to inherit its server socket channel | |
| from fd0/1(stdin/stdout). When set to true, the server can be socket | |
| activated via systemd or xinetd. | |
| + | |
| By default, false. | |
| [[httpd.requestHeaderSize]]httpd.requestHeaderSize:: | |
| + | |
| Size, in bytes, of the buffer used to parse the HTTP headers of an | |
| incoming HTTP request. The entire request headers, including any | |
| cookies sent by the browser, must fit within this buffer, otherwise | |
| the server aborts with the response '413 Request Entity Too Large'. | |
| + | |
| One buffer of this size is allocated per active connection. | |
| Allocating a buffer that is too large wastes memory that cannot be | |
| reclaimed, allocating a buffer that is too small may cause unexpected | |
| errors caused by very long Referer URLs or large cookie values. | |
| + | |
| By default, 16384 (16 K), which is sufficient for most OpenID and | |
| other web-based single-sign-on integrations. | |
| [[httpd.sslCrl]]httpd.sslCrl:: | |
| + | |
| Path of the certificate revocation list file in PEM format. This | |
| crl file is optional, and available for CLIENT_SSL_CERT_LDAP | |
| authentication. | |
| + | |
| To create and view a crl using openssl: | |
| + | |
| ---- | |
| openssl ca -gencrl -out crl.pem | |
| openssl crl -in crl.pem -text | |
| ---- | |
| + | |
| If not absolute, the path is resolved relative to `$site_path`. | |
| + | |
| By default, `$site_path/etc/crl.pem`. | |
| [[httpd.sslKeyStore]]httpd.sslKeyStore:: | |
| + | |
| Path of the Java keystore containing the server's SSL certificate | |
| and private key. This keystore is required for `https://` in URL. | |
| + | |
| To create a self-signed certificate for simple internal usage: | |
| + | |
| ---- | |
| keytool -keystore keystore -alias jetty -genkey -keyalg RSA | |
| chmod 600 keystore | |
| ---- | |
| + | |
| If not absolute, the path is resolved relative to `$site_path`. | |
| + | |
| By default, `$site_path/etc/keystore`. | |
| [[httpd.sslKeyPassword]]httpd.sslKeyPassword:: | |
| + | |
| Password used to decrypt the private portion of the sslKeyStore. | |
| Java keystores require a password, even if the administrator | |
| doesn't want to enable one. | |
| + | |
| If set to the empty string the embedded server will prompt for the | |
| password during startup. | |
| + | |
| By default, `gerrit`. | |
| [[httpd.requestLog]]httpd.requestLog:: | |
| + | |
| Enable (or disable) the `'$site_path'/logs/httpd_log` request log. | |
| If enabled, an NCSA combined log format request log file is written | |
| out by the internal HTTP daemon. | |
| + | |
| `log4j.appender` with the name `httpd_log` can be configured to overwrite | |
| programmatic configuration. | |
| + | |
| By default, true if httpd.listenUrl uses http:// or https://, | |
| and false if httpd.listenUrl uses proxy-http:// or proxy-https://. | |
| [[httpd.acceptorThreads]]httpd.acceptorThreads:: | |
| + | |
| Number of worker threads dedicated to accepting new incoming TCP | |
| connections and allocating them connection-specific resources. | |
| + | |
| By default, 2, which should be suitable for most high-traffic sites. | |
| [[httpd.minThreads]]httpd.minThreads:: | |
| + | |
| Minimum number of spare threads to keep in the worker thread pool. | |
| This number must be at least 1 larger than httpd.acceptorThreads | |
| multiplied by the number of httpd.listenUrls configured. | |
| + | |
| By default, 5, suitable for most lower-volume traffic sites. | |
| [[httpd.maxThreads]]httpd.maxThreads:: | |
| + | |
| Maximum number of threads to permit in the worker thread pool. | |
| + | |
| By default 25, suitable for most lower-volume traffic sites. | |
| + | |
| [NOTE] | |
| Unless SSH daemon is disabled, see <<sshd.listenAddress, sshd.listenAddress>>, | |
| the max number of concurrent Git requests over HTTP and SSH together is | |
| defined by the <<sshd.threads, sshd.threads>> and | |
| <<sshd.batchThreads, sshd.batchThreads>>. | |
| [[httpd.maxQueued]]httpd.maxQueued:: | |
| + | |
| Maximum number of client connections which can enter the worker | |
| thread pool waiting for a worker thread to become available. | |
| 0 sets the queue size to the Integer.MAX_VALUE. | |
| + | |
| By default 200. | |
| [[httpd.maxWait]]httpd.maxWait:: | |
| + | |
| Maximum amount of time a client will wait for an available | |
| thread to handle a project clone, fetch or push request over the | |
| smart HTTP transport. | |
| + | |
| 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 connections will not | |
| abort until the client disconnects. | |
| By default, 5 minutes. | |
| -- | |
| [[httpd.filterClass]]httpd.filterClass:: | |
| + | |
| Class that implements the javax.servlet.Filter interface | |
| for filtering any HTTP related traffic going through the Gerrit | |
| HTTP protocol. | |
| Class is loaded and configured in the Gerrit Jetty container | |
| and run in front of all Gerrit URL handlers, allowing the filter | |
| to inspect, modify, allow or reject each request. | |
| It needs to be provided as JAR library | |
| under $GERRIT_SITE/lib as it is resolved using the default Gerrit class | |
| loader and cannot be dynamically loaded by a plugin. | |
| + | |
| Failing to load the Filter class would result in a Gerrit start-up | |
| failure, as this class is supposed to provide mandatory filtering | |
| in front of Gerrit HTTP protocol. | |
| + | |
| Typical usage is in conjunction with the `auth.type=HTTP` as replacement | |
| of an Apache HTTP proxy layer as security enforcement on top of Gerrit | |
| by returning a trusted username as HTTP Header. | |
| + | |
| Allow multiple values to install multiple servlet filters. | |
| + | |
| Example of using a security library secure.jar under $GERRIT_SITE/lib | |
| that provides a org.anyorg.MySecureHeaderFilter Servlet Filter that enforces | |
| a trusted username in the `TRUSTED_USER` HTTP Header and | |
| org.anyorg.MySecureIPFilter that performs source IP security filtering: | |
| + | |
| ---- | |
| [auth] | |
| type = HTTP | |
| httpHeader = TRUSTED_USER | |
| [httpd] | |
| filterClass = org.anyorg.MySecureHeaderFilter | |
| filterClass = org.anyorg.MySecureIPFilter | |
| ---- | |
| [[httpd.idleTimeout]]httpd.idleTimeout:: | |
| + | |
| Maximum idle time for a connection, which roughly translates to the | |
| TCP socket `SO_TIMEOUT`. | |
| + | |
| This value is interpreted as the maximum time between some progress | |
| being made on the connection. So if a single byte is read or written, | |
| then the timeout is reset. | |
| + | |
| The max idle time is applied: | |
| + | |
| * When waiting for a new message to be received on a connection | |
| * When waiting for a new message to be sent on a connection | |
| + | |
| By default, 30 seconds. | |
| [[httpd.robotsFile]]httpd.robotsFile:: | |
| + | |
| Location of an external robots.txt file to be used instead of the one | |
| bundled with the .war of the application. | |
| + | |
| If not absolute, the path is resolved relative to `$site_path`. | |
| + | |
| If the file doesn't exist or can't be read the default robots.txt file | |
| bundled with the .war will be used instead. | |
| [[httpd.registerMBeans]]httpd.registerMBeans:: | |
| + | |
| Enable (or disable) registration of Jetty MBeans for Java JMX. | |
| + | |
| By default, false. | |
| [[index]] | |
| === Section index | |
| The index section configures the secondary index. | |
| Note that after enabling the secondary index, the index must be built | |
| using the link:pgm-reindex.html[reindex program] before restarting the | |
| Gerrit server. | |
| [[index.type]]index.type:: | |
| + | |
| Type of secondary indexing employed by Gerrit. The supported | |
| values are: | |
| + | |
| * `LUCENE` | |
| + | |
| A link:http://lucene.apache.org/[Lucene] index is used. | |
| + | |
| + | |
| * `ELASTICSEARCH` look into link:#elasticsearch[Elasticsearch section] | |
| + | |
| An link:https://www.elastic.co/products/elasticsearch[Elasticsearch] index is | |
| used. Refer to the link:#elasticsearch[Elasticsearch section] for further | |
| configuration details. | |
| + | |
| By default, `LUCENE`. | |
| [[index.threads]]index.threads:: | |
| + | |
| Number of threads to use for indexing in normal interactive operations. Setting | |
| it to 0 disables the dedicated thread pool and indexing will be done in the same | |
| thread as the operation. | |
| + | |
| If not set or set to a zero, defaults to the number of logical CPUs as returned | |
| by the JVM. If set to a negative value, defaults to a direct executor. | |
| [[index.batchThreads]]index.batchThreads:: | |
| + | |
| Number of threads to use for indexing in background operations, such as | |
| online schema upgrades. | |
| + | |
| If not set or set to a zero, defaults to the number of logical CPUs as returned | |
| by the JVM. If set to a negative value, defaults to a direct executor. | |
| [[index.onlineUpgrade]]index.onlineUpgrade:: | |
| + | |
| Whether to upgrade to new index schema versions while the server is | |
| running. This is recommended as it prevents additional downtime during | |
| Gerrit version upgrades (avoiding the need for an offline reindex step | |
| using Reindex), but can add additional server load during the upgrade. | |
| + | |
| If set to false, there is no way to upgrade the index schema to take | |
| advantage of new search features without restarting the server. | |
| + | |
| Defaults to true. | |
| [[index.maxLimit]]index.maxLimit:: | |
| + | |
| Maximum limit to allow for search queries. Requesting results above this | |
| limit will truncate the list (but will still set `_more_changes` on | |
| result lists). Set to 0 for no limit. | |
| + | |
| When `index.type` is set to `ELASTICSEARCH`, this value should not exceed | |
| the `index.max_result_window` value configured on the Elasticsearch | |
| server. If a value is not configured during site initialization, defaults to | |
| 10000, which is the default value of `index.max_result_window` in Elasticsearch. | |
| + | |
| When `index.type` is set to `LUCENE`, defaults to no limit. | |
| [[index.maxPages]]index.maxPages:: | |
| + | |
| Maximum number of pages of search results to allow, as index | |
| implementations may have to scan through large numbers of skipped | |
| results when searching with an offset. Requesting results starting past | |
| this threshold times the requested limit will result in an error. Set to | |
| 0 for no limit. | |
| + | |
| Defaults to no limit. | |
| [[index.maxTerms]]index.maxTerms:: | |
| + | |
| Maximum number of leaf terms to allow in a query. Too-large queries may | |
| perform poorly, so setting this option causes query parsing to fail fast | |
| before attempting to send them to the secondary index. | |
| + | |
| When the index type is `LUCENE`, also sets the maximum number of clauses | |
| permitted per BooleanQuery. This is so that all enforced query limits | |
| are the same. | |
| + | |
| Defaults to 1024. | |
| [[index.reindexAfterRefUpdate]]index.reindexAfterRefUpdate:: | |
| + | |
| Whether to reindex all affected open changes after a ref is updated. This | |
| includes reindexing all open changes to recompute the "mergeable" bit every time | |
| the destination branch moves, as well as reindexing changes to take into account | |
| new project configuration (e.g. label definitions). | |
| + | |
| Leaving this enabled may result in fresher results, but may cause performance | |
| problems if there are lots of open changes on a project whose branches advance | |
| frequently. | |
| + | |
| Defaults to true. | |
| [[index.autoReindexIfStale]]index.autoReindexIfStale:: | |
| + | |
| Whether to automatically check if a document became stale in the index | |
| immediately after indexing it. If false, there is a race condition during two | |
| simultaneous writes that may cause one of the writes to not be reflected in the | |
| index. The check to avoid this does consume some resources. | |
| + | |
| Defaults to false. | |
| [[index.scheduledIndexer]] | |
| ==== Subsection index.scheduledIndexer | |
| This section configures periodic indexing. Periodic indexing is | |
| intended to run only on replicas and only updates the group index. | |
| Replication to replicas happens on Git level so that Gerrit is not aware | |
| of incoming replication events. But replicas need an updated group index | |
| to resolve memberships of users for ACL validation. To keep the group | |
| index in replicas up-to-date the Gerrit replica periodically scans the | |
| group refs in the All-Users repository to reindex groups if they are | |
| stale. | |
| The scheduled reindexer is not able to detect group deletions that | |
| happened while the replica was offline, but since group deletions are not | |
| supported this should never happen. If nevertheless groups refs were | |
| deleted while a replica was offline a full offline link:pgm-reindex.html[ | |
| reindex] must be performed. | |
| This section is only used if Gerrit runs in replica mode, otherwise it is | |
| ignored. | |
| [[index.scheduledIndexer.runOnStartup]]index.scheduledIndexer.runOnStartup:: | |
| + | |
| Whether the scheduled indexer should run once immediately on startup. | |
| If set to `true` the replica startup is blocked until all stale groups | |
| were reindexed. Enabling this allows to prevent that replicas that were | |
| offline for a longer period of time run with outdated group information | |
| until the first scheduled indexing is done. | |
| + | |
| Defaults to `true`. | |
| [[index.scheduledIndexer.enabled]]index.scheduledIndexer.enabled:: | |
| + | |
| Whether the scheduled indexer is enabled. If the scheduled indexer is | |
| disabled you must implement other means to keep the group index for the | |
| replica up-to-date (e.g. by using ElasticSearch for the indexes). | |
| + | |
| Defaults to `true`. | |
| [[index.scheduledIndexer.startTime]]index.scheduledIndexer.startTime:: | |
| + | |
| The link:#schedule-configuration-startTime[start time] for running | |
| the scheduled indexer. | |
| + | |
| Defaults to `00:00`. | |
| [[index.scheduledIndexer.interval]]index.scheduledIndexer.interval:: | |
| + | |
| The link:#schedule-configuration-interval[interval] for running | |
| the scheduled indexer. | |
| + | |
| Defaults to `5m`. | |
| link:#schedule-configuration-examples[Schedule examples] can be found | |
| in the link:#schedule-configuration[Schedule Configuration] section. | |
| ==== Lucene configuration | |
| Open and closed changes are indexed in separate indexes named | |
| 'open' and 'closed' respectively. | |
| The following settings are only used when the index type is `LUCENE`. | |
| [[index.name.ramBufferSize]]index.name.ramBufferSize:: | |
| + | |
| Determines the amount of RAM that may be used for buffering added documents | |
| and deletions before they are flushed to the index. See the | |
| link:http://lucene.apache.org/core/4_6_0/core/org/apache/lucene/index/LiveIndexWriterConfig.html#setRAMBufferSizeMB(double)[ | |
| Lucene documentation] for further details. | |
| + | |
| Defaults to 16M. | |
| [[index.name.maxBufferedDocs]]index.name.maxBufferedDocs:: | |
| + | |
| Determines the minimal number of documents required before the buffered | |
| in-memory documents are flushed to the index. Large values generally | |
| give faster indexing. See the | |
| link:http://lucene.apache.org/core/4_6_0/core/org/apache/lucene/index/LiveIndexWriterConfig.html#setMaxBufferedDocs(int)[ | |
| Lucene documentation] for further details. | |
| + | |
| Defaults to -1, meaning no maximum is set and the writer will flush | |
| according to RAM usage. | |
| [[index.name.commitWithin]]index.name.commitWithin:: | |
| + | |
| Determines the period at which changes are automatically committed to | |
| stable store on disk. This is a costly operation and may block | |
| additional index writes, so lower with caution. | |
| + | |
| If zero, changes are committed after every write. This is very costly | |
| but may be useful if offline reindexing is infeasible, or for development | |
| servers. | |
| + | |
| Values can be specified using standard time unit abbreviations (`ms`, `sec`, | |
| `min`, etc.). | |
| + | |
| If negative, `commitWithin` is disabled. Changes are flushed to disk when | |
| the in-memory buffer fills, but only committed and guaranteed to be synced | |
| to disk when the process finishes. | |
| + | |
| Defaults to 300000 ms (5 minutes). | |
| [[index.name.maxMergeCount]]index.name.maxMergeCount:: | |
| + | |
| Determines the max number of simultaneous merges that are allowed. If a merge | |
| is necessary yet we already have this many threads running, the incoming thread | |
| (that is calling add/updateDocument) will block until a merge thread has | |
| completed. Note that Lucene will only run the smallest maxThreadCount merges | |
| at a time. See the | |
| link:https://lucene.apache.org/core/5_5_0/core/org/apache/lucene/index/ConcurrentMergeScheduler.html#setDefaultMaxMergesAndThreads(boolean)[ | |
| Lucene documentation] for further details. | |
| + | |
| Defaults to -1 for (auto detection). | |
| [[index.name.maxThreadCount]]index.name.maxThreadCount:: | |
| + | |
| Determines the max number of simultaneous Lucene merge threads that should be running at | |
| once. This must be less than or equal to maxMergeCount. See the | |
| link:https://lucene.apache.org/core/5_5_0/core/org/apache/lucene/index/ConcurrentMergeScheduler.html#setDefaultMaxMergesAndThreads(boolean)[ | |
| Lucene documentation] for further details. | |
| + | |
| For further details on Lucene index configuration (auto detection) which | |
| affects maxThreadCount and maxMergeCount settings. | |
| See the | |
| link:https://lucene.apache.org/core/5_5_0/core/org/apache/lucene/index/ConcurrentMergeScheduler.html#AUTO_DETECT_MERGES_AND_THREADS[ | |
| Lucene documentation] | |
| + | |
| Defaults to -1 for (auto detection). | |
| [[index.name.enableAutoIOThrottle]]index.name.enableAutoIOThrottle:: | |
| + | |
| Allows the control of whether automatic IO throttling is enabled and used by | |
| default in the lucene merge queue. Automatic dynamic IO throttling, which when | |
| on is used to adaptively rate limit writes bytes/sec to the minimal rate necessary | |
| so merges do not fall behind. See the | |
| link:https://lucene.apache.org/core/5_5_0/core/org/apache/lucene/index/ConcurrentMergeScheduler.html#enableAutoIOThrottle()[ | |
| Lucene documentation] for further details. | |
| + | |
| Defaults to true (throttling enabled). | |
| Sample Lucene index configuration: | |
| ---- | |
| [index] | |
| type = LUCENE | |
| [index "changes_open"] | |
| ramBufferSize = 60 m | |
| maxBufferedDocs = 3000 | |
| maxThreadCount = 5 | |
| maxMergeCount = 50 | |
| [index "changes_closed"] | |
| ramBufferSize = 20 m | |
| maxBufferedDocs = 500 | |
| maxThreadCount = 10 | |
| maxMergeCount = 100 | |
| enableIOThrottle = false | |
| ---- | |
| [[elasticsearch]] | |
| === Section elasticsearch | |
| WARNING: Support for Elasticsearch is still experimental and is not recommended | |
| for production use. For compatibility information, please refer to the | |
| link:https://www.gerritcodereview.com/elasticsearch.html[project homepage]. | |
| When using Elasticsearch version 5.6, the open and closed changes are | |
| indexed in a single index, separated into types `open_changes` and `closed_changes` | |
| respectively. When using version 6.2 or later, the open and closed changes are | |
| merged into the default `_doc` type. The latter is also used for the accounts and | |
| groups indices starting with Elasticsearch 6.2. | |
| Note that when Gerrit is configured to use Elasticsearch, the Elasticsearch | |
| server(s) must be reachable during the site initialization. | |
| [[elasticsearch.prefix]]elasticsearch.prefix:: | |
| + | |
| This setting can be used to prefix index names to allow multiple Gerrit | |
| instances in a single Elasticsearch cluster. Prefix `gerrit1_` would result in a | |
| change index named `gerrit1_changes_0001`. | |
| + | |
| Not set by default. | |
| [[elasticsearch.server]]elasticsearch.server:: | |
| + | |
| Elasticsearch server URI in the form `http[s]://hostname:port`. The `port` is | |
| optional and defaults to `9200` if not specified. | |
| + | |
| At least one server must be specified. May be specified multiple times to | |
| configure multiple Elasticsearch servers. | |
| + | |
| Note that the site initialization program only allows to configure a single | |
| server. To configure multiple servers the `gerrit.config` file must be edited | |
| manually. | |
| [[elasticsearch.numberOfShards]]elasticsearch.numberOfShards:: | |
| + | |
| Sets the number of shards to use per index. Refer to the | |
| link:https://www.elastic.co/guide/en/elasticsearch/reference/current/getting-started-concepts.html#getting-started-shards-and-replicas[ | |
| Elasticsearch documentation] for details. | |
| + | |
| Defaults to 5 for Elasticsearch versions 5 and 6, and to 1 starting with Elasticsearch 7. | |
| [[elasticsearch.numberOfReplicas]]elasticsearch.numberOfReplicas:: | |
| + | |
| Sets the number of replicas to use per index. Refer to the | |
| link:https://www.elastic.co/guide/en/elasticsearch/reference/current/getting-started-concepts.html#getting-started-shards-and-replicas[ | |
| Elasticsearch documentation] for details. | |
| + | |
| Defaults to 1. | |
| ==== Elasticsearch Security | |
| When security is enabled in Elasticsearch, the username and password must be provided. | |
| Note that the same username and password are used for all servers. | |
| For further information about Elasticsearch security, please refer to the documentation: | |
| * link:https://www.elastic.co/guide/en/x-pack/5.6/security-getting-started.html[Elasticsearch 5.6] | |
| * link:https://www.elastic.co/guide/en/x-pack/6.2/security-getting-started.html[Elasticsearch 6.2] | |
| * link:https://www.elastic.co/guide/en/elastic-stack-overview/6.3/security-getting-started.html[Elasticsearch 6.3] | |
| * link:https://www.elastic.co/guide/en/elastic-stack-overview/6.4/security-getting-started.html[Elasticsearch 6.4] | |
| * link:https://www.elastic.co/guide/en/elastic-stack-overview/6.5/security-getting-started.html[Elasticsearch 6.5] | |
| * link:https://www.elastic.co/guide/en/elastic-stack-overview/6.6/security-getting-started.html[Elasticsearch 6.6] | |
| [[elasticsearch.username]]elasticsearch.username:: | |
| + | |
| Username used to connect to Elasticsearch. | |
| + | |
| If a password is set, defaults to `elastic`, otherwise not set by default. | |
| [[elasticsearch.password]]elasticsearch.password:: | |
| + | |
| Password used to connect to Elasticsearch. | |
| + | |
| Not set by default. | |
| [[event]] | |
| === Section event | |
| [[event.payload.listChangeOptions]]events.payload.listChangeOptions:: | |
| + | |
| List of options that Gerrit applies when rendering the payload of an | |
| internal event. This is the same set of options that are documented | |
| link:rest-api-changes.html#query-options[here]. | |
| + | |
| Depending on the setup, these events might get serialized using stream | |
| events. | |
| + | |
| This can be set to the set of minimal options that consumers of Gerrit's | |
| events need. A minimal set would be (`SKIP_MERGEABLE`,`SKIP_DIFFSTAT`). | |
| + | |
| Every option that gets added here will have a performance impact. The | |
| general recommendation is therefore to set this to a minimal set of | |
| required options. | |
| + | |
| Defaults to all available options minus `CHANGE_ACTIONS`, | |
| `CURRENT_ACTIONS` and `CHECK`. This is a rich default to make sure the | |
| config is backwards compatible with what the default was before the config | |
| was added. | |
| [[ldap]] | |
| === Section ldap | |
| LDAP integration is only enabled if `auth.type` is set to | |
| `HTTP_LDAP`, `LDAP` or `CLIENT_SSL_CERT_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 | |
| link:http://www.ietf.org/rfc/rfc2307.txt[RFC 2307], Active | |
| Directory and link:https://www.freeipa.org[FreeIPA]. | |
| ---- | |
| [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})) | |
| ---- | |
| [[ldap.guessRelevantGroups]]ldap.guessRelevantGroups:: | |
| + | |
| Filter the groups found in LDAP by guessing the ones relevant to | |
| Gerrit and removing the others from list completions and ACL evaluations. | |
| The guess is based on two elements: the projects most recently | |
| accessed in the cache and the list of LDAP groups included in their ACLs. | |
| + | |
| Please note that projects rarely used and thus not cached may be | |
| temporarily inaccessible by users even with LDAP membership and grants | |
| referenced in the ACLs. | |
| + | |
| By default, true. | |
| [[ldap.server]]ldap.server:: | |
| + | |
| 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. | |
| [[ldap.startTls]]ldap.startTls:: | |
| + | |
| If true, Gerrit will perform StartTLS extended operation. | |
| + | |
| By default, false, StartTLS will not be enabled. | |
| [[ldap.supportAnonymous]]ldap.supportAnonymous:: | |
| + | |
| If false, Gerrit will provide credentials only at connection open, this is | |
| required for some `LDAP` implementations that do not allow anonymous bind | |
| for StartTLS or for reauthentication. | |
| + | |
| By default, true. | |
| [[ldap.sslVerify]]ldap.sslVerify:: | |
| + | |
| If false and ldap.server is an `ldaps://` style URL or `ldap.startTls` | |
| is true, Gerrit will not verify the server certificate when it connects | |
| to perform a query. | |
| + | |
| By default, true, requiring the certificate to be verified. | |
| [[ldap.groupsVisibleToAll]]ldap.groupsVisibleToAll:: | |
| + | |
| If true, LDAP groups are visible to all registered users. | |
| + | |
| By default, false, LDAP groups are visible only to administrators and | |
| group members. | |
| [[ldap.username]]ldap.username:: | |
| + | |
| _(Optional)_ Username to bind to the LDAP server with. If not set, | |
| an anonymous connection to the LDAP server is attempted. | |
| [[ldap.password]]ldap.password:: | |
| + | |
| _(Optional)_ Password for the user identified by `ldap.username`. | |
| If not set, an anonymous (or passwordless) connection to the LDAP | |
| server is attempted. | |
| [[ldap.referral]]ldap.referral:: | |
| + | |
| _(Optional)_ How an LDAP referral should be handled if it is | |
| encountered during directory traversal. Set to `follow` to | |
| automatically follow any referrals, or `ignore` to ignore the | |
| referrals. | |
| + | |
| By default, `ignore`. | |
| [[ldap.readTimeout]]ldap.readTimeout:: | |
| + | |
| _(Optional)_ The read timeout for an LDAP operation. The value is | |
| in the usual time-unit format like "1 s", "100 ms", etc... | |
| A timeout can be used to avoid blocking all of the SSH command start | |
| threads in case the LDAP server becomes slow. | |
| + | |
| By default there is no timeout and Gerrit will wait for the LDAP | |
| server to respond until the TCP connection times out. | |
| [[ldap.accountBase]]ldap.accountBase:: | |
| + | |
| Root of the tree containing all user accounts. This is typically | |
| of the form `ou=people,dc=example,dc=com`. | |
| + | |
| This setting may be added multiple times to specify more than | |
| one root. | |
| [[ldap.accountScope]]ldap.accountScope:: | |
| + | |
| 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. | |
| [[ldap.accountPattern]]ldap.accountPattern:: | |
| + | |
| 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 FreeIPA and RFC 2307 servers, | |
| and `(&(objectClass=user)(sAMAccountName=${username}))` | |
| for Active Directory. | |
| [[ldap.accountFullName]]ldap.accountFullName:: | |
| + | |
| _(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 FreeIPA and RFC 2307 servers, | |
| and `${givenName} ${sn}` for Active Directory. | |
| [[ldap.accountEmailAddress]]ldap.accountEmailAddress:: | |
| + | |
| _(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 addresses, | |
| and select a different preferred email address. | |
| + | |
| Default is `mail`. | |
| [[ldap.accountSshUserName]]ldap.accountSshUserName:: | |
| + | |
| _(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. Note that once the | |
| username has been set it cannot be changed, therefore it is | |
| recommended not to make changes to this setting that would cause the | |
| value to differ, as this will prevent users from logging in. | |
| + | |
| Default is `uid` for FreeIPA and RFC 2307 servers, | |
| and `${sAMAccountName.toLowerCase}` for Active Directory. | |
| [[ldap.accountMemberField]]ldap.accountMemberField:: | |
| + | |
| _(Optional)_ Name of an attribute on the user account object which | |
| contains the groups the user is part of. Typically used for Active | |
| Directory and FreeIPA servers. | |
| + | |
| Default is unset for RFC 2307 servers (disabled) | |
| and `memberOf` for Active Directory and FreeIPA. | |
| [[ldap.accountMemberExpandGroups]]ldap.accountMemberExpandGroups:: | |
| + | |
| _(Optional)_ Whether to expand nested groups recursively. This | |
| setting is used only if `ldap.accountMemberField` is set. | |
| + | |
| Default is unset for FreeIPA and `true` for RFC 2307 servers | |
| and Active Directory. | |
| [[ldap.fetchMemberOfEagerly]]ldap.fetchMemberOfEagerly:: | |
| + | |
| _(Optional)_ Whether to fetch the `memberOf` account attribute on | |
| login. Setups which use LDAP for user authentication but don't make | |
| use of the LDAP groups may benefit from setting this option to `false` | |
| as this will result in a much faster LDAP login. | |
| + | |
| Default is unset for RFC 2307 servers (disabled) and `true` for | |
| Active Directory and FreeIPA. | |
| [[ldap.groupBase]]ldap.groupBase:: | |
| + | |
| Root of the tree containing all group objects. This is typically | |
| of the form `ou=groups,dc=example,dc=com`. | |
| + | |
| This setting may be added multiple times to specify more than | |
| one root. | |
| [[ldap.groupScope]]ldap.groupScope:: | |
| + | |
| 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. | |
| [[ldap.groupPattern]]ldap.groupPattern:: | |
| + | |
| 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 FreeIPA and RFC 2307 servers, | |
| and `(&(objectClass=group)(cn=${groupname}))` for Active Directory. | |
| [[ldap.groupMemberPattern]]ldap.groupMemberPattern:: | |
| + | |
| 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})(gidNumber=${gidNumber}))` for | |
| RFC 2307, and unset (disabled) for Active Directory and FreeIPA. | |
| [[ldap.groupName]]ldap.groupName:: | |
| + | |
| _(Optional)_ Name of the attribute on the group object which contains | |
| the value to use as the group name in Gerrit. | |
| + | |
| Typically the attribute name is `cn` for RFC 2307 and Active Directory | |
| servers. For other servers the attribute name may differ, for example | |
| `apple-group-realname` on Apple MacOS X Server. | |
| + | |
| It is also possible to specify a literal string containing a pattern of | |
| attribute values. For example to create a Gerrit group name consisting of | |
| LDAP group name and group ID, use the pattern `${cn} (${gidNumber})`. | |
| + | |
| Default is `cn`. | |
| [[ldap.mandatoryGroup]]ldap.mandatoryGroup:: | |
| + | |
| All users must be a member of this group to allow account creation or | |
| authentication. | |
| + | |
| Setting mandatoryGroup implies enabling of `ldap.fetchMemberOfEagerly` | |
| + | |
| By default, unset. | |
| [[ldap.localUsernameToLowerCase]]ldap.localUsernameToLowerCase:: | |
| + | |
| Converts the local username, that is used to login into the Gerrit | |
| Web UI, to lower case before doing the LDAP authentication. By setting | |
| this parameter to true, a case insensitive login to the Gerrit Web UI | |
| can be achieved. | |
| + | |
| If set, it must be ensured that the local usernames for all existing | |
| accounts are converted to lower case, otherwise a user that has a | |
| local username that contains upper case characters will not be able to login | |
| anymore. The local usernames for the existing accounts can be | |
| converted to lower case by running the server program | |
| link:pgm-LocalUsernamesToLowerCase.html[LocalUsernamesToLowerCase]. | |
| Please be aware that the conversion of the local usernames to lower | |
| case can't be undone. For newly created accounts the local username | |
| will be directly stored in lower case. | |
| + | |
| By default, unset/false. | |
| [[ldap.authentication]]ldap.authentication:: | |
| + | |
| Defines how Gerrit authenticates with the server. When set to `GSSAPI` | |
| Gerrit will use Kerberos. To use kerberos the | |
| `java.security.auth.login.config` system property must point to a | |
| login to a JAAS configuration file and, if Java 6 is used, the system | |
| property `java.security.krb5.conf` must point to the appropriate | |
| krb5.ini file with references to the KDC. | |
| Typical jaas.conf. | |
| ---- | |
| KerberosLogin { | |
| com.sun.security.auth.module.Krb5LoginModule | |
| required | |
| useTicketCache=true | |
| doNotPrompt=true | |
| renewTGT=true; | |
| }; | |
| ---- | |
| See Java documentation on how to create the krb5.ini file. | |
| Note the `renewTGT` property to make sure the TGT does not expire, | |
| and `useTicketCache` to use the TGT supplied by the operating system. As | |
| the whole point of using GSSAPI is to have passwordless authentication | |
| to the LDAP service, this option does not acquire a new TGT on its own. | |
| On Windows servers the registry key `HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\Parameters` | |
| must have the DWORD value `allowtgtsessionkey` set to 1 and the account must not | |
| have local administrator privileges. | |
| [[ldap.useConnectionPooling]]ldap.useConnectionPooling:: | |
| + | |
| _(Optional)_ Enable the LDAP connection pooling or not. | |
| + | |
| If it is true, the LDAP service provider maintains a pool of (possibly) | |
| previously used connections and assigns them to a Context instance as | |
| needed. When a Context instance is done with a connection (closed or | |
| garbage collected), the connection is returned to the pool for future use. | |
| + | |
| For details, see link:http://docs.oracle.com/javase/tutorial/jndi/ldap/pool.html[ | |
| LDAP connection management (Pool)] and link:http://docs.oracle.com/javase/tutorial/jndi/ldap/config.html[ | |
| LDAP connection management (Configuration)] | |
| + | |
| By default, false. | |
| [[ldap.connectTimeout]]ldap.connectTimeout:: | |
| + | |
| _(Optional)_ Timeout period for establishment of an LDAP connection. | |
| + | |
| The value is in the usual time-unit format like "1 s", "100 ms", | |
| etc... | |
| + | |
| By default there is no timeout and Gerrit will wait indefinitely. | |
| [[ldap-connection-pooling]] | |
| ==== LDAP Connection Pooling | |
| Once LDAP connection pooling is enabled by setting the link:#ldap.useConnectionPooling[ | |
| ldap.useConnectionPooling] configuration property to `true`, the connection pool | |
| can be configured using JVM system properties as explained in the | |
| link:http://docs.oracle.com/javase/7/docs/technotes/guides/jndi/jndi-ldap.html#POOL[ | |
| Java SE Documentation]. | |
| For standalone Gerrit (running with the embedded Jetty), JVM system properties | |
| are specified in the link:#container[container section]: | |
| ---- | |
| javaOptions = -Dcom.sun.jndi.ldap.connect.pool.maxsize=20 | |
| javaOptions = -Dcom.sun.jndi.ldap.connect.pool.prefsize=10 | |
| javaOptions = -Dcom.sun.jndi.ldap.connect.pool.timeout=300000 | |
| ---- | |
| [[lfs]] | |
| === Section lfs | |
| [[lfs.plugin]]lfs.plugin:: | |
| + | |
| The name of a plugin which serves the | |
| link:https://github.com/github/git-lfs/blob/master/docs/api/v1/http-v1-batch.md[ | |
| LFS protocol] on the `<project-name>/info/lfs/objects/batch` endpoint. When | |
| not configured Gerrit will respond with `501 Not Implemented` on LFS protocol | |
| requests. | |
| + | |
| By default unset. | |
| [[log]] | |
| === Section log | |
| [[log.jsonLogging]]log.jsonLogging:: | |
| + | |
| If set to true, enables error logging in JSON format (file name: "logs/error_log.json"). | |
| + | |
| Defaults to false. | |
| [[log.textLogging]]log.textLogging:: | |
| + | |
| If set to true, enables error logging in regular plain text format. Can only be disabled | |
| if `jsonLogging` is enabled. | |
| + | |
| Defaults to true. | |
| [[log.compress]]log.compress:: | |
| + | |
| If set to true, log files are compressed at server startup and then daily at 11pm | |
| (in the server's local time zone). | |
| + | |
| Defaults to true. | |
| [[log.rotate]]log.rotate:: | |
| + | |
| If set to true, log files are rotated daily at midnight (GMT). | |
| + | |
| Defaults to true. | |
| [[mimetype]] | |
| === Section mimetype | |
| [[mimetype.name.safe]]mimetype.<name>.safe:: | |
| + | |
| 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 | |
| ---- | |
| [[note-db]] | |
| === Section noteDb | |
| NoteDb is the Git-based database storage backend for Gerrit. For more | |
| information, including how to migrate data from an older Gerrit version, see the | |
| link:note-db.html[documentation]. | |
| [[notedb.accounts.sequenceBatchSize]]notedb.accounts.sequenceBatchSize:: | |
| + | |
| The next available account sequence number is stored as UTF-8 text in a | |
| blob pointed to by the `refs/sequences/accounts` ref in the `All-Users` | |
| repository. Multiple processes share the same sequence by incrementing | |
| the counter using normal git ref updates. To amortize the cost of these | |
| ref updates, processes increment the counter by a larger number and | |
| hand out numbers from that range in memory until they run out. This | |
| configuration parameter controls the size of the account ID batch that | |
| each process retrieves at once. | |
| + | |
| By default, 1. | |
| [[oauth]] | |
| === Section oauth | |
| OAuth integration is only enabled if `auth.type` is set to `OAUTH`. See | |
| link:#auth.type[above] for a detailed description of the `auth.type` settings | |
| and their implications. | |
| By default, contact information, like the full name and email address, | |
| is retrieved from the selected OAuth provider when a user account is created, | |
| or when a user requests to reload that information in the settings UI. If | |
| that is not supported by the OAuth provider, users can be allowed to edit | |
| their contact information manually. | |
| [[oauth.allowEditFullName]]oauth.allowEditFullName:: | |
| + | |
| If true, the full name can be edited in the contact information. | |
| + | |
| Default is false. | |
| [[oauth.allowRegisterNewEmail]]oauth.allowRegisterNewEmail:: | |
| + | |
| If true, additional email addresses can be registered in the contact | |
| information. | |
| + | |
| Default is false. | |
| [[pack]] | |
| === Section pack | |
| Global settings controlling how Gerrit Code Review creates pack | |
| streams for Git clients running clone, fetch, or pull. Most of these | |
| variables are per-client request, and thus should be carefully set | |
| given the expected concurrent request load and available CPU and | |
| memory resources. | |
| [[pack.deltacompression]]pack.deltacompression:: | |
| + | |
| If true, delta compression between objects is enabled. This may | |
| result in a smaller overall transfer for the client, but requires | |
| more server memory and CPU time. | |
| + | |
| False (off) by default, matching Gerrit Code Review 2.1.4. | |
| [[pack.threads]]pack.threads:: | |
| + | |
| Maximum number of threads to use for delta compression (if enabled). | |
| This is per-client request. If set to 0 then the number of CPUs is | |
| auto-detected and one thread per CPU is used, per client request. | |
| + | |
| By default, 1. | |
| [[plugins]] | |
| === Section plugins | |
| [[plugins.checkFrequency]]plugins.checkFrequency:: | |
| + | |
| How often plugins should be examined for new plugins to load, removed | |
| plugins to be unloaded, or updated plugins to be reloaded. Values can | |
| be specified using standard time unit abbreviations ('ms', 'sec', | |
| 'min', etc.). | |
| + | |
| If set to 0, automatic plugin reloading is disabled. Administrators | |
| may force reloading with link:cmd-plugin-reload.html[gerrit plugin reload]. | |
| + | |
| Default is 1 minute. | |
| [[plugins.allowRemoteAdmin]]plugins.allowRemoteAdmin:: | |
| + | |
| Enable remote installation, enable and disable of plugins over HTTP | |
| and SSH. If set to true Administrators can install new plugins | |
| remotely, or disable existing plugins. Defaults to false. | |
| [[plugins.mandatory]]plugins.mandatory:: | |
| + | |
| List of mandatory plugins. If a plugin from this list does not load, | |
| Gerrit will fail to start. | |
| + | |
| Disabling and restarting of a mandatory plugin is rejected, but reloading | |
| of a mandatory plugin is still possible. | |
| [[plugins.jsLoadTimeout]]plugins.jsLoadTimeout:: | |
| + | |
| Set the timeout value for loading JavaScript plugins in Gerrit UI. | |
| Values can be specified using standard time unit abbreviations ('ms', | |
| 'sec', 'min', etc.). | |
| + | |
| Default is 5 seconds. Negative values will be converted to 0. | |
| [[receive]] | |
| === Section receive | |
| This section is used to configure behavior of the 'receive-pack' | |
| handler, which responds to 'git push' requests. | |
| [[receive.allowGroup]]receive.allowGroup:: | |
| + | |
| Name of the groups of users that are allowed to execute | |
| 'receive-pack' on the server. One or more groups can be set. | |
| + | |
| If no groups are added, any user will be allowed to execute | |
| 'receive-pack' on the server. | |
| [[receive.certNonceSeed]]receive.certNonceSeed:: | |
| + | |
| If set to a non-empty value and server-side signed push validation is | |
| link:#receive.enableSignedPush[enabled], use this value as the seed to | |
| the HMAC SHA-1 nonce generator. If unset, a 64-byte random seed will be | |
| generated at server startup. | |
| + | |
| As this is used as the seed of a cryptographic algorithm, it is | |
| recommended to be placed in link:#secure-config[`secure.config`]. | |
| + | |
| Defaults to unset. | |
| [[receive.certNonceSlop]]receive.certNonceSlop:: | |
| + | |
| When validating the nonce passed as part of the signed push protocol, | |
| accept valid nonces up to this many seconds old. This allows | |
| certificate verification to work over HTTP where there is a lag between | |
| the HTTP response providing the nonce to sign and the next request | |
| containing the signed nonce. This can be significant on large | |
| repositories, since the lag also includes the time to count objects on | |
| the client. | |
| + | |
| Default is 5 minutes. | |
| [[receive.changeUpdateThreads]]receive.changeUpdateThreads:: | |
| + | |
| Number of threads to perform change creation or patch set updates | |
| concurrently. Each thread uses its own database connection from | |
| the database connection pool, and if all threads are busy then | |
| main receive thread will also perform a change creation or patch | |
| set update. | |
| + | |
| Defaults to 1, using only the main receive thread. This feature is for | |
| databases with very high latency that can benefit from concurrent | |
| operations when multiple changes are impacted at once. | |
| [[receive.checkMagicRefs]]receive.checkMagicRefs:: | |
| + | |
| If true, Gerrit will verify the destination repository has | |
| no references under the magic 'refs/for' branch namespace. Names under | |
| these locations confuse clients when trying to upload code reviews so | |
| Gerrit requires them to be empty. | |
| + | |
| If false Gerrit skips the sanity check and assumes administrators | |
| have ensured the repository does not contain any magic references. | |
| Setting to false to skip the check can decrease latency during push. | |
| + | |
| Default is true. | |
| [[receive.allowProjectOwnersToChangeParent]]receive.allowProjectOwnersToChangeParent:: | |
| + | |
| If true, Gerrit will allow project owners to change the parent of a project. | |
| + | |
| By default only Gerrit administrators are allowed to change the parent | |
| of a project. By allowing project owners to change parents, it may | |
| allow the owner to circumvent certain enforced rules (like important | |
| BLOCK rules). | |
| + | |
| Default is false. | |
| + | |
| This value supports configuration reloads: | |
| link:cmd-reload-config.html[reload-config] | |
| [[receive.checkReferencedObjectsAreReachable]]receive.checkReferencedObjectsAreReachable:: | |
| + | |
| If set to true, Gerrit will validate that all referenced objects that | |
| are not included in the received pack are reachable by the user. | |
| + | |
| Carrying out this check on gits with many refs and commits can be a | |
| very CPU-heavy operation. For non public Gerrit-servers this check may | |
| be overkill. | |
| + | |
| Only disable this check if you trust the clients not to forge SHA1 | |
| references to access commits intended to be hidden from the user. | |
| + | |
| Default is true. | |
| [[receive.enableSignedPush]]receive.enableSignedPush:: | |
| + | |
| If true, server-side signed push validation is enabled. | |
| + | |
| When a client pushes with `git push --signed`, this ensures that the | |
| push certificate is valid and signed with a valid public key stored in | |
| the `refs/meta/gpg-keys` branch of `All-Users`. | |
| + | |
| Defaults to false. | |
| [[receive.maxBatchChanges]]receive.maxBatchChanges:: | |
| + | |
| The maximum number of changes that Gerrit allows to be pushed | |
| in a batch for review. When this number is exceeded Gerrit rejects | |
| the push with an error message. | |
| + | |
| May be overridden for certain groups by specifying a limit in the | |
| link:access-control.html#capability_batchChangesLimit['Batch Changes Limit'] | |
| global capability. | |
| + | |
| This setting can be used to prevent users from uploading large | |
| number of changes for review by mistake. | |
| + | |
| Default is zero, no limit. | |
| [[receive.maxBatchCommits]]receive.maxBatchCommits:: | |
| + | |
| The maximum number of commits that Gerrit allows to be pushed in a batch | |
| directly to a branch when link:user-upload.html#bypass_review[bypassing review]. | |
| This limit can be bypassed if a user link:user-upload.html#skip_validation[skips | |
| validation]. | |
| + | |
| Default is 10000. | |
| [[receive.maxObjectSizeLimit]]receive.maxObjectSizeLimit:: | |
| + | |
| Maximum allowed Git object size that 'receive-pack' will accept. | |
| If an object is larger than the given size the pack-parsing will abort | |
| and the push operation will fail. If set to zero then there is no | |
| limit. | |
| + | |
| Gerrit administrators can use this setting to prevent developers | |
| from pushing objects which are too large to Gerrit. | |
| + | |
| This setting can also be set in the `project.config` | |
| (link:config-project-config.html[receive.maxObjectSizeLimit]) in order | |
| to further reduce the global setting. The project specific setting is | |
| only honored when it further reduces the global limit. | |
| + | |
| Default is zero. | |
| + | |
| Common unit suffixes of 'k', 'm', or 'g' are supported. | |
| [[receive.inheritProjectMaxObjectSizeLimit]]receive.inheritProjectMaxObjectSizeLimit:: | |
| + | |
| Controls whether the project-level link:config-project-config.html[`receive.maxObjectSizeLimit`] | |
| value is inherited from the parent project. When `true`, the value is | |
| inherited, otherwise it is not inherited. | |
| + | |
| Default is false, the value is not inherited. | |
| [[receive.maxTrustDepth]]receive.maxTrustDepth:: | |
| + | |
| If signed push validation is link:#receive.enableSignedPush[enabled], | |
| set to the maximum depth to search when checking if a key is | |
| link:#receive.trustedKey[trusted]. | |
| + | |
| Default is 0, meaning only explicitly trusted keys are allowed. | |
| [[receive.threadPoolSize]]receive.threadPoolSize:: | |
| + | |
| Maximum size of the thread pool in which the change data in received packs is | |
| processed. | |
| + | |
| Defaults to the number of available CPUs according to the Java runtime. | |
| [[receive.timeout]]receive.timeout:: | |
| + | |
| Overall timeout on the time taken to process the change data in | |
| received packs. Only includes the time processing Gerrit changes | |
| and updating references, not the time to index the pack. Values can | |
| be specified using standard time unit abbreviations ('ms', 'sec', | |
| 'min', etc.). | |
| + | |
| Default is 4 minutes. If no unit is specified, milliseconds | |
| is assumed. | |
| [[receive.trustedKey]]receive.trustedKey:: | |
| + | |
| List of GPG key fingerprints that should be considered trust roots by | |
| the server when signed push validation is | |
| link:#receive.enableSignedPush[enabled]. A key is trusted by the server | |
| if it is either in this list, or a path of trust signatures leads from | |
| the key to a configured trust root. The maximum length of the path is | |
| determined by link:#receive.maxTrustDepth[`receive.maxTrustDepth`]. | |
| + | |
| Key fingerprints can be displayed with `gpg --list-keys | |
| --with-fingerprint`. | |
| + | |
| Trust signatures can be added to a key using the `tsign` command to | |
| link:https://www.gnupg.org/documentation/manuals/gnupg/OpenPGP-Key-Management.html[ | |
| `gpg --edit-key`], after which the signed key should be re-uploaded. | |
| + | |
| If no keys are specified, web-of-trust checks are disabled. This is the | |
| default behavior. | |
| [[repository]] | |
| === Section repository | |
| Repositories in this sense are the same as projects. | |
| In the following example configuration `Registered Users` is set | |
| to be the default owner of new projects. | |
| ---- | |
| [repository "*"] | |
| ownerGroup = Registered Users | |
| ---- | |
| The only matching patterns supported are exact match or wildcard matching which | |
| can be specified by ending the name with a `*`. If a project matches more than one | |
| repository configuration, then the configuration from the more precise match | |
| will be used. In the following example, the default submit type for a project | |
| named `project/plugins/a` would be `CHERRY_PICK`. | |
| ---- | |
| [repository "project/*"] | |
| defaultSubmitType = MERGE_IF_NECESSARY | |
| [repository "project/plugins/*"] | |
| defaultSubmitType = CHERRY_PICK | |
| ---- | |
| [NOTE] | |
| All properties are used from the matching repository configuration. In | |
| the previous example, all properties will be used from `project/plugins/\*` | |
| section and no properties will be inherited nor overridden from `project/*`. | |
| [[repository.name.basePath]]repository.<name>.basePath:: | |
| + | |
| Alternate to <<gerrit.basePath,gerrit.basePath>>. The repository will be created | |
| and used from this location instead: ${alternateBasePath}/${projectName}.git. | |
| + | |
| If configuring the basePath for an existing project in gerrit, make sure to stop | |
| gerrit, move the repository in the alternate basePath, configure basePath for | |
| this repository and then start Gerrit. | |
| + | |
| Path must be absolute. | |
| [[repository.name.defaultSubmitType]]repository.<name>.defaultSubmitType:: | |
| + | |
| The default submit type for newly created projects. Supported values | |
| are `INHERIT`, `MERGE_IF_NECESSARY`, `FAST_FORWARD_ONLY`, `REBASE_IF_NECESSARY`, | |
| `REBASE_ALWAYS`, `MERGE_ALWAYS` and `CHERRY_PICK`. | |
| + | |
| For more details see link:config-project-config.html#submit-type[Submit Types]. | |
| + | |
| Default is link:config-project-config.html#submit_type_inherit[`INHERIT`]. | |
| + | |
| This submit type is only applied at project creation time if a submit type is | |
| omitted from the link:rest-api-projects.html#project-input[ProjectInput]. If the | |
| submit type is unset in the project config at runtime, for backwards | |
| compatibility purposes, it defaults to | |
| link:project-configuration.html#merge_if_necessary[`MERGE_IF_NECESSARY`] rather | |
| than `INHERIT`. | |
| [[repository.name.ownerGroup]]repository.<name>.ownerGroup:: | |
| + | |
| A name of a group which exists in the database. Zero, one or many | |
| groups are allowed. Each on its own line. Groups which don't exist | |
| in the database are ignored. | |
| [[retry]] | |
| === Section retry | |
| [[retry.maxWait]]retry.maxWait:: | |
| + | |
| Maximum time to wait between attempts to retry an operations when one attempt | |
| fails (e.g. on NoteDb updates due to contention, aka lock failure, on the | |
| underlying ref storage). Operations are retried with exponential backoff, plus | |
| some random jitter, until the interval reaches this limit. After that, retries | |
| continue to occur after a fixed timeout (plus jitter), up to | |
| link:#retry.timeout[`retry.timeout`]. | |
| + | |
| Defaults to 5 seconds; unit suffixes are supported, and assumes milliseconds if | |
| not specified. | |
| [[retry.timeout]]retry.timeout:: | |
| + | |
| Total timeout for retrying operations when one attempt fails. | |
| + | |
| It is possible to overwrite this default timeout based on operation types by | |
| setting link:#retry.operationType.timeout[`retry.<operationType>.timeout`]. | |
| + | |
| Defaults to 20 seconds; unit suffixes are supported, and assumes milliseconds if | |
| not specified. | |
| [[retry.operationType.timeout]]retry.<operationType>.timeout:: | |
| + | |
| Total timeout for retrying operations of type `<operationType>` when one | |
| attempt fails. `<operationType>` can be `ACCOUNT_UPDATE`, `CHANGE_UPDATE`, | |
| `GROUP_UPDATE` and `INDEX_QUERY`. | |
| + | |
| Defaults to link:#retry.timeout[`retry.timeout`]; unit suffixes are supported, | |
| and assumes milliseconds if not specified. | |
| [[retry.retryWithTraceOnFailure]]retry.retryWithTraceOnFailure:: | |
| + | |
| Whether Gerrit should automatically retry operations on failure with tracing | |
| enabled. The automatically generated traces can help with debugging. Please | |
| note that only some of the REST endpoints support automatic retry. | |
| + | |
| By default this is set to false. | |
| [[rules]] | |
| === Section rules | |
| [[rules.enable]]rules.enable:: | |
| + | |
| If true, Gerrit will load and execute 'rules.pl' files in each | |
| project's refs/meta/config branch, if present. When set to false, | |
| only the default internal rules will be used. | |
| + | |
| Default is true, to execute project specific rules. | |
| [[rules.reductionLimit]]rules.reductionLimit:: | |
| + | |
| Maximum number of Prolog reductions that can be performed when | |
| evaluating rules for a single change. Each function call made | |
| in user rule code, internal Gerrit Prolog code, or the Prolog | |
| interpreter counts against this limit. | |
| + | |
| Sites using very complex rules that need many reductions should | |
| compile Prolog to Java bytecode with link:pgm-rulec.html[rulec]. | |
| This eliminates the dynamic Prolog interpreter from charging its | |
| own reductions against the limit, enabling more logic to execute | |
| within the same bounds. | |
| + | |
| A reductionLimit of 0 is nearly infinite, implemented by setting | |
| the internal limit to 2^31-1. | |
| + | |
| Default is 100,000 reductions (about 14 ms on Intel Core i7 CPU). | |
| [[rules.compileReductionLimit]]rules.compileReductionLimit:: | |
| + | |
| Maximum number of Prolog reductions that can be performed when | |
| compiling source code to internal Prolog machine code. | |
| + | |
| Default is 10x reductionLimit (1,000,000). | |
| [[rules.maxSourceBytes]]rules.maxSourceBytes:: | |
| + | |
| Maximum input size (in bytes) of a Prolog rules.pl file. Larger | |
| source files may need a larger rules.compileReductionLimit. Consider | |
| using link:pgm-rulec.html[rulec] to precompile larger rule files. | |
| + | |
| A size of 0 bytes disables rules, same as rules.enable = false. | |
| + | |
| Common unit suffixes of 'k', 'm', or 'g' are supported. | |
| + | |
| Default is 128 KiB. | |
| [[rules.maxPrologDatabaseSize]]rules.maxPrologDatabaseSize:: | |
| + | |
| Number of predicate clauses allowed to be defined in the Prolog | |
| database by project rules. Very complex rules may need more than the | |
| default 256 limit, but cost more memory and may need more time to | |
| evaluate. Consider using link:pgm-rulec.html[rulec] to precompile | |
| larger rule files. | |
| + | |
| Default is 256. | |
| [[execution]] | |
| === Section execution | |
| [[execution.defaultThreadPoolSize]]execution.defaultThreadPoolSize:: | |
| + | |
| The default size of the background execution thread pool in | |
| which miscellaneous tasks are handled. | |
| + | |
| Default is 1. | |
| [[execution.fanOutThreadPoolSize]]execution.fanOutThreadPoolSize:: | |
| + | |
| Maximum size of thread pool to on which a serving thread can fan-out | |
| work to parallelize it. | |
| + | |
| When set to 0, a direct executor will be used. | |
| + | |
| By default, 25 which means that formatting happens in the caller thread. | |
| [[receiveemail]] | |
| === Section receiveemail | |
| [[receiveemail.protocol]]receiveemail.protocol:: | |
| + | |
| Specifies the protocol used for receiving emails. Valid options are | |
| 'POP3', 'IMAP' and 'NONE'. Note that Gerrit will automatically switch between | |
| POP3 and POP3s as well as IMAP and IMAPS depending on the specified | |
| link:#receiveemail.encryption[encryption]. | |
| + | |
| Defaults to 'NONE' which means that receiving emails is disabled. | |
| [[receiveemail.host]]receiveemail.host:: | |
| + | |
| The hostname of the mailserver. Example: 'imap.gmail.com'. | |
| + | |
| Defaults to an empty string which means that receiving emails is disabled. | |
| [[receiveemail.port]]receiveemail.port:: | |
| + | |
| The port the email server exposes for receiving emails. | |
| + | |
| Defaults to the industry standard for a given protocol and encryption: | |
| POP3: 110; POP3S: 995; IMAP: 143; IMAPS: 993. | |
| [[receiveemail.username]]receiveemail.username:: | |
| + | |
| Username used for authenticating with the email server. | |
| + | |
| Defaults to an empty string. | |
| [[receiveemail.password]]receiveemail.password:: | |
| + | |
| Password used for authenticating with the email server. | |
| + | |
| Defaults to an empty string. | |
| [[receiveemail.encryption]]receiveemail.encryption:: | |
| + | |
| Encryption standard used for transport layer security between Gerrit and the | |
| email server. Possible values include 'NONE', 'SSL' and 'TLS'. | |
| + | |
| Defaults to 'NONE'. | |
| [[receiveemail.fetchInterval]]receiveemail.fetchInterval:: | |
| + | |
| Time between two consecutive fetches from the email server. Communication with | |
| the email server is not kept alive. Examples: 60s, 10m, 1h. | |
| + | |
| Defaults to 60 seconds. | |
| [[receiveemail.enableImapIdle]]receiveemail.enableImapIdle:: | |
| + | |
| If the IMAP protocol is used for retrieving emails, IMAPv4 IDLE can be used to | |
| keep the connection with the email server alive and receive a push when a new | |
| email is delivered to the inbox. In this case, Gerrit will process the email | |
| immediately and will not have a fetch delay. | |
| + | |
| Defaults to false. | |
| [[receiveemail.filter.mode]]receiveemail.filter.mode:: | |
| + | |
| A black- and whitelist filter to filter incoming emails. | |
| + | |
| If `OFF`, emails are not filtered by the list filter. | |
| + | |
| If `WHITELIST`, only emails where a pattern from | |
| <<receiveemail.filter.patterns,receiveemail.filter.patterns>> | |
| matches 'From' will be processed. | |
| + | |
| If `BLACKLIST`, only emails where no pattern from | |
| <<receiveemail.filter.patterns,receiveemail.filter.patterns>> | |
| matches 'From' will be processed. | |
| + | |
| Defaults to `OFF`. | |
| [[receiveemail.filter.patterns]]receiveemail.filter.patterns:: | |
| + | |
| A list of regular expressions to match the email sender against. This can also | |
| be a list of addresses when regular expression characters are escaped. | |
| [[sendemail]] | |
| === Section sendemail | |
| [[sendemail.enable]]sendemail.enable:: | |
| + | |
| 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. | |
| [[sendemail.html]]sendemail.html:: | |
| + | |
| If false, Gerrit will only send plain-text emails. | |
| If true, Gerrit will send multi-part emails with an HTML and | |
| plain text part. | |
| + | |
| By default, true, allowing HTML in the emails Gerrit sends. | |
| [[sendemail.connectTimeout]]sendemail.connectTimeout:: | |
| + | |
| The connection timeout of opening a socket connected to a | |
| remote SMTP server. | |
| + | |
| Values can be specified using standard time unit abbreviations | |
| ('ms', 'sec', 'min', etc.). | |
| If no unit is specified, milliseconds is assumed. | |
| + | |
| Default is 0. A timeout of zero is interpreted as an infinite | |
| timeout. The connection will then block until established or | |
| an error occurs. | |
| [[sendemail.threadPoolSize]]sendemail.threadPoolSize:: | |
| + | |
| Maximum size of thread pool in which the review comments | |
| notifications are sent out asynchronously. | |
| + | |
| By default, 1. | |
| [[sendemail.from]]sendemail.from:: | |
| + | |
| 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 messages to be | |
| classified as spam if the user's domain has SPF or DKIM enabled | |
| and <<sendemail.smtpServer,sendemail.smtpServer>> is not a trusted | |
| relay for that domain. You can specify | |
| <<sendemail.allowedDomain,sendemail.allowedDomain>> to instruct Gerrit to only | |
| send as USER if USER is from those domains. | |
| + | |
| * `MIXED` | |
| + | |
| Shorthand for `${user} (Code Review) <review@example.com>` where | |
| `review@example.com` is the same as <<user.email,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,user.name>> and <<user.email,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. | |
| [[sendemail.allowedDomain]]sendemail.allowedDomain:: | |
| + | |
| Only used when `sendemail.from` is set to `USER`. | |
| List of allowed domains. If user's email matches one of the domains, emails will | |
| be sent as USER, otherwise as MIXED mode. Wildcards may be specified by | |
| including `\*` to match any number of characters, for example `*.example.com` | |
| matches any subdomain of `example.com`. | |
| + | |
| By default, `*`. | |
| [[sendemail.smtpServer]]sendemail.smtpServer:: | |
| + | |
| 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). | |
| [[sendemail.smtpServerPort]]sendemail.smtpServerPort:: | |
| + | |
| Port number of the SMTP server in sendemail.smtpserver. | |
| + | |
| By default, 25, or 465 if smtpEncryption is 'ssl'. | |
| [[sendemail.smtpEncryption]]sendemail.smtpEncryption:: | |
| + | |
| Specify the encryption to use, either 'ssl' or 'tls'. | |
| + | |
| By default, 'none', indicating no encryption is used. | |
| [[sendemail.sslVerify]]sendemail.sslVerify:: | |
| + | |
| 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. | |
| [[sendemail.smtpUser]]sendemail.smtpUser:: | |
| + | |
| User name to authenticate with, if required for relay. | |
| [[sendemail.smtpPass]]sendemail.smtpPass:: | |
| + | |
| Password for the account named by sendemail.smtpUser. | |
| [[sendemail.allowrcpt]]sendemail.allowrcpt:: | |
| + | |
| 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. | |
| [[sendemail.includeDiff]]sendemail.includeDiff:: | |
| + | |
| If true, new change emails and merged change emails from Gerrit | |
| will include the complete unified diff of the change. | |
| Variable maxmimumDiffSize places an upper limit on how large the | |
| email can get when this option is enabled. | |
| + | |
| By default, false. | |
| [[sendemail.maximumDiffSize]]sendemail.maximumDiffSize:: | |
| + | |
| Largest size of unified diff output to include in an email. When | |
| the diff exceeds this size the file paths will be listed instead. | |
| Standard byte unit suffixes are supported. | |
| + | |
| By default, 256 KiB. | |
| [[sendemail.importance]]sendemail.importance:: | |
| + | |
| If present, emails sent from Gerrit will have the given level | |
| of importance. Valid values include 'high' and 'low', which | |
| email clients will render in different ways. | |
| + | |
| By default, unset, so no Importance header is generated. | |
| [[sendemail.expiryDays]]sendemail.expiryDays:: | |
| + | |
| If present, emails sent from Gerrit will expire after the given | |
| number of days. This will add the Expiry-Date header and | |
| email clients may expire or expunge mails whose Expiry-Date | |
| header is in the past. This should be a positive non-zero | |
| number indicating how many days in the future the mails | |
| should expire. | |
| + | |
| By default, unset, so no Expiry-Date header is generated. | |
| [[sendemail.replyToAddress]]sendemail.replyToAddress:: | |
| + | |
| A custom Reply-To address should only be provided if Gerrit is set up to | |
| receive emails and the inbound address differs from | |
| <<sendemail.from,sendemail.from>>. | |
| It will be set as Reply-To header on all types of outgoing email where | |
| Gerrit can parse back a user's reply. | |
| + | |
| Defaults to an empty string which adds <<sendemail.from,sendemail.from>> as | |
| Reply-To if inbound email is enabled and the review's author otherwise. | |
| [[sendemail.allowTLD]]sendemail.allowTLD:: | |
| + | |
| List of custom TLDs to allow sending emails to in addition to those specified | |
| in the link:http://data.iana.org/TLD/[IANA list]. | |
| + | |
| Defaults to an empty list, meaning no additional TLDs are allowed. | |
| [[sendemail.addInstanceNameInSubject]]sendemail.addInstanceNameInSubject:: | |
| + | |
| When set to true, Gerrit will add its short name to the email subject, allowing recipients to quickly identify | |
| what Gerrit instance the email came from. | |
| + | |
| The short name can be customized via the gerrit.instanceName option. | |
| + | |
| Defaults to false. | |
| [[site]] | |
| === Section site | |
| [[site.allowOriginRegex]]site.allowOriginRegex:: | |
| + | |
| List of regular expressions matching origins that should be permitted | |
| to use the full Gerrit REST API. These should be trusted applications, | |
| as the sites may be able to use the user's credentials. Applies to | |
| all requests, including state changing methods (PUT, DELETE, POST). | |
| + | |
| Expressions should not require trailing slash. For example a valid | |
| pattern might be `https://build-status[.]example[.]com`. | |
| + | |
| By default, unset, denying all cross-origin requests. | |
| [[site.refreshHeaderFooter]]site.refreshHeaderFooter:: | |
| + | |
| If true the server checks the site header, footer and CSS files for | |
| updated versions. If false, a server restart is required to change | |
| any of these resources. Default is true, allowing automatic reloads. | |
| [[ssh-alias]] | |
| === Section ssh-alias | |
| Variables in section ssh-alias permit the site administrator to alias | |
| another command from Gerrit or a plugin into the `gerrit` command | |
| namespace. To alias `replication start` to `gerrit replicate`: | |
| ---- | |
| [ssh-alias] | |
| replicate = replication start | |
| ---- | |
| [[sshd]] | |
| === Section sshd | |
| [[sshd.enableCompression]]sshd.enableCompression:: | |
| + | |
| In the general case, we want to disable transparent compression, since | |
| the majority of our data transfer is highly compressed Git pack files | |
| and we cannot make them any smaller than they already are. | |
| + | |
| However, if there are CPU in abundance and the server is reachable | |
| through slow networks, gits with huge amount of refs can benefit from | |
| SSH-compression since git does not compress the ref announcement during | |
| handshake. | |
| + | |
| Compression can be especially useful when Gerrit replicas are being used | |
| for the larger clones and fetches and the master server mostly takes | |
| small receive-packs. | |
| + | |
| By default, `false`. | |
| [[sshd.backend]]sshd.backend:: | |
| + | |
| Starting from version 0.9.0 Apache SSHD project added support for NIO2 | |
| IoSession. To use the old MINA session the `backend` option must be set | |
| to `MINA`. | |
| + | |
| By default, `NIO2`. | |
| [[sshd.listenAddress]]sshd.listenAddress:: | |
| + | |
| 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. | |
| To disable the internal SSHD, set listenAddress to `off`. | |
| By default, `*:29418`. | |
| -- | |
| [[sshd.advertisedAddress]]sshd.advertisedAddress:: | |
| + | |
| Specifies the addresses clients should be told to connect to. | |
| This may differ from sshd.listenAddress if a firewall based port | |
| redirector is being used, making Gerrit appear to answer on port | |
| 22. The following forms may be used to specify an address. In any | |
| form, `:'port'` may be omitted to use the default SSH port of 22. | |
| * `'hostname':'port'` (for example `review.example.com:22`) | |
| * `'IPv4':'port'` (for example `10.0.0.1:29418`) | |
| * `['IPv6']:'port'` (for example `[ff02::1]:29418`) | |
| + | |
| -- | |
| If multiple values are supplied, the daemon will advertise all | |
| of them. | |
| By default uses the value of `sshd.listenAddress`. | |
| -- | |
| [[sshd.tcpKeepAlive]]sshd.tcpKeepAlive:: | |
| + | |
| If true, enables TCP keepalive messages to the other side, so | |
| the daemon can terminate connections if the peer disappears. | |
| + | |
| Only effective when `sshd.backend` is set to `MINA`. | |
| + | |
| By default, `true`. | |
| [[sshd.threads]]sshd.threads:: | |
| + | |
| Number of threads to use when executing SSH command requests. | |
| If additional requests are received while all threads are busy they | |
| are queued and serviced in a first-come-first-served order. | |
| + | |
| By default, 2x the number of CPUs available to the JVM (but at least 4 | |
| threads). | |
| + | |
| [NOTE] | |
| When SSH daemon is enabled then this setting also defines the max number of | |
| concurrent Git requests for interactive users over SSH and HTTP together. | |
| [[sshd.batchThreads]]sshd.batchThreads:: | |
| + | |
| Number of threads to allocate for SSH command requests from | |
| link:access-control.html#non-interactive_users[non-interactive users]. | |
| If equals to 0, then all non-interactive requests are executed in the same | |
| queue as interactive requests. | |
| + | |
| Any other value will remove the number of threads from the queue | |
| allocated to interactive users, and create a separate thread pool | |
| of the requested size, which will be used to run commands from | |
| non-interactive users. | |
| + | |
| If the number of threads requested for non-interactive users is larger | |
| than the total number of threads allocated in sshd.threads, then the | |
| value of sshd.threads is increased to accommodate the requested value. | |
| + | |
| By default is 1 on single core node, 2 otherwise. | |
| + | |
| [NOTE] | |
| When SSH daemon is enabled then this setting also defines the max number of | |
| concurrent Git requests for batch users over SSH and HTTP together. | |
| [[sshd.streamThreads]]sshd.streamThreads:: | |
| + | |
| Number of threads to use when formatting events to asynchronous | |
| streaming clients. Event formatting is multiplexed onto this thread | |
| pool by a simple FIFO scheduling system. | |
| + | |
| By default, 1 plus the number of CPUs available to the JVM. | |
| [[sshd.commandStartThreads]]sshd.commandStartThreads:: | |
| + | |
| Number of threads used to parse a command line submitted by a client | |
| over SSH for execution, create the internal data structures used by | |
| that command, and schedule it for execution on another thread. | |
| + | |
| By default, 2. | |
| [[sshd.maxAuthTries]]sshd.maxAuthTries:: | |
| + | |
| Maximum number of authentication attempts before the server | |
| disconnects the client. Each public key that a client has loaded | |
| into its local agent counts as one auth request. Users can work | |
| around the server's limit by loading less keys into their agent, | |
| or selecting a specific key in their `~/.ssh/config` file with | |
| the `IdentityFile` option. | |
| + | |
| By default, 6. | |
| [[sshd.loginGraceTime]]sshd.loginGraceTime:: | |
| + | |
| Time in seconds that a client has to authenticate before the server | |
| automatically terminates their connection. 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 | |
| + | |
| By default, 2 minutes. | |
| [[sshd.idleTimeout]]sshd.idleTimeout:: | |
| + | |
| Time in seconds after which the server automatically terminates idle | |
| connections (or 0 to disable closing of idle connections) not waiting for | |
| any server operation to complete. | |
| 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 | |
| + | |
| By default, 0. | |
| [[sshd.waitTimeout]]sshd.waitTimeout:: | |
| + | |
| Time in seconds after which the server automatically terminates | |
| connections waiting for a server operation to complete, like for instance | |
| cloning a very large repo with lots of refs. | |
| 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 | |
| + | |
| By default, 30s. | |
| [[sshd.maxConnectionsPerUser]]sshd.maxConnectionsPerUser:: | |
| + | |
| Maximum number of concurrent SSH sessions that a user account | |
| may open at one time. This is the number of distinct SSH logins | |
| that each user may have active at one time, and is not related to | |
| the number of commands a user may issue over a single connection. | |
| If set to 0, there is no limit. | |
| + | |
| By default, 64. | |
| [[sshd.cipher]]sshd.cipher:: | |
| + | |
| 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-ctr` | |
| * `aes192-ctr` | |
| * `aes256-ctr` | |
| * `aes128-cbc` | |
| * `aes192-cbc` | |
| * `aes256-cbc` | |
| * `blowfish-cbc` | |
| * `3des-cbc` | |
| * `arcfour128` | |
| * `arcfour256` | |
| * `none` | |
| + | |
| By default, all supported ciphers except `none` are available. | |
| + | |
| If your setup allows for it, it's recommended to disable all ciphers except | |
| the AES-CTR modes. | |
| [[sshd.mac]]sshd.mac:: | |
| + | |
| 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` | |
| * `hmac-sha2-256` | |
| * `hmac-sha2-512` | |
| + | |
| By default, all supported MACs are available. | |
| [[sshd.kex]]sshd.kex:: | |
| + | |
| -- | |
| Available key exchange algorithms. To permit multiple algorithms, | |
| specify multiple `sshd.kex` keys in the configuration file, one key | |
| exchange algorithm per key. Key exchange algorithm names starting | |
| with `+` are enabled in addition to the default key exchange | |
| algorithms, key exchange algorithm names starting with `-` are | |
| removed from the default key exchange algorithms. | |
| In the following example configuration, support for the 1024-bit | |
| `diffie-hellman-group1-sha1` key exchange is disabled while leaving | |
| all of the other default algorithms enabled: | |
| ---- | |
| [sshd] | |
| kex = -diffie-hellman-group1-sha1 | |
| ---- | |
| Supported key exchange algorithms: | |
| * `ecdh-sha2-nistp521` | |
| * `ecdh-sha2-nistp384` | |
| * `ecdh-sha2-nistp256` | |
| * `diffie-hellman-group-exchange-sha256` | |
| * `diffie-hellman-group-exchange-sha1` | |
| * `diffie-hellman-group14-sha1` | |
| * `diffie-hellman-group1-sha1` | |
| By default, all supported key exchange algorithms are available. | |
| It is strongly recommended to disable at least `diffie-hellman-group1-sha1` | |
| as it's known to be vulnerable (logjam attack). Additionally, if your setup | |
| allows for it, it is recommended to disable the remaining two `sha1` key | |
| exchange algorithms. | |
| -- | |
| [[sshd.kerberosKeytab]]sshd.kerberosKeytab:: | |
| + | |
| Enable kerberos authentication for SSH connections. To permit | |
| kerberos authentication, the server must have a host principal | |
| (see `sshd.kerberosPrincipal`) which is acquired from a keytab. | |
| This must be provisioned by the kerberos administrators, and is | |
| typically installed into `/etc/krb5.keytab` on host machines. | |
| + | |
| The keytab must contain at least one `host/` principal, typically | |
| using the host's canonical name. If it does not use the | |
| canonical name, the `sshd.kerberosPrincipal` should be configured | |
| with the correct name. | |
| + | |
| By default, not set and so kerberos authentication is not enabled. | |
| [[sshd.kerberosPrincipal]]sshd.kerberosPrincipal:: | |
| + | |
| If kerberos authentication is enabled with `sshd.kerberosKeytab`, | |
| instead use the given principal name instead of the default. | |
| If the principal does not begin with `host/` a warning message is | |
| printed and may prevent successful authentication. | |
| + | |
| This may be useful if the host is behind an IP load balancer or | |
| other SSH forwarding systems, since the principal name is constructed | |
| by the client and must match for kerberos authentication to work. | |
| + | |
| By default, `host/canonical.host.name` | |
| [[sshd.requestLog]]sshd.requestLog:: | |
| + | |
| Enable (or disable) the `'$site_path'/logs/sshd_log` request log. | |
| If enabled, a request log file is written out by the SSH daemon. | |
| + | |
| `log4j.appender` with the name `sshd_log` can be configured to overwrite | |
| programmatic configuration. | |
| + | |
| By default, `true`. | |
| + | |
| This value supports link:#reloadConfig[configuration reloads]. | |
| [[sshd.rekeyBytesLimit]]sshd.rekeyBytesLimit:: | |
| + | |
| The SSH daemon will issue a rekeying after a certain amount of data. | |
| This configuration option allows you to tweak that setting. | |
| + | |
| By default, 1073741824 (bytes, 1GB). | |
| + | |
| The `rekeyBytesLimit` cannot be set to lower than 32. | |
| [[sshd.rekeyTimeLimit]]sshd.rekeyTimeLimit:: | |
| + | |
| The SSH daemon will issue a rekeying after a certain amount of time. | |
| This configuration option allows you to tweak that setting. | |
| + | |
| By default, 1h. | |
| + | |
| Set to 0 to disable this check. | |
| [[suggest]] | |
| === Section suggest | |
| [[suggest.maxSuggestedReviewers]]suggest.maxSuggestedReviewers:: | |
| + | |
| The maximum numbers of reviewers suggested. | |
| + | |
| By default 10. | |
| + | |
| This value supports link:#reloadConfig[configuration reloads]. | |
| [[suggest.from]]suggest.from:: | |
| + | |
| The number of characters that a user must have typed before suggestions | |
| are provided. If set to 0, suggestions are always provided. This is only | |
| used for suggesting accounts when adding members to a group. | |
| + | |
| By default 0. | |
| [[tracing]] | |
| === Section tracing | |
| [[tracing.performanceLogging]]tracing.performanceLogging:: | |
| + | |
| Whether performance logging is enabled. | |
| + | |
| When performance logging is enabled, performance events for some | |
| operations are collected in memory while a request is running. At the | |
| end of the request the performance events are handed over to the | |
| link:dev-plugins.html#performance-logger[PerformanceLogger] plugins. | |
| This means if performance logging is enabled, the memory footprint of | |
| requests is slightly increased. | |
| + | |
| This setting has no effect if no | |
| link:dev-plugins.html#performance-logger[PerformanceLogger] plugins are | |
| installed, because then performance logging is always disabled. | |
| + | |
| By default, true. | |
| [[tracing.traceid]] | |
| ==== Subsection tracing.<trace-id> | |
| There can be multiple `tracing.<trace-id>` subsections to configure | |
| automatic tracing of requests. To be traced a request must match all | |
| conditions of one `tracing.<trace-id>` subsection. The subsection name | |
| is used as trace ID. Using this trace ID administrators can find | |
| matching log entries. | |
| [[tracing.traceid.requestType]]tracing.<trace-id>.requestType:: | |
| + | |
| Type of request for which request tracing should be always enabled (can | |
| be `GIT_RECEIVE`, `GIT_UPLOAD`, `REST` and `SSH`). | |
| + | |
| May be specified multiple times. | |
| + | |
| By default, unset (all request types are matched). | |
| [[tracing.traceid.requestUriPattern]]tracing.<trace-id>.requestUriPattern:: | |
| + | |
| Regular expression to match request URIs for which request tracing | |
| should be always enabled. Request URIs are only available for REST | |
| requests. Request URIs never include the '/a' prefix. | |
| + | |
| May be specified multiple times. | |
| + | |
| By default, unset (all request URIs are matched). | |
| [[tracing.traceid.account]]tracing.<trace-id>.account:: | |
| + | |
| Account ID of an account for which request tracing should be always | |
| enabled. | |
| + | |
| May be specified multiple times. | |
| + | |
| By default, unset (all accounts are matched). | |
| [[tracing.traceid.projectPattern]]tracing.<trace-id>.projectPattern:: | |
| + | |
| Regular expression to match project names for which request tracing | |
| should be always enabled. | |
| + | |
| May be specified multiple times. | |
| + | |
| By default, unset (all projects are matched). | |
| [[trackingid]] | |
| === Section trackingid | |
| Tagged footer lines containing references to external | |
| tracking systems, parsed out of the commit message and | |
| saved in Gerrit's secondary index. | |
| After making changes to this section, existing changes | |
| must be reindexed with link:pgm-reindex.html[reindex]. | |
| The tracking ids are searchable using tr:<tracking id> or | |
| bug:<tracking id>. | |
| ---- | |
| [trackingid "jira-bug"] | |
| footer = Bugfix: | |
| footer = Bug: | |
| match = JRA\\d{2,8} | |
| system = JIRA | |
| [trackingid "jira-feature"] | |
| footer = Feature | |
| match = JRA(\\d{2,8}) | |
| system = JIRA | |
| ---- | |
| [[trackingid.name.footer]]trackingid.<name>.footer:: | |
| + | |
| A prefix tag that identifies the footer line to parse for tracking ids. | |
| + | |
| Several trackingid entries can have the same footer tag, and a single trackingid | |
| entry can have multiple footer tags. | |
| + | |
| If multiple footer tags are specified, each tag will be parsed separately and | |
| duplicates will be ignored. | |
| + | |
| The trailing ":" is optional. | |
| [[trackingid.name.match]]trackingid.<name>.match:: | |
| + | |
| A link:http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html[standard | |
| Java regular expression (java.util.regex)] used to match the | |
| external tracking id part of the footer line. The match can | |
| result in several entries in the DB. If grouping is used in the | |
| regex the first group will be interpreted as the tracking id. | |
| Tracking ids longer than 32 characters will be ignored. | |
| + | |
| The configuration file parser eats one level of backslashes, so the | |
| character class `\s` requires `\\s` in the configuration file. The | |
| parser also terminates the line at the first `#`, so a match | |
| expression containing # must be wrapped in double quotes. | |
| [[trackingid.name.system]]trackingid.<name>.system:: | |
| + | |
| The name of the external tracking system (maximum 10 characters). | |
| It is possible to have several trackingid entries for the same | |
| tracking system. | |
| [[transfer]] | |
| === Section transfer | |
| [[transfer.timeout]]transfer.timeout:: | |
| + | |
| Number of seconds to wait for a single network read or write | |
| to complete before giving up and declaring the remote side is | |
| not responding. If 0, there is no timeout, and this server will | |
| wait indefinitely for a transfer to finish. | |
| + | |
| A timeout should be large enough to mostly transfer the objects to | |
| the other side. 1 second may be too small for larger projects, | |
| especially over a WAN link, while 10-30 seconds is a much more | |
| reasonable timeout value. | |
| + | |
| Defaults to 0 seconds, wait indefinitely. | |
| [[upload]] | |
| === Section upload | |
| Options to control the behavior of `upload-pack` on the server side, | |
| which handles a user's fetch, clone, or repo sync command. | |
| ---- | |
| [upload] | |
| allowGroup = GROUP_ALLOWED_TO_EXECUTE | |
| allowGroup = YET_ANOTHER_GROUP_ALLOWED_TO_EXECUTE | |
| ---- | |
| [[upload.allowGroup]]upload.allowGroup:: | |
| + | |
| Name of the groups of users that are allowed to execute 'upload-pack'. | |
| One or more groups can be set. | |
| + | |
| If no groups are added, any user will be allowed to execute | |
| 'upload-pack' on the server. | |
| [[accountDeactivation]] | |
| === Section accountDeactivation | |
| Configures the parameters for the scheduled task to sweep and deactivate Gerrit | |
| accounts according to their status reported by the auth backend. Currently only | |
| supported for LDAP backends. | |
| [[accountDeactivation.startTime]]accountDeactivation.startTime:: | |
| + | |
| The link:#schedule-configuration-startTime[start time] for running | |
| account deactivations. | |
| [[accountDeactivation.interval]]accountDeactivation.interval:: | |
| + | |
| The link:#schedule-configuration-interval[interval] for running | |
| account deactivations. | |
| link:#schedule-configuration-examples[Schedule examples] can be found | |
| in the link:#schedule-configuration[Schedule Configuration] section. | |
| [[submodule]] | |
| === Section submodule | |
| [[submodule.verbosesuperprojectupdate]]submodule.verboseSuperprojectUpdate:: | |
| + | |
| When using link:user-submodules.html#automatic_update[automatic superproject updates] | |
| this option will determine how the submodule commit messages are included into | |
| the commit message of the superproject update. | |
| + | |
| If `FALSE`, will not include any commit messages for the gitlink update. | |
| + | |
| If `SUBJECT_ONLY`, will include only the commit subjects. | |
| + | |
| If `TRUE`, will include full commit messages. | |
| + | |
| By default this is `TRUE`. | |
| [[submodule.enableSuperProjectSubscriptions]]submodule.enableSuperProjectSubscriptions:: | |
| + | |
| This allows to enable the superproject subscription mechanism. | |
| + | |
| By default this is true. | |
| [[submodule.maxCombinedCommitMessageSize]]submodule.maxCombinedCommitMessageSize:: | |
| + | |
| This allows to limit the length of the commit message for a submodule. | |
| + | |
| By default this is 262144 (256 KiB). | |
| + | |
| Common unit suffixes of k, m, or g are supported. | |
| [[submodule.maxCommitMessages]]submodule.maxCommitMessages:: | |
| + | |
| This allows to limit the number of commit messages that should be combined when creating | |
| a commit message for a submodule. | |
| + | |
| By default this is 1000. | |
| [[user]] | |
| === Section user | |
| [[user.name]]user.name:: | |
| + | |
| 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". | |
| [[user.email]]user.email:: | |
| + | |
| 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. | |
| [[user.anonymousCoward]]user.anonymousCoward:: | |
| + | |
| Username that is displayed in the Gerrit Web UI and in e-mail | |
| notifications if the full name of the user is not set. | |
| + | |
| By default "Name of user not set" is used. | |
| [[schedule-configuration]] | |
| === Schedule Configuration | |
| Schedule configurations are used for running periodic background jobs. | |
| A schedule configuration consists of two parameters: | |
| [[schedule-configuration-interval]] | |
| * `interval`: | |
| Interval for running the periodic background job. The interval must be | |
| larger than zero. The following suffixes are supported to define the | |
| time unit for the interval: | |
| ** `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`) | |
| [[schedule-configuration-startTime]] | |
| * `startTime`: | |
| The start time defines the first execution of the periodic background | |
| job. If the configured `interval` is shorter than `startTime - now` the | |
| start time will be preponed by the maximum integral multiple of | |
| `interval` so that the start time is still in the future. `startTime` | |
| must have one of the following formats: | |
| ** `<day of week> <hours>:<minutes>` | |
| ** `<hours>:<minutes>` | |
| + | |
| The placeholders can have the following values: | |
| *** `<day of week>`: | |
| `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, `Sat`, `Sun` | |
| *** `<hours>`: | |
| `00`-`23` | |
| *** `<minutes>`: | |
| `00`-`59` | |
| + | |
| The time zone cannot be specified but is always the system default | |
| time zone. Hours must be zero-padded, i.e. `06:00` rather than `6:00`. | |
| The section (and optionally the subsection) in which the `interval` and | |
| `startTime` keys must be set depends on the background job for which a | |
| schedule should be configured. E.g. for the change cleanup job the keys | |
| must be set in the link:#changeCleanup[changeCleanup] section: | |
| ---- | |
| [changeCleanup] | |
| startTime = Fri 10:30 | |
| interval = 2 days | |
| ---- | |
| [[schedule-configuration-examples]] | |
| Examples for a schedule configuration: | |
| * Example 1: | |
| + | |
| ---- | |
| startTime = Fri 10:30 | |
| interval = 2 days | |
| ---- | |
| + | |
| Assuming that the server is started on `Mon 07:00` then | |
| `startTime - now` is `4 days 3:30 hours`. This is larger than the | |
| interval hence the start time is preponed by the maximum integral | |
| multiple of the interval so that start time is still in the future, | |
| i.e. preponed by 4 days. This yields a start time of `Mon 10:30`, next | |
| executions are `Wed 10:30`, `Fri 10:30`. etc. | |
| * Example 2: | |
| + | |
| ---- | |
| startTime = 06:00 | |
| interval = 1 day | |
| ---- | |
| + | |
| Assuming that the server is started on `Mon 07:00` then this yields the | |
| first run on Tuesday at 06:00 and a repetition interval of 1 day. | |
| [[All-Projects-project.config]] | |
| == File `etc/All-Projects/project.config` | |
| The optional file `'$site_path'/etc/All-Projects/project.config` provides | |
| defaults for configuration read from | |
| link:config-project-config.html[`project.config`] in the | |
| `All-Projects` repo. Unlike `gerrit.config`, this file contains project-type | |
| configuration rather than server-type configuration. | |
| Most administrators will not need this file, and should instead make commits to | |
| `All-Projects` to modify global config. However, a separate file can be useful | |
| when managing multiple Gerrit servers, since pushing changes to defaults using | |
| Puppet or a similar tool can be easier than scripting git updates to | |
| `All-Projects`. | |
| The contents of the file are loaded each time the `All-Projects` project is | |
| reloaded. Updating the file requires either evicting the project cache or | |
| restarting the server. | |
| Caveats: | |
| * The path from which the file is read corresponds to the name of the repo, | |
| which is link:#gerrit.allProjects[configurable]. | |
| * Although the file lives in a directory that shares a name with a repository, | |
| this directory is not a Git repository. | |
| * Only the file `project.config` is read from this directory to provide | |
| defaults; any other files in this directory, such as `rules.pl`, are ignored. | |
| (This behavior may change in the future.) | |
| * Group names listed in the access config in this file are resolved to UUIDs | |
| using the `groups` file in the repository, not in the config directory. As a | |
| result, setting ACLs in this file is not recommended. | |
| [[secure.config]] | |
| == File `etc/secure.config` | |
| The optional file `'$site_path'/etc/secure.config` overrides (or | |
| supplements) the settings supplied by `'$site_path'/etc/gerrit.config`. | |
| The file should be readable only by the daemon process and can be | |
| used to contain private configuration entries that wouldn't normally | |
| be exposed to everyone. | |
| Sample `etc/secure.config`: | |
| ---- | |
| [auth] | |
| registerEmailPrivateKey = 2zHNrXE2bsoylzUqDxZp0H1cqUmjgWb6 | |
| [database] | |
| username = webuser | |
| password = s3kr3t | |
| [ldap] | |
| password = l3tm3srch | |
| [httpd] | |
| sslKeyPassword = g3rr1t | |
| [sendemail] | |
| smtpPass = sp@m | |
| [remote "bar"] | |
| password = s3kr3t | |
| ---- | |
| == File `etc/peer_keys` | |
| The optional file `'$site_path'/etc/peer_keys` controls who can | |
| login as the 'Gerrit Code Review' user, required for the link:cmd-suexec.html[suexec] | |
| command. | |
| The format is one Base-64 encoded public key per line. | |
| === Configurable Parameters | |
| site_path:: | |
| + | |
| Local filesystem directory holding the site customization assets. | |
| Placing this directory under version control and/or backup is a | |
| good idea. | |
| + | |
| Files in this directory provide additional configuration. | |
| + | |
| Other files support site customization. | |
| + | |
| * link:config-themes.html[Themes] | |
| [[jgitConfig]] | |
| == File `etc/jgit.config` | |
| Gerrit uses the `$site_path/etc/jgit.config` file instead of the | |
| system-wide and user-global Git configuration for its runtime JGit | |
| configuration. | |
| Sample `etc/jgit.config` file: | |
| ---- | |
| [core] | |
| trustFolderStat = false | |
| ---- | |
| GERRIT | |
| ------ | |
| Part of link:index.html[Gerrit Code Review] | |
| SEARCHBOX | |
| --------- |