Configuration
=============

Quota
-----

The defined quotas are stored in a `quota.config` file in the
`refs/meta/config` branch of the `All-Projects` root project.
Administrators can add and edit quotas by fetching this branch, editing
the `quota.config` file locally and pushing back the changes. The
`quota.config` file is a Git config file:

```
  [quota "sandbox/*"]
    maxProjects = 50
    maxRepoSize = 2 m
  [quota "public/*"]
    maxProjects = 100
    maxRepoSize = 10 m
  [quota "customerX/*"]
    maxProjects = 20
    maxTotalSize = 200 m
```

<a id="maxProjects">
`quota.<namespace>.maxProjects`
: The maximum number of projects that can be created in this namespace.

<a id="maxRepoSize">
`quota.<namespace>.maxRepoSize`
: The maximum total file size of a repository in this namespace. This is
the sum of sizes of all files in a Git repository where the size is
taken using the File.length() method. This means that, for example, a
reference file is counted as 41 bytes although it typically occupies a
block of 4K in the file system.

<a id="maxTotalSize">
`quota.<namespace>.maxTotalSize`
: The maximum total file size of all repositories in this namespace.
This is the sum of sizes of all files in all Git repositories in this
namespace.

If both "maxRepoSize" and "maxTotalSize" are defined in a quota section
then the more limiting quota will apply. For example, if the remaining
repository size of a repository (based on the "maxRepoSize" and
currently occupied space of that repository) is 2m and the remaining
total size (based on the "maxTotalSize" and currently occupied space of
all repositoris under that namespace) is 1m then the 1m is the remaining
size for that repository.

A namespace can be specified as

* exact project name (`plugins/myPlugin`): Defines a quota for one project.

* pattern (`sandbox/*`): Defines a quota for one project namespace.

* regular expression (`^test-.*/.*`): Defines a quota for the
namespace matching the regular expression.

* for-each-pattern (`?/*`): Defines the same quota for each
subfolder. `?` is a placeholder for any name and '?/*' with
'maxProjects = 3' means that for every subfolder 3 projects are
allowed. Hence '?/*' is a shortcut for having n explicit quotas:
  '<name1>/*' with 'maxProjects = 3'
  '<name2>/*' with 'maxProjects = 3'
  ...


If a project name matches several quota namespaces the one quota
applies to the project that is defined first in the `quota.config`
file.

Example: Allow the creation of 10 projects in folder `test/*` and maximal
500 projects in total

```
  [quota "test/*"]
    maxProjects = 10
  [quota "*"]
    maxProjects = 500
```

Example: Allow the creation of 10 projects in folder `test/*` and 5
projects in each other folder

```
  [quota "test/*"]
    maxProjects = 10
  [quota "?/*"]
    maxProjects = 5
```

Example: Allow the creation of 10 projects in folder 'test/*' and set
the quota of 2m for each of them

```
  [quota "test/*"]
    maxProjects = 10
    maxRepoSize = 2 m
```

Example: Allow the creation of 10 projects in folder 'test/*' and set
a quota of 20m for the total size of all repositories

```
  [quota "test/*"]
    maxProjects = 10
    maxTotalSize = 20 m
```

Example: Allow the creation of 10 projects in folder 'test/*' and set
a quota of 20m for the total size of all repositories. In addition make
sure that each individual repository cannot exceed 3m

```
  [quota "test/*"]
    maxProjects = 10
    maxRepoSize = 3 m
    maxTotalSize = 20 m
```

If one prefers computing a repository size by adding the size of the git objects,
the following section should be added into the `gerrit.config` file:

```
  [plugin "quota"]
        useGitObjectCount = true
```

<a id="useGitObjectCount">
`plugin.quota.useGitObjectCount`
: Use git object count. If true, *repoSize = looseObjectsSize +
packedObjectsSize*, where *looseObjectsSize* and *packedObjectsSize* are given
by JGit RepoStatistics. By default, false.

Rate Limits
-----------

The defined rate limits are stored in a `quota.config` file in the
`refs/meta/config` branch of the `All-Projects` root project. Rate
limits are defined per user group and rate limit type:

Example:
```
[group "buildserver"]
    uploadpack = 10 / min burst 500

[group "Registered Users"]
    uploadpack = 1 /min burst 180

[group "Anonymous Users"]
    uploadpack = 6/h burst 12
```

For logged in users rate limits are associated to their accountId. For
anonymous users rate limits are associated to their remote host address.
If multiple anonymous users are accessing Gerrit via the same host (e.g.
a proxy) they share a common rate limit.

If a user is a member of multiple groups mentioned in `quota.config`
the limit applies that is defined first in the `quota.config` file.
This resolves ambiguity in case the user is a member of multiple groups
used in the configuration.

Use group "Anonymous Users" to define the rate limit for anonymous users.
Use group "Registered Users" to define the default rate limit for all logged
in users.

Format of the rate limit entries in `quota.config`:
```
[group "<groupName>"]
    <rateLimitType> = <rateLimit> <rateUnit> burst <storedRequests>
```

<a id="rateLimitType>">
`group.<groupName>.<rateLimitType>`
: identifies which request type is limited by this configuration.
The following rate limit types are supported:
* `uploadpack`: rate limit for uploadpack (fetch) requests
The group can be defined by its name or UUID.

<a id="uploadpack">
`group.<groupName>.uploadpack`
: rate limit for uploadpack (fetch) requests for the given group. The
group can be defined by its name or UUID.

<a id="rateLimit">
: The rate limit (first parameter) defines the maximum allowed request rate.

<a id="rateUnit">
: Rate limits can be defined using the following rate units:
`/s`, `/sec`, `/second`: requests per second
`/m`, `/min`, `/minute`: requests per minute
`/h`, `/hr`, `/hour`: requests per hour
`/d`, `/day`: requests per day

The default unit used if no unit is configured is `/hour`.

<a id="burst">
The `burst` parameter allows to define how many unused requests can be
stored for later use during idle times. This allows clients to send
bursts of requests exceeding their rate limit until all their stored
requests are consumed.

If a rate limit configuration value is invalid a default rate limit of 1
request per minute with 30 stored requests is assumed.

Example:

Configure a rate limit of maximum 30 fetch request per hour for
the group of registered users. Up to 60 unused requests can be stored
during idle times which may be consumed at a later time to send bursts
of requests above the maximum request rate.

```
[group "Registered Users"]
	uploadpack = 30/hour burst 60
```

Publication Schedule
--------------------

Publication of repository sizes to registered UsageDataPublishedListeners
is configured in the `plugin.quota` subsection of the `gerrit.config` file.
The publication interval can be configured using the same format as for the
[garbage collection schedule](../../../Documentation/config-gerrit.html#gc),
with the parameter names 'publicationStartTime' and 'publicationInterval'.

Example:

```
  [plugin "quota"]
    publicationStartTime = Fri 10:30
    publicationInterval  = 1 day
```

If no publicationInterval is configured, no data is published.