Commit 24bc1a9a authored by Evan Read's avatar Evan Read

Edit rate limit documentation

parent 8e886c89
......@@ -21,20 +21,21 @@ IP rate limits**:
These limits are disabled by default.
NOTE:
By default, all Git operations are first tried unathenticated. Because of this, HTTP Git operations may trigger the rate limits configured for unauthenticated requests.
By default, all Git operations are first tried unauthenticated. Because of this, HTTP Git operations
may trigger the rate limits configured for unauthenticated requests.
![user-and-ip-rate-limits](img/user_and_ip_rate_limits.png)
## Response text
A request that exceeds a rate limit will get a 429 response code and a
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.
It is possible to customize this response text in the Admin Area.
## Response headers
......@@ -80,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`.
......@@ -92,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
......@@ -115,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:
......@@ -132,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.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment