Merge "Documentation: Reverse Proxy Configuration" into stable-2.6

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'
+To run Gerrit behind an Apache server using 'mod_proxy', enable the
-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
 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
+Configure an Apache VirtualHost to proxy to the Gerrit daemon,
-the 'RewriteRule' line to use the 'http://' URL configured above.
+setting the 'ProxyPass' line to use the 'http://' URL configured
-Ensure the path of 'RewriteRule' (the part before '$1') and
+above.  Ensure the path of ProxyPass and httpd.listenUrl match,
-httpd.listenUrl match, or links will redirect to incorrect locations.
+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.
 
 ----
 	<VirtualHost *>
 	  ServerName review.example.com
 
-	  AllowEncodedSlashes NoDecode
+	  ProxyRequests Off
-	  RewriteEngine On
+	  ProxyVia Off
-	  RewriteRule ^/r/(.*) http://localhost:8081/r/$1 [NE,P]
+	  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]

ReleaseNotes/ReleaseNotes-2.6.txt

@@ -23,6 +23,17 @@ Schema Change
 a later 2.1.x version), and then to 2.6.x.  If you are upgrading from 2.2.x.x or
 newer, you may ignore this warning and upgrade directly to 2.6.x.
 
+Reverse Proxy Configuration Changes
+-----------------------------------
+
+If you are running a reverse proxy in front of Gerrit (e.g. Apache or Nginx),
+make sure to check your configuration, especially if you are encountering
+'Page Not Found' errors when opening the change screen.
+See the link:http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/config-reverseproxy.html[
+Reverse Proxy Configuration] for details.
+
+Gerrit now requires passed URLs to be unchanged by the proxy.
+
 Release Highlights
 ------------------
 * 42x improvement on `git clone` and `git fetch`
@@ -437,13 +448,6 @@ responses are protected from accidential sniffing and treatment as
 HTML thanks to Gson encoding HTML control characters using Unicode
 character escapes within JSON strings.
 
-* Apache reverse proxies must switch to mod_rewrite
-+
-When Apache is used as a reverse proxy the server must be reconfigured
-to use mod_rewrite and AllowEncodedSlashes.  For updated information
-link:http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/config-reverseproxy.html#_apache_2_configuration[
-review the Apache 2 Configuration documentation].
-
 Project Dashboards
 ~~~~~~~~~~~~~~~~~~
 * link:http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/user-dashboards.html#project-dashboards[

gerrit-httpd/src/main/resources/com/google/gerrit/httpd/auth/container/ConfigurationError.html

@@ -49,6 +49,15 @@
 &lt;VirtualHost <span class='ServerName'>review.example.com</span><span class='ServerPort'>:80</span>&gt;
     ServerName <span class='ServerName'>review.example.com</span>
 
+    ProxyRequests Off
+    ProxyVia Off
+    ProxyPreserveHost On
+
+    &lt;Proxy *&gt;
+          Order deny,allow
+          Allow from all
+    &lt;/Proxy&gt;
+
 <div class='apache_auth'>    &lt;Location <span class='ContextPath'>/r</span>/login/&gt;
       AuthType Basic
       AuthName "Gerrit Code Review"
@@ -56,9 +65,8 @@
       ...
     &lt;/Location&gt;</div>
 
-    AllowEncodedSlashes NoDecode
+    AllowEncodedSlashes On
-    RewriteEngine On
+    ProxyPass <span class='ContextPath'>/r</span>/ http://...<span class='ContextPath'>/r</span>/ nodecode
-    RewriteRule ^<span class='ContextPath'>/r</span>/(.*) http://...<span class='ContextPath'>/r</span>/$1 [NE,P]
 &lt;/VirtualHost&gt;
     </pre>
   </body>