| 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] |