diff options
Diffstat (limited to 'doc/user/admin_area/settings/user_and_ip_rate_limits.md')
| -rw-r--r-- | doc/user/admin_area/settings/user_and_ip_rate_limits.md | 65 |
1 files changed, 49 insertions, 16 deletions
diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md index 3f0d75dc682..e2040ef19d6 100644 --- a/doc/user/admin_area/settings/user_and_ip_rate_limits.md +++ b/doc/user/admin_area/settings/user_and_ip_rate_limits.md @@ -20,8 +20,42 @@ IP rate limits**: These limits are disabled by default. +NOTE: +By default, all Git operations are first tried unauthenticated. Because of this, HTTP Git operations +may trigger the rate limits configured for unauthenticated requests. +  +## Response text + +A request that exceeds a rate limit returns a 429 response code and a +plain-text body, which by default is: + +```plaintext +Retry later +``` + +It is possible to customize this response text in the Admin Area. + +## Response headers + +> [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/731) in GitLab 13.8, the `Rate-Limit` headers. `Retry-After` was introduced in an earlier version. + +When a client exceeds the associated rate limit, the following requests are +blocked. The server may respond with rate-limiting information allowing the +requester to retry after a specific period of time. These information are +attached into the response headers. + +| Header | Example | Description | +|:----------------------|:--------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `RateLimit-Limit` | `60` | The request quota for the client **each minute**. If the rate limit period set in the admin area is different from 1 minute, the value of this header is adjusted to approximately the nearest 60-minute period. | +| `RateLimit-Name` | `throttle_authenticated_web` | Name of the throttle blocking the requests. | +| `RateLimit-Observed` | `67` | Number of requests associated to the client in the time window. | +| `RateLimit-Remaining` | `0` | Remaining quota in the time window. The result of `RateLimit-Limit` - `RateLimit-Remaining`. | +| `RateLimit-Reset` | `1609844400` | [Unix time](https://en.wikipedia.org/wiki/Unix_time)-formatted time when the request quota is reset. | +| `RateLimit-ResetTime` | `Tue, 05 Jan 2021 11:00:00 GMT` | [RFC2616](https://tools.ietf.org/html/rfc2616#section-3.3.1)-formatted date and time when the request quota is reset. | +| `Retry-After` | `30` | Remaining duration **in seconds** until the quota is reset. This is a [standard HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After). | + ## Use an HTTP header to bypass rate limiting > [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/622) in GitLab 13.6. @@ -47,7 +81,7 @@ GitLab. For example: in `/etc/default/gitlab`. It is important that your load balancer erases or overwrites the bypass -header on all incoming traffic, because otherwise you must trust your +header on all incoming traffic. Otherwise, you must trust your users to not set that header and bypass the GitLab rate limiter. Note that the bypass only works if the header is set to `1`. @@ -59,7 +93,9 @@ are marked with `"throttle_safelist":"throttle_bypass_header"` in To disable the bypass mechanism, make sure the environment variable `GITLAB_THROTTLE_BYPASS_HEADER` is unset or empty. -## Allowing specific users to bypass authenticated request rate limiting +## Allow specific users to bypass authenticated request rate limiting + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49127) in GitLab 13.7. Similarly to the bypass header described above, it is possible to allow a certain set of users to bypass the rate limiter. This only applies @@ -82,13 +118,12 @@ are marked with `"throttle_safelist":"throttle_user_allowlist"` in At application startup, the allowlist is logged in [`auth.log`](../../../administration/logs.md#authlog). -## Trying out throttling settings before enforcing them +## Try out throttling settings before enforcing them > [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/629) in GitLab 13.6. -Trying out throttling settings can be done by setting the -`GITLAB_THROTTLE_DRY_RUN` environment variable to a comma-separated -list of throttle names. +You can try out throttling settings by setting the `GITLAB_THROTTLE_DRY_RUN` environment variable to +a comma-separated list of throttle names. The possible names are: @@ -99,21 +134,19 @@ The possible names are: - `throttle_authenticated_protected_paths_api` - `throttle_authenticated_protected_paths_web` -For example: trying out throttles for all authenticated requests to -non-protected paths could be done by setting +For example, to try out throttles for all authenticated requests to +non-protected paths can be done by setting `GITLAB_THROTTLE_DRY_RUN='throttle_authenticated_web,throttle_authenticated_api'`. -To enable the dry-run mode for all throttles, the variable can be set -to `*`. +To enable dry run mode for all throttles, the variable can be set to `*`. -Setting a throttle to dry-run mode will log a message to the -[`auth.log`](../../../administration/logs.md#authlog) when it would -hit the limit, while letting the request continue as normal. The log -message will contain an `env` field set to `track`. The `matched` -field will contain the name of throttle that was hit. +Setting a throttle to dry run mode logs a message to the +[`auth.log`](../../../administration/logs.md#authlog) when it would hit the limit, while letting the +request continue as normal. The log message contains an `env` field set to `track`. The `matched` +field contains the name of throttle that was hit. It is important to set the environment variable **before** enabling -the rate limiting in the settings. The settings in the admin panel +the rate limiting in the settings. The settings in the Admin Area take effect immediately, while setting the environment variable requires a restart of all the Puma processes. |