Clean-up some confusing info from security docs

10 files changed, 56 insertions, 29 deletions

diff --git a/doc/security/information_exclusivity.md b/doc/security/information_exclusivity.md
index 62a20d3f257..749ccf924b5 100644
--- a/doc/security/information_exclusivity.md
+++ b/doc/security/information_exclusivity.md
@@ -1,6 +1,7 @@
 ---
 type: concepts
 ---
+
 # Information exclusivity
 
 Git is a distributed version control system (DVCS). This means that everyone
diff --git a/doc/security/password_length_limits.md b/doc/security/password_length_limits.md
index d78293c75c6..9909ef4a8e4 100644
--- a/doc/security/password_length_limits.md
+++ b/doc/security/password_length_limits.md
@@ -1,19 +1,31 @@
 ---
 type: reference, howto
 ---
+
 # Custom password length limits
 
-If you want to enforce longer user passwords you can create an extra Devise
-initializer with the steps below.
+The user password length is set to a minimum of 8 characters by default.
+To change that for installations from source:
+
+1. Edit `devise_password_length.rb`:
+
+   ```sh
+   cd /home/git/gitlab
+   sudo -u git -H cp config/initializers/devise_password_length.rb.example config/initializers/devise_password_length.rb
+   sudo -u git -H editor config/initializers/devise_password_length.rb
+   ```
+
+1. Change the new password length limits:
+
+   ```ruby
+   config.password_length = 12..128
+   ```
 
-If you do not use the `devise_password_length.rb` initializer the password
-length is set to a minimum of 8 characters in `config/initializers/devise.rb`.
+   In this example, the minimum length is 12 characters, and the maximum length
+   is 128 characters.
 
-```bash
-cd /home/git/gitlab
-sudo -u git -H cp config/initializers/devise_password_length.rb.example config/initializers/devise_password_length.rb
-sudo -u git -H editor config/initializers/devise_password_length.rb   # inspect and edit the new password length limits
-```
+1. [Restart GitLab](../administration/restart_gitlab.md#installations-from-source)
+   for the changes to take effect.
 
 <!-- ## Troubleshooting
 
diff --git a/doc/security/rack_attack.md b/doc/security/rack_attack.md
index 1b75798013d..1e5678ec47c 100644
--- a/doc/security/rack_attack.md
+++ b/doc/security/rack_attack.md
@@ -1,6 +1,7 @@
 ---
 type: reference, howto
 ---
+
 # Rack Attack
 
 [Rack Attack](https://github.com/kickstarter/rack-attack), also known as Rack::Attack, is a Ruby gem
diff --git a/doc/security/reset_root_password.md b/doc/security/reset_root_password.md
index a58d70f0ff2..6a6c5262179 100644
--- a/doc/security/reset_root_password.md
+++ b/doc/security/reset_root_password.md
@@ -1,6 +1,7 @@
 ---
 type: howto
 ---
+
 # How to reset your root password
 
 To reset your root password, first log into your server with root privileges.
diff --git a/doc/security/ssh_keys_restrictions.md b/doc/security/ssh_keys_restrictions.md
index ae4cc44519e..4c60daf77f4 100644
--- a/doc/security/ssh_keys_restrictions.md
+++ b/doc/security/ssh_keys_restrictions.md
@@ -1,6 +1,7 @@
 ---
 type: reference, howto
 ---
+
 # Restrict allowed SSH key technologies and minimum length
 
 `ssh-keygen` allows users to create RSA keys with as few as 768 bits, which
diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md
index 6251f8e2f66..b08d9ffa26e 100644
--- a/doc/security/two_factor_authentication.md
+++ b/doc/security/two_factor_authentication.md
@@ -1,6 +1,7 @@
 ---
 type: howto
 ---
+
 # Enforce Two-factor Authentication (2FA)
 
 Two-factor Authentication (2FA) provides an additional level of security to your
diff --git a/doc/security/unlock_user.md b/doc/security/unlock_user.md
index 2e14e631d68..d34826c853c 100644
--- a/doc/security/unlock_user.md
+++ b/doc/security/unlock_user.md
@@ -2,37 +2,44 @@
 type: howto
 ---
 
-# How to unlock a locked user
+# How to unlock a locked user from the command line
 
-To unlock a locked user, first log into your server with root privileges.
+After six failed login attempts a user gets in a locked state.
 
-Start a Ruby on Rails console with this command:
+To unlock a locked user:
 
-```bash
-gitlab-rails console production
-```
+1. SSH into your GitLab server.
+1. Start a Ruby on Rails console:
 
-Wait until the console has loaded.
+   ```sh
+   ## For Omnibus GitLab
+   sudo gitlab-rails console production
 
-There are multiple ways to find your user. You can search for email or username.
+   ## For installations from source
+   sudo -u git -H bundle exec rails console RAILS_ENV=production
+   ```
 
-```bash
-user = User.where(id: 1).first
-```
+1. Find the user to unlock. You can search by email or ID.
 
-or
+   ```ruby
+   user = User.find_by(email: 'admin@local.host')
+   ```
 
-```bash
-user = User.find_by(email: 'admin@local.host')
-```
+   or
 
-Unlock the user:
+   ```ruby
+   user = User.where(id: 1).first
+   ```
 
-```bash
-user.unlock_access!
-```
+1. Unlock the user:
 
-Exit the console, the user should now be able to log in again.
+   ```ruby
+   user.unlock_access!
+   ```
+
+1. Exit the console with <kbd>Ctrl</kbd>+<kbd>d</kbd>
+
+The user should now be able to log in.
 
 <!-- ## Troubleshooting
 
diff --git a/doc/security/user_email_confirmation.md b/doc/security/user_email_confirmation.md
index f0af0a7ac6a..7ba50acbb06 100644
--- a/doc/security/user_email_confirmation.md
+++ b/doc/security/user_email_confirmation.md
@@ -1,6 +1,7 @@
 ---
 type: howto
 ---
+
 # User email confirmation at sign-up
 
 GitLab can be configured to require confirmation of a user's email address when
diff --git a/doc/security/user_file_uploads.md b/doc/security/user_file_uploads.md
index f34528a6e05..9fc8f7ec985 100644
--- a/doc/security/user_file_uploads.md
+++ b/doc/security/user_file_uploads.md
@@ -1,6 +1,7 @@
 ---
 type: reference
 ---
+
 # User File Uploads
 
 Images that are attached to issues, merge requests, or comments
diff --git a/doc/security/webhooks.md b/doc/security/webhooks.md
index d4fa088cb15..1194234a295 100644
--- a/doc/security/webhooks.md
+++ b/doc/security/webhooks.md
@@ -1,6 +1,7 @@
 ---
 type: concepts, reference, howto
 ---
+
 # Webhooks and insecure internal web services
 
 If you have non-GitLab web services running on your GitLab server or within its