| 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 propeties 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 |
| |
| [cache "diff"] |
| diskbuffer = 10 m |
| ---- |
| |
| [[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]. |
| + |
| * `HTTP` |
| + |
| Gerrit relies upon data presented in the HTTP request. This includes |
| HTTP basic authentication, or some types of commerical single-sign-on |
| solutions. With this setting enabled the authentication must |
| take place in the web server or servlet container, and not from |
| within Gerrit. |
| + |
| * `HTTP_LDAP` |
| + |
| Exactly like `HTTP` (above), but additionally Gerrit pre-populates |
| a user's full name and email address based on information obtained |
| from the user's account object in LDAP. The user's group membership |
| is also pulled from LDAP, making any LDAP groups that a user is a |
| member of available as groups in Gerrit. |
| + |
| * `LDAP` |
| + |
| Gerrit prompts the user to enter a username and a password, which |
| it then verifies by performing a simple bind against the configured |
| <<ldap.server,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>> identity. |
| |
| * `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 by in the dialog by the user. |
| The configured <<ldap.username>> identity is not used to obtain |
| account information. |
| + |
| * `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.trustedOpenID]]auth.trustedOpenID:: |
| + |
| List of trusted OpenID providers. Only used if `auth.type` was |
| set to OpenID (the default). |
| + |
| In order for a user to take advantage of permissions beyond those |
| granted to the `Anonymous Users` and `Registered Users` groups, |
| the user account must only have OpenIDs which match at least one |
| pattern from this list. |
| + |
| Patterns may be either a regular expression (start with `^` and |
| end with `$`) or be a simple prefix (any other string). |
| + |
| By default, the list contains two values, `http://` and `https://`, |
| allowing Gerrit to trust any OpenID it receives. |
| |
| [[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.httpHeader]]auth.httpHeader:: |
| + |
| HTTP header to trust the username from, or unset to select HTTP basic |
| or digest authentication. Only used if `auth.type` was set to HTTP. |
| |
| [[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`. |
| + |
| If not set, no "Register" link is displayed. |
| |
| [[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 insert one or more rows into |
| `contributor_agreements` and create agreement files under |
| `'$site_path'/static`, so users can actually complete one or |
| more agreements. |
| + |
| By default this is false (no agreements are used). |
| |
| auth.allowGoogleAccountUpgrade:: |
| + |
| Allows Google Account users to automatically update their Gerrit |
| account when/if their Google Account OpenID identity token changes. |
| Identity tokens can change if the server changes hostnames, or |
| for other reasons known only to Google. The upgrade path works |
| by matching users by email address if the identity is not present, |
| and then changing the identity. |
| + |
| This setting also permits old Gerrit 1.x users to seamlessly upgrade |
| from Google Accounts on Google App Engine to OpenID authentication. |
| + |
| Having this enabled incurs an extra database query when Google |
| Account users register with the Gerrit server. |
| + |
| By default, unset/false. |
| |
| [[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. If an entry has not |
| been accessed in this period of time, it is removed from the cache. |
| Values should use common unit suffixes to express their setting: |
| + |
| * s, sec, second, seconds |
| * m, min, minute, minutes |
| * h, hr, hour, hours |
| * d, day, days |
| * w, week, weeks (`1 week` is treated as `7 days`) |
| * mon, month, months (`1 month` is treated as `30 days`) |
| * y, year, years (`1 year` is treated as `365 days`) |
| |
| + |
| If a unit suffix is not specified, `minutes` is assumed. If 0 is |
| supplied, the maximum age is infinite and items are never purged |
| except when the cache is full. |
| + |
| Default is `90 days` for most caches, except: |
| + |
| * `"ldap_groups"`: default is `1 hour` |
| * `"openid"`: default is `5 minutes` |
| * `"web_sessions"`: default is `12 hours` |
| |
| [[cache.name.memoryLimit]]cache.<name>.memoryLimit:: |
| + |
| Maximum number of cache items to retain in memory. Keep in mind |
| this is total number of items, not bytes of heap used. |
| + |
| Default is 1024 for most caches, except: |
| + |
| * `"diff"`: default is `128` |
| * `"openid"`: default is `64` |
| |
| [[cache.name.diskLimit]]cache.<name>.diskLimit:: |
| + |
| Maximum number of cache items to retain on disk, if this cache |
| supports storing its items to disk. Like memoryLimit, this is |
| total number of items, not bytes of disk used. If 0, disk storage |
| for this cache is disabled. |
| + |
| Default is 16384. |
| |
| [[cache.name.diskBuffer]]cache.<name>.diskBuffer:: |
| + |
| Number of bytes to buffer in memory before writing less frequently |
| accessed cache items to disk, if this cache supports storing its |
| items to disk. |
| + |
| Default is 5 MiB. |
| + |
| Common unit suffixes of 'k', 'm', or 'g' are supported. |
| |
| [[cache_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 `"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 the memory limit |
| should not be set incredibly high. Administrators should try to |
| target cache.diff.memoryLimit to be roughly the number of changes |
| which their users will process in a 1 or 2 day span. |
| + |
| Keeping entries for 90 days gives sufficient time for most changes |
| to be submitted or abandoned before their relevant difference items |
| expire out. |
| |
| 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 `"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_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 `"openid"`:: |
| + |
| If OpenID authentication is enabled, caches the OpenID discovery |
| response by URL, for up to 5 minutes. This can reduce the time |
| required for OpenID authentication through very common providers, |
| such as Google Accounts. |
| |
| 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 248 bytes, depending on the JVM. |
| |
| See also link:cmd-flush-caches.html[gerrit flush-caches]. |
| |
| [[cache_options]]Cache Options |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| cache.diff.intraline:: |
| + |
| Boolean to enable or disable the computation of intraline differences |
| when populating a diff cache entry. Changing this setting in the |
| server configuration requires flushing the "diff" cache after a |
| restart, otherwise older cache entries stored on disk may not reflect |
| the current server setting. This flag is provided primarily as a |
| backdoor to disable the intraline difference feature if necessary. |
| + |
| Default is true, enabled. |
| |
| |
| [[commentlink]]Section commentlink |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| Comment links are find/replace strings applied to change descriptions, |
| patch comments, and in-line code comments 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 preciously control |
| how the replacement is displayed to the user. |
| |
| ---- |
| [commentlink "changeid"] |
| match = (I[0-9a-f]{8,40}) |
| link = "#q,$1,n,z" |
| |
| [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> |
| ---- |
| |
| [[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. |
| |
| |
| [[contactstore]]Section contactstore |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| [[contactstore.url]]contactstore.url:: |
| + |
| URL of the web based contact store Gerrit will send any offline |
| contact information to when it collects the data from users as part |
| of a contributor agreement. |
| + |
| See link:config-contact.html[Contact Information]. |
| |
| [[contactstore.appsec]]contactstore.appsec:: |
| + |
| Shared secret of the web based contact store. |
| |
| |
| [[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'. |
| |
| [[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.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 artifically running out |
| of virtual address space, as the garbage collector cannot reclaim |
| unused mapped spaces fast enough. |
| + |
| Default on JGit is false. Although potentially slower, it yields |
| much more predictable behavior. |
| |
| [[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.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. |
| |
| [[database.poolMinIdle]]database.poolMinIdle:: |
| + |
| Minimum number of connections to keep idle in the pool. |
| Default is 4. |
| |
| [[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. |
| |
| [[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`. |
| |
| |
| [[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.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. |
| |
| [[gitweb]]Section gitweb |
| ~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| Gerrit can forward requests to either an internally managed gitweb |
| (which allows Gerrit to enforce some access controls), or to an |
| externally managed gitweb (where the web server manages access). |
| See also link:config-gitweb.html[Gitweb Integration]. |
| |
| [[gitweb.cgi]]gitweb.cgi:: |
| + |
| Path to the locally installed `gitweb.cgi` executable. This CGI will |
| be called by Gerrit Code Review when the URL `/gitweb` is accessed. |
| Project level access controls are enforced prior to calling the CGI. |
| + |
| Defaults to `/usr/lib/cgi-bin/gitweb.cgi` if gitweb.url is not set. |
| |
| [[gitweb.url]]gitweb.url:: |
| + |
| Optional URL of an affiliated gitweb service. Defines the |
| web location where a `gitweb.cgi` is installed to browse |
| gerrit.basePath and the repositories it contains. |
| + |
| Gerrit appends any necessary query arguments onto the end of this URL. |
| For example, "?p=$project.git;h=$commit". |
| |
| [[gitweb.type]]gitweb.type:: |
| + |
| Optional type of affiliated gitweb service. This allows using |
| alternatives to gitweb, such as cgit. |
| + |
| Valid values are `gitweb`, `cgit` or `custom`. |
| |
| [[gitweb.type]]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.type]]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.type]]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. |
| |
| |
| [[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.patchsetCreatedHook]]hooks.patchsetCreatedHook:: |
| + |
| Optional filename for the patchset created hook, if not specified then |
| `patchset-created` will be used. |
| |
| [[hooks.commentAddedHook]]hooks.commentAddedHook:: |
| + |
| Optional filename for the comment added hook, if not specified then |
| `comment-added` will be used. |
| |
| [[hooks.changeMergedHook]]hooks.changeMergedHook:: |
| + |
| Optional filename for the change merged hook, if not specified then |
| `change-merged` will be used. |
| |
| [[hooks.changeAbandonedHook]]hooks.changeAbandonedHook:: |
| + |
| Optional filename for the change abandoned hook, if not specified then |
| `change-abandoned` 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. |
| |
| |
| [[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.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 key stores 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. |
| + |
| 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 allocate 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 |
| multipled 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 disables the queue and permits infinite number of connections. |
| + |
| By default 50. |
| |
| [[httpd.maxWait]]httpd.maxWait:: |
| + |
| Maximum amount of time a client will wait to 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. |
| |
| |
| [[ldap]]Section ldap |
| ~~~~~~~~~~~~~~~~~~~~ |
| |
| LDAP integration is only enabled if `auth.type` was set to |
| `HTTP_LDAP` or `LDAP`. See above for a detailed description of |
| the auth.type settings and their implications. |
| |
| An example LDAP configuration follows, and then discussion of |
| the parameters introduced here. Suitable defaults for most |
| parameters are automatically guessed based on the type of server |
| detected during startup. The guessed defaults support both |
| 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.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.accountBase]]ldap.accountBase:: |
| + |
| Root of the tree containing all user accounts. This is typically |
| of the form `ou=people,dc=example,dc=com`. |
| |
| [[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 address, |
| 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.groupBase]]ldap.groupBase:: |
| + |
| Root of the tree containing all group objects. This is typically |
| of the form `ou=groups,dc=example,dc=com`. |
| |
| [[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\})` for RFC 2307, |
| and unset (disabled) for Active Directory. |
| |
| |
| [[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 |
| ---- |
| |
| [[repo]]Section repo |
| ~~~~~~~~~~~~~~~~~~~~ |
| |
| [[repo.showDownloadCommand]]repo.showDownloadCommand:: |
| + |
| If set to true, Gerrit advertises patch set downloads with the |
| `repo download` command, assuming that all projects managed by this |
| instance are generally worked on with the repo multi-repository tool. |
| + |
| By default, false, as not all instances will deploy repo. |
| |
| [[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.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 messsages 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. |
| |
| [[sshd]] Section sshd |
| ~~~~~~~~~~~~~~~~~~~~~ |
| |
| [[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. |
| + |
| By default, *:29418. |
| |
| [[sshd.reuseAddress]]sshd.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. |
| |
| [[sshd.tcpKeepAlive]]sshd.tcpKeepAlive:: |
| + |
| If true, enables TCP keepalive messages to the other side, so |
| the daemon can terminate connections if the peer disappears. |
| + |
| 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-serve order. |
| + |
| By default, 1.5x the number of CPUs available to the JVM. |
| |
| [[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.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. |
| + |
| By default, all supported MACs are available. |
| |
| [[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. The value defaults to <<theme.trimColor,trimColor>>. |
| |
| [[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 black, `000000`. |
| |
| [[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 shade of green, `D4E9A9`. |
| |
| [[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 shade of yellow, `FFFFCC`. |
| |
| [[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. |
| |
| |
| 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`: |
| ---- |
| [database] |
| username = webuser |
| password = s3kr3t |
| |
| [ldap] |
| password = l3tm3srch |
| |
| [httpd] |
| sslKeyPassword = g3rr1t |
| |
| [sendemail] |
| smtpPass = sp@m |
| ---- |
| |
| File `etc/replication.config` |
| ----------------------------- |
| |
| The optional file `'$site_path'/etc/replication.config` controls how |
| Gerrit automatically replicates changes it makes to any of the Git |
| repositories under its control. |
| |
| * link:config-replication.html[Git Replication/Mirroring] |
| |
| 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-headerfooter.html[Site Header/Footer] |
| * link:config-replication.html[Git Replication/Mirroring] |
| |
| Not User Serviceable |
| ~~~~~~~~~~~~~~~~~~~~ |
| |
| These fields generally shouldn't be modified. |
| |
| register_email_private_key:: |
| + |
| Private key used to sign the links emailed to users when they |
| request to register a new email address on their user account. |
| When the link is activated, the private key authenticates the link |
| was created and sent by this Gerrit server, proving that the user |
| can receive email at the address they are registering. |
| + |
| This column is automatically generated when the database is |
| initialized. Changing it to a new value would cause all current |
| links to be invalidated. |
| + |
| Changing it is not recommended. |
| |
| admin_group_id:: |
| + |
| Unique identity of the group with full privileges. Any user who |
| is a member of this group may manage any other group, any project, |
| and other system settings over the web. |
| + |
| This is initialized by Gerrit to be the "Administrators" group. |
| + |
| Changing it is not recommended. |
| |
| anonymous_group_id:: |
| + |
| Unique identity of the group for anonymous (not authenticated) users. |
| + |
| All users are a member of this group, whether or not they are |
| actually signed in to Gerrit. Any access rights assigned to |
| this group are inherited by all users. |
| + |
| This is initialized by Gerrit to be the "Anonymous Users" group. |
| + |
| Changing it is not recommended. |
| |
| registered_group_id:: |
| + |
| Unique identity of the group for all authenticated users. |
| + |
| All signed-in users are a member of this group. Any access rights |
| assigned to this group are inherited by all users once they have |
| authenticated to Gerrit. |
| + |
| Since account registration is open and fairly easy to obtain, |
| moving from the "Anonymous Users" group to this group is not |
| very difficult. Caution should be taken when assigning any |
| permissions to this group. |
| + |
| This is initialized by Gerrit to be the "Registered Users" group. |
| + |
| Changing it is not recommended. |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |