# HG changeset patch
# User Marin Jankovski <maxlazio@gmail.com>
# Date 1454595128 -3600
#      Thu Feb 04 15:12:08 2016 +0100
# Node ID 0a0c993160375f949e9e33b290da2affed26618d
# Parent  cf03d2e05d74a850ab0b393d460b142c8cf71133
Add docs on how to change NGINX proxy headers.

diff --git a/doc/common_installation_problems/README.md b/doc/common_installation_problems/README.md
--- a/doc/common_installation_problems/README.md
+++ b/doc/common_installation_problems/README.md
@@ -347,10 +347,23 @@
 gitlab_workhorse['proxy_headers_timeout'] = "2m0s"
 ```
 
-Save the file and [reconfigure GitLab](http://doc.gitlab.com/ce/administration/restart_gitlab.html#omnibus-gitlab-reconfigure)
-for the changes to take effect.
+Save the file and [reconfigure GitLab][] for the changes to take effect.
+
+### The change you wanted was rejected
+
+Most likely you have GitLab setup in an environment that has proxy in front
+of Gitlab and the proxy headers set in package by default are incorrect
+for your environment.
+
+See [Change the default proxy headers section of nginx doc][] for details on
+how to override the default headers.
+
+### Can't verify CSRF token authenticity Completed 422 Unprocessable
+
 
 [CAcert.org]: http://www.cacert.org/
 [certificate link shell script]: https://gitlab.com/snippets/6285
 [script source]: https://www.madboa.com/geek/openssl/#verify-new
 [gitlab.rb.template]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template
+[Change the default proxy headers section of nginx doc]: doc/settings/nginx.md](doc/settings/nginx.md
+[reconfigure GitLab]: http://doc.gitlab.com/ce/administration/restart_gitlab.html#omnibus-gitlab-reconfigure
diff --git a/doc/settings/nginx.md b/doc/settings/nginx.md
--- a/doc/settings/nginx.md
+++ b/doc/settings/nginx.md
@@ -68,7 +68,9 @@
 external_url "https://gitlab.example.com:2443"
 ```
 
-To set the location of ssl certificates create `/etc/gitlab/ssl` directory, place the `.crt` and `.key` files in the directory and specify the following configuration:
+To set the location of ssl certificates create `/etc/gitlab/ssl` directory,
+place the `.crt` and `.key` files in the directory and specify the following
+configuration:
 
 ```ruby
 # For GitLab
@@ -78,6 +80,40 @@
 
 Run `sudo gitlab-ctl reconfigure` for the change to take effect.
 
+## Change the default proxy headers
+
+By default, when you specify `external_url` omnibus-gitlab will set a few
+NGINX proxy headers that are assumed to be sane in most environments.
+
+For example, omnibus-gitlab will set:
+
+```
+  "X-Forwarded-Proto" => "https",
+  "X-Forwarded-Ssl" => "on"
+```
+
+if you have specified `https` schema in the `external_url`.
+
+However, if you have a situation where your GitLab is in a more complex setup
+like behind a reverse proxy, you will need to tweak the proxy headers in order
+to avoid errors like `The change you wanted was rejected` or
+`Can't verify CSRF token authenticity Completed 422 Unprocessable`.
+
+This can be achieved by overriding the default headers, eg. specify
+in `/etc/gitlab/gitlab.rb`:
+
+```ruby
+ nginx['proxy_set_headers'] = {
+  "X-Forwarded-Proto" => "http",
+  "CUSTOM_HEADER" => "VALUE"
+ }
+```
+
+Save the file and [reconfigure GitLab](http://doc.gitlab.com/ce/administration/restart_gitlab.html#omnibus-gitlab-reconfigure)
+for the changes to take effect.
+
+This way you can specify any header supported by NGINX you require.
+
 ## Using a non-bundled web-server
 
 By default, omnibus-gitlab installs GitLab with bundled Nginx.