| = 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.enableDiskStatMetrics]]cache.enableDiskStatMetrics:: |
| + |
| Whether to enable the computation of disk statistics of persistent caches. |
| This computation is expensive and requires a long time on larger installations. |
| + |
| By default, false. |
| |
| [[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 a cluster setup using multiple primary |
| or multiple replica nodes. |
| + |
| 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.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 merge 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 compatibility 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. May be specified |
| multiple times to configure multiple values. 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 primary mode enabling write |
| operations. |
| |
| [[container.slave]]container.slave:: |
| + |
| Backward compatibility for link:#container.replica[`container.replica`] |
| 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.packedGitUseStrongRefs]]core.packedGitUseStrongRefs:: |
| + |
| Set to `true` in order to use strong references to reference packfile |
| pages cached in the WindowCache. Otherwise SoftReferences are used. |
| If this option is set to `false`, the Java garbage collector will |
| flush the WindowCache to free memory if the used heap comes close to |
| the maximum heap size. This has the advantage that it can quickly |
| reclaim memory which was used by the WindowCache but comes at the |
| price that the previously cached pack file content needs to be again |
| copied from the file system cache to the Gerrit process. |
| Setting this option to `true` prevents flushing the WindowCache |
| which provides more predictable performance. |
| + |
| Default is `false`. |
| |
| [[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 2g. |
| + |
| 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.xframeOption]]gerrit.xframeOption:: |
| + |
| Add link:https://tools.ietf.org/html/rfc7034[`X-Frame-Options`] header to all HTTP |
| responses. The `X-Frame-Options` HTTP response header can be used to indicate |
| whether or not a browser should be allowed to render a page in a |
| `<frame>`, `<iframe>`, `<embed>` or `<object>`. |
| + |
| Available values: |
| + |
| 1. ALLOW - The page can be displayed in a frame. |
| 2. SAMEORIGIN - The page can only be displayed in a frame on the same origin as the page itself. |
| + |
| If link:#gerrit.canLoadInIFrame is set to false this option is ignored and the |
| `X-Frame-Options` header is always set to `DENY`. |
| Setting this option to `ALLOW` will cause the `X-Frame-Options` header to be omitted |
| the the page can be displayed in a frame. |
| + |
| By default SAMEORIGIN. |
| |
| [[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.experimentalRollingUpgrade]]gerrit.experimentalRollingUpgrade:: |
| + |
| Enable Gerrit rolling upgrade to the next version. |
| For example if Gerrit v3.1 is version N (All-Projects:refs/meta/version=181) |
| then its next version N+1 is v3.2 (All-Projects:refs/meta/version=183). |
| Allow Gerrit to start even if the underlying schema version has been bumped to |
| the next Gerrit version. |
| + |
| Set to true if Gerrit is installed in |
| [high-availability configuration](https://gerrit.googlesource.com/plugins/high-availability/+/refs/heads/master/README.md) |
| during the rolling upgrade to the next version. |
| + |
| By default false. |
| + |
| The rolling upgrade process, at high level, assumes that Gerrit is installed |
| on two or more nodes sharing the repositories over NFS. The upgrade is composed |
| of the following steps: |
| + |
| 1. Set gerrit.experimentalRollingUpgrade to true on all Gerrit masters |
| 2. Set the first master unhealthy |
| 3. Shutdown the first master and [upgrade](install.html#init) to the next version |
| 4. Startup the first master, wait for the online reindex to complete |
| 5. Verify the the first master upgrade is successful and online reindex is complete |
| 6. Set the first master healthy |
| 7. Repeat steps 2. to 6. for all the other Gerrit nodes |
| + |
| [WARNING] |
| Rolling upgrade may or may not be possible depending on the changes introduced |
| by the target version of the upgrade. Refer to the release notes and check whether |
| the rolling upgrade is possible or not and the associated constraints. |
| |
| [[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. The httpd log format is documented |
| link:logs.html#_httpd_log[here]. |
| + |
| `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, and also for offline reindexing. |
| + |
| 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]. |
| |
| 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/index-modules.html#_static_index_settings[ |
| Elasticsearch documentation] for details. |
| + |
| Defaults to 1. |
| |
| [[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/index-modules.html#dynamic-index-settings[ |
| Elasticsearch documentation] for details. |
| + |
| Defaults to 1. |
| |
| [[elasticsearch.maxResultWindow]]elasticsearch.maxResultWindow:: |
| + |
| Sets the maximum value of `from + size` for searches to use per index. Refer to the |
| link:https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#dynamic-index-settings[ |
| Elasticsearch documentation] for details. |
| + |
| Defaults to 10000. |
| |
| ==== 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 |
| link:https://www.elastic.co/guide/en/elasticsearch/reference/current/security-getting-started.html[the documentation]. |
| This is the current documentation link. Select another Elasticsearch version |
| from the dropdown menu available on that page if need be. |
| |
| [[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, ssh and http logging in JSON format (file name: |
| "logs/{error|sshd|httpd}_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. |
| |
| [[notedb.changes.sequenceBatchSize]]notedb.changes.sequenceBatchSize:: |
| + |
| The next available change sequence number is stored as UTF-8 text in a |
| blob pointed to by the `refs/sequences/changes` ref in the `All-Projects` |
| 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 change ID batch that |
| each process retrieves at once. |
| + |
| By default, 20. |
| |
| [[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 and minimum is 2 so that a single, potentially longer executing |
| task (e.g. GC), is not blocking the entire execution. |
| |
| [[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. |
| + |
|