mod_pagespeed

https://github.com/pagespeed/mod_pagespeed.git

https://developers.google.com/speed/pagespeed/module/install

https://developers.google.com/speed/pagespeed/module/filter-js-combine

Combine JavaScript

Configuration

The 'Combine JavaScript' filter is enabled by specifying:

Apache:

 

ModPagespeedEnableFilters combine_javascript

Nginx:

 

pagespeed EnableFilters combine_javascript;

in the configuration file.

Description

'Combine JavaScript' seeks to reduce the number of HTTP requests made by a browser during page refresh by replacing multiple distinct JavaScript files with a single one.

This practice reduces the number of round-trip times.

Example

You can see the filter in action at www.modpagespeed.com on this example.

Parameters that affect JS combining

MaxCombinedJsBytes

Apache:

 

ModPagespeedMaxCombinedJsBytes MaxBytes

Nginx:

 

pagespeed MaxCombinedJsBytes MaxBytes;

MaxBytes is the maximum uncompressed size in bytes of the combined JavaScript files. JavaScript files larger thanMaxBytes will be kept intact; other JavaScript files will be combined into one or more files, each being no more thanMaxBytes in size. The current default value for MaxBytes is 92160 (90K).

Limitations

The JavaScript Combine filter operates within the scope of a "flush window". Specifically, large, or dynamically generated HTML files may be "flushed" by the resource generator before they are complete. When the filter encounters a flush, it will emit all script combinations seen up to the point of the flush. After the flush, it will begin collecting a new script combination.

This filter currently cannot combine across inline scripts, and IE conditional comments.

This filter generates URLs that are essentially the concatenation of the URLs of all the Javascript files being combined. The maximum URL size is generally limited to about 2k characters due to IE: Seehttp://support.microsoft.com/kb/208427/EN-US. Apache servers by default impose a further limitation of about 250 characters per URL segment (text between slashes). PageSpeed circumvents this limitation when it runs under Apache, but if you employ proxy servers in your path you may need to re-impose it by overriding the setting here. The default setting is 1024.

Apache:

 

ModPagespeedMaxSegmentLength 250

Nginx:

 

pagespeed MaxSegmentLength 250;

Requirements

By default, the filter will combine together script files from different paths, placing the combined element at the lowest level common to both origins. In some cases, this may be undesirable. You can turn off the behavior with:

Apache:

 

ModPagespeedCombineAcrossPaths off

Nginx:

 

pagespeed CombineAcrossPaths off;

Risks

This filter is considered moderate risk. However, JavaScript can be written that walks the DOM looking for <script>entries with certain syntax. Such JavaScript may behave differently on a page which has modified script locations and structure.

This filter is sensitive to AvoidRenamingIntrospectiveJavascript. For example, a JavaScript file that callsdocument.getElementsByTagName('script') will not be combined with other JavaScript files.

This filter employs the Javascript 'eval' expression to evaluate each <script> tag at its proper location in the DOM, but getting the aggregated script content in one HTTP fetch. The effects of this are likely to differ between browsers, and haven't yet been thoroughly measured.

PageSpeed HTTPS Support

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 (In nginx since 1.8, in Apache since 1.7, on by default since 1.10).
• Use ModPagespeedFetchFromModSpdy to fetch same-domain HTTPS resources with help of mod_spdy (Apache only).

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.

Please read the Risks section before enabling https support.

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 thelocalhost 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

Note: New feature in mod_pagespeed as of 1.7.30.1 and in ngx_pagespeed as of 1.8.31.2

Note: Enabled by default as of 1.10.33.0

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. 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:

 

  ModPagespeedSslCertDirectory directory
  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

Note: New feature as of 1.1.23.1

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.

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.

Fetching HTTPS using mod_spdy

Note: Apache-only

Note: New feature as of 1.7.30.1, and mod_spdy 0.9.4.1

If you are using both mod_pagespeed and mod_spdy, it is possible to get fetch HTTPS resources more efficiently than via ModPagespeedFetchHttps by letting the two modules cooperate. You can do so by using the option:

 

  ModPagespeedFetchFromModSpdy on

Note that it has no effect on fetching of resources that are not on the same domain as the webpage, and for visitors who are not using HTTPS or SPDY.

SPDY/HTTP2-specific configuration

Note: This feature is significantly different between Apache and Nginx

It's possible to tell PageSpeed to use a different configuration for clients using the SPDY or HTTP/2 protocols than for clients using HTTPS or HTTP. You can configure this with the <ModPagespeedIf> construct in Apache and with script variables in Nginx.

Apache Version

Note: New feature as of 1.1.23.1

Note: Only supports SPDY

 

<ModPagespeedIf spdy>
  ModPagespeedDisableFilters filter1,filter2
</ModPagespeedIf>

<ModPagespeedIf !spdy>
  ModPagespeedShardDomain https://www.example.com https://example1.cdn.com,https://example2.cdn.com
</ModPagespeedIf>

You can use <ModPagespeedIf> at top-level and virtual host scopes. The conditional blocks may contain any mod_pagespeed configuration directive that is not server global. The configurations will be applied in the following order, with latter items having precedence over earlier ones:

1. Global configuration
2. Virtual host configuration
3. Relevant <ModPagespeedIf spdy> or <ModPagespeedIf !spdy> blocks at global scope
4. Relevant <ModPagespeedIf spdy> or <ModPagespeedIf !spdy> blocks at virtual host scope
5. Path or directory-specific configuration

mod_pagespeed will consider a request to be using SPDY if it either:

• Is a SPDY request handled by mod_spdy.
• The request has the header X-PSA-Optimize-For-SPDY set, with any value. If you are using a separate proxy to terminate your SPDY connections, configuring it to set this header will therefore permit the use of this feature.

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 you're using the older ngx_http_spdy_module, the $spdy variable is available instead, and you can change the configuration example above to substitute $spdy for $http2.

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 thehttp_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.