Merge branch 'ee-updates-protected-paths-docs' into 'master'

Update protected paths documentation

See merge request gitlab-org/gitlab!16540

doc/security/rack_attack.md

@@ -36,6 +36,9 @@ will be enabled:
 
 ### Protected paths throttle
 
+NOTE: **Note:** Omnibus GitLab protected paths throttle is deprecated and is scheduled for removal in
+GitLab 13.0. Please refer to [Migrate settings from GitLab 12.3 and earlier](../user/admin_area/settings/protected_paths.md#migrate-settings-from-gitlab-123-and-earlier).
+
 GitLab responds with HTTP status code `429` to POST requests at protected paths
 that exceed 10 requests per minute per IP address.
 
@@ -124,6 +127,9 @@ The following settings can be configured:
 
 **Installations from source**
 
+NOTE: **Note:** Rack Attack initializer was temporarily renamed to `rack_attack_new`, to
+support backwards compatibility with the one [Omnibus initializer](https://docs.gitlab.com/omnibus/settings/configuration.html#setting-up-paths-to-be-protected-by-rack-attack). It'll be renamed back to `rack_attack.rb` once Omnibus throttle is removed. Please see the [GitLab issue](https://gitlab.com/gitlab-org/gitlab/issues/29952) for more information.
+
 These settings can be found in `config/initializers/rack_attack.rb`. If you are
 missing `config/initializers/rack_attack.rb`, the following steps need to be
 taken in order to enable protection for your GitLab instance:

doc/user/admin_area/settings/index.md

@@ -20,6 +20,7 @@ include:
 - [Visibility and access controls](visibility_and_access_controls.md)
 - [User and IP rate limits](user_and_ip_rate_limits.md)
 - [Custom templates repository](instance_template_repository.md) **(PREMIUM)**
+- [Protected paths](protected_paths.md) **(CORE ONLY)**
 
 NOTE: **Note:**
 You can change the [first day of the week](../../profile/preferences.md) for the entire GitLab instance

doc/user/admin_area/settings/protected_paths.md

+---
+type: reference
+---
+
+# Protected paths **(CORE ONLY)**
+
+GitLab protects the following paths with Rack Attack by default:
+
+```
+'/users/password',
+'/users/sign_in',
+'/api/#{API::API.version}/session.json',
+'/api/#{API::API.version}/session',
+'/users',
+'/users/confirmation',
+'/unsubscribes/',
+'/import/github/personal_access_token'
+```
+
+GitLab responds with HTTP status code `429` to POST requests at protected paths
+that exceed 10 requests per minute per IP address.
+
+This header is included in responses to blocked requests:
+
+```
+Retry-After: 60
+```
+
+For example, the following are limited to a maximum 10 requests per minute:
+
+- User sign-in
+- User sign-up (if enabled)
+- User password reset
+
+After 10 requests, the client must wait 60 seconds before it can
+try again.
+
+## Configure using GitLab UI
+
+> Introduced in [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/31246).
+
+Throttling of protected paths is enabled by default and can be disabled or
+customized on **Admin > Network > Protected Paths**, along with these options:
+
+- Maximum number of requests per period per user.
+- Rate limit period in seconds.
+- Paths to be protected.
+
+![protected-paths](img/protected_paths.png)
+
+Requests over the rate limit are logged into `auth.log`.
+
+## Migrate settings from GitLab 12.3 and earlier
+
+Omnibus GitLab protected paths throttle is deprecated and is scheduled for removal in
+GitLab 13.0. Please see the [GitLab issue](https://gitlab.com/gitlab-org/gitlab/issues/29952) and the [Omnibus GitLab issue](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/4688) for more information.
+
+NOTE: **Note:** If Omnibus settings are present, applications settings will be automatically ignored to avoid generating multiple requests blocks.
+
+To migrate from Omnibus GitLab 12.3 and earlier settings:
+
+1. Disable the Protected Paths throttle from Omnibus, by changing `rack_attack_enabled` value to `false` on [`rack_attack.rb.erb`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/templates/default/rack_attack.rb.erb#L18):
+
+   ```ruby
+   rack_attack_enabled = false
+   ```
+
+1. Customize and enable your protected paths settings by following [Configure using GitLab UI](#configure-using-gitlab-ui) section.
+
+1. Restart GitLab:
+
+   ```bash
+   sudo gitlab-ctl restart
+   ```
+
+That's it. Protected paths throttle are now managed by GitLab admin settings.

doc/user/gitlab_com/index.md

@@ -316,9 +316,7 @@ This header is included in responses to blocked requests:
 Retry-After: 60
 ```
 
-Source:
-
-- Search for `rate_limit_requests_per_period`, `rate_limit_period`, and `rack_attack_protected_paths` in [GitLab.com's current Rails app settings](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/attributes/default.rb).
+See [Protected Paths](../admin_area/settings/protected_paths.md) for more details.
 
 #### Git and container registry failed authentication ban