# 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.