mod_pagespeed is an open-source Apache module that automatically optimizes web pages and resources on them. It does this by rewriting the resources using filters that implement web performance best practices. Webmasters and web developers can use mod_pagespeed to improve the performance of their web pages when serving content with the Apache HTTP Server.
mod_pagespeed is an Apache 2.x module. It is added into an existing Apache installation, and configured with the
pagespeed.conf configuration file.
mod_pagespeed can be installed from source or binary form.
In binary form mod_pagespeed is available as as Debian package for Linux distributions such as Ubuntu, installable with
dpkg. It is also available as an RPM package for CentOS or compatible Linux distributions.
You can browse or check out the source code in the open source repository.
mod_pagespeed contains an Apache “output filter” plus several content handlers.
On Debian/Ubuntu Linux distributions, the directory will be:
On CentOS/Fedora, the directory will be:
The mod_pagespeed configuration directives should be wrapped inside an
<IfModule pagespeed_module> .... </IfModule>
mod_pagespeed contains three handlers:
- mod_pagespeed_resource_generator: serves optimized resources
- mod_pagespeed_statistics: shows server statistics since startup, from which one can compute average latency, and thereby measure the effectiveness of various rewriting passes
- mod_pagespeed_beacon: part of the infrastructure we provide for measuring page latency.
The following settings for the handlers can be used as a guideline:
# This page shows statistics about the mod_pagespeed module. <Location /mod_pagespeed_statistics> Order allow,deny # One may insert other "Allow from" lines to add hosts that are # allowed to look at generated statistics. Another possibility is # to comment out the "Order" and "Allow" options from the config # file, to allow any client that can reach the server to examine # statistics. This might be appropriate in an experimental setup or # if the Apache server is protected by a reverse proxy that will # filter URLs to avoid exposing these statistics, which may # reveal site metrics that should not be shared otherwise. Allow from localhost SetHandler mod_pagespeed_statistics </Location> # This handles the client-side instrumentation callbacks which are injected # by the add_instrumentation filter. <Location /mod_pagespeed_beacon> SetHandler mod_pagespeed_beacon </Location>
Setting up the Output Filter
The output filter is used to parse, optimize, and re-serialize HTML content that is generated elsewhere in the Apache server.
# Direct Apache to send all HTML output to the mod_pagespeed output handler. SetOutputFilter MOD_PAGESPEED_OUTPUT_FILTER
ModPagepeedDomain http://my_site.com ModPagepeedDomain http://cdn.my_site.com
mod_pagespeed will rewrite resources found from these two explicitly listed domains. Addtionally, it will rewrite resources that are served from the same domain as the HTML file, or are specified as a path relative to the HTML. When resources are rewritten, their domain and path are not changed. However, the leaf-name is changed to encode rewriting information that can be used to identify and serve the optimized resource.
Configuring Server-Side Cache for mod_pagespeed
In order to rewrite resources, mod_pagespeed must cache them on the server. The output filter must be configured with paths where it can write cache files, and tuned to limit the amount of disk space consumed. The file-based cache has a built in LRU mechanism to remove old files, targeting a certain total disk space usage, and a certain interval for the cleanup process. It is also useful to have a small in-memory write-through LRU-cache that’s kept in each Apache process. Keep in mind that in pre-fork mode, Apache spawns dozens of processes, so the total memory consumed (
ModPagespeedLRUCacheKbPerProcess * num_processes) must fit into the capabilitiess of the HTTP server.
The default values are, which perform reasonably well are:
ModPagespeedFileCacheSizeKb 102400 ModPagespeedFileCacheCleanIntervalMs 3600000 ModPagespeedLRUCacheKbPerProcess 1024 ModPagespeedLRUCacheByteLimit 16384
mod_pagespeed requires a file-path for the cache. The user can use the following suggested setting:
mod_pagespeed also requires another file-path, although it’s not currently used. It’s reserved for future use as a shared database in a multi-server environment. The user can use the following suggested setting:
Configuring HTML rewriting filters
The ‘ModPagespeedEnableFilters’ configuration file directive allows specification of one or more filters by name, separated by commas. The directive may be issued multiple times, to split the filter lists logically. The order of the directives is not important: the rewriters are run in a pre-defined order, which corresponds to the order presented in the documentation.
Configuration Options for the Filters
By default mod_pagespeed uses a core set of filters that are generally safe for most web sites. To disable the core set, one can specify
and then enable specific filters with the ModPagespeedEnableFilters directive.
The core set of filters is set to:
To turn off specific filters in the core set, specify:
AND remove all ModPagespeedEnableFilters directives.To turn on specific filters not in the core set, specify:
Tuning the Filters
Once the rewriters are selected, some of them may also be tuned. These parameters control the inlining and outlining thresholds of various resources.
ModPagespeedCssInlineMaxBytes 2048 ModPagespeedImgInlineMaxBytes 2048 ModPagespeedJsInlineMaxBytes 2048 ModPagespeedOutlineThreshold 3000
mod_pagespeed requires publically cacheable resources to provide maximum benefit. As discussed in the “Cache Extender” filter, the origin TTL specified in the Apache configuration file dictates how quickly changes made to the source can propagate to users’ browser caches. However, using mod_pagespeed, resources referenced statically from HTML files will be served with a one-year cache lifetime, but with a URL that is versioned using a content hash.
The cache settings suggested above for mod_pagespeed_example also serve as our recommended starting point for ensuring that your sites’ content is cacheable, and thus rewritable by mod_pagespeed.
Turning OFF mod_pagespeed
To turn off mod_pagespeed completely, insert as the top line of pagespeed.conf:
Turning ON mod_pagespeed
To turn mod_pagespeed ON, insert as the top line of pagespeed.conf:
Trying out mod_pagespeed using mod_proxy
Ideally, you will experiment with mod_pagespeed on an Apache server that is already serving its own content. However, to experiment with mod_pagespeed on an Apache server that does not serve its own content, you can set up Apache as proxy:
# Proxy configuration file to enable mod_pagespeed to rewrite external # content. In this configuration we use assume a browser proxy, # pointing to HOSTNAME:80. LoadModule proxy_module /etc/apache2/modules/mod_proxy.so # Depends: proxy LoadModule proxy_http_module /etc/apache2/modules/mod_proxy_http.so <IfModule mod_proxy.c> ProxyRequests On ProxyVia On # limit connections to LAN clients <Proxy *> AddDefaultCharset off Order Deny,Allow Allow from all </Proxy> ProxyPreserveHost On ProxyStatus On ProxyBadHeader Ignore # Enable/disable the handling of HTTP/1.1 "Via:" headers. # ("Full" adds the server version; "Block" removes all outgoing Via: headers) # Set to one of: Off | On | Full | Block ProxyVia On </IfModule>
Set the browser proxy to point to that proxy server, and you will then be able to view any Internet site rewritten by Apache and mod_pagespeed.