PageSpeed HTTPS Support

As of version 1.10 HTTPS fetching (FetchHttps) 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.

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:

Use MapOriginDomain to map the https domain to an http domain.
Use LoadFromFile to map a locally available directory to the https domain.
Use FetchHttps to directly fetch HTTPS resources (On by default since 1.10).

The first two mechanisms can both be used on the same server, but they must be used for different domains, for example:

Apache:

  ModPagespeedMapOriginDomain "http://localhost" "https://www.example.com"
  ModPagespeedLoadFromFile "https://static.example.com" "/var/www/example/static/"

Nginx:

  pagespeed MapOriginDomain "http://localhost" "https://www.example.com";
  pagespeed LoadFromFile "https://static.example.com" "/var/www/example/static/";

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.

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.

Map the origin domain

Https resource URLs can be fetched by mapping them to a non-https origin domain as described in Mapping Origin Domains:

Apache:

  ModPagespeedMapOriginDomain "http://localhost" "https://www.example.com"

Nginx:

  pagespeed MapOriginDomain "http://localhost" "https://www.example.com";

This allows the server to accept https requests for www.example.com while fetching resources for it from the localhost http server, which could be the same Apache process or a different server process. All fetched resources will be optimized as usual. As many MapOriginDomain directives can be used as is required as long as https is only used on the second domain.

Load static files from disk

Https resource URLs can be served from static files using the LoadFromFile directive:

Apache:

ModPagespeedLoadFromFile "https://www.example.com" "/var/www/example/static/";

Nginx:

pagespeed LoadFromFile "https://www.example.com" "/var/www/example/static/";

Fetch HTTPS resources directly

HTTPS fetching is built in and is enabled by default as of 1.10.33.0. To turn the feature off, set FetchHttps to disable:

Apache:

  ModPagespeedFetchHttps enable

Nginx:

  pagespeed FetchHttps enable;

You may set multiple options, separated with a comma. For example, to test a configuration with a self-signed certificate you could do:

Apache:

  ModPagespeedFetchHttps enable,allow_self_signed

Nginx:

  pagespeed FetchHttps enable,allow_self_signed;

The available options are

enable
disable
allow_self_signed
allow_unknown_certificate_authority
allow_certificate_not_yet_valid

Configuring SSL Certificates

Acting as an HTTPS client, PageSpeed must be configured to point to a directory identifying trusted Certificate Authorities (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.

Apache:

  # Certificate Authorities directory, not your domain SSL keys
  ModPagespeedSslCertDirectory directory
  # Web Server's HTTPS client SSL key, not your domain SSL keys
  ModPagespeedSslCertFile file

Nginx:

  pagespeed SslCertDirectory directory;
  pagespeed SslCertFile file;

The default directory for Debian-based systems is /etc/ssl/certs, and there is no certificate file setting. On CentOS-based systems, the default directory is /etc/pki/tls/certs and default file is /etc/pki/tls/cert.pem.

These directive cannot be used in .htaccess files or <Directory> scopes.

Rewrite domains

Rewritten resources can have their https domain rewritten if required for the reasons described in Mapping Rewrite Domains:

Apache:

  ModPagespeedMapOriginDomain "http://localhost" "https://www.example.com"
  ModPagespeedMapRewriteDomain "https://example.cdn.com" "https://www.example.com"

Nginx:

  pagespeed MapOriginDomain "http://localhost" "https://www.example.com";
  pagespeed MapRewriteDomain "https://example.cdn.com" "https://www.example.com";

Shard domains

Rewritten resources can have their https domain sharded if required for the reasons described in Sharding Domains:

Apache:

  ModPagespeedMapOriginDomain "http://localhost" "https://www.example.com"
  ModPagespeedShardDomain "https://www.example.com" \
                          "https://example1.cdn.com,https://example2.cdn.com"

Nginx:

  pagespeed MapOriginDomain "http://localhost" "https://www.example.com";
  pagespeed ShardDomain "https://www.example.com"
                        "https://example1.cdn.com,https://example2.cdn.com";

Respecting X-Forwarded-Proto

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 http:// URLs. For PageSpeed to operate correctly, it needs to know what the originally requested URL was. If your front-end sends X-Forwarded-Proto headers (as, for example, AWS Elastic Load Balancer does) then you can tell PageSpeed to respect that header with:

Apache:

  ModPagespeedRespectXForwardedProto on

Nginx:

  pagespeed RespectXForwardedProto on;

This will correctly rewrite your subresources with https:// 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.

This directive cannot be used in .htaccess files or <Directory> scopes.

Risks

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, BoringSSL 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.

HTTP/2-specific configuration

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 <If> construct in Apache and with script variables in Nginx.

Apache Version

Note: Versions older than 1.12.34.1 provided a <ModPagespeedIf> construct. This is no longer supported, but configuration inside <ModPagespeedIf !spdy> blocks will be applied unconditionally for backwards compatibility.

mod_http2 in Apache ≥ 2.4.19 provides an HTTP2 variable that can be used with the server's <If> 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:

<If "%{HTTP2} == 'on'">
  ModPagespeedDisableFilters filter1,filter2
</If>
<Else>
  ModPagespeedShardDomain https://www.example.com https://example1.cdn.com,https://example2.cdn.com
</Else>

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 req function.

Nginx Version

Note: New feature as of 1.10.33.0

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";
  }
}

The $http2 variable is defined by the ngx_http_v2_module, and will be non-empty on any connection over HTTP/2.

If the connection is terminated on another server the $http2 variable won't be available. In that case, you can have the other server add a header for HTTP/2 connections like X-ConnectionIsHTTP2 and then use the http_X_ConnectionIsHTTP2 variable in the if-block above.

Note that this configuration depends on the if construct, which is generally discouraged. Using if only to set variables in server blocks, however, is completely safe.

For more details on script variables, including how to handle dollar signs, see Script Variable Support.