| = 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. If you modify any properties in this file, Gerrit needs |
| to be restarted before it will use the new values. |
| |
| Sample `etc/gerrit.config`: |
| ---- |
| [core] |
| packedGitLimit = 200 m |
| |
| [cache] |
| directory = /var/cache/gerrit2 |
| ---- |
| |
| [[accounts]] |
| === Section accounts |
| |
| [[accounts.visibility]]accounts.visibility:: |
| + |
| Controls visibility of other users' dashboard pages and |
| completion suggestions to web users. |
| + |
| If `ALL`, all users are visible to all other users, even |
| anonymous users. |
| + |
| If `SAME_GROUP`, only users who are also members of a group the |
| current user is a member of are visible. |
| + |
| If `VISIBLE_GROUP`, only users who are members of at least one group |
| that is visible to the current user are visible. |
| + |
| If `NONE`, no users other than the current user are visible. |
| + |
| Default is `ALL`. |
| |
| [[addreviewer]] |
| === Section addreviewer |
| |
| [[addreviewer.maxWithoutConfirmation]]addreviewer.maxWithoutConfirmation:: |
| + |
| The maximum number of reviewers a user can add at once by adding a |
| group as reviewer without being asked to confirm the operation. |
| + |
| If set to 0, the user will never be asked to confirm adding a group |
| as reviewer. |
| + |
| Default is 10. |
| + |
| This setting only applies for adding reviewers in the Gerrit Web UI, |
| but is ignored when adding reviewers with the |
| link:cmd-set-reviewers.html[set-reviewers] command. |
| |
| [[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. |
| |
| [[auth]] |
| === Section auth |
| |
| See also link:config-sso.html[SSO configuration]. |
| |
| [[auth.type]]auth.type:: |
| + |
| Type of user authentication employed by Gerrit. The supported |
| values are: |
| + |
| * `OpenID` |
| + |
| The default setting. Gerrit uses any valid OpenID |
| provider chosen by the end-user. For more information see |
| http://openid.net/[openid.net]. |
| + |
| * `OpenID_SSO` |
| + |
| Supports OpenID from a single provider. There is no registration |
| link, and the "Sign In" link sends the user directly to the provider's |
| SSO entry point. |
| + |
| * `HTTP` |
| + |
| Gerrit relies upon data presented in the HTTP request. This includes |
| HTTP basic authentication, or some types of commercial single-sign-on |
| solutions. With this setting enabled the authentication must |
| take place in the web server or servlet container, and not from |
| within Gerrit. |
| + |
| * `HTTP_LDAP` |
| + |
| Exactly like `HTTP` (above), but additionally Gerrit pre-populates |
| a user's full name and email address based on information obtained |
| from the user's account object in LDAP. The user's group membership |
| is also pulled from LDAP, making any LDAP groups that a user is a |
| member of available as groups in Gerrit. |
| + |
| * `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. |
| Therefore, the "_LDAP" suffix in the name of this authentication type. |
| 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`. |
| |
| * `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. |
| + |
| * `DEVELOPMENT_BECOME_ANY_ACCOUNT` |
| + |
| *DO NOT USE*. Only for use in a development environment. |
| + |
| When this is the configured authentication method a hyperlink titled |
| `Become` appears in the top right corner of the page, taking the |
| user to a form where they can enter the username of any existing |
| user account, and immediately login as that account, without any |
| authentication taking place. This form of authentication is only |
| useful for the GWT hosted mode shell, where OpenID authentication |
| redirects might be risky to the developer's host computer, and HTTP |
| authentication is not possible. |
| |
| + |
| By default, OpenID. |
| |
| [[auth.allowedOpenID]]auth.allowedOpenID:: |
| + |
| List of permitted OpenID providers. A user may only authenticate |
| with an OpenID that matches this list. Only used if `auth.type` |
| is set to `OpenID` (the default). |
| + |
| Patterns may be either a |
| link:http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html[standard |
| Java regular expression (java.util.regex)] (start with `^` and |
| end with `$`) or be a simple prefix (any other string). |
| + |
| By default, the list contains two values, `http://` and `https://`, |
| allowing users to authenticate with any OpenID provider. |
| |
| [[auth.trustedOpenID]]auth.trustedOpenID:: |
| + |
| List of trusted OpenID providers. Only used if `auth.type` is |
| set to `OpenID` (the default). |
| + |
| In order for a user to take advantage of permissions beyond those |
| granted to the `Anonymous Users` and `Registered Users` groups, |
| the user account must only have OpenIDs which match at least one |
| pattern from this list. |
| + |
| Patterns may be either a |
| link:http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html[standard |
| Java regular expression (java.util.regex)] (start with `^` and |
| end with `$`) or be a simple prefix (any other string). |
| + |
| By default, the list contains two values, `http://` and `https://`, |
| allowing Gerrit to trust any OpenID it receives. |
| |
| [[auth.openIdDomain]]auth.openIdDomain:: |
| + |
| List of allowed OpenID email address domains. Only used if |
| `auth.type` is set to `OPENID` or `OPENID_SSO`. |
| + |
| Domain is case insensitive and must be in the same form as it |
| appears in the email address, for example, "example.com". |
| + |
| By default, any domain is accepted. |
| |
| [[auth.maxOpenIdSessionAge]]auth.maxOpenIdSessionAge:: |
| + |
| Time in seconds before an OpenID provider must force the user |
| to authenticate themselves again before authentication to this |
| Gerrit server. Currently this is only a polite request, and users |
| coming from providers that don't support the PAPE extension will |
| be accepted anyway. In the future it may be enforced, rejecting |
| users coming from providers that don't honor the max session age. |
| + |
| If set to 0, the provider will always force the user to authenticate |
| (e.g. supply their password). Values should use common unit suffixes |
| to express their setting: |
| + |
| * s, sec, second, seconds |
| * m, min, minute, minutes |
| * h, hr, hour, hours |
| * d, day, days |
| * w, week, weeks (`1 week` is treated as `7 days`) |
| * mon, month, months (`1 month` is treated as `30 days`) |
| * y, year, years (`1 year` is treated as `365 days`) |
| |
| + |
| Default is -1, permitting infinite time between authentications. |
| |
| [[auth.registerEmailPrivateKey]]auth.registerEmailPrivateKey:: |
| + |
| Private key to use when generating an email verification token. |
| + |
| If not set, a random key is generated when running the |
| link:pgm-init.html[site initialization]. |
| |
| [[auth.maxRegisterEmailTokenAge]]auth.maxRegisterEmailTokenAge:: |
| + |
| Time in seconds before an email verification token sent to a user in |
| order to validate their email address expires. |
| + |
| * s, sec, second, seconds |
| * m, min, minute, minutes |
| * h, hr, hour, hours |
| * d, day, days |
| * w, week, weeks (`1 week` is treated as `7 days`) |
| * mon, month, months (`1 month` is treated as `30 days`) |
| * y, year, years (`1 year` is treated as `365 days`) |
| |
| + |
| Default is 12 hours. |
| |
| [[auth.openIdSsoUrl]]auth.openIdSsoUrl:: |
| + |
| The SSO entry point URL. Only used if `auth.type` is set to |
| `OpenID_SSO`. |
| + |
| The "Sign In" link will send users directly to this URL. |
| |
| [[auth.httpHeader]]auth.httpHeader:: |
| + |
| HTTP header to trust the username from, or unset to select HTTP basic |
| or digest 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/` or `$canonicalWebUrl/login`, allowing users to |
| begin a new web session. |
| |
| [[auth.cookiePath]]auth.cookiePath:: |
| + |
| Sets "path" attribute of the authentication cookie. |
| + |
| If not set, HTTP request's path is used. |
| |
| [[auth.cookieSecure]]auth.cookieSecure:: |
| + |
| Sets "secure" flag of the authentication cookie. If true, cookies |
| will be transmitted only over HTTPS protocol. |
| + |
| By default, false. |
| |
| [[auth.emailFormat]]auth.emailFormat:: |
| + |
| Optional format string to construct user email addresses out of |
| user login names. Only used if `auth.type` is `HTTP`, `HTTP_LDAP` |
| or `LDAP`. |
| + |
| This value can be set to a format string, where `{0}` is replaced |
| with the login name. E.g. "\{0\}+gerrit@example.com" with a user |
| login name of "foo" will produce "foo+gerrit@example.com" during |
| the first time user "foo" registers. |
| + |
| If the site is using `HTTP_LDAP` or `LDAP`, using this option is |
| discouraged. Setting `ldap.accountEmailAddress` and importing the |
| email address from the LDAP directory is generally preferred. |
| |
| [[auth.contributorAgreements]]auth.contributorAgreements:: |
| + |
| Controls whether or not the contributor agreement features are |
| enabled for the Gerrit site. If enabled a user must complete a |
| contributor agreement before they can upload changes. |
| + |
| If enabled, the admin must also add one or more |
| link:config-cla.html[contributor-agreement sections] |
| in project.config and create agreement files under |
| `'$site_path'/static`, so users can actually complete one or |
| more agreements. |
| + |
| By default this is false (no agreements are used). |
| + |
| To enable the actual usage of contributor agreement the project |
| specific config option in the `project.config` must be set: |
| link:config-project-config.html[receive.requireContributorAgreement]. |
| |
| [[auth.trustContainerAuth]]auth.trustContainerAuth:: |
| + |
| If true then it is the responsibility of the container hosting |
| Gerrit to authenticate users. In this case Gerrit will blindly trust |
| the container. |
| + |
| This parameter only affects git over http traffic. If set to false |
| then Gerrit will do the authentication (using DIGEST authentication). |
| + |
| By default this is set to false. |
| |
| [[auth.gitBasicAuth]]auth.gitBasicAuth:: |
| + |
| If true then Git over HTTP and HTTP/S traffic is authenticated using |
| standard BasicAuth and the credentials are validated against the randomly |
| generated HTTP password or against LDAP when it is configured as Gerrit |
| Web UI authentication method. |
| + |
| This parameter affects git over HTTP traffic and access to the REST |
| API. If set to false then Gerrit will authenticate through DIGEST |
| authentication and the randomly generated HTTP password in the Gerrit |
| database. |
| + |
| When `auth.type` is `LDAP`, service users that only exist in the Gerrit |
| database are still authenticated by their HTTP passwords. |
| + |
| By default this is set to false. |
| |
| [[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. |
| + |
| This parameter only affects git over http and git over SSH traffic. |
| + |
| By default this is set to false. |
| |
| [[auth.enableRunAs]]auth.enableRunAs:: |
| + |
| If true HTTP REST APIs will accept the `X-Gerrit-RunAs` HTTP request |
| header from any users granted the link:access-control.html#capability_runAs[Run As] |
| capability. The header and capability permit the authenticated user |
| to impersonate another account. |
| + |
| If false the feature is disabled and cannot be re-enabled without |
| editing gerrit.config and restarting the server. |
| + |
| Default is true. |
| |
| [[auth.allowRegisterNewEmail]]auth.allowRegisterNewEmail:: |
| + |
| Whether users are allowed to register new email addresses. |
| + |
| In addition for the HTTP authentication type |
| link:#auth.httpemailheader[auth.httpemailheader] must *not* be set to |
| enable registration of new email addresses. |
| + |
| By default, true. |
| |
| [[cache]] |
| === Section cache |
| |
| [[cache.directory]]cache.directory:: |
| + |
| Path to a local directory where Gerrit can write cached entities for |
| future lookup. This local disk cache is used to retain potentially |
| expensive to compute information across restarts. If the location |
| does not exist, Gerrit will try to create it. |
| + |
| If not absolute, the path is resolved relative to `$site_path`. |
| + |
| Default is unset, no disk cache. |
| |
| [[cache.name.maxAge]]cache.<name>.maxAge:: |
| + |
| Maximum age to keep an entry in the cache. Entries are removed from |
| the cache and refreshed from source data every maxAge interval. |
| Values should use common unit suffixes to express their setting: |
| + |
| * s, sec, second, seconds |
| * m, min, minute, minutes |
| * h, hr, hour, hours |
| * d, day, days |
| * w, week, weeks (`1 week` is treated as `7 days`) |
| * mon, month, months (`1 month` is treated as `30 days`) |
| * y, year, years (`1 year` is treated as `365 days`) |
| |
| + |
| -- |
| If a unit suffix is not specified, `seconds` is assumed. If 0 is |
| supplied, the maximum age is infinite and items are never purged |
| except when the cache is full. |
| |
| Default is `0`, meaning store forever with no expire, except: |
| |
| * `"adv_bases"`: default is `10 minutes` |
| * `"ldap_groups"`: default is `1 hour` |
| * `"web_sessions"`: default is `12 hours` |
| -- |
| |
| [[cache.name.memoryLimit]]cache.<name>.memoryLimit:: |
| + |
| The total cost of entries to retain in memory. The cost computation |
| varies by the cache. For most caches where the in-memory size of each |
| entry is relatively the same, memoryLimit is currently defined to be |
| the number of entries held by the cache (each entry costs 1). |
| + |
| For caches where the size of an entry can vary significantly between |
| individual entries (notably `"diff"`, `"diff_intraline"`), memoryLimit |
| is an approximation of the total number of bytes stored by the cache. |
| Larger entries that represent bigger patch sets or longer source files |
| will consume a bigger portion of the memoryLimit. For these caches the |
| memoryLimit should be set to roughly the amount of RAM (in bytes) the |
| administrator can dedicate to the cache. |
| + |
| Default is 1024 for most caches, except: |
| + |
| * `"adv_bases"`: default is `4096` |
| * `"diff"`: default is `10m` (10 MiB of memory) |
| * `"diff_intraline"`: default is `10m` (10 MiB of memory) |
| * `"plugin_resources"`: default is 2m (2 MiB of memory) |
| |
| + |
| If set to 0 the cache is disabled. Entries are removed immediately |
| after being stored by the cache. This is primarily useful for testing. |
| |
| [[cache.name.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. |
| + |
| If 0, disk storage for the cache is disabled. |
| |
| ==== [[cache_names]]Standard Caches |
| |
| cache `"accounts"`:: |
| + |
| Cache entries contain important details of an active user, including |
| their display name, preferences, known email addresses, and group |
| memberships. Entry information is obtained from the following |
| database tables: |
| + |
| * `accounts` |
| + |
| * `account_group_members` |
| + |
| * `account_external_ids` |
| |
| + |
| If direct updates are made to any of these database tables, this |
| cache should be flushed. |
| |
| cache `"accounts_byemail"`:: |
| + |
| Caches account identities keyed by email address, which is scanned |
| from the `account_external_ids` database table. If updates are |
| made to this table, this cache should be flushed. |
| |
| cache `"adv_bases"`:: |
| + |
| Used only for push over smart HTTP when branch level access controls |
| are enabled. The cache entry contains all commits that are available |
| for the client to use as potential delta bases. Push over smart HTTP |
| requires two HTTP requests, and this cache tries to carry state from |
| the first request into the second to ensure it can complete. |
| |
| cache `"changes"`:: |
| + |
| The size of `memoryLimit` determines the number of projects for which |
| all changes will be cached. If the cache is set to 1024, this means all |
| changes for up to 1024 projects can be held in the cache. |
| + |
| Default value is 0 (disabled). It is disabled by default due to the fact |
| that change updates are not communicated between Gerrit servers. Hence |
| this cache should be disabled in an multi-master/multi-slave setup. |
| + |
| The cache should be flushed whenever the database changes table is modified |
| outside of Gerrit. |
| |
| cache `"diff"`:: |
| + |
| Each item caches the differences between two commits, at both the |
| directory and file levels. Gerrit uses this cache to accelerate |
| the display of affected file names, as well as file contents. |
| + |
| Entries in this cache are relatively large, so memoryLimit is an |
| estimate in bytes of memory used. Administrators should try to target |
| cache.diff.memoryLimit to fit all changes users will view in a 1 or 2 |
| day span. |
| |
| cache `"diff_intraline"`:: |
| + |
| Each item caches the intraline difference of one file, when compared |
| between two commits. Gerrit uses this cache to accelerate display of |
| intraline differences when viewing a file. |
| + |
| Entries in this cache are relatively large, so memoryLimit is an |
| estimate in bytes of memory used. Administrators should try to target |
| cache.diff.memoryLimit to fit all files users will view in a 1 or 2 |
| day span. |
| |
| cache `"git_tags"`:: |
| + |
| If branch or reference level READ access controls are used, this |
| cache tracks which tags are reachable from the branch tips of a |
| repository. Gerrit uses this information to determine the set |
| of tags that a client may access, derived from which tags are |
| part of the history of a visible branch. |
| + |
| The cache is persisted to disk across server restarts as it can |
| be expensive to compute (60 or more seconds for a large history |
| like the Linux kernel repository). |
| |
| cache `"groups"`:: |
| + |
| Caches the basic group information from the `account_groups` table, |
| including the group owner, name, and description. |
| + |
| Gerrit group membership obtained from the `account_group_members` |
| table is cached under the `"accounts"` cache, above. External group |
| membership obtained from LDAP is cached under `"ldap_groups"`. |
| |
| cache `"groups_byinclude"`:: |
| + |
| Caches group inclusions in other groups. If direct updates are made |
| to the `account_group_includes` table, this cache should be flushed. |
| |
| cache `"groups_members"`:: |
| + |
| Caches subgroups. If direct updates are made to the |
| `account_group_includes` table, this cache should be flushed. |
| |
| cache `"ldap_groups"`:: |
| + |
| Caches the LDAP groups that a user belongs to, if LDAP has been |
| configured on this server. This cache should be configured with a |
| low maxAge setting, to ensure LDAP modifications are picked up in |
| a timely fashion. |
| |
| cache `"ldap_groups_byinclude"`:: |
| + |
| Caches the hierarchical structure of LDAP groups. |
| |
| cache `"ldap_usernames"`:: |
| + |
| Caches a mapping of LDAP username to Gerrit account identity. The |
| cache automatically updates when a user first creates their account |
| within Gerrit, so the cache expire time is largely irrelevant. |
| |
| cache `"permission_sort"`:: |
| + |
| Caches the order in which access control sections must be applied to a |
| reference. Sorting the sections can be expensive when regular |
| expressions are used, so this cache remembers the ordering for |
| each branch. |
| |
| cache `"plugin_resources"`:: |
| + |
| Caches formatted plugin resources, such as plugin documentation that |
| has been converted from Markdown to HTML. The memoryLimit refers to |
| the bytes of memory dedicated to storing the documentation. |
| |
| cache `"projects"`:: |
| + |
| Caches the project description records, from the `projects` table |
| in the database. If a project record is updated or deleted, this |
| cache should be flushed. Newly inserted projects do not require |
| a cache flush, as they will be read upon first reference. |
| |
| cache `"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. |
| + |
| This cache is based off the `account_ssh_keys` table and the |
| `accounts.ssh_user_name` column in the database. If either is |
| modified directly, this cache should be flushed. |
| |
| cache `"web_sessions"`:: |
| + |
| Tracks the live user sessions coming in over HTTP. Flushing this |
| cache would cause all users to be signed out immediately, forcing |
| them to sign-in again. To avoid breaking active users, this cache |
| is not flushed automatically by `gerrit flush-caches --all`, but |
| instead must be explicitly requested. |
| + |
| If no disk cache is configured (or `cache.web_sessions.diskLimit` |
| is set to 0) a server restart will force all users to sign-out, |
| and need to sign-in again after the restart, as the cache was |
| unable to persist the session information. Enabling a disk cache |
| is strongly recommended. |
| + |
| Session storage is relatively inexpensive. The average entry in |
| this cache is approximately 346 bytes. |
| |
| See also link:cmd-flush-caches.html[gerrit flush-caches]. |
| |
| ==== [[cache_options]]Cache Options |
| |
| [[cache.diff.timeout]]cache.diff.timeout:: |
| + |
| Maximum number of milliseconds to wait for diff data before giving up and |
| falling back on a simpler diff algorithm that will not be able to break down |
| modified regions into smaller ones. This is a work around for an infinite loop |
| bug in the default difference algorithm implementation. |
| + |
| Values should use common unit suffixes to express their setting: |
| + |
| * ms, milliseconds |
| * s, sec, second, seconds |
| * m, min, minute, minutes |
| * h, hr, hour, hours |
| |
| + |
| -- |
| If a unit suffix is not specified, `milliseconds` is assumed. |
| |
| Default is 5 seconds. |
| -- |
| |
| [[cache.diff_intraline.timeout]]cache.diff_intraline.timeout:: |
| + |
| Maximum number of milliseconds to wait for intraline difference data |
| before giving up and disabling it for a particular file pair. This is |
| a work around for an infinite loop bug in the intraline difference |
| implementation. |
| + |
| If computation takes longer than the timeout, the worker thread is |
| terminated, an error message is shown, and no intraline difference is |
| displayed for the file pair. |
| + |
| Values should use common unit suffixes to express their setting: |
| + |
| * ms, milliseconds |
| * s, sec, second, seconds |
| * m, min, minute, minutes |
| * h, hr, hour, hours |
| |
| + |
| -- |
| If a unit suffix is not specified, `milliseconds` is assumed. |
| |
| Default is 5 seconds. |
| -- |
| |
| [[cache.diff_intraline.enabled]]cache.diff_intraline.enabled:: |
| + |
| Boolean to enable or disable the computation of intraline differences |
| when populating a diff cache entry. This flag is provided primarily |
| as a backdoor to disable the intraline difference feature if |
| necessary. To maintain backwards compatibility with prior versions, |
| this setting will fallback to `cache.diff.intraline` if not set in the |
| configuration. |
| + |
| Default is true, enabled. |
| |
| [[cache.projects.checkFrequency]]cache.projects.checkFrequency:: |
| + |
| How often project configuration should be checked for update from Git. |
| Gerrit Code Review caches project access rules and configuration in |
| memory, checking the refs/meta/config branch every checkFrequency |
| minutes to see if a new revision should be loaded and used for future |
| access. Values can be specified using standard time unit abbreviations |
| ('ms', 'sec', 'min', etc.). |
| + |
| If set to 0, checks occur every time, which may slow down operations. |
| If set to 'disabled' or 'off', no check will ever be done. |
| Administrators may force the cache to flush with |
| link:cmd-flush-caches.html[gerrit flush-caches]. |
| + |
| Default is 5 minutes. |
| |
| [[cache.projects.loadOnStartup]]cache.projects.loadOnStartup:: |
| + |
| If the project cache should be loaded during server startup. |
| + |
| The cache is loaded concurrently. Admins should ensure that the cache |
| size set under <<cache.name.memoryLimit,cache.projects.memoryLimit>> |
| is not smaller than the number of repos. |
| + |
| Default is false, disabled. |
| |
| [[cache.projects.loadThreads]]cache.projects.loadThreads:: |
| + |
| Only relevant if <<cache.projects.loadOnStartup,cache.projects.loadOnStartup>> |
| is true. |
| + |
| The number of threads to allocate for loading the cache at startup. These |
| threads will die out after the cache is loaded. |
| + |
| Default is the number of CPUs. |
| |
| [[change]] |
| === Section change |
| |
| [[change.largeChange]]change.largeChange:: |
| + |
| Number of changed lines from which on a change is considered as a large |
| change. The number of changed lines of a change is the sum of the lines |
| that were inserted and deleted in the change. |
| + |
| The specified value is used to visualize the change sizes in the Web UI |
| in change tables and user dashboards. |
| + |
| By default 500. |
| |
| [[change.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 30 seconds. |
| |
| [[change.allowDrafts]]change.allowDrafts:: |
| + |
| Allow drafts workflow. If set to false, drafts cannot be created, |
| deleted or published. |
| + |
| Default is true. |
| |
| [[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.submitWholeTopic]]change.submitWholeTopic (*Experimental*):: |
| + |
| Determines if the submit button submits the whole topic instead of |
| just the current change. |
| + |
| Default is false. |
| |
| [[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 configuerd 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.replyLabel]]change.replyLabel:: |
| + |
| Label name for the reply button. In the user interface an ellipsis (…) |
| is appended. |
| + |
| Default is "Reply". In the user interface it becomes "Reply…". |
| |
| [[change.replyTooltip]]change.replyTooltip:: |
| + |
| Tooltip for the reply button. In the user interface a note about the |
| keyboard shortcut is appended. |
| + |
| Default is "Reply and score". In the user interface it becomes "Reply |
| and score (Shortcut: a)". |
| |
| [[changeCleanup]] |
| === Section changeCleanup |
| |
| This section allows to configure change cleanups and schedules them to |
| run periodically. |
| |
| [[changeCleanup.abandonAfter]]changeCleanup.abandonAfter:: |
| + |
| Period of inactivity after which open changes should be abandoned |
| automatically. |
| + |
| By default `0`, never abandon open changes. |
| + |
| [WARNING] Auto-Abandoning changes may confuse/annoy users. When |
| enabling this, make sure to choose a reasonably large grace period and |
| inform users in advance. |
| + |
| The following suffixes are supported to define the time unit: |
| + |
| * `d, day, days` |
| * `w, week, weeks` (`1 week` is treated as `7 days`) |
| * `mon, month, months` (`1 month` is treated as `30 days`) |
| * `y, year, years` (`1 year` is treated as `365 days`) |
| |
| [[changeCleanup.abandonIfMergeable]]changeCleanup.abandonIfMergeable:: |
| + |
| Whether changes which are mergeable should be auto-abandoned. |
| + |
| By default `true`. |
| |
| [[changeCleanup.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:: |
| + |
| Start time to define the first execution of the change cleanups. |
| If the configured `'changeCleanup.interval'` is shorter than |
| `'changeCleanup.startTime - now'` the start time will be preponed by |
| the maximum integral multiple of `'changeCleanup.interval'` so that the |
| start time is still in the future. |
| + |
| ---- |
| <day of week> <hours>:<minutes> |
| or |
| <hours>:<minutes> |
| |
| <day of week> : Mon, Tue, Wed, Thu, Fri, Sat, Sun |
| <hours> : 00-23 |
| <minutes> : 0-59 |
| ---- |
| |
| |
| [[changeCleanup.interval]]changeCleanup.interval:: |
| + |
| Interval for periodic repetition of triggering the change cleanups. |
| The interval must be larger than zero. The following suffixes are supported |
| to define the time unit for the interval: |
| + |
| * `s, sec, second, seconds` |
| * `m, min, minute, minutes` |
| * `h, hr, hour, hours` |
| * `d, day, days` |
| * `w, week, weeks` (`1 week` is treated as `7 days`) |
| * `mon, month, months` (`1 month` is treated as `30 days`) |
| * `y, year, years` (`1 year` is treated as `365 days`) |
| |
| link:#schedule-examples[Schedule examples] can be found in the |
| link:#gc[gc] section. |
| |
| [[changeMerge]] |
| === Section changeMerge |
| |
| [[changeMerge.checkFrequency]]changeMerge.checkFrequency:: |
| + |
| How often the database should be rescanned for changes that have been |
| submitted but not merged due to transient errors. Values can be |
| specified using standard time unit abbreviations ('ms', 'sec', 'min', |
| etc.). Set to 0 to disable periodic rescanning, only scanning once on |
| master node startup. |
| + |
| Default is 300 seconds (5 minutes). |
| |
| [[changeMerge.threadPoolSize]]changeMerge.threadPoolSize:: |
| + |
| _Deprecated:_ Formerly used to control thread pool size for background |
| mergeability checks. These checks were moved to the indexing threadpool, |
| so this value is now used for |
| link:#index.batchThreads[index.batchThreads], only if that value is not |
| provided. |
| + |
| This option may be removed in a future version. |
| |
| [[changeMerge.interactiveThreadPoolSize]]changeMerge.interactiveThreadPoolSize:: |
| + |
| _Deprecated:_ Formerly used to control thread pool size for interactive |
| mergeability checks. These checks were moved to the indexing threadpool, |
| so this value is now used for link:#index.threads[index.threads], only |
| if that value is not provided. |
| + |
| This option may be removed in a future version. |
| |
| [[commentlink]] |
| === Section commentlink |
| |
| Comment links are find/replace strings applied to change descriptions, |
| patch comments, in-line code comments and approval category value descriptions |
| to turn set strings into hyperlinks. One common use is for linking to |
| bug-tracking systems. |
| |
| In the following example configuration the 'changeid' comment link |
| will match typical Gerrit Change-Id values and create a hyperlink |
| to changes which reference it. The second configuration 'bugzilla' |
| will hyperlink terms such as 'bug 42' to an external bug tracker, |
| supplying the argument record number '42' for display. The third |
| configuration 'tracker' uses raw HTML to more precisely control |
| how the replacement is displayed to the user. |
| |
| ---- |
| [commentlink "changeid"] |
| match = (I[0-9a-f]{8,40}) |
| link = "#q,$1" |
| |
| [commentlink "bugzilla"] |
| match = "(bug\\s+#?)(\\d+)" |
| link = http://bugs.example.com/show_bug.cgi?id=$2 |
| |
| [commentlink "tracker"] |
| match = ([Bb]ug:\\s+)(\\d+) |
| html = $1<a href=\"http://trak.example.com/$2\">$2</a> |
| ---- |
| |
| Comment links can also be specified in `project.config` and sections in |
| children override those in parents. The only restriction is that to |
| avoid injecting arbitrary user-supplied HTML in the page, comment links |
| defined in `project.config` may only supply `link`, not `html`. |
| |
| [[commentlink.name.match]]commentlink.<name>.match:: |
| + |
| A JavaScript regular expression to match positions to be replaced |
| with a hyperlink. Subexpressions of the matched string can be |
| stored using groups and accessed with `$'n'` syntax, where 'n' |
| is the group number, starting from 1. |
| + |
| The configuration file parser eats one level of backslashes, so the |
| character class `\s` requires `\\s` in the configuration file. The |
| parser also terminates the line at the first `#`, so a match |
| expression containing # must be wrapped in double quotes. |
| + |
| To match case insensitive strings, a character class with both the |
| upper and lower case character for each position must be used. For |
| example, to match the string `bug` in a case insensitive way the match |
| pattern `[bB][uU][gG]` needs to be used. |
| + |
| A common pattern to match is `bug\\s+(\\d+)`. |
| |
| [[commentlink.name.link]]commentlink.<name>.link:: |
| + |
| The URL to direct the user to whenever the regular expression is |
| matched. Groups in the match expression may be accessed as `$'n'`. |
| + |
| The link property is used only when the html property is not present. |
| |
| [[commentlink.name.html]]commentlink.<name>.html:: |
| + |
| HTML to replace the entire matched string with. If present, |
| this property overrides the link property above. Groups in the |
| match expression may be accessed as `$'n'`. |
| + |
| The configuration file eats double quotes, so escaping them as |
| `\"` is necessary to protect them from the parser. |
| |
| [[commentlink.name.enabled]]commentlink.<name>.enabled:: |
| + |
| Whether the comment link is enabled. A child project may override a |
| section in a parent or the site-wide config that is disabled by |
| specifying `enabled = true`. |
| + |
| Disabling sections in `gerrit.config` can be used by site administrators |
| to create a library of comment links with `html` set that are not |
| user-supplied and thus can be verified to be XSS-free, but are only |
| enabled for a subset of projects. |
| + |
| By default, true. |
| + |
| Note that the names and contents of disabled sections are visible even |
| to anonymous users via the |
| link:rest-api-projects.html#get-config[REST API]. |
| |
| |
| [[container]] |
| === Section container |
| |
| These settings are applied only if Gerrit is started as the container |
| process through Gerrit's 'gerrit.sh' rc.d compatible wrapper script. |
| |
| [[container.heapLimit]]container.heapLimit:: |
| + |
| Maximum heap size of the Java process running Gerrit, in bytes. |
| This property is translated into the '-Xmx' flag for the JVM. |
| + |
| Default is platform and JVM specific. |
| + |
| Common unit suffixes of 'k', 'm', or 'g' are supported. |
| |
| [[container.javaHome]]container.javaHome:: |
| + |
| Path of the JRE/JDK installation to run Gerrit with. If not set, the |
| Gerrit startup script will attempt to search your system and guess |
| a suitable JRE. Overrides the environment variable 'JAVA_HOME'. |
| |
| [[container.javaOptions]]container.javaOptions:: |
| + |
| Additional options to pass along to the Java runtime. If multiple |
| values are configured, they are passed in order on the command line, |
| separated by spaces. These options are appended onto 'JAVA_OPTIONS'. |
| |
| For example, it is possible to overwrite Gerrit's default log4j |
| configuration: |
| |
| ---- |
| javaOptions = -Dlog4j.configuration=file:///home/gerrit/site/etc/log4j.properties |
| ---- |
| |
| [[container.daemonOpt]]container.daemonOpt:: |
| + |
| Additional options to pass to the daemon (e.g. '--enable-httpd'). If |
| multiple values are configured, they are passed in that order to the command |
| line, separated by spaces. |
| + |
| Execute `java -jar gerrit.war daemon --help` to see all possible |
| options. |
| |
| [[container.slave]]container.slave:: |
| + |
| Used on Gerrit slave installations. If set to true the Gerrit JVM is |
| called with the '--slave' switch, enabling slave mode. If no value is |
| set (or any other value), Gerrit defaults to master mode. |
| |
| [[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 |
| |
| [[core.packedGitWindowSize]]core.packedGitWindowSize:: |
| + |
| Number of bytes of a pack file to load into memory in a single |
| read operation. This is the "page size" of the JGit buffer cache, |
| used for all pack access operations. All disk IO occurs as single |
| window reads. Setting this too large may cause the process to load |
| more data than is required; setting this too small may increase |
| the frequency of `read()` system calls. |
| + |
| Default on JGit is 8 KiB on all platforms. |
| + |
| Common unit suffixes of 'k', 'm', or 'g' are supported. |
| |
| [[core.packedGitLimit]]core.packedGitLimit:: |
| + |
| Maximum number of bytes to load and cache in memory from pack files. |
| If JGit needs to access more than this many bytes it will unload less |
| frequently used windows to reclaim memory space within the process. |
| As this buffer must be shared with the rest of the JVM heap, it |
| should be a fraction of the total memory available. |
| + |
| Default on JGit is 10 MiB on all platforms. |
| + |
| Common unit suffixes of 'k', 'm', or 'g' are supported. |
| |
| [[core.deltaBaseCaseLimit]]core.deltaBaseCacheLimit:: |
| + |
| Maximum number of bytes to reserve for caching base objects |
| that multiple deltafied objects reference. By storing the entire |
| decompressed base object in a cache Git is able to avoid unpacking |
| and decompressing frequently used base objects multiple times. |
| + |
| Default on JGit is 10 MiB on all platforms. You probably do not |
| need to adjust this value. |
| + |
| Common unit suffixes of 'k', 'm', or 'g' are supported. |
| |
| [[core.packedGitOpenFiles]]core.packedGitOpenFiles:: |
| + |
| Maximum number of pack files to have open at once. A pack file |
| must be opened in order for any of its data to be available in |
| a cached window. |
| + |
| If you increase this to a larger setting you may need to also adjust |
| the ulimit on file descriptors for the host JVM, as Gerrit needs |
| additional file descriptors available for network sockets and other |
| repository data manipulation. |
| + |
| Default on JGit is 128 file descriptors on all platforms. |
| |
| [[core.streamFileThreshold]]core.streamFileThreshold:: |
| + |
| Largest object size, in bytes, that JGit will allocate as a |
| contiguous byte array. Any file revision larger than this threshold |
| will have to be streamed, typically requiring the use of temporary |
| files under '$GIT_DIR/objects' to implement pseudo-random access |
| during delta decompression. |
| + |
| Servers with very high traffic should set this to be larger than |
| the size of their common big files. For example a server managing |
| the Android platform typically has to deal with ~10-12 MiB XML |
| files, so `15 m` would be a reasonable setting in that environment. |
| Setting this too high may cause the JVM to run out of heap space |
| when handling very big binary files, such as device firmware or |
| CD-ROM ISO images. |
| + |
| Defaults to 25% of the available JVM heap, limited to 2048m. |
| + |
| Common unit suffixes of 'k', 'm', or 'g' are supported. |
| |
| [[core.packedGitMmap]]core.packedGitMmap:: |
| + |
| When true, JGit will use `mmap()` rather than `malloc()+read()` |
| to load data from pack files. The use of mmap can be problematic |
| on some JVMs as the garbage collector must deduce that a memory |
| mapped segment is no longer in use before a call to `munmap()` |
| can be made by the JVM native code. |
| + |
| In server applications (such as Gerrit) that need to access many |
| pack files, setting this to true risks artificially running out |
| of virtual address space, as the garbage collector cannot reclaim |
| unused mapped spaces fast enough. |
| + |
| Default on JGit is false. Although potentially slower, it yields |
| much more predictable behavior. |
| |
| [[core.asyncLoggingBufferSize]]core.asyncLoggingBufferSize:: |
| + |
| Size of the buffer to store logging events for asynchronous logging. |
| Putting a larger value can protect threads from stalling when the |
| AsyncAppender threads are not fast enough to consume the logging events |
| from the buffer. It also protects from losing log entries in this case. |
| + |
| Default is 64 entries. |
| |
| [[core.useRecursiveMerge]]core.useRecursiveMerge:: |
| + |
| Use JGit's recursive merger for three-way merges. This only affects |
| projects that allow content merges. |
| + |
| As explained in this |
| link:http://codicesoftware.blogspot.com/2011/09/merge-recursive-strategy.html[ |
| blog], the recursive merge produces better results if the two commits |
| that are merged have more than one common predecessor. |
| + |
| Default is true. |
| |
| [[database]] |
| === Section database |
| |
| The database section configures where Gerrit stores its metadata |
| records about user accounts and change reviews. |
| |
| ---- |
| [database] |
| type = POSTGRESQL |
| hostname = localhost |
| database = reviewdb |
| username = gerrit2 |
| password = s3kr3t |
| ---- |
| |
| [[database.type]]database.type:: |
| + |
| Type of database server to connect to. If set this value will be |
| used to automatically create correct database.driver and database.url |
| values to open the connection. |
| + |
| * `POSTGRESQL` |
| + |
| Connect to a PostgreSQL database server. |
| + |
| * `H2` |
| + |
| Connect to a local embedded H2 database. |
| + |
| * `MYSQL` |
| + |
| Connect to a MySQL database server. |
| + |
| * `JDBC` |
| + |
| Connect using a JDBC driver class name and URL. |
| |
| + |
| If not specified, database.driver and database.url are used as-is, |
| and if they are also not specified, defaults to H2. |
| |
| [[database.hostname]]database.hostname:: |
| + |
| Hostname of the database server. Defaults to 'localhost'. |
| |
| [[database.port]]database.port:: |
| + |
| Port number of the database server. Defaults to the default port |
| of the server named by database.type. |
| |
| [[database.database]]database.database:: |
| + |
| For POSTGRESQL or MYSQL, the name of the database on the server. |
| + |
| For H2, this is the path to the database, and if not absolute is |
| relative to `'$site_path'`. |
| |
| [[database.username]]database.username:: |
| + |
| Username to connect to the database server as. |
| |
| [[database.password]]database.password:: |
| + |
| Password to authenticate to the database server with. |
| |
| [[database.driver]]database.driver:: |
| + |
| Name of the JDBC driver class to connect to the database with. |
| Setting this usually isn't necessary as it can be derived from |
| database.type or database.url for any supported database. |
| |
| [[database.url]]database.url:: |
| + |
| 'jdbc:' URL for the database. Setting this variable usually |
| isn't necessary as it can be constructed from the all of the |
| above properties. |
| |
| [[database.connectionPool]]database.connectionPool:: |
| + |
| If true, use connection pooling for database connections. Otherwise, a |
| new database connection is opened for each request. |
| + |
| Default is false for MySQL, and true for other database backends. |
| |
| [[database.poolLimit]]database.poolLimit:: |
| + |
| Maximum number of open database connections. If the server needs |
| more than this number, request processing threads will wait up |
| to <<database.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 8. |
| + |
| This setting only applies if |
| <<database.connectionPool,database.connectionPool>> is true. |
| |
| [[database.poolMinIdle]]database.poolMinIdle:: |
| + |
| Minimum number of connections to keep idle in the pool. |
| Default is 4. |
| + |
| This setting only applies if |
| <<database.connectionPool,database.connectionPool>> is true. |
| |
| [[database.poolMaxIdle]]database.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 4. |
| + |
| This setting only applies if |
| <<database.connectionPool,database.connectionPool>> is true. |
| |
| [[database.poolMaxWait]]database.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`. |
| |
| This setting only applies if |
| <<database.connectionPool,database.connectionPool>> is true. |
| -- |
| |
| [[database.dataSourceInterceptorClass]]database.dataSourceInterceptorClass:: |
| |
| Class that implements DataSourceInterceptor interface to monitor SQL activity. |
| This class must have default constructor and be available on Gerrit's bootstrap |
| classpath, e. g. in `$gerrit_site/lib` directory. Example implementation of |
| SQL monitoring can be found in javamelody-plugin. |
| |
| [[download]] |
| === Section download |
| |
| ---- |
| [download] |
| command = checkout |
| command = cherry_pick |
| command = pull |
| command = format_patch |
| scheme = ssh |
| scheme = http |
| scheme = anon_http |
| scheme = anon_git |
| scheme = repo_download |
| ---- |
| |
| The download section configures the allowed download methods. |
| |
| [[download.command]]download.command:: |
| + |
| Commands that should be offered to download changes. |
| + |
| Multiple commands are supported: |
| + |
| * `checkout` |
| + |
| Command to fetch and checkout the patch set. |
| + |
| * `cherry_pick` |
| + |
| Command to fetch the patch set and to cherry-pick it onto the current |
| commit. |
| + |
| * `pull` |
| + |
| Command to pull the patch set. |
| + |
| * `format_patch` |
| + |
| Command to fetch the patch set and to feed it into the `format-patch` |
| command. |
| |
| + |
| If `download.command` is not specified, all download commands are |
| offered. |
| |
| [[download.scheme]]download.scheme:: |
| + |
| Schemes that should be used to download changes. |
| + |
| Multiple schemes are supported: |
| + |
| * `http` |
| + |
| Authenticated HTTP download is allowed. |
| + |
| * `ssh` |
| + |
| Authenticated SSH download is allowed. |
| + |
| * `anon_http` |
| + |
| Anonymous HTTP download is allowed. |
| + |
| * `anon_git` |
| + |
| Anonymous Git download is allowed. This is not default, it is also |
| necessary to set <<gerrit.canonicalGitUrl,gerrit.canonicalGitUrl>> |
| variable. |
| + |
| * `repo_download` |
| + |
| Gerrit advertises patch set downloads with the `repo download` |
| command, assuming that all projects managed by this instance are |
| generally worked on with the repo multi-repository tool. This is |
| not default, as not all instances will deploy repo. |
| |
| + |
| If `download.scheme` is not specified, SSH, HTTP and Anonymous HTTP |
| downloads are allowed. |
| |
| [[download.checkForHiddenChangeRefs]]download.checkForHiddenChangeRefs:: |
| + |
| Whether the download commands should be adapted when the change refs |
| are hidden. |
| + |
| Git has a configuration option to hide refs from the initial |
| advertisement (`uploadpack.hideRefs`). This option can be used to hide |
| the change refs from the client. As consequence fetching changes by |
| change ref does not work anymore. However by setting |
| `uploadpack.allowTipSha1InWant` to `true` fetching changes by commit ID |
| is possible. If `download.checkForHiddenChangeRefs` is set to `true` |
| the git download commands use the commit ID instead of the change ref |
| when a project is configured like this. |
| + |
| Example git configuration on a project: |
| + |
| ---- |
| [uploadpack] |
| hideRefs = refs/changes/ |
| hideRefs = refs/cache-automerge/ |
| allowTipSha1InWant = true |
| ---- |
| + |
| By default `false`. |
| |
| [[download.archive]]download.archive:: |
| + |
| Specifies which archive formats, if any, should be offered on the change |
| screen and supported for `git-upload-archive` operation: |
| + |
| ---- |
| [download] |
| archive = tar |
| archive = tbz2 |
| archive = tgz |
| archive = txz |
| archive = zip |
| ---- |
| |
| If `download.archive` is not specified defaults to all archive |
| commands. Set to `off` or empty string to disable. |
| |
| Zip is not supported because it may be interpreted by a Java plugin as a |
| valid JAR file, whose code would have access to cookies on the domain. |
| For this reason `zip` format is always excluded from formats offered |
| through the `Download` drop down or accessible in the REST API. |
| |
| [[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:: |
| + |
| Start time to define the first execution of the git garbage collection. |
| If the configured `'gc.interval'` is shorter than `'gc.startTime - now'` |
| the start time will be preponed by the maximum integral multiple of |
| `'gc.interval'` so that the start time is still in the future. |
| + |
| ---- |
| <day of week> <hours>:<minutes> |
| or |
| <hours>:<minutes> |
| |
| <day of week> : Mon, Tue, Wed, Thu, Fri, Sat, Sun |
| <hours> : 00-23 |
| <minutes> : 0-59 |
| ---- |
| |
| |
| [[gc.interval]]gc.interval:: |
| + |
| Interval for periodic repetition of triggering the git garbage collection. |
| The interval must be larger than zero. The following suffixes are supported |
| to define the time unit for the interval: |
| + |
| * `s, sec, second, seconds` |
| * `m, min, minute, minutes` |
| * `h, hr, hour, hours` |
| * `d, day, days` |
| * `w, week, weeks` (`1 week` is treated as `7 days`) |
| * `mon, month, months` (`1 month` is treated as `30 days`) |
| * `y, year, years` (`1 year` is treated as `365 days`) |
| |
| [[schedule-examples]] |
| Examples:: |
| + |
| ---- |
| gc.startTime = Fri 10:30 |
| gc.interval = 2 day |
| ---- |
| + |
| Assuming the server is started on Mon 7:00 -> `'startTime - now = 4 days 3:30 hours'`. |
| This is larger than the interval hence prepone the start time |
| by the maximum integral multiple of the interval so that start |
| time is still in the future, i.e. prepone by 4 days. This yields |
| a start time of Mon 10:30, next executions are Wed 10:30, Fri 10:30 |
| etc. |
| + |
| ---- |
| gc.startTime = 6:00 |
| gc.interval = 1 day |
| ---- |
| + |
| Assuming the server is started on Mon 7:00 this yields the first run on next Tuesday |
| at 6:00 and a repetition interval of 1 day. |
| |
| |
| [[gerrit]] |
| === Section gerrit |
| |
| [[gerrit.basePath]]gerrit.basePath:: |
| + |
| Local filesystem directory holding all Git repositories that |
| Gerrit knows about and can process changes for. A project |
| entity in Gerrit maps to a local Git repository by creating |
| the path string `"${basePath}/${project_name}.git"`. |
| + |
| If relative, the path is resolved relative to `'$site_path'`. |
| |
| [[gerrit.allProjects]]gerrit.allProjects:: |
| + |
| Name of the permissions-only project defining global server |
| access controls and settings. These are inherited into every |
| other project managed by the running server. The name is |
| relative to `gerrit.basePath`. |
| + |
| Defaults to `All-Projects` if not set. |
| |
| [[gerrit.allUsers]]gerrit.allUsers:: |
| + |
| Name of the project in which meta data of all users is stored. |
| The name is relative to `gerrit.basePath`. |
| + |
| Defaults to `All-Users` if not set. |
| |
| [[gerrit.canonicalWebUrl]]gerrit.canonicalWebUrl:: |
| + |
| The default URL for Gerrit to be accessed through. |
| + |
| Typically this would be set to "http://review.example.com/" or |
| "http://example.com/gerrit/" so Gerrit can output links that point |
| back to itself. |
| + |
| Setting this is highly recommended, as its necessary for the upload |
| code invoked by "git push" or "repo upload" to output hyperlinks |
| to the newly uploaded changes. |
| |
| [[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.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.reportBugText]]gerrit.reportBugText:: |
| + |
| Text to be displayed in the link to the bug report URL. |
| + |
| Only used when `gerrit.reportBugUrl` is set. |
| + |
| Defaults to "Report Bug". |
| |
| [[gerrit.disableReverseDnsLookup]]gerrit.disableReverseDnsLookup:: |
| + |
| Disables reverse DNS lookup during computing 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. |
| |
| [[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. If set to disabled there |
| is no gitweb hyperlinking support. |
| + |
| Valid values are `gitweb`, `cgit`, `disabled` or `custom`. |
| |
| [[gitweb.revision]]gitweb.revision:: |
| + |
| Optional pattern to use for constructing the gitweb URL when pointing |
| at a specific commit when `custom` is used above. |
| + |
| Valid replacements are `${project}` for the project name in Gerrit |
| and `${commit}` for the SHA1 hash for the commit. |
| |
| [[gitweb.project]]gitweb.project:: |
| + |
| Optional pattern to use for constructing the gitweb URL when pointing |
| at a specific project when `custom` is used above. |
| + |
| 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 `custom` is used above. |
| + |
| Valid replacements are `${project}` for the project name in Gerrit |
| and `${branch}` for the name of the branch. |
| |
| [[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 `custom` is |
| used above. |
| + |
| Valid replacements are `${project}` for the project name in Gerrit |
| and `${commit}` for the SHA1 hash for the commit. |
| |
| [[gitweb.file]]gitweb.file:: |
| + |
| Optional pattern to use for constructing the gitweb URL when pointing |
| at the contents of a file in a specific commit when `custom` is used |
| above. |
| + |
| Valid replacements are `${project}` for the project name in Gerrit, |
| `${file}` for the file name and `${commit}` for the SHA1 hash for |
| the commit. |
| |
| [[gitweb.filehistory]]gitweb.filehistory:: |
| + |
| Optional pattern to use for constructing the gitweb URL when pointing |
| at the history of a file in a specific branch when `custom` is used |
| above. |
| + |
| 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. |
| + |
| Default linkname for custom type is "gitweb". |
| |
| [[gitweb.pathSeparator]]gitweb.pathSeparator:: |
| + |
| Optional character to substitute the standard path separator (slash) in |
| project names and branch names. |
| + |
| By default, Gerrit will use hexadecimal encoding for slashes in project and |
| branch names. Some web servers, such as Tomcat, reject this hexadecimal |
| encoding in the URL. |
| + |
| Some alternative gitweb services, such as link:http://gitblit.com[Gitblit], |
| allow using an alternative path separator character. In Gitblit, this can be |
| configured through the property link:http://gitblit.com/properties.html[web.forwardSlashCharacter]. |
| In Gerrit, the alternative path separator can be configured correspondingly |
| using the property 'gitweb.pathSeparator'. |
| + |
| Valid values are the characters '*', '(' and ')'. |
| |
| [[gitweb.linkDrafts]]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," default is "true." |
| |
| [[gitweb.linkDrafts]]gitweb.linkDrafts:: |
| + |
| Whether or not Gerrit should provide links to gitweb on draft patch sets. |
| + |
| By default, Gerrit will show links to gitweb on all patch sets. If gitweb |
| only allows publicly viewable references, set this to false to remove |
| the links to draft patch sets from the change review screen. |
| + |
| Valid values are "true" and "false," default is "true". |
| |
| [[groups]] |
| === Section groups |
| |
| [[groups.newGroupsVisibleToAll]]groups.newGroupsVisibleToAll:: |
| + |
| Controls whether newly created groups should be by default visible to |
| all registered users. |
| + |
| By default, false. |
| |
| [[hooks]] |
| === Section hooks |
| |
| See also link:config-hooks.html[Hooks]. |
| |
| [[hooks.path]]hooks.path:: |
| + |
| Optional path to hooks, if not specified then `'$site_path'/hooks` will be used. |
| |
| [[hooks.syncHookTimeout]]hooks.syncHookTimeout:: |
| + |
| Optional timeout value in seconds for synchronous hooks, if not specified |
| then 30 seconds will be used. |
| |
| [[hooks.changeAbandonedHook]]hooks.changeAbandonedHook:: |
| + |
| Optional filename for the change abandoned hook, if not specified then |
| `change-abandoned` will be used. |
| |
| [[hooks.changeMergedHook]]hooks.changeMergedHook:: |
| + |
| Optional filename for the change merged hook, if not specified then |
| `change-merged` will be used. |
| |
| [[hooks.changeRestoredHook]]hooks.changeRestoredHook:: |
| + |
| Optional filename for the change restored hook, if not specified then |
| `change-restored` will be used. |
| |
| [[hooks.claSignedHook]]hooks.claSignedHook:: |
| + |
| Optional filename for the CLA signed hook, if not specified then |
| `cla-signed` will be used. |
| |
| [[hooks.commentAddedHook]]hooks.commentAddedHook:: |
| + |
| Optional filename for the comment added hook, if not specified then |
| `comment-added` will be used. |
| |
| [[hooks.draftPublishedHook]]hooks.draftPublishedHook:: |
| + |
| Optional filename for the draft published hook, if not specified then |
| `draft-published` will be used. |
| |
| [[hooks.hashtagsChangedHook]]hooks.hashtagsChangedHook:: |
| + |
| Optional filename for the hashtags changed hook, if not specified then |
| `hashtags-changed` will be used. |
| |
| [[hooks.projectCreatedHook]]hooks.projectCreatedHook:: |
| + |
| Optional filename for the project created hook, if not specified then |
| `project-created` will be used. |
| |
| [[hooks.mergeFailedHook]]hooks.mergeFailedHook:: |
| + |
| Optional filename for the merge failed hook, if not specified then |
| `merge-failed` will be used. |
| |
| [[hooks.patchsetCreatedHook]]hooks.patchsetCreatedHook:: |
| + |
| Optional filename for the patchset created hook, if not specified then |
| `patchset-created` will be used. |
| |
| [[hooks.refUpdateHook]]hooks.refUpdateHook:: |
| + |
| Optional filename for the ref update hook, if not specified then |
| `ref-update` will be used. |
| |
| [[hooks.refUpdatedHook]]hooks.refUpdatedHook:: |
| + |
| Optional filename for the ref updated hook, if not specified then |
| `ref-updated` will be used. |
| |
| [[hooks.reviewerAddedHook]]hooks.reviewerAddedHook:: |
| + |
| Optional filename for the reviewer added hook, if not specified then |
| `reviewer-added` will be used. |
| |
| [[hooks.topicChangedHook]]hooks.topicChangedHook:: |
| + |
| Optional filename for the topic changed hook, if not specified then |
| `topic-changed` will be used. |
| |
| [[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. |
| |
| [[httpd]] |
| === Section httpd |
| |
| The httpd section configures the embedded servlet container. |
| |
| [[httpd.listenUrl]]httpd.listenUrl:: |
| + |
| Specifies the URLs the internal HTTP daemon should listen for |
| connections on. The special hostname '*' may be used to listen |
| on all local addresses. A context path may optionally be included, |
| placing Gerrit Code Review's web address within a subdirectory of |
| the server. |
| + |
| Multiple protocol schemes are supported: |
| + |
| * `http://`'hostname'`:`'port' |
| + |
| Plain-text HTTP protocol. If port is not supplied, defaults to 80, |
| the standard HTTP port. |
| + |
| * `https://`'hostname'`:`'port' |
| + |
| SSL encrypted HTTP protocol. If port is not supplied, defaults to |
| 443, the standard HTTPS port. |
| + |
| Externally facing production sites are encouraged to use a reverse |
| proxy configuration and `proxy-https://` (below), rather than using |
| the embedded servlet container to implement the SSL processing. |
| The proxy server with SSL support is probably easier to configure, |
| provides more configuration options to control cipher usage, and |
| is likely using natively compiled encryption algorithms, resulting |
| in higher throughput. |
| + |
| * `proxy-http://`'hostname'`:`'port' |
| + |
| 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:http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#x-headers[mod_proxy]. |
| + |
| * `proxy-https://`'hostname'`:`'port' |
| + |
| 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. |
| |
| + |
| -- |
| If multiple values are supplied, the daemon will listen on all |
| of them. |
| |
| 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.requestHeaderSize]]httpd.requestHeaderSize:: |
| + |
| Size, in bytes, of the buffer used to parse the HTTP headers of an |
| incoming HTTP request. The entire request headers, including any |
| cookies sent by the browser, must fit within this buffer, otherwise |
| the server aborts with the response '413 Request Entity Too Large'. |
| + |
| One buffer of this size is allocated per active connection. |
| Allocating a buffer that is too large wastes memory that cannot be |
| reclaimed, allocating a buffer that is too small may cause unexpected |
| errors caused by very long Referer URLs or large cookie values. |
| + |
| By default, 16384 (16 K), which is sufficient for most OpenID and |
| other web-based single-sign-on integrations. |
| |
| [[httpd.sslCrl]]httpd.sslCrl:: |
| + |
| Path of the certificate revocation list file in PEM format. This |
| crl file is optional, and available for CLIENT_SSL_CERT_LDAP |
| authentication. |
| + |
| To create and view a crl using openssl: |
| + |
| ---- |
| openssl ca -gencrl -out crl.pem |
| openssl crl -in crl.pem -text |
| ---- |
| + |
| If not absolute, the path is resolved relative to `$site_path`. |
| + |
| By default, `$site_path/etc/crl.pem`. |
| |
| [[httpd.sslKeyStore]]httpd.sslKeyStore:: |
| + |
| Path of the Java keystore containing the server's SSL certificate |
| and private key. This keystore is required for `https://` in URL. |
| + |
| To create a self-signed certificate for simple internal usage: |
| + |
| ---- |
| keytool -keystore keystore -alias jetty -genkey -keyalg RSA |
| chmod 600 keystore |
| ---- |
| + |
| If not absolute, the path is resolved relative to `$site_path`. |
| + |
| By default, `$site_path/etc/keystore`. |
| |
| [[httpd.sslKeyPassword]]httpd.sslKeyPassword:: |
| + |
| Password used to decrypt the private portion of the sslKeyStore. |
| Java keystores require a password, even if the administrator |
| doesn't want to enable one. |
| + |
| If set to the empty string the embedded server will prompt for the |
| password during startup. |
| + |
| By default, `gerrit`. |
| |
| [[httpd.requestLog]]httpd.requestLog:: |
| + |
| Enable (or disable) the `'$site_path'/logs/httpd_log` request log. |
| If enabled, an NCSA combined log format request log file is written |
| out by the internal HTTP daemon. |
| + |
| `log4j.appender` with the name `httpd_log` can be configured to overwrite |
| programmatic configuration. |
| + |
| By default, true if httpd.listenUrl uses http:// or https://, |
| and false if httpd.listenUrl uses proxy-http:// or proxy-https://. |
| |
| [[httpd.acceptorThreads]]httpd.acceptorThreads:: |
| + |
| Number of worker threads dedicated to accepting new incoming TCP |
| connections and allocating them connection-specific resources. |
| + |
| By default, 2, which should be suitable for most high-traffic sites. |
| |
| [[httpd.minThreads]]httpd.minThreads:: |
| + |
| Minimum number of spare threads to keep in the worker thread pool. |
| This number must be at least 1 larger than httpd.acceptorThreads |
| multiplied by the number of httpd.listenUrls configured. |
| + |
| By default, 5, suitable for most lower-volume traffic sites. |
| |
| [[httpd.maxThreads]]httpd.maxThreads:: |
| + |
| Maximum number of threads to permit in the worker thread pool. |
| + |
| By default 25, suitable for most lower-volume traffic sites. |
| |
| [[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. |
| + |
| Example of using a security library secure.jar under $GERRIT_SITE/lib |
| that provides a org.anyorg.MySecureFilter Servlet Filter that enforces |
| a trusted username in the `TRUSTED_USER` HTTP Header: |
| |
| ---- |
| [auth] |
| type = HTTP |
| httpHeader = TRUSTED_USER |
| |
| [httpd] |
| filterClass = org.anyorg.MySecureFilter |
| ---- |
| |
| [[httpd.robotsFile]]httpd.robotsFile:: |
| + |
| Location of an external robots.txt file to be used instead of the one |
| bundled with the .war of the application. |
| + |
| If not absolute, the path is resolved relative to `$site_path`. |
| + |
| If the file doesn't exist or can't be read the default robots.txt file |
| bundled with the .war will be used instead. |
| |
| [[httpd.registerMBeans]]httpd.registerMBeans:: |
| + |
| Enable (or disable) registration of Jetty MBeans for Java JMX. |
| + |
| By default, false. |
| |
| [[index]] |
| === Section index |
| |
| The index section configures the secondary index. |
| |
| Note that after enabling the secondary index, the index must be built |
| using the link:pgm-reindex.html[reindex program] before restarting the |
| Gerrit server. |
| |
| [[index.type]]index.type:: |
| + |
| Type of secondary indexing employed by Gerrit. The supported |
| values are: |
| + |
| * `LUCENE` |
| + |
| A link:http://lucene.apache.org/[Lucene] index is used. |
| + |
| |
| + |
| By default, `LUCENE`. |
| |
| [[index.threads]]index.threads:: |
| + |
| Number of threads to use for indexing in normal interactive operations. |
| + |
| Defaults to 1 if not set, or set to a negative value (unless |
| link:#changeMerge.interactiveThreadPoolSize[changeMerge.interactiveThreadPoolSize] |
| is iset). |
| |
| [[index.batchThreads]]index.batchThreads:: |
| + |
| Number of threads to use for indexing in background operations, such as |
| online schema upgrades. |
| + |
| If not set or set to a negative value, defaults to the number of logical |
| CPUs as returned by the JVM (unless |
| link:#changeMerge.threadPoolSize[changeMerge.threadPoolSize] is set). |
| |
| [[index.onlineUpgrade]]index.onlineUpgrade:: |
| + |
| Whether to upgrade to new index schema versions while the server is |
| running. This is recommended as it prevents additional downtime during |
| Gerrit version upgrades (avoiding the need for an offline reindex step |
| using Reindex), but can add additional server load during the upgrade. |
| + |
| If set to false, there is no way to upgrade the index schema to take |
| advantage of new search features without restarting the server. |
| + |
| Defaults to true. |
| |
| [[index.maxLimit]]index.maxLimit:: |
| + |
| Maximum limit to allow for search queries. Requesting results above this |
| limit will truncate the list (but will still set `_more_changes` on |
| result lists). Set to 0 for no limit. |
| + |
| Defaults to no limit. |
| |
| [[index.maxPages]]index.maxPages:: |
| + |
| Maximum number of pages of search results to allow, as index |
| implementations may have to scan through large numbers of skipped |
| results when searching with an offset. Requesting results starting past |
| this threshold times the requested limit will result in an error. Set to |
| 0 for no limit. |
| + |
| Defaults to no limit. |
| |
| [[index.maxTerms]]index.maxTerms:: |
| + |
| Maximum number of leaf terms to allow in a query. Too-large queries may |
| perform poorly, so setting this option causes query parsing to fail fast |
| before attempting to send them to the secondary index. Set to 0 for no |
| limit. |
| + |
| Defaults to 500. |
| |
| ==== 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.defaultMaxClauseCount]]index.defaultMaxClauseCount:: |
| + |
| Only used when the type is `LUCENE`. |
| + |
| Sets the maximum number of clauses permitted per BooleanQuery. |
| + |
| Defaults to 1024. |
| |
| [[index.name.ramBufferSize]]index.name.ramBufferSize:: |
| + |
| Determines the amount of RAM that may be used for buffering added documents |
| and deletions before they are flushed to the index. See the |
| link:http://lucene.apache.org/core/4_6_0/core/org/apache/lucene/index/LiveIndexWriterConfig.html#setRAMBufferSizeMB(double)[ |
| Lucene documentation] for further details. |
| + |
| Defaults to 16M. |
| |
| [[index.name.maxBufferedDocs]]index.name.maxBufferedDocs:: |
| + |
| Determines the minimal number of documents required before the buffered |
| in-memory documents are flushed to the index. Large values generally |
| give faster indexing. See the |
| link:http://lucene.apache.org/core/4_6_0/core/org/apache/lucene/index/LiveIndexWriterConfig.html#setMaxBufferedDocs(int)[ |
| Lucene documentation] for further details. |
| + |
| Defaults to -1, meaning no maximum is set and the writer will flush |
| according to RAM usage. |
| |
| [[index.name.commitWithin]]index.name.commitWithin:: |
| + |
| Determines the period at which changes are automatically committed to |
| stable store on disk. This is a costly operation and may block |
| additional index writes, so lower with caution. |
| + |
| If zero, changes are committed after every write. This is very costly |
| but may be useful if offline reindexing is infeasible, or for development |
| servers. |
| + |
| Values can be specified using standard time unit abbreviations (`ms`, `sec`, |
| `min`, etc.). |
| + |
| If negative, `commitWithin` is disabled. Changes are flushed to disk when |
| the in-memory buffer fills, but only committed and guaranteed to be synced |
| to disk when the process finishes. |
| + |
| Defaults to 300000 ms (5 minutes). |
| |
| Sample Lucene index configuration: |
| ---- |
| [index] |
| type = LUCENE |
| defaultMaxClauseCount = 2048 |
| |
| [index "changes_open"] |
| ramBufferSize = 60 m |
| maxBufferedDocs = 3000 |
| |
| [index "changes_closed"] |
| ramBufferSize = 20 m |
| maxBufferedDocs = 500 |
| ---- |
| |
| [[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 both |
| link:http://www.ietf.org/rfc/rfc2307.txt[RFC 2307] and Active |
| Directory. |
| |
| ---- |
| [ldap] |
| server = ldap://ldap.example.com |
| |
| accountBase = ou=people,dc=example,dc=com |
| accountPattern = (&(objectClass=person)(uid=${username})) |
| accountFullName = displayName |
| accountEmailAddress = mail |
| |
| groupBase = ou=groups,dc=example,dc=com |
| groupMemberPattern = (&(objectClass=group)(member=${dn})) |
| ---- |
| |
| [[ldap.server]]ldap.server:: |
| + |
| URL of the organization's LDAP server to query for user information |
| and group membership from. Must be of the form `ldap://host` or |
| `ldaps://host` to bind with either a plaintext or SSL connection. |
| + |
| If `auth.type` is `LDAP` this setting should use `ldaps://` to |
| ensure the end user's plaintext password is transmitted only over |
| an encrypted connection. |
| |
| [[ldap.sslVerify]]ldap.sslVerify:: |
| + |
| If false and ldap.server is an `ldaps://` style URL, Gerrit |
| will not verify the server certificate when it connects to |
| perform a query. |
| + |
| By default, true, requiring the certificate to be verified. |
| |
| [[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 RFC 2307 servers, |
| and `(&(objectClass=user)(sAMAccountName=${username}))` |
| for Active Directory. |
| |
| [[ldap.accountFullName]]ldap.accountFullName:: |
| + |
| _(Optional)_ Name of an attribute on the user account object which |
| contains the initial value for the user's full name field in Gerrit. |
| Typically this is the `displayName` property in LDAP, but could |
| also be `legalName` or `cn`. |
| + |
| Attribute values may be concatenated with literal strings. For |
| example to join given name and surname together, use the pattern |
| `${givenName} ${SN}`. |
| + |
| If set, users will be unable to modify their full name field, as |
| Gerrit will populate it only from the LDAP data. |
| + |
| Default is `displayName` for RFC 2307 servers, |
| and `${givenName} ${sn}` for Active Directory. |
| |
| [[ldap.accountEmailAddress]]ldap.accountEmailAddress:: |
| + |
| _(Optional)_ Name of an attribute on the user account object which |
| contains the user's Internet email address, as defined by this |
| LDAP server. |
| + |
| Attribute values may be concatenated with literal strings, |
| for example to set the email address to the lowercase form |
| of sAMAccountName followed by a constant domain name, use |
| `${sAMAccountName.toLowerCase}@example.com`. |
| + |
| If set, the preferred email address will be prefilled from LDAP, |
| but users may still be able to register additional email addresses, |
| and select a different preferred email address. |
| + |
| Default is `mail`. |
| |
| [[ldap.accountSshUserName]]ldap.accountSshUserName:: |
| + |
| _(Optional)_ Name of an attribute on the user account object which |
| contains the initial value for the user's SSH username field in |
| Gerrit. Typically this is the `uid` property in LDAP, but could |
| also be `cn`. Administrators should prefer to match the attribute |
| corresponding to the user's workstation username, as this is what |
| SSH clients will default to. |
| + |
| Attribute values may also be forced to lowercase, or to uppercase in |
| an expression. For example, `${sAMAccountName.toLowerCase}` will |
| force the value of sAMAccountName, if defined, to be all lowercase. |
| The suffix `.toUpperCase` can be used for the other direction. |
| The suffix `.localPart` can be used to split attribute values of |
| the form 'user@example.com' and return only the left hand side, for |
| example `${userPrincipalName.localPart}` would provide only 'user'. |
| + |
| If set, users will be unable to modify their SSH username field, as |
| Gerrit will populate it only from the LDAP data. |
| + |
| Default is `uid` for 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 servers. |
| + |
| Default is unset for RFC 2307 servers (disabled) |
| and `memberOf` for 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. |
| |
| [[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 RFC 2307, |
| 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. |
| |
| [[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.localUsernameToLowerCase]]ldap.localUsernameToLowerCase:: |
| + |
| Converts the local username, that is used to login into the Gerrit |
| Web UI, to lower case before doing the LDAP authentication. By setting |
| this parameter to true, a case insensitive login to the Gerrit Web UI |
| can be achieved. |
| + |
| If set, it must be ensured that the local usernames for all existing |
| accounts are converted to lower case, otherwise a user that has a |
| local username that contains upper case characters will not be able to login |
| anymore. The local usernames for the existing accounts can be |
| converted to lower case by running the server program |
| link:pgm-LocalUsernamesToLowerCase.html[LocalUsernamesToLowerCase]. |
| Please be aware that the conversion of the local usernames to lower |
| case can't be undone. For newly created accounts the local username |
| will be directly stored in lower case. |
| + |
| By default, unset/false. |
| |
| [[ldap.authentication]]ldap.authentication:: |
| + |
| Defines how Gerrit authenticates with the server. When set to `GSSAPI` |
| Gerrit will use Kerberos. To use kerberos the |
| `java.security.auth.login.config` system property must point to a |
| login to a JAAS configuration file and, if Java 6 is used, the system |
| property `java.security.krb5.conf` must point to the appropriate |
| krb5.ini file with references to the KDC. |
| |
| Typical jaas.conf. |
| |
| ---- |
| KerberosLogin { |
| com.sun.security.auth.module.Krb5LoginModule |
| required |
| useTicketCache=true |
| doNotPrompt=true |
| renewTGT=true; |
| }; |
| ---- |
| |
| See Java documentation on how to create the krb5.ini file. |
| |
| Note the `renewTGT` property to make sure the TGT does not expire, |
| and `useTicketCache` to use the TGT supplied by the operating system. As |
| the whole point of using GSSAPI is to have passwordless authentication |
| to the LDAP service, this option does not acquire a new TGT on its own. |
| |
| On Windows servers the registry key `HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\Parameters` |
| must have the DWORD value `allowtgtsessionkey` set to 1 and the account must not |
| have local administrator privileges. |
| |
| [[ldap.useConnectionPooling]]ldap.useConnectionPooling:: |
| + |
| _(Optional)_ Enable the LDAP connection pooling or not. |
| + |
| If it is true, the LDAP service provider maintains a pool of (possibly) |
| previously used connections and assigns them to a Context instance as |
| needed. When a Context instance is done with a connection (closed or |
| garbage collected), the connection is returned to the pool for future use. |
| + |
| For details, see link:http://docs.oracle.com/javase/tutorial/jndi/ldap/pool.html[ |
| LDAP connection management (Pool)] and link:http://docs.oracle.com/javase/tutorial/jndi/ldap/config.html[ |
| LDAP connection management (Configuration)] |
| + |
| By default, false. |
| |
| [[ldap.connectTimeout]]ldap.connectTimeout:: |
| + |
| _(Optional)_ Timeout period for establishment of an LDAP connection. |
| + |
| The value is in the usual time-unit format like "1 s", "100 ms", |
| etc... |
| + |
| By default there is no timeout and Gerrit will wait indefinitely. |
| |
| [[ldap-connection-pooling]] |
| ==== LDAP Connection Pooling |
| Once LDAP connection pooling is enabled by setting the link:#ldap.useConnectionPooling[ |
| ldap.useConnectionPooling] configuration property to `true`, the connection pool |
| can be configured using JVM system properties as explained in the |
| link:http://docs.oracle.com/javase/7/docs/technotes/guides/jndi/jndi-ldap.html#POOL[ |
| Java SE Documentation]. |
| |
| For standalone Gerrit (running with the embedded Jetty), JVM system properties |
| are specified in the link:#container[container section]: |
| |
| ---- |
| javaOptions = -Dcom.sun.jndi.ldap.connect.pool.maxsize=20 |
| javaOptions = -Dcom.sun.jndi.ldap.connect.pool.prefsize=10 |
| javaOptions = -Dcom.sun.jndi.ldap.connect.pool.timeout=300000 |
| ---- |
| |
| [[log]] |
| === Section log |
| |
| [[log.jsonLogging]]log.jsonLogging:: |
| + |
| If set to true, enables error logging in JSON format (file name: "logs/error_log.json"). |
| + |
| Defaults to false. |
| |
| [[log.textLogging]]log.textLogging:: |
| + |
| If set to true, enables error logging in regular plain text format. Can only be disabled |
| if `jsonLogging` is enabled. |
| + |
| Defaults to true. |
| |
| [[mimetype]] |
| === Section mimetype |
| |
| [[mimetype.name.safe]]mimetype.<name>.safe:: |
| + |
| If set to true, files with the MIME type `<name>` will be sent as |
| direct downloads to the user's browser, rather than being wrapped up |
| inside of zipped archives. The type name may be a complete type |
| name, e.g. `image/gif`, a generic media type, e.g. `+image/*+`, |
| or the wildcard `+*/*+` to match all types. |
| + |
| By default, false for all MIME types. |
| |
| Common examples: |
| ---- |
| [mimetype "image/*"] |
| safe = true |
| |
| [mimetype "application/pdf"] |
| safe = true |
| |
| [mimetype "application/msword"] |
| safe = true |
| |
| [mimetype "application/vnd.ms-excel"] |
| safe = true |
| ---- |
| |
| |
| [[pack]] |
| === Section pack |
| |
| Global settings controlling how Gerrit Code Review creates pack |
| streams for Git clients running clone, fetch, or pull. Most of these |
| variables are per-client request, and thus should be carefully set |
| given the expected concurrent request load and available CPU and |
| memory resources. |
| |
| [[pack.deltacompression]]pack.deltacompression:: |
| + |
| If true, delta compression between objects is enabled. This may |
| result in a smaller overall transfer for the client, but requires |
| more server memory and CPU time. |
| + |
| False (off) by default, matching Gerrit Code Review 2.1.4. |
| |
| [[pack.threads]]pack.threads:: |
| + |
| Maximum number of threads to use for delta compression (if enabled). |
| This is per-client request. If set to 0 then the number of CPUs is |
| auto-detected and one thread per CPU is used, per client request. |
| + |
| By default, 1. |
| |
| |
| [[plugins]] |
| === Section plugins |
| |
| [[plugins.checkFrequency]]plugins.checkFrequency:: |
| + |
| How often plugins should be examined for new plugins to load, removed |
| plugins to be unloaded, or updated plugins to be reloaded. Values can |
| be specified using standard time unit abbreviations ('ms', 'sec', |
| 'min', etc.). |
| + |
| If set to 0, automatic plugin reloading is disabled. Administrators |
| may force reloading with link:cmd-plugin-reload.html[gerrit plugin reload]. |
| + |
| Default is 1 minute. |
| |
| [[plugins.allowRemoteAdmin]]plugins.allowRemoteAdmin:: |
| + |
| Enable remote installation, enable and disable of plugins over HTTP |
| and SSH. If set to true Administrators can install new plugins |
| remotely, or disable existing plugins. Defaults to false. |
| |
| [[plugins.jsLoadTimeout]]plugins.jsLoadTimeout:: |
| + |
| Set the timeout value for loading JavaScript plugins in Gerrit UI. |
| Values can be specified using standard time unit abbreviations ('ms', |
| 'sec', 'min', etc.). |
| + |
| Default is 5 seconds. Negative values will be converted to 0. |
| |
| [[receive]] |
| === Section receive |
| |
| This section is used to configure behavior of the 'receive-pack' |
| handler, which responds to 'git push' requests. |
| |
| [[receive.allowGroup]]receive.allowGroup:: |
| + |
| Name of the groups of users that are allowed to execute |
| 'receive-pack' on the server. One or more groups can be set. |
| + |
| If no groups are added, any user will be allowed to execute |
| 'receive-pack' on the server. |
| |
| [[receive.certNonceSeed]]receive.certNonceSeed:: |
| + |
| If set to a non-empty value and server-side signed push validation is |
| link:#receive.enableSignedPush[enabled], use this value as the seed to |
| the HMAC SHA-1 nonce generator. If unset, a 64-byte random seed will be |
| generated at server startup. |
| + |
| As this is used as the seed of a cryptographic algorithm, it is |
| recommended to be placed in link:#secure-config[`secure.config`]. |
| + |
| Defaults to unset. |
| |
| [[receive.certNonceSlop]]receive.certNonceSlop:: |
| + |
| When validating the nonce passed as part of the signed push protocol, |
| accept valid nonces up to this many seconds old. This allows |
| certificate verification to work over HTTP where there is a lag between |
| the HTTP response providing the nonce to sign and the next request |
| containing the signed nonce. This can be significant on large |
| repositories, since the lag also includes the time to count objects on |
| the client. |
| + |
| Default is 5 minutes. |
| |
| [[receive.changeUpdateThreads]]receive.changeUpdateThreads:: |
| + |
| Number of threads to perform change creation or patch set updates |
| concurrently. Each thread uses its own database connection from |
| the database connection pool, and if all threads are busy then |
| main receive thread will also perform a change creation or patch |
| set update. |
| + |
| Defaults to 1, using only the main receive thread. This feature is for |
| databases with very high latency that can benefit from concurrent |
| operations when multiple changes are impacted at once. |
| |
| [[receive.checkMagicRefs]]receive.checkMagicRefs:: |
| + |
| If true, Gerrit will verify the destination repository has |
| no references under the magic 'refs/drafts', 'refs/for', or |
| 'refs/publish' branch namespaces. Names under these locations |
| confuse clients when trying to upload code reviews so Gerrit |
| requires them to be empty. |
| + |
| If false Gerrit skips the sanity check and assumes administrators |
| have ensured the repository does not contain any magic references. |
| Setting to false to skip the check can decrease latency during push. |
| + |
| Default is true. |
| |
| [[receive.checkReferencedObjectsAreReachable]]receive.checkReferencedObjectsAreReachable:: |
| + |
| If set to true, Gerrit will validate that all referenced objects that |
| are not included in the received pack are reachable by the user. |
| + |
| Carrying out this check on gits with many refs and commits can be a |
| very CPU-heavy operation. For non public Gerrit-servers this check may |
| be overkill. |
| + |
| Only disable this check if you trust the clients not to forge SHA1 |
| references to access commits intended to be hidden from the user. |
| + |
| Default is true. |
| |
| [[receive.enableSignedPush]]receive.enableSignedPush:: |
| + |
| If true, server-side signed push validation is enabled. |
| + |
| When a client pushes with `git push --signed`, this ensures that the |
| push certificate is valid and signed with a valid public key stored in |
| the `refs/gpg-keys` branch of `All-Users`. |
| + |
| Defaults to false. |
| |
| [[receive.maxBatchChanges]]receive.maxBatchChanges:: |
| + |
| The maximum number of changes that Gerrit allows to be pushed |
| in a batch for review. When this number is exceeded Gerrit rejects |
| the push with an error message. |
| + |
| May be overridden for certain groups by specifying a limit in the |
| link:access-control.html#capability_batchChangesLimit['Batch Changes Limit'] |
| global capability. |
| + |
| This setting can be used to prevent users from uploading large |
| number of changes for review by mistake. |
| + |
| Default is zero, no limit. |
| |
| [[receive.maxObjectSizeLimit]]receive.maxObjectSizeLimit:: |
| + |
| Maximum allowed Git object size that 'receive-pack' will accept. |
| If an object is larger than the given size the pack-parsing will abort |
| and the push operation will fail. If set to zero then there is no |
| limit. |
| + |
| Gerrit administrators can use this setting to prevent developers |
| from pushing objects which are too large to Gerrit. |
| + |
| This setting can also be set in the `project.config` |
| link:config-project-config.html[receive.maxObjectSizeLimit] in order |
| to further reduce the global setting. The project specific setting is |
| only honored when it further reduces the global limit. |
| + |
| Default is zero. |
| + |
| Common unit suffixes of 'k', 'm', or 'g' are supported. |
| |
| [[receive.maxTrustDepth]]receive.maxTrustDepth:: |
| + |
| If signed push validation is link:#receive.enableSignedPush[enabled], |
| set to the maximum depth to search when checking if a key is |
| link:#receive.trustedKey[trusted]. |
| + |
| Default is 0, meaning only explicitly trusted keys are allowed. |
| |
| [[receive.threadPoolSize]]receive.threadPoolSize:: |
| + |
| Maximum size of the thread pool in which the change data in received packs is |
| processed. |
| + |
| Defaults to the number of available CPUs according to the Java runtime. |
| |
| [[receive.timeout]]receive.timeout:: |
| + |
| Overall timeout on the time taken to process the change data in |
| received packs. Only includes the time processing Gerrit changes |
| and updating references, not the time to index the pack. Values can |
| be specified using standard time unit abbreviations ('ms', 'sec', |
| 'min', etc.). |
| + |
| Default is 4 minutes. If no unit is specified, milliseconds |
| is assumed. |
| |
| [[receive.trustedKey]]receive.trustedKey:: |
| + |
| List of GPG key fingerprints that should be considered trust roots by |
| the server when signed push validation is |
| link:#receive.enableSignedPush[enabled]. A key is trusted by the server |
| if it is either in this list, or a path of trust signatures leads from |
| the key to a configured trust root. The maximum length of the path is |
| determined by link:#receive.maxTrustDepth[`receive.maxTrustDepth`]. |
| + |
| Key fingerprints can be displayed with `gpg --list-keys |
| --with-fingerprint`. |
| + |
| Trust signatures can be added to a key using the `tsign` command to |
| link:https://www.gnupg.org/documentation/manuals/gnupg/OpenPGP-Key-Management.html[ |
| `gpg --edit-key`], after which the signed key should be re-uploaded. |
| + |
| If no keys are specified, web-of-trust checks are disabled. This is the |
| default behavior. |
| |
| |
| [[repository]] |
| === Section repository |
| |
| Repositories in this sense are the same as projects. |
| |
| In the following example configuration `Registered Users` is set |
| to be the default owner of new projects. |
| |
| ---- |
| [repository "*"] |
| ownerGroup = Registered Users |
| ---- |
| |
| The only matching patterns supported are exact match or wildcard matching which |
| can be specified by ending the name with a `*`. If a project matches more than one |
| repository configuration, then the configuration from the more precise match |
| will be used. In the following example, the default submit type for a project |
| named `project/plugins/a` would be `CHERRY_PICK`. |
| |
| ---- |
| [repository "project/*"] |
| defaultSubmitType = MERGE_IF_NECESSARY |
| [repository "project/plugins/*"] |
| defaultSubmitType = CHERRY_PICK |
| ---- |
| |
| [NOTE] All properties are used from the matching repository configuration. In |
| the previous example, all properties will be used from `project/plugins/\*` |
| section and no properties will be inherited nor overridden from `project/*`. |
| |
| [[repository.name.defaultSubmitType]]repository.<name>.defaultSubmitType:: |
| + |
| The default submit type for newly created projects. Supported values |
| are `MERGE_IF_NECESSARY`, `FAST_FORWARD_ONLY`, `REBASE_IF_NECESSARY`, |
| `MERGE_ALWAYS` and `CHERRY_PICK`. |
| + |
| By default, `MERGE_IF_NECESSARY`. |
| |
| [[repository.name.ownerGroup]]repository.<name>.ownerGroup:: |
| + |
| A name of a group which exists in the database. Zero, one or many |
| groups are allowed. Each on its own line. Groups which don't exist |
| in the database are ignored. |
| |
| [[rules]] |
| === Section rules |
| |
| [[rules.enable]]rules.enable:: |
| + |
| If true, Gerrit will load and execute 'rules.pl' files in each |
| project's refs/meta/config branch, if present. When set to false, |
| only the default internal rules will be used. |
| + |
| Default is true, to execute project specific rules. |
| |
| [[rules.reductionLimit]]rules.reductionLimit:: |
| + |
| Maximum number of Prolog reductions that can be performed when |
| evaluating rules for a single change. Each function call made |
| in user rule code, internal Gerrit Prolog code, or the Prolog |
| interpreter counts against this limit. |
| + |
| Sites using very complex rules that need many reductions should |
| compile Prolog to Java bytecode with link:pgm-rulec.html[rulec]. |
| This eliminates the dynamic Prolog interpreter from charging its |
| own reductions against the limit, enabling more logic to execute |
| within the same bounds. |
| + |
| A reductionLimit of 0 is nearly infinite, implemented by setting |
| the internal limit to 2^31-1. |
| + |
| Default is 100,000 reductions (about 14 ms on Intel Core i7 CPU). |
| |
| [[rules.compileReductionLimit]]rules.compileReductionLimit:: |
| + |
| Maximum number of Prolog reductions that can be performed when |
| compiling source code to internal Prolog machine code. |
| + |
| Default is 10x reductionLimit (1,000,000). |
| |
| [[execution]] |
| === Section execution |
| |
| [[execution.defaultThreadPoolSize]]execution.defaultThreadPoolSize:: |
| + |
| The default size of the background execution thread pool in |
| which miscellaneous tasks are handled. |
| + |
| Default is 1. |
| |
| [[sendemail]] |
| === Section sendemail |
| |
| [[sendemail.enable]]sendemail.enable:: |
| + |
| If false Gerrit will not send email messages, for any reason, |
| and all other properties of section sendemail are ignored. |
| + |
| By default, true, allowing notifications to be sent. |
| |
| [[sendemail.connectTimeout]]sendemail.connectTimeout:: |
| + |
| The connection timeout of opening a socket connected to a |
| remote SMTP server. |
| + |
| Values can be specified using standard time unit abbreviations |
| ('ms', 'sec', 'min', etc.). |
| If no unit is specified, milliseconds is assumed. |
| + |
| Default is 0. A timeout of zero is interpreted as an infinite |
| timeout. The connection will then block until established or |
| an error occurs. |
| |
| [[sendemail.threadPoolSize]]sendemail.threadPoolSize:: |
| + |
| Maximum size of thread pool in which the review comments |
| notifications are sent out asynchronously. |
| + |
| By default, 1. |
| |
| [[sendemail.from]]sendemail.from:: |
| + |
| Designates what name and address Gerrit will place in the From |
| field of any generated email messages. The supported values are: |
| + |
| * `USER` |
| + |
| Gerrit will set the From header to use the current user's |
| Full Name and Preferred Email. This may cause messages to be |
| classified as spam if the user's domain has SPF or DKIM enabled |
| and <<sendemail.smtpServer,sendemail.smtpServer>> is not a trusted |
| relay for that domain. |
| + |
| * `MIXED` |
| + |
| Shorthand for `${user} (Code Review) <review@example.com>` where |
| `review@example.com` is the same as <<user.email,user.email>>. |
| See below for a description of how the replacement is handled. |
| + |
| * `SERVER` |
| + |
| Gerrit will set the From header to the same name and address |
| it records in any commits Gerrit creates. This is set by |
| <<user.name,user.name>> and <<user.email,user.email>>, or guessed |
| from the local operating system. |
| + |
| * `Code Review <review@example.com>` |
| + |
| If set to a name and email address in brackets, Gerrit will use |
| this name and email address for any messages, overriding the name |
| that may have been selected for commits by user.name and user.email. |
| Optionally, the name portion may contain the placeholder `${user}`, |
| which is replaced by the Full Name of the current user. |
| |
| + |
| By default, MIXED. |
| |
| [[sendemail.smtpServer]]sendemail.smtpServer:: |
| + |
| Hostname (or IP address) of a SMTP server that will relay |
| messages generated by Gerrit to end users. |
| + |
| By default, 127.0.0.1 (aka localhost). |
| |
| [[sendemail.smtpServerPort]]sendemail.smtpServerPort:: |
| + |
| Port number of the SMTP server in sendemail.smtpserver. |
| + |
| By default, 25, or 465 if smtpEncryption is 'ssl'. |
| |
| [[sendemail.smtpEncryption]]sendemail.smtpEncryption:: |
| + |
| Specify the encryption to use, either 'ssl' or 'tls'. |
| + |
| By default, 'none', indicating no encryption is used. |
| |
| [[sendemail.sslVerify]]sendemail.sslVerify:: |
| + |
| If false and sendemail.smtpEncryption is 'ssl' or 'tls', Gerrit |
| will not verify the server certificate when it connects to send |
| an email message. |
| + |
| By default, true, requiring the certificate to be verified. |
| |
| [[sendemail.smtpUser]]sendemail.smtpUser:: |
| + |
| User name to authenticate with, if required for relay. |
| |
| [[sendemail.smtpPass]]sendemail.smtpPass:: |
| + |
| Password for the account named by sendemail.smtpUser. |
| |
| [[sendemail.allowrcpt]]sendemail.allowrcpt:: |
| + |
| If present, each value adds one entry to the whitelist of email |
| addresses that Gerrit can send email to. If set to a complete |
| email address, that one address is added to the white list. |
| If set to a domain name, any address at that domain can receive |
| email from Gerrit. |
| + |
| By default, unset, permitting delivery to any email address. |
| |
| [[sendemail.includeDiff]]sendemail.includeDiff:: |
| + |
| If true, new change emails and merged change emails from Gerrit |
| will include the complete unified diff of the change. |
| Variable maxmimumDiffSize places an upper limit on how large the |
| email can get when this option is enabled. |
| + |
| By default, false. |
| |
| [[sendemail.maximumDiffSize]]sendemail.maximumDiffSize:: |
| + |
| Largest size of unified diff output to include in an email. When |
| the diff exceeds this size the file paths will be listed instead. |
| Standard byte unit suffixes are supported. |
| + |
| By default, 256 KiB. |
| |
| [[sendemail.importance]]sendemail.importance:: |
| + |
| If present, emails sent from Gerrit will have the given level |
| of importance. Valid values include 'high' and 'low', which |
| email clients will render in different ways. |
| + |
| By default, unset, so no Importance header is generated. |
| |
| [[sendemail.expiryDays]]sendemail.expiryDays:: |
| + |
| If present, emails sent from Gerrit will expire after the given |
| number of days. This will add the Expiry-Date header and |
| email clients may expire or expunge mails whose Expiry-Date |
| header is in the past. This should be a positive non-zero |
| number indicating how many days in the future the mails |
| should expire. |
| + |
| By default, unset, so no Expiry-Date header is generated. |
| |
| |
| [[site]] |
| === Section site |
| |
| [[site.refreshHeaderFooter]]site.refreshHeaderFooter:: |
| + |
| If true the server checks the site header, footer and CSS files for |
| updated versions. If false, a server restart is required to change |
| any of these resources. Default is true, allowing automatic reloads. |
| |
| [[ssh-alias]] |
| === Section ssh-alias |
| |
| Variables in section ssh-alias permit the site administrator to alias |
| another command from Gerrit or a plugin into the `gerrit` command |
| namespace. To alias `replication start` to `gerrit replicate`: |
| |
| ---- |
| [ssh-alias] |
| replicate = replication start |
| ---- |
| |
| [[sshd]] |
| === Section sshd |
| |
| [[sshd.enableCompression]]sshd.enableCompression:: |
| + |
| In the general case, we want to disable transparent compression, since |
| the majority of our data transfer is highly compressed Git pack files |
| and we cannot make them any smaller than they already are. |
| + |
| However, if there are CPU in abundance and the server is reachable |
| through slow networks, gits with huge amount of refs can benefit from |
| SSH-compression since git does not compress the ref announcement during |
| handshake. |
| + |
| Compression can be especially useful when Gerrit slaves are being used |
| for the larger clones and fetches and the master server mostly takes |
| small receive-packs. |
| + |
| By default, `false`. |
| |
| [[sshd.backend]]sshd.backend:: |
| + |
| Starting from version 0.9.0 Apache SSHD project added support for NIO2 |
| IoSession. To use the new NIO2 session the `backend` option must be set |
| to `NIO2`. |
| + |
| By default, `MINA`. |
| |
| [[sshd.listenAddress]]sshd.listenAddress:: |
| + |
| Specifies the local addresses the internal SSHD should listen |
| for connections on. The following forms may be used to specify |
| an address. In any form, `:'port'` may be omitted to use the |
| default of 29418. |
| + |
| * 'hostname':'port' (for example `review.example.com:29418`) |
| * 'IPv4':'port' (for example `10.0.0.1:29418`) |
| * ['IPv6']:'port' (for example `[ff02::1]:29418`) |
| * +*:'port'+ (for example `+*:29418+`) |
| |
| + |
| -- |
| If multiple values are supplied, the daemon will listen on all |
| of them. |
| |
| To disable the internal SSHD, set listenAddress to `off`. |
| |
| By default, *:29418. |
| -- |
| |
| [[sshd.advertisedAddress]]sshd.advertisedAddress:: |
| + |
| Specifies the addresses clients should be told to connect to. |
| This may differ from sshd.listenAddress if a firewall based port |
| redirector is being used, making Gerrit appear to answer on port |
| 22. The following forms may be used to specify an address. In any |
| form, `:'port'` may be omitted to use the default SSH port of 22. |
| |
| * 'hostname':'port' (for example `review.example.com:22`) |
| * 'IPv4':'port' (for example `10.0.0.1:29418`) |
| * ['IPv6']:'port' (for example `[ff02::1]:29418`) |
| |
| + |
| -- |
| If multiple values are supplied, the daemon will advertise all |
| of them. |
| |
| By default, sshd.listenAddress. |
| -- |
| |
| [[sshd.tcpKeepAlive]]sshd.tcpKeepAlive:: |
| + |
| If true, enables TCP keepalive messages to the other side, so |
| the daemon can terminate connections if the peer disappears. |
| + |
| Only effective when `sshd.backend` is set to `MINA`. |
| + |
| By default, true. |
| |
| [[sshd.threads]]sshd.threads:: |
| + |
| Number of threads to use when executing SSH command requests. |
| If additional requests are received while all threads are busy they |
| are queued and serviced in a first-come-first-served order. |
| + |
| By default, 1.5x the number of CPUs available to the JVM. |
| |
| [[sshd.batchThreads]]sshd.batchThreads:: |
| + |
| Number of threads to allocate for SSH command requests from |
| link:access-control.html#non-interactive_users[non-interactive users]. |
| If equals to 0, then all non-interactive requests are executed in the same |
| queue as interactive requests. |
| + |
| Any other value will remove the number of threads from the queue |
| allocated to interactive users, and create a separate thread pool |
| of the requested size, which will be used to run commands from |
| non-interactive users. |
| + |
| If the number of threads requested for non-interactive users is larger |
| than the total number of threads allocated in sshd.threads, then the |
| value of sshd.threads is increased to accommodate the requested value. |
| + |
| By default is 1 on single core node, 2 otherwise. |
| |
| [[sshd.streamThreads]]sshd.streamThreads:: |
| + |
| Number of threads to use when formatting events to asynchronous |
| streaming clients. Event formatting is multiplexed onto this thread |
| pool by a simple FIFO scheduling system. |
| + |
| By default, 1 plus the number of CPUs available to the JVM. |
| |
| [[sshd.commandStartThreads]]sshd.commandStartThreads:: |
| + |
| Number of threads used to parse a command line submitted by a client |
| over SSH for execution, create the internal data structures used by |
| that command, and schedule it for execution on another thread. |
| + |
| By default, 2. |
| |
| [[sshd.maxAuthTries]]sshd.maxAuthTries:: |
| + |
| Maximum number of authentication attempts before the server |
| disconnects the client. Each public key that a client has loaded |
| into its local agent counts as one auth request. Users can work |
| around the server's limit by loading less keys into their agent, |
| or selecting a specific key in their `~/.ssh/config` file with |
| the `IdentityFile` option. |
| + |
| By default, 6. |
| |
| [[sshd.loginGraceTime]]sshd.loginGraceTime:: |
| + |
| Time in seconds that a client has to authenticate before the server |
| automatically terminates their connection. Values should use common |
| unit suffixes to express their setting: |
| + |
| * s, sec, second, seconds |
| * m, min, minute, minutes |
| * h, hr, hour, hours |
| * d, day, days |
| |
| + |
| By default, 2 minutes. |
| |
| [[sshd.idleTimeout]]sshd.idleTimeout:: |
| + |
| Time in seconds after which the server automatically terminates idle |
| connections (or 0 to disable closing of idle connections). Values |
| should use common unit suffixes to express their setting: |
| + |
| * s, sec, second, seconds |
| * m, min, minute, minutes |
| * h, hr, hour, hours |
| * d, day, days |
| |
| + |
| By default, 0. |
| |
| [[sshd.maxConnectionsPerUser]]sshd.maxConnectionsPerUser:: |
| + |
| Maximum number of concurrent SSH sessions that a user account |
| may open at one time. This is the number of distinct SSH logins |
| that each user may have active at one time, and is not related to |
| the number of commands a user may issue over a single connection. |
| If set to 0, there is no limit. |
| + |
| By default, 64. |
| |
| [[sshd.cipher]]sshd.cipher:: |
| + |
| Available ciphers. To permit multiple ciphers, specify multiple |
| `sshd.cipher` keys in the configuration file, one cipher name |
| per key. Cipher names starting with `+` are enabled in addition |
| to the default ciphers, cipher names starting with `-` are removed |
| from the default cipher set. |
| + |
| Supported ciphers: aes128-cbc, aes128-cbc, aes256-cbc, blowfish-cbc, |
| 3des-cbc, none. |
| + |
| By default, all supported ciphers except `none` are available. |
| |
| [[sshd.mac]]sshd.mac:: |
| + |
| Available MAC (message authentication code) algorithms. To permit |
| multiple algorithms, specify multiple `sshd.mac` keys in the |
| configuration file, one MAC per key. MAC names starting with `+` |
| are enabled in addition to the default MACs, MAC names starting with |
| `-` are removed from the default MACs. |
| + |
| Supported MACs: hmac-md5, hmac-md5-96, hmac-sha1, hmac-sha1-96, |
| hmac-sha2-256, hmac-sha2-512. |
| + |
| By default, all supported MACs are available. |
| |
| [[sshd.kerberosKeytab]]sshd.kerberosKeytab:: |
| + |
| Enable kerberos authentication for SSH connections. To permit |
| kerberos authentication, the server must have a host principal |
| (see `sshd.kerberosPrincipal`) which is acquired from a keytab. |
| This must be provisioned by the kerberos administrators, and is |
| typically installed into `/etc/krb5.keytab` on host machines. |
| + |
| The keytab must contain at least one `host/` principal, typically |
| using the host's canonical name. If it does not use the |
| canonical name, the `sshd.kerberosPrincipal` should be configured |
| with the correct name. |
| + |
| By default, not set and so kerberos authentication is not enabled. |
| |
| [[sshd.kerberosPrincipal]]sshd.kerberosPrincipal:: |
| + |
| If kerberos authentication is enabled with `sshd.kerberosKeytab`, |
| instead use the given principal name instead of the default. |
| If the principal does not begin with `host/` a warning message is |
| printed and may prevent successful authentication. |
| + |
| This may be useful if the host is behind an IP load balancer or |
| other SSH forwarding systems, since the principal name is constructed |
| by the client and must match for kerberos authentication to work. |
| + |
| By default, `host/canonical.host.name` |
| |
| [[sshd.requestLog]]sshd.requestLog:: |
| + |
| Enable (or disable) the `'$site_path'/logs/sshd_log` request log. |
| If enabled, a request log file is written out by the SSH daemon. |
| + |
| `log4j.appender` with the name `sshd_log` can be configured to overwrite |
| programmatic configuration. |
| + |
| By default, true. |
| |
| [[sshd.rekeyBytesLimit]]sshd.rekeyBytesLimit:: |
| + |
| The SSH daemon will issue a rekeying after a certain amount of data. |
| This configuration option allows you to tweak that setting. |
| + |
| By default, 1073741824 (bytes, 1GB). |
| + |
| The rekeyBytesLimit cannot be set to lower than 32. |
| |
| [[sshd.rekeyTimeLimit]]sshd.rekeyTimeLimit:: |
| + |
| The SSH daemon will issue a rekeying after a certain amount of time. |
| This configuration option allows you to tweak that setting. |
| + |
| By default, 1h. |
| + |
| Set to 0 to disable this check. |
| |
| [[suggest]] |
| === Section suggest |
| |
| [[suggest.accounts]]suggest.accounts:: |
| + |
| If `true`, visible user accounts (according to the value of |
| `accounts.visibility`) will be offered as completion suggestions |
| when adding a reviewer to a change, or a user to a group. |
| + |
| If `false`, account suggestion is disabled. |
| + |
| Older configurations may also have one of the `accounts.visibility` |
| values for this field, including `OFF` as a synonym for `NONE`. If |
| `accounts.visibility` is also set, that value overrides this one; |
| otherwise, this value applies to both `suggest.accounts` and |
| `accounts.visibility`. |
| + |
| New configurations should prefer the boolean value for this field |
| and an enum value for `accounts.visibility`. |
| |
| [[suggest.maxSuggestedReviewers]]suggest.maxSuggestedReviewers:: |
| + |
| The maximum numbers of reviewers suggested. |
| + |
| By default 10. |
| |
| [[suggest.fullTextSearch]]suggest.fullTextSearch:: |
| + |
| If `true` the reviewer completion suggestions will be based on a full text search. |
| + |
| By default `false`. |
| |
| [[suggest.from]]suggest.from:: |
| + |
| The number of characters that a user must have typed before suggestions |
| are provided. If set to 0, suggestions are always provided. |
| + |
| By default 0. |
| |
| [[suggest.fullTextSearchMaxMatches]]suggest.fullTextSearchMaxMatches:: |
| + |
| The maximum number of matches evaluated for change access when using full text search. |
| + |
| By default 100. |
| |
| [[suggest.fullTextSearchRefresh]]suggest.fullTextSearchRefresh:: |
| + |
| Refresh interval for the in-memory account search index. |
| + |
| By default 1 hour. |
| |
| |
| [[theme]] |
| === Section theme |
| |
| [[theme.backgroundColor]]theme.backgroundColor:: |
| + |
| Background color for the page, and major data tables like the all |
| open changes table or the account dashboard. The value must be a |
| valid HTML hex color code, or standard color name. |
| + |
| By default white, `FFFFFF`. |
| |
| [[theme.topMenuColor]]theme.topMenuColor:: |
| + |
| This is the color of the main menu bar at the top of the page. |
| The value must be a valid HTML hex color code, or standard color |
| name. |
| + |
| By default white, `FFFFFF`. |
| |
| [[theme.textColor]]theme.textColor:: |
| + |
| Text color for the page, and major data tables like the all |
| open changes table or the account dashboard. The value must be a |
| valid HTML hex color code, or standard color name. |
| + |
| By default dark grey, `353535`. |
| |
| [[theme.trimColor]]theme.trimColor:: |
| + |
| Primary color used as a background color behind text. This is |
| the color of the main menu bar at the top, of table headers, |
| and of major UI areas that we want to offset from other portions |
| of the page. The value must be a valid HTML hex color code, or |
| standard color name. |
| + |
| By default a light grey, `EEEEEE`. |
| |
| [[theme.selectionColor]]theme.selectionColor:: |
| + |
| Background color used within a trimColor area to denote the currently |
| selected tab, or the background color used in a table to denote the |
| currently selected row. The value must be a valid HTML hex color |
| code, or standard color name. |
| + |
| By default a pale blue, `D8EDF9`. |
| |
| [[theme.changeTableOutdatedColor]]theme.changeTableOutdatedColor:: |
| + |
| Background color used for patch outdated messages. The value must be |
| a valid HTML hex color code, or standard color name. |
| + |
| By default a shade of red, `F08080`. |
| |
| [[theme.tableOddRowColor]]theme.tableOddRowColor:: |
| + |
| Background color for tables such as lists of open reviews for odd |
| rows. This is so you can have a different color for odd and even |
| rows of the table. The value must be a valid HTML hex color code, |
| or standard color name. |
| + |
| By default transparent. |
| |
| [[theme.tableEvenRowColor]]theme.tableEvenRowColor:: |
| + |
| Background color for tables such as lists of open reviews for even |
| rows. This is so you can have a different color for odd and even |
| rows of the table. The value must be a valid HTML hex color code, |
| or standard color name. |
| + |
| By default transparent. |
| |
| A different theme may be used for signed-in vs. signed-out user status |
| by using the "signed-in" and "signed-out" theme sections. Variables |
| not specified in a section are inherited from the default theme. |
| |
| ---- |
| [theme] |
| backgroundColor = FFFFFF |
| [theme "signed-in"] |
| backgroundColor = C0C0C0 |
| [theme "signed-out"] |
| backgroundColor = 00FFFF |
| ---- |
| |
| As example, here is the theme configuration to have the old green look: |
| |
| ---- |
| [theme] |
| backgroundColor = FCFEEF |
| textColor = 000000 |
| trimColor = D4E9A9 |
| selectionColor = FFFFCC |
| topMenuColor = D4E9A9 |
| changeTableOutdatedColor = F08080 |
| [theme "signed-in"] |
| backgroundColor = FFFFFF |
| ---- |
| |
| [[trackingid]] |
| === Section trackingid |
| |
| Tagged footer lines containing references to external |
| tracking systems, parsed out of the commit message and |
| saved in Gerrit's secondary index. |
| |
| After making changes to this section, existing changes |
| must be reindexed with link:pgm-reindex.html[reindex]. |
| |
| The tracking ids are searchable using tr:<tracking id> or |
| bug:<tracking id>. |
| |
| ---- |
| [trackingid "jira-bug"] |
| footer = Bugfix: |
| footer = Bug: |
| match = JRA\\d{2,8} |
| system = JIRA |
| |
| [trackingid "jira-feature"] |
| footer = Feature |
| match = JRA(\\d{2,8}) |
| system = JIRA |
| ---- |
| |
| [[trackingid.name.footer]]trackingid.<name>.footer:: |
| + |
| A prefix tag that identifies the footer line to parse for tracking ids. |
| + |
| Several trackingid entries can have the same footer tag, and a single trackingid |
| entry can have multiple footer tags. |
| + |
| If multiple footer tags are specified, each tag will be parsed separately and |
| duplicates will be ignored. |
| + |
| The trailing ":" is optional. |
| |
| [[trackingid.name.match]]trackingid.<name>.match:: |
| + |
| A link:http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html[standard |
| Java regular expression (java.util.regex)] used to match the |
| external tracking id part of the footer line. The match can |
| result in several entries in the DB. If grouping is used in the |
| regex the first group will be interpreted as the tracking id. |
| Tracking ids longer than 32 characters will be ignored. |
| + |
| The configuration file parser eats one level of backslashes, so the |
| character class `\s` requires `\\s` in the configuration file. The |
| parser also terminates the line at the first `#`, so a match |
| expression containing # must be wrapped in double quotes. |
| |
| [[trackingid.name.system]]trackingid.<name>.system:: |
| + |
| The name of the external tracking system (maximum 10 characters). |
| It is possible to have several trackingid entries for the same |
| tracking system. |
| |
| [[transfer]] |
| === Section transfer |
| |
| [[transfer.timeout]]transfer.timeout:: |
| + |
| Number of seconds to wait for a single network read or write |
| to complete before giving up and declaring the remote side is |
| not responding. If 0, there is no timeout, and this server will |
| wait indefinitely for a transfer to finish. |
| + |
| A timeout should be large enough to mostly transfer the objects to |
| the other side. 1 second may be too small for larger projects, |
| especially over a WAN link, while 10-30 seconds is a much more |
| reasonable timeout value. |
| + |
| Defaults to 0 seconds, wait indefinitely. |
| |
| |
| [[upload]] |
| === Section upload |
| |
| Sets the group of users allowed to execute 'upload-pack' on the |
| server, 'upload-pack' is what runs on the server during a user's |
| fetch, clone or repo sync command. |
| |
| ---- |
| [upload] |
| allowGroup = GROUP_ALLOWED_TO_EXECUTE |
| allowGroup = YET_ANOTHER_GROUP_ALLOWED_TO_EXECUTE |
| ---- |
| |
| [[upload.allowGroup]]upload.allowGroup:: |
| + |
| Name of the groups of users that are allowed to execute 'upload-pack' |
| on the server. One or more groups can be set. |
| + |
| If no groups are added, any user will be allowed to execute |
| 'upload-pack' on the server. |
| |
| [[urlAlias]] |
| === Section urlAlias |
| |
| URL aliases define regular expressions for URL tokens that are mapped |
| to target URL tokens. |
| |
| Each URL alias must be specified in its own subsection. The subsection |
| name should be a descriptive name. It must be unique, but is not |
| interpreted in any way. |
| |
| The URL aliases are applied in no particular order. The first matching |
| URL alias is used and further matches are ignored. |
| |
| URL aliases can be used to map plugin screens into the Gerrit URL |
| namespace, or to replace Gerrit screens by plugin screens. |
| |
| Example: |
| |
| ---- |
| [urlAlias "MyPluginScreen"] |
| match = /myscreen/(.*) |
| token = /x/myplugin/myscreen/$1 |
| [urlAlias "MyChangeScreen"] |
| match = /c/(.*) |
| token = /x/myplugin/c/$1 |
| ---- |
| |
| [[urlAlias.match]]urlAlias.match:: |
| + |
| A regular expression for a URL token. |
| + |
| The matched URL token is replaced by `urlAlias.token`. |
| |
| [[urlAlias.token]]urlAlias.token:: |
| + |
| The target URL token. |
| + |
| It can contain placeholders for the groups matched by the |
| `urlAlias.match` regular expression: `$1` for the first matched group, |
| `$2` for the second matched group, etc. |
| |
| [[submodule]] |
| === Section submodule |
| |
| [[submodule.verbosesuperprojectupdate]]submodule.verboseSuperprojectUpdate |
| + |
| When using link:user-submodules.html#automatic_update[automatic superproject updates] |
| this option will determine if the submodule commit messages are included into |
| the commit message of the superproject update. |
| + |
| By default this is true. |
| |
| |
| [[user]] |
| === Section user |
| |
| [[user.name]]user.name:: |
| + |
| Name that Gerrit calls itself in Git when it creates a new Git |
| commit, such as a merge during change submission. |
| + |
| By default this is "Gerrit Code Review". |
| |
| [[user.email]]user.email:: |
| + |
| Email address that Gerrit refers to itself as when it creates a |
| new Git commit, such as a merge commit during change submission. |
| + |
| If not set, Gerrit generates this as "gerrit@`hostname`", where |
| `hostname` is the hostname of the system Gerrit is running on. |
| + |
| By default, not set, generating the value at startup. |
| |
| [[user.anonymousCoward]]user.anonymousCoward:: |
| + |
| Username that is displayed in the Gerrit Web UI and in e-mail |
| notifications if the full name of the user is not set. |
| + |
| By default "Anonymous Coward" is used. |
| |
| |
| == [[secure.config]]File `etc/secure.config` |
| The optional file `'$site_path'/etc/secure.config` overrides (or |
| supplements) the settings supplied by `'$site_path'/etc/gerrit.config`. |
| The file should be readable only by the daemon process and can be |
| used to contain private configuration entries that wouldn't normally |
| be exposed to everyone. |
| |
| Sample `etc/secure.config`: |
| ---- |
| [auth] |
| registerEmailPrivateKey = 2zHNrXE2bsoylzUqDxZp0H1cqUmjgWb6 |
| |
| [database] |
| username = webuser |
| password = s3kr3t |
| |
| [ldap] |
| password = l3tm3srch |
| |
| [httpd] |
| sslKeyPassword = g3rr1t |
| |
| [sendemail] |
| smtpPass = sp@m |
| |
| [remote "bar"] |
| password = s3kr3t |
| ---- |
| |
| == File `etc/peer_keys` |
| |
| The optional file `'$site_path'/etc/peer_keys` controls who can |
| login as the 'Gerrit Code Review' user, required for the link:cmd-suexec.html[suexec] |
| command. |
| |
| The format is one Base-64 encoded public key per line. |
| |
| |
| == Database system_config |
| |
| Several columns in the `system_config` table within the metadata |
| database may be set to control how Gerrit behaves. |
| |
| [NOTE] |
| The contents of the `system_config` table are cached at startup |
| by Gerrit. If you modify any columns in this table, Gerrit needs |
| to be restarted before it will use the new values. |
| |
| === Configurable Parameters |
| |
| site_path:: |
| + |
| Local filesystem directory holding the site customization assets. |
| Placing this directory under version control and/or backup is a |
| good idea. |
| + |
| Files in this directory provide additional configuration. |
| + |
| Other files support site customization. |
| + |
| * link:config-themes.html[Themes] |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
| |
| SEARCHBOX |
| --------- |