| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <html> |
| <head> |
| <meta name="viewport" content="width=device-width, initial-scale=1"> |
| <title>PageSpeed HTTPS Support</title> |
| <link rel="stylesheet" href="doc.css"> |
| </head> |
| <body> |
| <!--#include virtual="_header.html" --> |
| |
| |
| <div id=content> |
| <h1>PageSpeed HTTPS Support</h1> |
| <p class="note"> |
| As of version 1.10 HTTPS fetching (<code>FetchHttps</code>) is enabled by |
| default, and PageSpeed no longer requires additional configuration to |
| fetch and optimize resources over https. The alternatives described |
| below, however, are more efficient in situations where they apply. |
| </p> |
| |
| <p> |
| PageSpeed supports sites that serve content through https. There are |
| several mechanisms through which PageSpeed can be configured to fully |
| optimize sites served under https: |
| </p> |
| <ul> |
| <li>Use <code>MapOriginDomain</code> to |
| <a href="https_support#map_the_origin">map the https domain to an http |
| domain</a>.</li> |
| <li>Use <code>LoadFromFile</code> to |
| <a href="https_support#load_from_file">map a |
| locally available directory to the https domain</a>.</li> |
| <li>Use <code>FetchHttps</code> to <a href="https_support#https_fetch" |
| >directly fetch HTTPS resources</a> (On by default since 1.10).</li> |
| </ul> |
| |
| <p> |
| The first two mechanisms can both be used on the same server, but they |
| must be used for different domains, for example: |
| </p> |
| |
| <dl> |
| <dt>Apache:<dd><pre class="prettyprint" |
| > ModPagespeedMapOriginDomain "http://localhost" "https://www.example.com" |
| ModPagespeedLoadFromFile "https://static.example.com" "/var/www/example/static/"</pre> |
| </dd></dt> |
| <dt>Nginx:<dd><pre class="prettyprint" |
| > pagespeed MapOriginDomain "http://localhost" "https://www.example.com"; |
| pagespeed LoadFromFile "https://static.example.com" "/var/www/example/static/";</pre> |
| </dl> |
| |
| <p> |
| Even without configuring any of these options, PageSpeed |
| rewrites HTML documents requested via https. PageSpeed is able to |
| serve these documents because the server passes the HTML document through |
| all its output filters, including *_pagespeed. But by default, |
| PageSpeed will only rewrite non-HTML resources which are served |
| via http. Due to the complexity and security required to manage client |
| SSL certificates, PageSpeed requires the server administrator to |
| explicitly enable https fetching. |
| </p> |
| |
| <p> |
| The configuration options mentioned above are intended to help |
| optimize sites with HTTPS resources. Fetching https resource URLs |
| using http should be used only in installations where using http is |
| safe, such as where the server running PageSpeed is a |
| front-end to other back-end systems with private communications and |
| mutual trust between them. |
| </p> |
| |
| <h2 id="map_the_origin">Map the origin domain</h2> |
| |
| <p> |
| Https resource URLs can be fetched by mapping them to a non-https origin |
| domain as described in |
| <a href="domains#mapping_origin">Mapping Origin Domains</a>: |
| </p> |
| <dl> |
| <dt>Apache:<dd> |
| <pre class="prettyprint"> |
| ModPagespeedMapOriginDomain "http://localhost" "https://www.example.com" |
| </pre> |
| </dd></dt> |
| <dt>Nginx:<dd> |
| <pre class="prettyprint"> |
| pagespeed MapOriginDomain "http://localhost" "https://www.example.com"; |
| </pre> |
| </dd></dt> |
| </dl> |
| |
| <p> |
| This allows the server to accept https requests for |
| <code>www.example.com</code> while fetching resources for it from the |
| <code>localhost</code> http server, which could be the same Apache process or a |
| different server process. All fetched resources will be optimized as usual. As |
| many <code>MapOriginDomain</code> directives can be used as is required as long |
| as https is only used on the second domain. |
| </p> |
| |
| <h2 id="load_from_file">Load static files from disk</h2> |
| |
| <p> |
| Https resource URLs can be served from static files using the |
| <a href="domains#ModPagespeedLoadFromFile">LoadFromFile</a> directive: |
| </p> |
| |
| <dl> |
| <dt>Apache:<dd><pre class="prettyprint" |
| >ModPagespeedLoadFromFile "https://www.example.com" "/var/www/example/static/";</pre> |
| <dt>Nginx:<dd><pre class="prettyprint" |
| >pagespeed LoadFromFile "https://www.example.com" "/var/www/example/static/";</pre> |
| </dl> |
| |
| <h2 id="https_fetch">Fetch HTTPS resources directly</h2> |
| <p> |
| HTTPS fetching is built in and is enabled by default as of 1.10.33.0. |
| To turn the feature off, set <code>FetchHttps</code> to |
| <code>disable</code>: |
| </p> |
| |
| <dl> |
| <dt>Apache:<dd> |
| <pre class="prettyprint"> |
| ModPagespeedFetchHttps enable |
| </pre> |
| </dd></dt> |
| <dt>Nginx:<dd> |
| <pre class="prettyprint"> |
| pagespeed FetchHttps enable; |
| </pre> |
| </dd></dt> |
| </dl> |
| <p> |
| You may set multiple options, separated with a comma. For example, to |
| test a configuration with a self-signed certificate you could do: |
| </p> |
| |
| <dl> |
| <dt>Apache:<dd> |
| <pre class="prettyprint"> |
| ModPagespeedFetchHttps enable,allow_self_signed |
| </pre> |
| </dd></dt> |
| <dt>Nginx:<dd> |
| <pre class="prettyprint"> |
| pagespeed FetchHttps enable,allow_self_signed; |
| </pre> |
| </dd></dt> |
| </dl> |
| |
| <p> |
| The available options are |
| <ul> |
| <li><code>enable</code></li> |
| <li><code>disable</code></li> |
| <li><code>allow_self_signed</code></li> |
| <li><code>allow_unknown_certificate_authority</code></li> |
| <li><code>allow_certificate_not_yet_valid</code></li> |
| </ul> |
| </p> |
| |
| |
| <h3 id="configuring_ssl_certificates">Configuring SSL Certificates</h3> |
| |
| <p> |
| Acting as an HTTPS client, PageSpeed must be configured to point to a |
| directory identifying trusted |
| <a href="http://en.wikipedia.org/wiki/Certificate_authority" |
| >Certificate Authorities</a> (not SSL keys for your domain). These settings will be automatically |
| applied to configuration files for new binary installations on Debian, |
| Ubuntu, and CentOS systems. Upgrades, source-installs, and other |
| distributions may require manual configuration updates to identify the |
| proper location.</p> |
| |
| <dl> |
| <dt>Apache:<dd> |
| <pre class="prettyprint"> |
| # Certificate Authorities directory, not your domain SSL keys |
| ModPagespeedSslCertDirectory directory |
| # Web Server's HTTPS client SSL key, not your domain SSL keys |
| ModPagespeedSslCertFile file |
| </pre> |
| </dd></dt> |
| <dt>Nginx:<dd> |
| <pre class="prettyprint"> |
| pagespeed SslCertDirectory directory; |
| pagespeed SslCertFile file; |
| </pre> |
| </dd></dt> |
| </dl> |
| |
| <p> |
| The default directory for Debian-based systems |
| is <code>/etc/ssl/certs</code>, and there is no certificate file |
| setting. On CentOS-based systems, the default directory |
| is <code>/etc/pki/tls/certs</code> and default file |
| is <code>/etc/pki/tls/cert.pem</code>.</p> |
| |
| <p> |
| These directive cannot be used |
| in <a href="configuration#htaccess"><code>.htaccess</code> files |
| or <code><Directory></code></a> scopes. |
| </p> |
| |
| <h2 id="rewrite_domains">Rewrite domains</h2> |
| |
| <p> |
| Rewritten resources can have their https domain rewritten if required |
| for the reasons described in <a href="domains#mapping_rewrite">Mapping Rewrite |
| Domains</a>: |
| </p> |
| |
| <dl> |
| <dt>Apache:<dd><pre class="prettyprint" |
| > ModPagespeedMapOriginDomain "http://localhost" "https://www.example.com" |
| ModPagespeedMapRewriteDomain "https://example.cdn.com" "https://www.example.com"</pre> |
| </dd></dt> |
| <dt>Nginx:<dd><pre class="prettyprint" |
| > pagespeed MapOriginDomain "http://localhost" "https://www.example.com"; |
| pagespeed MapRewriteDomain "https://example.cdn.com" "https://www.example.com";</pre> |
| </dd></dt> |
| </dl> |
| |
| <h2 id="shard_domains">Shard domains</h2> |
| |
| <p> |
| Rewritten resources can have their https domain sharded if required |
| for the reasons described in <a href="domains#shard">Sharding Domains</a>: |
| </p> |
| |
| <dl> |
| <dt>Apache:<dd><pre class="prettyprint" |
| > ModPagespeedMapOriginDomain "http://localhost" "https://www.example.com" |
| ModPagespeedShardDomain "https://www.example.com" \ |
| "https://example1.cdn.com,https://example2.cdn.com"</pre> |
| </dd></dt> |
| <dt>Nginx:<dd><pre class="prettyprint" |
| > pagespeed MapOriginDomain "http://localhost" "https://www.example.com"; |
| pagespeed ShardDomain "https://www.example.com" |
| "https://example1.cdn.com,https://example2.cdn.com";</pre> |
| </dd></dt> |
| </dl> |
| |
| <h2 id="RespectXForwardedProto">Respecting X-Forwarded-Proto</h2> |
| <p> |
| If you are running behind a load-balancer or other front-end that |
| terminates the HTTPS connection and makes an HTTP subrequest to your |
| server running PageSpeed, it will not know that the original URL was |
| HTTPS and so it will rewrite subresources with <code>http://</code> URLs. |
| For PageSpeed to operate correctly, it needs to know what |
| the originally requested URL was. If your front-end sends |
| <code>X-Forwarded-Proto</code> headers (as, for example, |
| <a href="https://forums.aws.amazon.com/ann.jspa?annID=805">AWS Elastic |
| Load Balancer does</a>) then you can tell PageSpeed to |
| respect that header with: |
| </p> |
| <dl> |
| <dt>Apache:<dd><pre class="prettyprint" |
| > ModPagespeedRespectXForwardedProto on</pre> |
| <dt>Nginx:<dd><pre class="prettyprint" |
| > pagespeed RespectXForwardedProto on;</pre> |
| </dl> |
| <p> |
| This will correctly rewrite your subresources with <code>https://</code> |
| URLs and thus avoid mixed content warnings. Note, that you should only |
| enable this option if you are behind a load-balancer that will set this |
| header, otherwise your users will be able to set the protocol |
| PageSpeed uses to interpret the request. Also, note that by default |
| PageSpeed will loop back to the inbound ip/port for fetching resources |
| on behalf of a html response using http(s). When X-Forwarded-Proto is in |
| effect and the protocol is changed in front of the PageSpeed-enabled server, |
| a mismatch may arise when performing loopback fetches, leading up to fetching |
| failures. Explicitly authorizing the domain used to fetch resources will |
| resolve this problem, because doing so allows the loopback fetching mechanism |
| to be bypassed. |
| </p> |
| |
| <p> |
| This directive cannot be used |
| in <a href="configuration#htaccess"><code>.htaccess</code> files |
| or <code><Directory></code></a> scopes. |
| </p> |
| |
| <h2 id="risks">Risks</h2> |
| <p> |
| As discussed above, using http to fetch https resources URLs should only be |
| used when communication between the front-end and back-end servers is secure |
| as otherwise the benefits of using https in the first place are lost. When |
| fetching by HTTPS, <a |
| href="https://boringssl.googlesource.com/boringssl/">BoringSSL</a> |
| is used to authenticate the fetches. We bundle a copy of BoringSSL, which |
| means that when security vulnerabilities are discovered that affect our usage |
| we need to release updated versions of PageSpeed with the fixed BoringSSL |
| library. |
| </p> |
| |
| <h2 id="h2_configuration">HTTP/2-specific configuration</h2> |
| <p> |
| It's possible to tell PageSpeed to use a different configuration for |
| clients using the HTTP/2 protocol than for clients using HTTP/1. You can |
| configure this with the <code><If></code> construct in Apache and |
| with script variables in Nginx. |
| </p> |
| <h3 id="h2_configuration_apache">Apache Version</h3> |
| <p class="note">Note: Versions older than 1.12.34.1 provided |
| a <code><ModPagespeedIf></code> construct. This is no longer supported, but |
| configuration inside <code><ModPagespeedIf !spdy></code> blocks will be applied |
| unconditionally for backwards compatibility.</p> |
| |
| <p>mod_http2 in Apache ≥ 2.4.19 provides an HTTP2 variable that can be used with the |
| server's <code><If></code> construct to provide a different configuration for |
| HTTP2 sessions. For example, one may want to disable some filters in such sessions, and only |
| enable sharding in HTTP/1: |
| <pre class="prettyprint"> |
| <If "%{HTTP2} == 'on'"> |
| ModPagespeedDisableFilters filter1,filter2 |
| </If> |
| <Else> |
| ModPagespeedShardDomain https://www.example.com https://example1.cdn.com,https://example2.cdn.com |
| </Else></pre> |
| |
| <p> |
| Note that this only covers requests terminated by mod_http2 on the Apache server itself. |
| If an earlier proxy terminates HTTP/2, you may need to have it set a custom header, |
| and test it using the <code>req</code> function. |
| </p> |
| |
| <h3 id="h2_configuration_nginx">Nginx Version</h3> |
| <p class="note"><strong>Note: New feature as of 1.10.33.0</strong></p> |
| <pre class="prettyprint"> |
| http { |
| pagespeed ProcessScriptVariables on; |
| server { |
| set $disable_filters ""; |
| set $domain_shards "shard1,shard2,shard3..." |
| |
| if ($http2) { |
| set $disable_filters "filter1,filter2"; |
| set $domain_shards ""; |
| } |
| pagespeed DisableFilters "$disable_filters"; |
| pagespeed ShardDomain domain_to_shard "$domain_shards"; |
| } |
| }</pre> |
| <p> |
| The <code>$http2</code> variable is defined by |
| the <a href="http://nginx.org/en/docs/http/ngx_http_v2_module.html" |
| ><code>ngx_http_v2_module</a></code>, and will be non-empty on any |
| connection over HTTP/2. |
| </p> |
| <p> |
| If the connection is terminated on another server |
| the <code>$http2</code> variable won't be available. In that case, you |
| can have the other server add a header for HTTP/2 connections |
| like <code>X-ConnectionIsHTTP2</code> and then use |
| the <code>http_X_ConnectionIsHTTP2</code> variable in |
| the <code>if</code>-block above. |
| </p> |
| <p> |
| Note that this configuration depends on the <code>if</code> construct, |
| which <a href="https://www.nginx.com/resources/wiki/start/topics/depth/ifisevil/">is |
| generally discouraged</a>. Using <code>if</code> only to set variables in |
| server blocks, however, is completely safe. |
| </p> |
| <p> |
| For more details on script variables, including how to handle dollar |
| signs, see <a href="system#nginx_script_variables">Script Variable |
| Support</a>. |
| </p> |
| </div> |
| <!--#include virtual="_footer.html" --> |
| </body> |
| </html> |