Documentation: Reverse Proxy Configuration

Update the Reverse Proxy documentation and the Release Notes to reflect
the possible changes required for reverse proxy setups (to prevent
slashes from being decoded).

This reverts the following two commits:
  27a3917dcbf851b62433a0f2360f9ac64db7938d
  768cff15b09b724cd930f904eaac867443fb966d

Change-Id: I57e93b724685ba94cb4d935fbe3d933fa12bad2d

1 files changed, 37 insertions, 17 deletions

diff --git a/Documentation/config-reverseproxy.txt b/Documentation/config-reverseproxy.txt
index 0857442fa3..064fe2e548 100644
--- a/Documentation/config-reverseproxy.txt
+++ b/Documentation/config-reverseproxy.txt
@@ -28,37 +28,40 @@ during 'init'.
 Apache 2 Configuration
 ----------------------
 
-To run Gerrit behind an Apache server we cannot use 'mod_proxy'
-directly, as Gerrit relies on getting unmodified escaped forward
-slashes. Depending on the setting of 'AllowEncodedSlashes',
-'mod_proxy' would either decode encoded slashes, or encode them once
-again. Hence, we resort to using 'mod_rewrite'. To enable the
+To run Gerrit behind an Apache server using 'mod_proxy', enable the
 necessary Apache2 modules:
 
 ----
-  a2enmod rewrite
+  a2enmod proxy_http
   a2enmod ssl          ; # optional, needed for HTTPS / SSL
 ----
 
-Configure an Apache VirtualHost to proxy to the Gerrit daemon, setting
-the 'RewriteRule' line to use the 'http://' URL configured above.
-Ensure the path of 'RewriteRule' (the part before '$1') and
-httpd.listenUrl match, or links will redirect to incorrect locations.
-
-Note that this configuration allows to pass encoded characters to the
-virtual host, which is potentially dangerous. Be sure to read up on
-this topic and that you understand the risks.
+Configure an Apache VirtualHost to proxy to the Gerrit daemon,
+setting the 'ProxyPass' line to use the 'http://' URL configured
+above.  Ensure the path of ProxyPass and httpd.listenUrl match,
+or links will redirect to incorrect locations.
 
 ----
 	<VirtualHost *>
 	  ServerName review.example.com
 
-	  AllowEncodedSlashes NoDecode
-	  RewriteEngine On
-	  RewriteRule ^/r/(.*) http://localhost:8081/r/$1 [NE,P]
+	  ProxyRequests Off
+	  ProxyVia Off
+	  ProxyPreserveHost On
+
+	  <Proxy *>
+	    Order deny,allow
+	    Allow from all
+	  </Proxy>
+
+	  AllowEncodedSlashes On
+	  ProxyPass /r/ http://127.0.0.1:8081/r/ nocanon
 	</VirtualHost>
 ----
 
+The two options 'AllowEncodedSlashes On' and 'ProxyPass .. nocanon' are required
+since Gerrit 2.6.
+
 SSL
 ~~~
 
@@ -80,6 +83,15 @@ See the Apache 'mod_ssl' documentation for more details on how to
 configure SSL within the server, like controlling how strong of an
 encryption algorithm is required.
 
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+If you are encountering 'Page Not Found' errors when opening the change
+screen, your Apache proxy is very likely decoding the passed URL.
+Make sure to either use 'AllowEncodedSlashes On' together with
+'ProxyPass .. nodecode' or alternatively a 'mod_rewrite' configuration with
+'AllowEncodedSlashes NoDecode' set.
+
 
 Nginx Configuration
 -------------------
@@ -124,6 +136,14 @@ See the Nginx 'http ssl module' documentation for more details on
 how to configure SSL within the server, like controlling how strong
 of an encryption algorithm is required.
 
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+If you are encountering 'Page Not Found' errors when opening the change
+screen, your Nginx proxy is very likely decoding the passed URL.
+Make sure to use a 'proxy_pass' URL without any path (esp. no trailing
+'/' after the 'host:port').
+
 GERRIT
 ------
 Part of link:index.html[Gerrit Code Review]