Document how to enable SSL with Jetty and Apache2

This is some black magic necessary to inform Jetty that the connection
is actually an https:// connection, and not a http://.  Without this
special configuration Gerrit will send redirects from https:// to a
normal http:// connection, dropping the user out of a secure channel.

Signed-off-by: Shawn O. Pearce <sop@google.com>

2 files changed, 106 insertions, 7 deletions

diff --git a/Documentation/install.txt b/Documentation/install.txt
index 74398e2916..4df16dcdfe 100644
--- a/Documentation/install.txt
+++ b/Documentation/install.txt
@@ -249,20 +249,48 @@ script such as the following in `/etc/init.d/gerrit2-jetty`
   JAVA_OPTIONS=""
   JAVA_OPTIONS="$JAVA_OPTIONS -Djetty.host=$JETTY_HOST"
   export JAVA_OPTIONS
+
+  C="jetty-logging jetty"
+  [ -f "$JETTY_HOME/etc/jetty_sslproxy.xml" ] && C="$C jetty_sslproxy"
   
-  exec $JETTY_HOME/bin/jetty.sh "$@"
+  exec $JETTY_HOME/bin/jetty.sh "$@" $C
 ====
 
-To deploy on port 80, or to use SSL, you should configure Jetty
-to listen on another port, such as 127.0.0.1:8081 (like the start
-script above does) and then follow the <<apache2,reverse proxy>>
-section below.
-
 [TIP]
 Under Jetty, restarting the web application (e.g. after modifying
 `system_config`) is as simple as touching the config file:
 `$JETTY_HOME/contexts/gerrit.xml`
 
+Port 80
+^^^^^^^
+
+To deploy on port 80, you should configure Jetty to listen on another
+port, such as 127.0.0.1:8081 (like the start script above does)
+and then follow the <<apache2,reverse proxy>> section below.
+
+Port 443 (HTTPS / SSL)
+^^^^^^^^^^^^^^^^^^^^^^
+
+To deploy on port 443 with SSL enabled, unpack the SSL proxy handling
+rule into `$JETTY_HOME`:
+====
+  java -jar gerrit.war --cat extra/jetty_sslproxy.xml >$JETTY_HOME/etc/jetty_sslproxy.xml
+====
+
+Create a start script like the one above, configuring Jetty to
+listen on another port, such as 127.0.0.1:8081.
+
+Set `canonical_url` in `system_config` to an `https://` style URL
+for your application, so that non-SSL connections are automatically
+upgraded to SSL by issuing a redirect.  Gerrit does not currently
+support a dual http/https usage on the same site as it doesn't
+know when to upgrade a non-secure connection to a secure one if
+data needs to be protected.
+
+Follow the <<apache2,reverse proxy>> section below to setup an
+Apache2 server to handle SSL for Jetty.
+
+
 Other Servlet Containers
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -286,6 +314,7 @@ You may need to download and install the Java Mail JARs in your
 container's classpath.  If this is not configured, Gerrit will
 function, but will not be able to send email.
 
+
 [[apache2]]
 Apache2 Reverse Proxy
 ~~~~~~~~~~~~~~~~~~~~~
@@ -295,6 +324,9 @@ Enable the necessary Apache2 modules:
 ====
   a2enmod proxy_http
   a2enmod disk_cache   ; # optional, but helps performance
+
+  a2enmod ssl          ; # optional, needed for HTTPS / SSL
+  a2enmod headers      ; # optional, needed for HTTPS / SSL
 ====
 
 then setup a VirtualHost to proxy to Gerrit's servlet container,
@@ -322,7 +354,36 @@ in your servlet container's configuration:
 	</VirtualHost>
 =======================================
 
-To enable SSL, see the Apache server documentation.
+if you are using SSL with a Jetty container:
+
+====
+	<VirtualHost *:443>
+	  ServerName review.example.com
+	#
+	  SSLEngine on
+	  SSLCertificateFile    conf/server.crt
+	  SSLCertificateKeyFile conf/server.key
+	#
+	  ProxyRequests Off
+	  ProxyVia Off
+	  ProxyPreserveHost On
+	  ProxyPass / http://127.0.0.1:8081/
+	  RequestHeader set X-Forwarded-Scheme https
+	#
+	  <IfModule mod_disk_cache.c>
+		CacheEnable disk /
+		CacheIgnoreHeaders Set-Cookie
+	  </IfModule>
+	</VirtualHost>
+====
+
+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.
+
+For Gerrit, the only difference between plain HTTP and HTTPS is
+adding the "`RequestHeader set X-Forwarded-Scheme https`" line
+within the SSL enabled virtual host.
 
 
 Administrator Setup
diff --git a/src/main/webapp/WEB-INF/extra/jetty_sslproxy.xml b/src/main/webapp/WEB-INF/extra/jetty_sslproxy.xml
new file mode 100644
index 0000000000..2bf77b8383
--- /dev/null
+++ b/src/main/webapp/WEB-INF/extra/jetty_sslproxy.xml
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd">
+<!--
+
+  Jetty configuration to correctly handle SSL/HTTPS traffic when
+  Apache is handling the SSL and proxying over plain HTTP to us.
+
+  Requires Jetty 6.1.12 (or later) or 7.0.0pre3 (or later).
+
+  * Copy this file to $JETTY_HOME/etc/jetty_sslproxy.xml
+  * Add jetty_sslproxy to your start line:
+
+      $JETTY_HOME/bin/jetty.sh start jetty-logging jetty jetty_sslproxy
+
+  * Configure Apache to set X-Forwarded-Scheme on requests:
+
+      RequestHeader set X-Forwarded-Scheme https
+
+-->
+<Configure id="Server" class="org.mortbay.jetty.Server">
+  <Get id="oldHandler" name="handler"/>
+  <Set name="handler">
+    <New class="org.mortbay.jetty.handler.rewrite.RewriteHandler">
+      <Set name="handler"><Ref id="oldHandler"/></Set>
+      <Set name="rules">
+        <Array type="org.mortbay.jetty.handler.rewrite.Rule">
+          <Item>
+            <New class="org.mortbay.jetty.handler.rewrite.ForwardedSchemeHeaderRule">
+              <Set name="header">X-Forwarded-Scheme</Set>
+              <Set name="headerValue">https</Set>
+              <Set name="scheme">https</Set>
+            </New>
+          </Item>
+        </Array>
+      </Set>
+    </New>
+  </Set>
+</Configure>