Documentation/config-gerrit.txt

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.
+
* `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.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.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].


[[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.

====
  [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?d=$1
====

[[commentlink.<name>.match]]commentlink.<name>.match::
+
A regex string used to search.  The whole match string will be turned into
a hyperlink.  You can get portions of the string with regex groupings - for
example, `match = issue\\s*(\\d+)`
+
Note the configuration file parser eats one level of backslashes, so using
the regex code `\s` requires `\\s` in the configuration file.

[[commentlink.<name>.link]]commentlink.<name>.link::
+
The URL to use when creating a hyperlink out of all strings found using the
match regex.  You can specify portions of the match with regex groups - for
example, `link = http://bugs.example.com/show_bug.cgi?d=$1 `


[[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 = postgres
		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.
+
* `Postgres` or `PostgreSQL`
+
Connect to a PostgreSQL database server.
+
* `H2`
+
Connect to a local (or remote) H2 database.
+
* `MySQL`
+
Connect to a MySQL database server.

+
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.
Setting this usually isn't necessary, set database.type instead.

[[database.url]]database.url::
+
JDBC style URL for the database.  Setting this usually isn't
necessary, set database.type instead.


[[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
~~~~~~~~~~~~~~~~~~~~~~~~

See also link:config-gitweb.html[Gitweb Integration].

[[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".


[[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.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.


[[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.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.

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