(DOCUMENT-129) Add warning notes about PassengerHighPerformance

We talked to Ryan McKern about this, since he'd recently audited our vhost
configs for performance. He pointed out that the setting can be changed in vhost
or directory scope, which means you can disable it for only certain routes.

I added notes about what it interferes with to the Passenger and multi-master
pages, and a quick example on how to disable it. I also moved the example
declaration to within the puppet master vhost, so at least it wouldn't clobber
other modules globally.

source/guides/passenger.markdown

@@ -116,7 +116,6 @@ puppetmaster port (8140). You can also see a similar file at `ext/rack/example-p
     #PassengerRuby /usr/bin/ruby
 
     # And the passenger performance tuning settings:
-    PassengerHighPerformance On
     # Set this to about 1.5 times the number of CPU cores in your master:
     PassengerMaxPoolSize 12
     # Recycle master processes after they service 1000 requests
@@ -126,6 +125,10 @@ puppetmaster port (8140). You can also see a similar file at `ext/rack/example-p
 
     Listen 8140
     <VirtualHost *:8140>
+        # Make Apache hand off HTTP requests to Puppet earlier, at the cost of
+        # interfering with mod_proxy, mod_rewrite, etc. See note below.
+        PassengerHighPerformance On
+
         SSLEngine On
 
         # Only allow high security cryptography. Alter if needed for compatibility.
@@ -180,6 +183,12 @@ need to use different paths to the CA certificate and CRL:
 For additional details about enabling and configuring Passenger, see the
 [Passenger install guide](http://www.modrails.com/install.html) and the [Apache version of the Passenger user's guide][passenger_apache_guide].
 
+> ### Notes on PassengerHighPerformance
+>
+> The example vhost config above sets `PassengerHighPerformance On`. This setting basically allows Passenger to shortcut some of Apache's normal layers of request handling, so the Puppet application can respond earlier. Unfortunately, it can also interfere with other Apache modules, including important ones like `mod_proxy`, `mod_rewrite`, and `mod_authz_core`.
+>
+> In the example, we've limited its effect by setting PassengerHighPerformance at the vhost scope, so it won't interfere with any non-Puppet requests the Apache process is handling. You can also enable or disable it in a `<Location>` directive, which may be necessary if you're proxying traffic to the Puppet CA in a multi-master setup.
+
 > ### Notes on DocumentRoot and PassengerAppRoot
 >
 > Passenger usually uses Apache's DocumentRoot directive to guess where to find its config.ru file --- it assumes config.ru will be right beside the `public` directory.

source/guides/scaling_multiple_masters.markdown

@@ -9,7 +9,7 @@ Using Multiple Puppet Masters
 
 To scale beyond a certain size, or for geographic distribution or disaster recovery, a deployment may warrant having more than one puppet master server. This document outlines options for open source Puppet deployments with multiple masters.
 
-> Note: This document is specific to open source Puppet, versions 2.7 through 3.2. 
+> Note: This document is specific to open source Puppet, versions 2.7 through 3.2.
 
 In brief:
 
@@ -123,6 +123,12 @@ All certificate related URLs begin with `/<NAME OF PUPPET ENVIRONMENT>/certifica
 >
 > This change must be made to the Apache configuration on every puppet master server other than the one serving as the CA. No changes need to be made to agent nodes' configurations.
 >
+> Note that if your puppet master vhost sets `PassengerHighPerformance On`, you'll need to disable it for the CA routes, since it interferes with `mod_proxy` (among other things). Since PassengerHighPerformance can be enabled or disabled at global, vhost, or directory scope, you can use a Location directive to disable it:
+>
+>     <Location ~ "/[^/]+/certificate">
+>         PassengerHighPerformance Off
+>     </Location>
+>
 > Additionally, the CA master must allow the nodes to download the certificate revocation list via the proxy, without authentication --- certificate requests and retrieval of signed certificates are allowed by default, but not CRLs.  Add the following to the CA master's `auth.conf`:
 >
 >     path /certificate_revocation_list