| :linkattrs: |
| = 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 `CLOUDSPANNER`, `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. To make an account |
| visible to all users (e.g. because it is a service account) when |
| `VISIBLE_GROUP` is used, create a `Public Users` group that has the |
| `Make group visible to all registered users` option enabled and add the |
| account as a group member. |
| + |
| If `NONE`, no users other than the current user are visible. |
| + |
| Default is `ALL`. |
| |
| [[accounts.defaultDisplayName]]accounts.defaultDisplayName:: |
| + |
| If a user account does not have a display name set, which is the normal |
| case, then this configuration value chooses the strategy how to choose |
| the display name. Note that this strategy is not applied by the backend. |
| If the AccountInfo has the display name unset, then the client has to |
| apply this strategy. |
| + |
| If `FULL_NAME`, then the (full) name of the user is chosen from |
| link:rest-api-accounts.html#account-info[AccountInfo]. |
| + |
| If `FIRST_NAME`, then the first word (i.e. everything until first |
| whitespace character) of the (full) name of the user is chosen from |
| link:rest-api-accounts.html#account-info[AccountInfo]. |
| + |
| If `USERNAME`, then the username of the user is chosen from |
| link:rest-api-accounts.html#account-info[AccountInfo]. If that is not |
| set, then the (full) name will be used. |
| + |
| Default is `FULL_NAME`. |
| |
| [[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,role=external,window=_blank]. |
| + |
| * `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 are link:cmd-create-account.html[internal-only] 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),role=external,window=_blank] (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),role=external,window=_blank] (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 the Gerrit web app, so absolute URLs like |
| `https://someotherhost/login` work as well. |
| + |
| If a ${path} parameter is included, then the Gerrit web app 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[ |
| 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`. |
| + |
| When gitBasicAuthPolicy is set to `LDAP` or `HTTP_LDAP` and the user |
| is authenticating with the LDAP username/password, the Git client config |
| needs to have `http.cookieFile` set to a local file, otherwise every |
| single call would trigger a full LDAP authentication and groups resolution |
| which could introduce a noticeable latency on the overall execution |
| and produce unwanted load to the LDAP server. |
| |
| [[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. Accounts |
| created using the REST API or the `create-account` SSH command will |
| be created with all lowercase characters, when this option is set. |
| + |
| 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.userNameCaseInsensitive]]auth.userNameCaseInsensitive:: |
| + |
| If set the username will be handled case insensitively but case preserving, |
| i.e. a user can login with `johndoe` or `JohnDoe` for the same account |
| created for `JohnDoe`. The form of the username used during account creation |
| will be used wherever the username is displayed. Sandbox branches created |
| for a user can also only be created for this original form. |
| + |
| Note, that this does not work for all existing accounts, if they were |
| not originally created with all lowercase, since the note keys of the |
| external IDs will not match the new scheme. For more details refer to |
| the link:config-accounts.html#external-ids[External ID documentation]. |
| + |
| Gerrit provides the |
| link:pgm-ChangeExternalIdCaseSensitivity.html[offline] |
| and the online link:externalid-case-insensitivity.html#online-migration[online] |
| tools to migrate existing accounts to match the new scheme. |
| + |
| Naturally, if there were two accounts only different in capitalization, |
| e.g. `johndoe` and `JohnDoe`, the account `JohnDoe` will not be able |
| to authenticate anymore after setting this option. If such duplicate |
| accounts exist the migration tool will fail, since the newly computed |
| note name would be identical and thus conflict. These duplicates thus |
| have to be deleted manually by deleting the respective external ID. |
| + |
| For newly initialized sites this option defaults to `true`. |
| + |
| Default is `false`. |
| |
| [[auth.userNameCaseInsensitiveMigrationMode]]auth.userNameCaseInsensitiveMigrationMode:: |
| + |
| Setting migration mode to `true` allows to fallback to case sensitive |
| behaviour if the migrated external ID cannot be found. This allows to |
| trigger the migration while Gerrit process is running. |
| + |
| Default is `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 NoteDb 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 a |
| user has READ permission for all refs. |
| + |
| The full ref filtering would filter out refs for pending edits, private changes |
| and auto merge commits. |
| + |
| By default, `true`. |
| |
| [[cache]] |
| === Section cache |
| |
| [[cache.threads]]cache.threads:: |
| + |
| Number of threads to use when running asynchronous cache tasks. |
| The threads executor is delegated to when sending removal notifications to listeners, |
| when asynchronous computations like refresh, refreshAfterWrite are performed, or when |
| performing periodic maintenance. |
| + |
| **NOTE**: Setting it to 0 disables the dedicated thread pool and indexing will be done in the |
| same thread as the operation. This may result in evictions taking longer because the |
| listeners are executed in the caller's thread. |
| + |
| By default, the JVM common ForkJoinPool is used. |
| |
| [[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,role=external,window=_blank] |
| + |
| 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,role=external,window=_blank] |
| for detail. |
| + |
| Default is `false`. |
| |
| [[cache.openFiles]]cache.openFiles:: |
| + |
| The number of file descriptors to add to the limit set by the Gerrit daemon. |
| + |
| Persistent caches are stored on the file system and as such participate in the |
| file descriptors utilization. The number of file descriptors can vary depending |
| on the cache configuration and the specific backend used. |
| + |
| The additional file descriptors required by the cache should be accounted for |
| via this setting, so that the Gerrit daemon can adjust the ulimit accordingly. |
| + |
| 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 is 0. |
| |
| [[cache.name.maxAge]]cache.<name>.maxAge:: |
| + |
| Maximum age to keep an entry in the cache. |
| Values should use common unit suffixes to express their setting: |
| + |
| * s, sec, second, seconds |
| * m, min, minute, minutes |
| * h, hr, hour, hours |
| * d, day, days |
| * w, week, weeks (`1 week` is treated as `7 days`) |
| * mon, month, months (`1 month` is treated as `30 days`) |
| * y, year, years (`1 year` is treated as `365 days`) |
| |
| + |
| -- |
| If a unit suffix is not specified, `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 `"git_modified_files"`, `"modified_files"`, `"git_file_diff"`, |
| `"gerrit_file_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` |
| * `"git_modified_files"`: default is `10m` (10 MiB of memory) |
| * `"modified_files"`: default is `10m` (10 MiB of memory) |
| * `"git_file_diff"`: default is `10m` (10 MiB of memory) |
| * `"gerrit_file_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 |
| * `"groups_byuuid_persisted"`: default is `1g` (1 GiB of disk space) |
| * `"plugin_resources"`: default is 2m (2 MiB of memory) |
| |
| + |
| If set to 0 the cache is disabled; entries are loaded but not stored |
| in-memory. |
| |
| + |
| **NOTE**: When the cache is disabled, there is no locking when accessing |
| the same key/value, and therefore multiple threads may |
| load the same value concurrently with a higher memory footprint. |
| To keep a minimum caching and avoid concurrent loading of the same |
| key/value, set `memoryLimit` to `1` and `maxAge` to `1`. |
| |
| [[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 |
| * `"persisted_projects"`: default is `1g` (1 GiB of disk space) |
| |
| + |
| If 0 or negative, disk storage for the cache is disabled. |
| |
| [[cache.name.refreshAfterWrite]]cache.<name>.refreshAfterWrite:: |
| + |
| Duration after which we asynchronously refresh the cached value. |
| + |
| Values should use common unit suffixes to express their setting: |
| + |
| * ms, milliseconds |
| * s, sec, second, seconds |
| * m, min, minute, minutes |
| * h, hr, hour, hours |
| + |
| This applies only to these caches that support refreshing: |
| + |
| * `"projects"`: Caching project information in-memory. Defaults to 15 minutes. |
| |
| [[cache.refreshThreadPoolSize]]cache.refreshThreadPoolSize:: |
| + |
| Number of threads that are available to refresh cached values that became |
| out of date. This applies only to these caches that support refreshing: |
| + |
| * `"projects"`: Caching project information in-memory |
| + |
| Refreshes will only be scheduled on this executor if the values are |
| out of sync. |
| The check if they are is cheap and always happens on the thread that |
| inquires for a cached value. |
| + |
| Defaults to 2. |
| |
| ==== [[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 `"default_preferences"`:: |
| + |
| Caches the server's default general, edit and diff preferences. |
| + |
| Default value is 1 to hold only the most current version in-memory. |
| |
| 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 NoteDb change metadata in a repository is |
| modified outside of Gerrit. |
| |
| cache `"changes_by_project"`:: |
| + |
| Ideally, the memorylimit of this cache is large enough to cover all projects. |
| This should significantly speed up change ref advertisements and git pushes, |
| especially for projects with lots of changes, and particularly on replicas |
| where there is no index. |
| |
| cache `"git_modified_files"`:: |
| + |
| Each item caches the list of git modified files between two git trees |
| corresponding to two different commits. This cache does not read the actual |
| file contents nor does it include the edits (modified regions) of the files. |
| |
| cache `"modified_files"`:: |
| + |
| Each item caches the list of modified files between two commits. This cache |
| is similar to the `git_modified_files` cache but performs extra logic including |
| filtering out files that are untouched by both commits because they were purely |
| modified between the parent commits. |
| |
| cache `"git_file_diff"`:: |
| + |
| Each item caches the pure git diff between two git trees for a specific file |
| path. The diff includes all the file attributes (old/new paths, change/patch |
| types) as well as the list of edits corresponding to the modified regions in |
| the file. |
| |
| cache `"gerrit_file_diff"`:: |
| + |
| Each item caches the diff between two git commits for a specific file path. |
| This cache is similar to the `git_file_diff` cache but performs extra logic |
| including identifying the edits that are due to rebase. The diff for the |
| "commit message" and "merge list" can also be requested from this cache. |
| + |
| 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. The same applies for other diff caches: `"git_modified_files"`, |
| `"modified_files"` and `"git_file_diff"`. |
| |
| 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. |
| |
| 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 `"comment_context"`:: |
| + |
| Caches the context lines of comments, which are the lines of the source file |
| highlighted by the user when the comment was written. |
| |
| 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_byuuid_persisted"`:: |
| + |
| Caches the basic group information of internal groups by group UUID, |
| including the group owner, name, and description. |
| + |
| This is the persisted version of `groups_byuuid` cache. The intention of this |
| cache is to have an in-memory size of 0. |
| + |
| 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 `"groups_external"`:: |
| + |
| Caches all the external groups available to Gerrit. The cache holds a |
| single entry which maps to the latest available of all external groups' |
| UUIDs. This cache uses "groups_external_persisted" to load its value. |
| |
| cache `"groups_external_persisted"`:: |
| + |
| Caches all external groups available to Gerrit at some point in history. |
| The cache key is representation of a specific groups state in NoteDb and |
| the value is the list of all external groups. |
| The cache is persisted to enhance performance. |
| |
| 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 `"persisted_projects"`:: |
| + |
| Caches the project description records, from the `refs/meta/config` |
| branch of each project. This is the persisted variant of the |
| `projects` cache. The intention is for this cache to have an in-memory |
| size of 0. |
| |
| cache `"projects"`:: |
| + |
| Caches the project description records, from the `refs/meta/config` |
| branch of each project. 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. |
| |
| NOTE: This cache should be disabled or set with a low refreshAfterWrite |
| in a cluster setup using multiple primary or multiple replica nodes. |
| |
| cache `"prolog_rules"`:: |
| + |
| Caches parsed `rules.pl` contents for each project. This cache uses the same |
| size as the `projects` cache when `cache.prolog_rules.memoryLimit` is not set. |
| |
| cache `"pure_revert"`:: |
| + |
| Result of checking if one change or commit is a pure/clean revert of |
| another. |
| |
| cache `"soy_sauce_compiled_templates"`:: |
| + |
| Caches compiled soy templates. Stores at most only one key-value pair with |
| a constant key value and the value is a compiled SoySauce templates. The value |
| is reloaded automatically every few seconds if there are reads from the cache. |
| If cache is not used for 1 minute, the item is removed (i.e. emails can be send |
| with templates which are max 1 minute old). |
| |
| 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. |
| |
| NOTE: This cache should be disabled or set with a low refreshAfterWrite |
| in a cluster setup using multiple primary or multiple replica nodes. |
| |
| 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. |
| + |
| The `maxAge` configuration is also used for as maximum lifetime |
| of the HTTP servlet container session. |
| |
| See also link:cmd-flush-caches.html[gerrit flush-caches]. |
| |
| ==== [[cache_options]]Cache Options |
| |
| [[cache.git_file_diff.timeout]]cache.git_file_diff.timeout:: |
| + |
| Maximum number of milliseconds to wait for git 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.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. |
| |
| [[cache.project_list.interval]]cache.project_list.interval:: |
| + |
| The link:#schedule-configuration-interval[interval] for running |
| the project_list cache warmer. |
| |
| By default, if `cache.project_list.maxAge` is set, `interval` will be set to |
| half its value. If `cache.project_list.maxAge` is not set or `interval` is set |
| to `-1`, it is disabled. |
| |
| [[cache.project_list.startTime]]cache.project_list.startTime:: |
| + |
| The link:#schedule-configuration-startTime[start time] for running |
| the project_list cache warmer. |
| |
| Default is 00:00 if the project_list cache warmer is enabled. |
| |
| [[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 link:config-accounts.html[account data]. |
| + |
| 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.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 caches (`"git_modified_files"`, `modified_files`, `"git_file_diff"`, |
| `"file_diff"`). |
| + |
| 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 caches. If `false`, no extra data is |
| stored in the repository, only the diff caches. This can result in slight |
| performance improvements by reducing the number of refs in the repo. |
| + |
| Default is `true`. |
| |
| [[change.commentSizeLimit]]change.commentSizeLimit:: |
| + |
| Maximum allowed size in characters of a regular (non-robot) comment. Comments |
| which exceed this size will be rejected. Size computation is approximate and may |
| be off by roughly 1%. Common unit suffixes of 'k', 'm', or 'g' are supported. |
| The value must be positive. |
| + |
| The default limit is 16kiB. |
| |
| [[change.topicLimit]]change.topicLimit:: |
| + |
| Maximum allowed number of changes with the same topic. 0 or negative values |
| mean "unlimited". |
| + |
| By default 5,000. |
| |
| [[change.cumulativeCommentSizeLimit]]change.cumulativeCommentSizeLimit:: |
| + |
| Maximum allowed size in characters of all comments (including robot comments) |
| and change messages. Size computation is approximate and may be off by roughly |
| 1%. Common unit suffixes of 'k', 'm', or 'g' are supported. |
| + |
| The default limit is 3MiB. |
| |
| [[change.disablePrivateChanges]]change.disablePrivateChanges:: |
| + |
| If set to `true`, users are not allowed to create private changes. |
| + |
| The default is `false`. |
| |
| [[change.maxComments]]change.maxComments:: |
| + |
| Maximum number of comments (regular plus robot) allowed per change. Additional |
| comments are rejected. |
| + |
| By default 5,000. |
| |
| [[change.maxFiles]]change.maxFiles:: |
| + |
| Maximum number of files allowed per change. Larger changes are rejected and must |
| be split up. For merge changes we are comparing against the auto-merge commit, |
| so we allow large merges, if they merge cleanly. |
| + |
| By default 100,000. |
| |
| [[change.maxFileSizeDownload]]change.maxFileSizeDownload:: |
| + |
| The link:rest-api-changes.html#get-content[GetContent] and |
| link:rest-api-changes.html#get-safe-content[DownloadContent] REST APIs will |
| refuse to load files larger than this limit (in bytes). 0 or negative values |
| mean "unlimited". |
| |
| + |
| By default 0 (unlimited). |
| |
| [[change.maxPatchSets]]change.maxPatchSets:: |
| + |
| Maximum number of patch sets allowed per change. If this is insufficient, |
| recreate the change with a new Change-Id, then abandon the old change. |
| + |
| By default 1000. |
| |
| [[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.mergeabilityComputationBehavior]]change.mergeabilityComputationBehavior:: |
| + |
| This setting determines when Gerrit computes if a change is mergeable or not. |
| This computation is expensive, especially when the repository is large or when |
| there are many open changes. |
| + |
| This config can have the following states: |
| + |
| * `API_REF_UPDATED_AND_CHANGE_REINDEX`: Gerrit indexes `mergeability` enabling |
| the `is:mergeable` predicate in change search and allowing fast retrieval of |
| this bit in query responses. Gerrit will always serve `mergeable` in |
| link:rest-api-changes.html#change-info[ChangeInfo] objects. |
| Gerrit will reindex all open changes when the target ref advances (expensive). |
| * `REF_UPDATED_AND_CHANGE_REINDEX`: Gerrit indexes `mergeability` enabling the |
| `is:mergeable` predicate in change search and allowing fast retrieval of this |
| bit in query responses. Gerrit will never serve `mergeable` in |
| link:rest-api-changes.html#change-info[ChangeInfo] |
| objects. This state can be a final state for instances that only want to |
| optimize the read path, but not the write path for speed or serve as an |
| intermediary step for instances that want to optimize both and need to migrate |
| callers of their API. |
| Gerrit will reindex all open changes when the target ref advances (expensive). |
| * `NEVER`: Gerrit does not index `mergeable`, so `is:mergeable` is disabled as |
| query operator. Gerrit does not serve `mergeable` in |
| link:rest-api-changes.html#change-info[ChangeInfo]. |
| |
| NOTE: Gerrit would only render conflict changes section on change |
| screen if `API_REF_UPDATED_AND_CHANGE_REINDEX` value is set. |
| |
| Default is `NEVER`. |
| |
| [[change.conflictsPredicateEnabled]]change.conflictsPredicateEnabled:: |
| |
| + |
| This setting determines when Gerrit renders conflict changes section on change |
| screen and also supports `conflicts` predicate. This computation is expensive, |
| computing ConflictsPredicate has a runtime complexity of O(nˆ2) with n number |
| of open changes on a branch. When set to `false` GUI will silently ignore the |
| error message and leave the conflict changes section on change screen empty. |
| See also implications on rendering of conflict changes section in configuration |
| section:link:#change.mergeabilityComputationBehavior[change.mergeabilityComputationBehavior]. |
| |
| Default is `true`. |
| |
| [[change.maxSubmittableAtOnce]]change.maxSubmittableAtOnce:: |
| + |
| Maximum number of changes that can be chained together in the same repository |
| to be submitted at once. |
| + |
| Default is 32767. |
| |
| [[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://issues.gerritcodereview.com/issues/40009784[issue 40009784]). |
| + |
| By default `true`. |
| |
| [[change.enableRobotComments]]change.enableRobotComments:: |
| + |
| Are robot comments enabled in the Gerrit UI? This setting allows phasing out |
| robot comments. |
| + |
| By default `true`. |
| |
| [[change.propagateSubmitRequirementErrors]]change.propagateSubmitRequirementErrors:: |
| + |
| If set, requests that access the submit requirements of a change fail with an |
| HTTP 500 error if the change has a submit requirement with a non-parseable |
| expression that would otherwise result in an |
| link:config-submit-requirements#status-error[ERROR] status for the submit |
| requirement. |
| + |
| Submit requirement expressions can become non-parseable due to bypassing the |
| validation that normally happens when updating the project configuration in |
| the `refs/meta/config` branch, or due to bugs in Gerrit. |
| + |
| A special case are expressions that use plugin-provided predicates. If any |
| plugin that provides a predicate fails to load (e.g. due to an error in the |
| plugin) the predicate can no longer be resolved and expressions that are using |
| it can no longer be parsed. This is an error that requires the attention of the |
| team that operates Gerrit, but in order to get notified when this happens the |
| operation team would need to setup custom monitoring that observes whether |
| link:config-submit-requirements#status-error[ERROR] statuses are returned for |
| submit requirements. Instead this config option can be used to make |
| non-parseable submit requirement expressions cause HTTP 500 errors which |
| triggers the automatic alerting for errors that Gerrit operation teams usually |
| have in place. This allows the operation team to react quickly when this |
| happens. |
| + |
| The drawback of enabling this option is that it causes requests to fail rather |
| than handling parsing errors gracefully, which can make Gerrit for impacted |
| users unusable. |
| |
| [[change.robotCommentSizeLimit]]change.robotCommentSizeLimit:: |
| + |
| Maximum allowed size in characters of a robot comment. Robot comments which |
| exceed this size will be rejected on addition. Size computation is approximate |
| and may be off by roughly 1%. Common unit suffixes of 'k', 'm', or 'g' are |
| supported. Zero or negative values allow robot comments of unlimited size. |
| + |
| The default limit is 1MiB. |
| |
| [[change.sendNewPatchsetEmails]]change.sendNewPatchsetEmails:: |
| + |
| When `false`, emails will not be sent to owners, reviewers, and cc for |
| creating a new patchset unless they are project watchers or have starred |
| the change. |
| + |
| Default is `true`. |
| |
| [[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. |
| |
| [[change.diff3ConflictView]]change.diff3ConflictView:: |
| + |
| Use the diff3 formatter for merge commits with conflicts. With diff3 when |
| the conflicts are shown in the "Auto Merge" view, the base section from the |
| common parents will be shown as well. |
| This setting takes effect when generating the automerge, which happens on upload. |
| Changing the setting leaves existing changes unaffected. |
| + |
| Default is `false`. |
| |
| [[change.maxFileSizeDiff]]change.maxFileSizeDiff:: |
| + |
| The threshold of file sizes in megabytes beyond which a |
| link:rest-api-changes.html#get-diff[file diff] request will fail. |
| + |
| If not set or set to zero, no limits are applied on file sizes. |
| |
| [[change.skipCurrentRulesEvaluationOnClosedChanges]]change.skipCurrentRulesEvaluationOnClosedChanges:: |
| + |
| If `false`, Gerrit will always take latest project configuration to |
| compute submit labels. This means that, closed changes (either merged |
| or abandoned) will be evaluated against the latest configuration which |
| may produce different results. Especially for merged changes, they may |
| look like they didn't meet the submit requirements. |
| + |
| When `true`, evaluation will be skipped and Gerrit will show the |
| exact status of submit labels when change was submitted. Post-review |
| votes will only be allowed on labels that were configured when change |
| was closed. |
| + |
| Default is `false`. |
| |
| [[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. When set |
| to `false`, `-is:mergeable` is appended to the query used to find |
| the changes to auto-abandon. |
| + |
| By default `true`, meaning mergeable changes are auto-abandoned. |
| + |
| If |
| link:#change.mergeabilityComputationBehavior[`change.mergeabilityComputationBehavior`] |
| is set to `NEVER`, setting this option to `false` has no effect and it behaves |
| as though it were set to `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. |
| |
| [[attentionSet]] |
| === Section attentionSet |
| |
| This section allows to configure readding of change owners and schedules them to |
| run periodically. |
| |
| [[attentionSet.readdAfter]]attentionSet.readdAfter:: |
| + |
| Period of inactivity after which open no-WIP/private changes should have change owner |
| added to attention-set automatically (if they are not already). |
| + |
| By default `0`, never readd change owner. |
| + |
| [WARNING] Auto-readding change owners 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`) |
| |
| [[attentionSet.readdMessage]]attentionSet.readdMessage:: |
| + |
| Attention-set message that should be shown as reason when an change owner is readded. |
| + |
| '${URL}' can be used as a placeholder for the Gerrit web URL. |
| + |
| By default "Owner readded to attention-set due to inactivity, see |
| ${URL}Documentation/user-attention-set.html#auto-readd-owner\n\n |
| If you do not want to be readded to the attention-set when the timer has counted down. |
| Set this change as WIP or private.". |
| |
| [[attentionSet.startTime]]attentionSet.startTime:: |
| + |
| The link:#schedule-configuration-startTime[start time] for running |
| readd owner to attention-set. |
| |
| [[attentionSet.interval]]attentionSet.interval:: |
| + |
| The link:#schedule-configuration-interval[interval] for running |
| readd owner to attention-set. |
| |
| 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. |
| |
| Before matching is done the relevant contents are html-escaped. If 'match' needs |
| to contain `&`, `<`, `>`, `"` or `'`, replace them with `&`, `>`, |
| `<`, `"` and `'` respectively. |
| |
| 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 = "(^|\\s)(bug\\s+#?)(\\d+)($|\\s)" |
| link = http://bugs.example.com/show_bug.cgi?id=$3 |
| prefix = $1 |
| suffix = $4 |
| text = $2$3 |
| ---- |
| |
| Comment links can also be specified in `project.config` and sections in |
| children override those in parents. |
| |
| [[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+)`. |
| + |
| In order to better control the visual presentation of the link `prefix`, |
| `suffix` and `text` is used. With the generated link html looking like: |
| `prefix<a ...>text</a>suffix`. |
| |
| [[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'`. |
| |
| [[commentlink.name.prefix]]commentlink.<name>.prefix:: |
| + |
| The text inserted before the link. Groups in the match expression may be |
| accessed as `$'n'`. |
| |
| [[commentlink.name.suffix]]commentlink.<name>.suffix:: |
| + |
| The text inserted after the link. Groups in the match expression may be |
| accessed as `$'n'`. |
| |
| [[commentlink.name.text]]commentlink.<name>.text:: |
| + |
| The text content of the link. Groups in the match expression may be |
| accessed as `$'n'`. |
| + |
| If not specified defaults to `$&` (the matched text). |
| |
| [[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`. |
| + |
| 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 |
| ---- |
| + |
| Gerrit built-in loggers are then ignored: error logger (`error_log` file), |
| link:#httpd.requestLog[httpd.requestLog] and |
| link:#sshd.requestLog[sshd.requestLog]. The |
| link:#log.jsonLogging[log.jsonLogging] and |
| link:#log.textLogging[log.textLogging] options are also ignored. |
| |
| [[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.shutdownTimeout]]container.shutdownTimeout:: |
| + |
| The maximum time (in seconds) to wait for a gerrit.sh stop command. |
| This is added to the highest value between either 'sshd.gracefulStopTimeout' |
| or 'httpd.gracefulStopTimeout'. If not set, defaults to |
| 30 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,role=external,window=_blank], 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. |
| |
| [[core.usePerRequestRefCache]]core.usePerRequestRefCache:: |
| + |
| Use a per request (currently per request thread) ref cache. The ref |
| cache uses JGit's SnapshottingRefDirectory to ensure that packed |
| refs are checked and potentially read at least once per request |
| (lazily) if needed. This helps reduce the overhead of checking if |
| the packed-refs file is outdated. |
| + |
| Default is `true`. |
| |
| [[dashboard]] |
| === Section dashboard |
| |
| [[dashboard.submitRequirementColumns]]dashboard.submitRequirementColumns:: |
| + |
| The list of submit requirement names that should be displayed as separate |
| columns in the dashboard. |
| |
| [[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 |
| hide = ssh |
| ---- |
| |
| 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` |
| + |
| Gerrit advertises patch set downloads with the `repo download` |
| command, assuming that all projects managed by this instance are |
| generally worked on with the |
| https://gerrit.googlesource.com/git-repo[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.hide]]download.hide:: |
| + |
| Schemes that can be used to download changes, but will not be advertised |
| in the UI. This can be any scheme that can be configured in <<download.scheme>>. |
| + |
| This is mostly useful in a deprecation scenario during a time where using |
| a scheme is discouraged, but has to be supported until all clients have |
| migrated to use a different scheme. |
| + |
| By default, no scheme will be hidden in the UI. |
| |
| [[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. |
| |
| [[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`. |
| + |
| The link:#cache_names[persisted_projects cache] must be |
| flushed after this setting is changed. |
| + |
| Defaults to `All-Projects` if not set. |
| |
| [[gerrit.defaultBranch]]gerrit.defaultBranch:: |
| + |
| Name of the link:project-configuration.html#default-branch[default branch] |
| to use on the project creation, if no other branches were specified in the input. |
| + |
| Defaults to `refs/heads/master` 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 it is 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.installBatchModule]]gerrit.installBatchModule:: |
| + |
| Repeatable list of class name of additional Guice modules to load as |
| override to the batchInjector's modules 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.installDbModule]]gerrit.installDbModule:: |
| + |
| Repeatable list of class name of additional Guice modules to load at |
| Gerrit startup as part of the dbInjector. |
| 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.installIndexModule]]gerrit.installIndexModule:: |
| + |
| Class name of the Guice modules to load as alternate implementation |
| for the Gerrit indexes backend. |
| 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. |
| + |
| NOTE: The `gerrit.installIndexModule` has precedence over the |
| `index.type`. |
| + |
| By default unset. |
| + |
| Example: |
| ---- |
| [gerrit] |
| installIndexModule = com.google.gerrit.elasticsearch.ElasticIndexModule |
| ---- |
| |
| [[gerrit.installModule]]gerrit.installModule:: |
| + |
| Repeatable list of class name of additional Guice modules to load at |
| Gerrit startup as part of the sysInjector. |
| 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 |
| installBatchModule = com.example.ghi.CustomBatchInitModule |
| ---- |
| |
| [[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.enablePeerIPInReflogRecord]]gerrit.enablePeerIPInReflogRecord:: |
| |
| Record actual peer IP address in ref log entry for identified user. |
| |
| Defaults to `false`. |
| |
| [[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 Gerrit's static resources if using a CDN. |
| |
| [[gerrit.faviconPath]]gerrit.faviconPath:: |
| + |
| Path for Gerrit's favicon after link:#gerrit.canonicalWebUrl[default URL], |
| including icon name and extension (.ico should be used). |
| |
| [[gerrit.instanceId]]gerrit.instanceId:: |
| + |
| Optional identifier for this Gerrit instance. |
| Used to identify a specific instance within a group of Gerrit instances with the |
| same `serverId` (i.e.: a Gerrit cluster). |
| Unlike `instanceName` this value is not available in the email templates. |
| |
| The instance ID can also be configured by setting the Java system property |
| `gerrit.instanceId` on startup. This will override the configuration in the |
| gerrit.config. |
| |
| [[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.2 is version N (All-Projects:refs/meta/version=183) |
| then its next version N+1 is v3.3 (All-Projects:refs/meta/version=184). |
| 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 (where applicable) |
| 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.importedServerId]]gerrit.importedServerId:: |
| + |
| ServerId of the repositories imported from other Gerrit servers. Changes coming |
| associated with the imported serverIds are indexed and displayed in the UI |
| but they are not searchable by `changeNumber` therefore the |
| `index.cacheQueryResultsByChangeNum` must also be set to `false`. |
| Imported changes are still discoverable in any other ways, for example: |
| |
| project:someproject branch:main changeId:I78a7add1fe2597cad788c833d8f771f09b54cf33 |
| + |
| Specify multiple `gerrit.importedServerId` for allowing the import from multiple |
| Gerrit servers with different serverIds. |
| + |
| [NOTE] |
| The account-ids referenced in the imported changes are used for looking up the |
| associated account-id locally, using the `imported:` external-id. |
| Example: the account-id 1000 from the imported server-id 59a4964e-6376-4ed9-beef |
| will be looked up in the local accounts using the `imported:1000@59a4964e-6376-4ed9-beef` |
| external-id. |
| + |
| If this value is not set, all changes imported from other Gerrit servers will be |
| ignored. |
| + |
| By default empty. |
| |
| [[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 SHA-1 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 SHA-1 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, `${hash}` for the SHA-1 hash for the commit, |
| and `${commit}` for the change ref or SHA-1 of the commit if no base |
| patch set. |
| |
| [[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,role=external,window=_blank], |
| allow using an alternative path separator character. In Gitblit, this can be |
| configured through the property link:http://gitblit.com/properties.html[web.forwardSlashCharacter,role=external,window=_blank]. |
| 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.auditLog.ignoreRecordsFromUnidentifiedUsers]]groups.auditLog.ignoreRecordsFromUnidentifiedUsers:: |
| + |
| Controls whether AuditLogReader should ignore commits created by unidentified users. |
| If `true`, then AuditLogReader ignores commits in the refs/groups/* made by unidentified users (i.e. |
| when the author of a commit can't be parsed as account id). |
| + |
| The current version of Gerrit writes identified users as authors for new refs/groups/* commits. |
| However, some old versions used a server identity as the author (e.g. "Gerrit Code Review |
| <server@googlesource.com>") for such commits. Such string can't be converted to account id but |
| usually the commit shouldn't be ignored. |
| + |
| By default, `false`. |
| + |
| Setting it to `true` may lead to some unexpected results in audit log and must be set carefully. |
| |
| [[groups.includeExternalUsersInRegisteredUsersGroup]]groups.includeExternalUsersInRegisteredUsersGroup:: |
| + |
| Controls whether external users (these are users we have sufficient |
| knowledge about but who don't yet have a Gerrit account) are considered |
| to be members of the `REGISTERED_USERS` group. |
| + |
| This setting only makes sense if you run custom code (e.g. from a plugin |
| or a custom authentication backend). By default, Gerrit core always requires |
| users to register and doesn't use external users. |
| + |
| By default, `true`. |
| |
| [[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. |
| |
| [[groups.relevantGroup]]groups.relevantGroup:: |
| + |
| UUID of an external group that should always be considered as relevant |
| when checking whether an account is visible. |
| + |
| This setting is only relevant for external group backends and only if |
| the link:#accounts.visibility[account visibility] is set to |
| `SAME_GROUP` or `VISIBLE_GROUP`. |
| + |
| If the link:#accounts.visibility[account visibility] is set to |
| `SAME_GROUP` or `VISIBLE_GROUP` users should see all accounts that are |
| a member of a group that contains themselves or that is visible to |
| them. Checking this would require getting all groups of the current |
| user and all groups of the accounts for which the visibility is being |
| checked, but since getting all groups that a user is a member of is |
| expensive for external group backends Gerrit doesn't query these groups |
| but instead guesses the relevant groups. Guessing relevant groups |
| limits the inspected groups to all groups that are mentioned in the |
| ACLs of the projects that are currently cached (i.e. all groups that |
| are listed in the link:config-project-config.html#file-groups[groups] |
| files of the cached projects). This is not very reliable since it |
| depends on which groups are mentioned in the ACLs and which projects |
| are currently cached. To make this more reliable this configuration |
| parameter allows to configure external groups that should always be |
| considered as relevant. |
| + |
| As said this setting is only relevant for external group backends. In |
| Gerrit core this is only the LDAP backend, but it may apply to further |
| group backends that are added by plugins. |
| + |
| This parameter may be added multiple times to specify multiple relevant |
| groups. |
| |
| [[has-operand-alias]] |
| === Section has operand alias |
| |
| 'has' operand aliasing allows global aliases to be defined for query |
| 'has' operands. Currently only change queries are supported. The alias |
| name is the git config key name, and the 'has' operand being aliased |
| is the git config value. |
| |
| For example: |
| |
| ---- |
| [has-operand-alias "change"] |
| oldtopic = topic |
| ---- |
| |
| This section is particularly useful to alias 'has' operands (which may |
| be long and clunky as they include a plugin name in them) to shorter |
| operands without the plugin name. Admins should take care to choose |
| shorter operands that are unique and unlikely to conflict in the future. |
| |
| Aliases are resolved dynamically at invocation time to the currently |
| loaded version of plugins. If a referenced plugin is not loaded, or |
| does not define the command, "unsupported operand" is returned to the |
| user. |
| |
| Aliases will override existing 'has' operands. In case of multiple |
| aliases with same name, the last one defined will be used. |
| |
| When the target of an alias does not exist, the 'has' operand with the |
| name of the alias will be used (if present). This enables an admin to |
| configure the system to override a core 'has' operand with an operand |
| provided by a plugin when present and otherwise fall back to the 'has' |
| operand provided by core. |
| |
| [[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,role=external,window=_blank]. |
| + |
| [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 |
| ---- |
| |
| [[filterClass.className.initParam]]filterClass.<className>.initParam:: |
| + |
| Gerrit supports customized pluggable HTTP filters as `filterClass`. This |
| option allows to pass extra initialization parameters to the filter. It |
| allows for multiple key/value pairs to be passed in this pattern: |
| + |
| ---- |
| initParam = <key>=<value> |
| ---- |
| For a comprehensive example: |
| + |
| ---- |
| [httpd] |
| filterClass = org.anyorg.AFilter |
| filterClass = org.anyorg.BFilter |
| [filterClass "org.anyorg.AFilter"] |
| key1 = value1 |
| key2 = value2 |
| [filterClass "org.anyorg.BFilter"] |
| key3 = value3 |
| ---- |
| |
| [[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:: |
| + |
| *(DEPRECATED)* The only supported value is `LUCENE`, which is the default, |
| that means a link:http://lucene.apache.org/[Lucene] |
| index is used. |
| + |
| For using other indexing backends (e.g. ElasticSearch), refer to |
| `gerrit.installIndexModule` setting. |
| + |
| [[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 the default 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.cacheQueryResultsByChangeNum]]index.cacheQueryResultsByChangeNum:: |
| + |
| Allow to cache and reuse the change JSON elements by their Change number. |
| This improves the performance of queries that are returning Changes duplicates. |
| It needs to be turned off when having Changes imported from other servers |
| because of the potential conflicts of change numbers. |
| + |
| Defaults to `true`. |
| |
| [[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.excludeProjectFromChangeReindex]]index.excludeProjectFromChangeReindex:: |
| + |
| A list of projects that will be excluded from reindexing. This can be used |
| to exclude projects which are expensive to reindex to prioritize the other |
| projects. |
| + |
| Excluded projects can later be reindexed by for example using the |
| link:cmd-index-changes-in-project.html[index changes in project command]. |
| |
| [[index.paginationType]]index.paginationType:: |
| + |
| The pagination type to use when index queries are repeated to |
| obtain the next set of results. Supported values are: |
| + |
| * `OFFSET` |
| + |
| Index queries are repeated with a non-zero offset to obtain the |
| next set of results. |
| _Note: Results may be inaccurate if the data-set is changing during the query |
| execution._ |
| + |
| * `SEARCH_AFTER` |
| + |
| Index queries are repeated using a search-after object. Index |
| backends can provide their custom implementations for search-after. |
| Note that, `SEARCH_AFTER` does not impact using offsets in Gerrit |
| query APIs. |
| _Note: Depending on the index backend and its settings, results may be |
| inaccurate if the data-set is changing during the query execution._ |
| + |
| * `NONE` |
| + |
| Index queries are executed returning all results, without internal |
| pagination. |
| _Note: Since the entire set of indexing results is kept in memory |
| during the API execution, this option may lead to higher memory utilisation |
| and overall reduced performance. |
| Bear in mind that some indexing backends may not support unbounded queries; |
| therefore, the NONE option is unavailable._ |
| + |
| Defaults to `OFFSET`. |
| |
| [[index.defaultLimit]]index.defaultLimit:: |
| + |
| Default limit, if the user does not provide a limit. If this is not set or set |
| to 0, then index queries are executed with the maximum permitted limit for the |
| user, which may be really high and cause too much load on the index. Thus |
| setting this default limit to something smaller like 100 allows you to control |
| the load, while not taking away any permission from the user. If the user |
| provides a limit themselves, then `defaultLimit` is ignored. |
| |
| [[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 `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.pageSizeMultiplier]]index.pageSizeMultiplier:: |
| + |
| When index queries are repeated to obtain more results, this multiplier |
| will be used to determine the limit for the next query. Using a page |
| multiplier allows queries to start off small and thus provide good |
| latency for queries which may end up only having very few results, and |
| then scaling up to have better throughput to handle queries with larger |
| result sets without incurring the overhead of making as many queries as |
| would be required with a smaller limit. This strategy of using a multiplier |
| attempts to create a balance between latency and throughput by dynamically |
| adjusting the query size to the number of results being returned by each |
| query in the pagination. |
| + |
| The larger the multiplier, the better the throughput on large queries, and |
| it also improves latency on large queries by scaling up quickly. However, a |
| larger multiplier can hurt latencies a bit by making the "last" query in a |
| series longer than needed. The impact of this depends on how much the backend |
| latency goes up when specifying a large limit and few results are returned. |
| Setting link:#index.maxPageSize[index.maxPageSize] that isn't too large, can |
| likely help reduce the impacts of this. |
| + |
| For example, if the limit of the previous query was 500 and pageSizeMultiplier |
| is configured to 5, the next query will have a limit of 2500. |
| + |
| _Note: ignored when paginationType is `NONE`_ |
| + |
| Defaults to 1 which effectively turns this feature off. |
| |
| [[index.maxPageSize]]index.maxPageSize:: |
| + |
| Maximum size to allow when index queries are repeated to obtain more results. Note |
| that, link:#index.maxLimit[index.maxLimit] will be used to limit page size if it |
| is configured to a value lower than maxPageSize. |
| + |
| For example, if the limit of previous query was 500, pageSizeMultiplier is |
| configured to 5 and maxPageSize to 2000, the next query will have a limit of |
| 2000 (instead of 2500). |
| + |
| _Note: ignored when paginationType is `NONE`_ |
| + |
| 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.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.indexChangesAsync]]index.indexChangesAsync:: |
| + |
| On BatchUpdate, do not await indexing completion before returning the request |
| to the user (WEB_BROWSER requests only). |
| This has an advantage of faster UI (because indexing latency does not contribute |
| to the write request latency) and disadvantage that the indexing result might not be |
| immediately available after the write request. |
| + |
| 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. |
| + |
| 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,role=external,window=_blank] 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,role=external,window=_blank] 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,role=external,window=_blank] 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,role=external,window=_blank] 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,role=external,window=_blank] |
| + |
| 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,role=external,window=_blank] for further details. |
| + |
| Defaults to `true` (throttling enabled). |
| |
| During offline reindexing, setting ramBufferSize greater than the size |
| of index (size of specific index folder under <site_dir>/index) and |
| maxBufferedDocs as -1 avoids unnecessary flushes and triggers only a |
| single flush at the end of the process. |
| |
| 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 |
| |
| ---- |
| |
| [[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_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. |
| |
| [[event.comment-added.publishPatchSetLevelComment]]event.comment-added.publishPatchSetLevelComment:: |
| + |
| Add patch set level comment as event comment. Without this option, patch set |
| level comment will not be included in the event comment attribute. Given that |
| currently patch set level, file and robot comments are not exposed in the |
| `comment-added` event type, those comments will be lost. One particular use |
| case is to re-trigger CI build from the change screen by adding a comment with |
| specific content, e.g.: `recheck`. Jenkins Gerrit Trigger plugin and Zuul CI |
| depend on this feature to trigger change verification. |
| + |
| By default, `true`. |
| |
| [[event.stream-events.enableRefUpdatedEvents]]event.stream-events.enableRefUpdatedEvents:: |
| + |
| Enable streaming of `ref-updated` event which represents a single ref update operation. |
| Batch ref updates are represented as a series of `ref-updated` events. |
| This allows event listeners to react on a ref update. |
| Please consider switching to `batch-ref-updated` event which provides better control on grouping and |
| preserving order of the ref updates. |
| + |
| By default, `true`. |
| |
| [[event.stream-events.enableBatchRefUpdatedEvents]]event.stream-events.enableBatchRefUpdatedEvents:: |
| + |
| Enable streaming of `batch-ref-updated` event which represents group of |
| refs updated during a single batch ref update operation. |
| Single ref updates are also streamed as a `batch-ref-updated` events with a single ref specified. |
| This allows event listeners to react on all ref updated events and disable individual `ref-updated` |
| events by setting <<event.stream-events.enableRefUpdatedEvents, event.stream-events.enableRefUpdatedEvents>> to `false`. |
| + |
| By default, `false`. |
| |
| [[event.stream-events.enableDraftCommentEvents]]event.stream-events.enableDraftCommentEvents:: |
| + |
| Enable streaming of `ref-updated` events for `refs/draft-comments` refs. |
| Enable this flag in case listeners in your system are supposed to react on draft operations. |
| + |
| NOTE: Due to the nature of drafts, the amount of `ref-updated` events created on draft operations could be high. |
| The extra amount of events depends on the usage pattern of the installation. It is worth evaluating |
| the amount of extra events produced before enabling this flag by counting the calls to the draft APIs. |
| + |
| By default, `false`. |
| |
| [[experiments]] |
| === Section experiments |
| |
| This section covers experimental new features. Gerrit uses experiments |
| to research new behavior in frontend and core backend. Once the research is done, the experimental |
| feature either stays and the experimentation flag gets removed, or the feature as a whole |
| gets removed |
| |
| [[experiments.enabled]]experiments.enabled:: |
| + |
| List of experiments that are currently enabled. The release notes contain currently |
| available experiments. |
| + |
| We will not remove experiments in stable patch releases. They are likely to be |
| removed in the next stable version. |
| |
| ---- |
| [experiments] |
| enabled = ExperimentKey |
| ---- |
| |
| [[experiments.disabled]]experiments.disabled:: |
| + |
| List of experiments that are currently disabled. The release notes contain currently |
| available experiments. This list disables experiments with the given key that are |
| either enabled by default or explicitly in the config. |
| |
| ---- |
| [experiments] |
| disabled = ExperimentKey |
| ---- |
| |
| [[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,role=external,window=_blank], Active |
| Directory and link:https://www.freeipa.org[FreeIPA,role=external,window=_blank]. |
| |
| ---- |
| [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. |
| + |
| If you want to configure multiple ldap servers you can try to put |
| multiple ldap urls separated by a space: |
| `server = ldaps://ldap1 ldaps://ldap2` |
| See https://issues.gerritcodereview.com/issues/40010644[issue 40010644]. |
| |
| [[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}`. |
| + |
| Default is `displayName` for FreeIPA and RFC 2307 servers, |
| and `${givenName} ${sn}` for Active Directory. |
| + |
| A non-empty or default value prevents users from modifying their full |
| name field. To allow edits to the full name field, set to the empty |
| string. |
| |
| [[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. |
| + |
| For example, setting to `ldap/gerritaccess` limits account creation or |
| authentication to members of the ldap group `gerritaccess`. |
| + |
| 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 |
<