| Gerrit2 - Configuration |
| ======================= |
| |
| File `gerrit.config` |
| -------------------- |
| |
| The optional file `'$site_path'/gerrit.config` is a Git-style config |
| file that controls many host specific settings for Gerrit. |
| |
| [NOTE] |
| The contents of the `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 `gerrit.config`: |
| ---- |
| [core] |
| packedGitLimit = 200 m |
| |
| [cache] |
| directory = /var/cache/gerrit2 |
| |
| [cache "diff"] |
| diskbuffer = 10 m |
| ---- |
| |
| Section auth |
| ~~~~~~~~~~~~ |
| |
| See also link:config-sso.html[SSO configuration]. |
| |
| auth.type:: |
| + |
| Type of user authentication employed by Gerrit. This setting has |
| two supported values: |
| + |
| * `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 in the HTTP request, such as the HTTP basic |
| authentication, or some types of commerical single-sign-on solutions. |
| |
| + |
| By default, OpenID. |
| |
| 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.emailFormat:: |
| + |
| Optional format string to construct user email addresses out of |
| user login names. Only used if auth.type is HTTP. |
| + |
| 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. |
| |
| 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.maxSessionAge:: |
| + |
| Maximum number of minutes that an XSRF token or a session cookie |
| is permitted to be valid for. |
| + |
| By default this is 720 minutes (12 hours). Any browser session |
| which has not been used in this time span will ask the user to |
| login again. |
| + |
| Administrators may increase (or decrease) this setting to control |
| how long an idle session is allowed to remain alive. |
| |
| auth.allowGoogleAccountUpgrade:: |
| + |
| Allow old Gerrit1 users to seamlessly upgrade from Google Accounts |
| on Google App Engine to OpenID authentication. This should only be |
| set to true on a Gerrit2 database that was imported from a Gerrit1 |
| database run on Google App Engine. Having it enabled incurs an |
| extra database query when new Google Account users register with |
| the Gerrit2 server. |
| + |
| Its strongly encouraged to unset this once the following query |
| drops to 0, or close to 0: |
| + |
| ==== |
| SELECT COUNT(*) FROM account_external_ids e |
| WHERE e.external_id LIKE 'Google Account %' |
| AND NOT EXISTS (SELECT 1 |
| FROM account_external_ids o |
| WHERE o.account_id = e.account_id |
| AND o.external_id LIKE '%.google.com%/id?id=%'); |
| ==== |
| + |
| By default, unset/false. |
| |
| Section cache[[section_cache]] |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| cache.directory:: |
| + |
| Path to a local directory where Gerrit can write cached entities for |
| future lookup. This local disk cache is used to retain expensively |
| computed information across restarts. |
| + |
| If the location does not exist, Gerrit will try to create it. |
| + |
| Default is `'$site_path'/disk_cache`. |
| |
| cache.maxAge:: |
| Default setting inherited by named caches; see below. |
| cache.memoryLimit:: |
| Default setting inherited by named caches; see below. |
| cache.diskLimit:: |
| Default setting inherited by named caches; see below. |
| cache.diskBuffer:: |
| Default setting inherited by named caches; see below. |
| |
| cache.<name>.maxAge:: |
| + |
| Maximum age, in minutes, 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. |
| + |
| Default is 129600 (90 days); 5 for cache "openid". |
| |
| 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. |
| |
| 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. |
| + |
| Default is 16384. |
| |
| 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. |
| |
| Standard Caches[[cache_names]] |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| cache `"accounts"`:: |
| + |
| Caches records from the `accounts` database table, containing user |
| preferences and preferred display name/email address. If updates are |
| made directly to this database table, this cache should be flushed. |
| |
| cache `"diff"`:: |
| + |
| Caches the edit list describing the differences between two versions |
| of a file. Gerrit uses this cache to accelerate display of file |
| contents by computing the difference only once, typically during |
| the initial upload. |
| + |
| The average entry in this cache is approximately 1100 bytes when |
| stored on disk. The in-memory representation is only slightly |
| larger, closer to 1300 bytes, depending on JVM. |
| + |
| 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 which groups a user is a member of. This is derived from the |
| `account_group_members` table, and also the `account_external_ids` |
| table if OpenID authentication is enabled. If either table is |
| modified directly in the database, this cache should be flushed. |
| |
| 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. |
| |
| See also link:cmd-flush-caches.html[gerrit flush-caches]. |
| |
| Section contactstore |
| ~~~~~~~~~~~~~~~~~~~~ |
| |
| 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:: |
| + |
| Shared secret of the web based contact store. |
| |
| Section core |
| ~~~~~~~~~~~~ |
| |
| 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:: |
| + |
| 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.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:: |
| + |
| 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:: |
| + |
| 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. |
| |
| Section gerrit |
| ~~~~~~~~~~~~~~ |
| |
| 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:: |
| + |
| 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:: |
| + |
| 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. |
| |
| Section gitweb[[section_gitweb]] |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| See also link:config-gitweb.html[Gitweb Integration]. |
| |
| 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". |
| |
| Section repo |
| ~~~~~~~~~~~ |
| |
| 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. |
| |
| Section sendemail |
| ~~~~~~~~~~~~~~~~~ |
| |
| 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.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:: |
| + |
| Port number of the SMTP server in sendemail.smtpserver. |
| + |
| By default, 25. |
| |
| sendemail.smtpUser:: |
| + |
| User name to authenticate with, if required for relay. |
| |
| sendemail.smtpPass:: |
| + |
| Password for the account named by sendemail.smtpUser. |
| |
| 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. |
| |
| Section sshd |
| ~~~~~~~~~~~~ |
| |
| 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:: |
| + |
| 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:: |
| + |
| If true, enables TCP keepalive messages to the other side, so |
| the daemon can terminate connections if the peer disappears. |
| + |
| By default, true. |
| |
| 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:: |
| + |
| 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. |
| |
| Section 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". |
| |
| 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 `replication.config` |
| ------------------------- |
| |
| The optional file `'$site_path'/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. |
| + |
| SSH key files (`ssh_host_rsa_key` and `ssh_host_dsa_key` or |
| `ssh_host_key`) in this directory provide the host keys for the |
| internal SSH daemon. |
| + |
| 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. |
| |
| xsrf_private_key:: |
| + |
| A private key used to sign the XSRF (cross site request forgey) |
| protection tokens. All RPC calls which can potentially modify |
| data require that the client obtain, and then later present an XSRF |
| token to Gerrit. The tokens are signed with this private key. |
| + |
| This column is automatically generated when the database is |
| initialized. Changing it to a new value would cause all current |
| XSRF tokens to be invalidated, forcing clients to either fail or |
| retry any requests in progress. |
| + |
| Changing it is not recommended. |
| |
| account_private_key:: |
| + |
| Like xsrf_private_key, but used to sign the cookie that tells Gerrit |
| what account the end-user has signed into. The key signs the cookie, |
| preventing a client from spoofing another account. |
| + |
| This column is automatically generated when the database is |
| initialized. Changing it to a new value would cause all current |
| cookies to be invalidated, forcing clients to fail their current |
| requests and require the user to sign in again. |
| + |
| 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] |