You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pagespeed.apache.org by os...@apache.org on 2019/05/16 08:13:50 UTC
[incubator-pagespeed-website] 02/02: Move in
incubator-pagespeed-mod/html
This is an automated email from the ASF dual-hosted git repository.
oschaaf pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-pagespeed-website.git
commit b756aa4a73e4fe505f67597fd172716604c396b8
Author: Otto van der Schaaf <os...@we-amp.com>
AuthorDate: Thu May 16 10:13:08 2019 +0200
Move in incubator-pagespeed-mod/html
Signed-off-by: Otto van der Schaaf <os...@we-amp.com>
---
doc/.htaccess | 38 +
doc/CVE-2012-4001.html | 59 +
doc/CVE-2012-4360.html | 49 +
doc/CVE-2013-6111.html | 80 +
doc/_footer.html | 110 +
doc/_header.html | 34 +
doc/_navline.html | 22 +
doc/admin.html | 411 ++
doc/analytics_screenshots/10_histogram.png | Bin 0 -> 88271 bytes
doc/analytics_screenshots/1_login.png | Bin 0 -> 34224 bytes
.../2_import_advanced_segment.png | Bin 0 -> 19527 bytes
doc/analytics_screenshots/3_segment_settings.png | Bin 0 -> 44501 bytes
doc/analytics_screenshots/4_profile_switch.png | Bin 0 -> 27378 bytes
doc/analytics_screenshots/5_profile_switched.png | Bin 0 -> 30339 bytes
doc/analytics_screenshots/6_standard_reporting.png | Bin 0 -> 53056 bytes
doc/analytics_screenshots/7_page_timings.png | Bin 0 -> 80962 bytes
doc/analytics_screenshots/8_advanced_segments.png | Bin 0 -> 40933 bytes
doc/analytics_screenshots/9_page_level_timings.png | Bin 0 -> 55774 bytes
doc/announce-0.10.22.6.html | 68 +
doc/announce-ngx-sec-update-201310.html | 102 +
doc/announce-sec-update-201310.html | 418 ++
doc/announce-sec-update-201601.html | 123 +
doc/announce-sec-update-201603.html | 168 +
doc/build_from_source.html | 45 +
doc/build_mod_pagespeed_from_source.html | 341 ++
doc/build_ngx_pagespeed_from_source.html | 203 +
doc/config_filters.html | 1004 +++++
doc/configuration.html | 638 +++
doc/console.html | 223 +
doc/doc.css | 212 +
doc/domains.html | 1025 +++++
doc/download.html | 133 +
doc/downstream-caching.html | 521 +++
doc/experiment.html | 449 ++
doc/faq.html | 777 ++++
doc/filter-attribute-elide.html | 119 +
doc/filter-cache-extend-pdfs.html | 83 +
doc/filter-cache-extend.html | 219 +
doc/filter-canonicalize-js.html | 293 ++
doc/filter-comment-remove.html | 129 +
doc/filter-convert-meta-tags.html | 78 +
doc/filter-css-above-scripts.html | 152 +
doc/filter-css-combine.html | 216 +
doc/filter-css-inline-google-fonts.html | 162 +
doc/filter-css-inline-import.html | 112 +
doc/filter-css-inline.html | 157 +
doc/filter-css-outline.html | 182 +
doc/filter-css-rewrite.html | 215 +
doc/filter-css-to-head.html | 143 +
doc/filter-dedup-inlined-images.html | 110 +
doc/filter-domain-rewrite.html | 95 +
doc/filter-flatten-css-imports.html | 165 +
doc/filter-head-add.html | 98 +
doc/filter-head-combine.html | 141 +
doc/filter-hint-preload-subresources.html | 123 +
doc/filter-image-optimize.html | 603 +++
doc/filter-image-responsive.html | 162 +
doc/filter-image-sprite.html | 187 +
doc/filter-inline-preview-images.html | 155 +
doc/filter-insert-dns-prefetch.html | 114 +
doc/filter-insert-ga.html | 81 +
doc/filter-instrumentation-add.html | 215 +
doc/filter-js-combine.html | 147 +
doc/filter-js-defer.html | 154 +
doc/filter-js-inline.html | 168 +
doc/filter-js-minify.html | 206 +
doc/filter-js-outline.html | 167 +
doc/filter-lazyload-images.html | 180 +
doc/filter-local-storage-cache.html | 149 +
doc/filter-make-google-analytics-async.html | 171 +
doc/filter-make-show-ads-async.html | 164 +
doc/filter-pedantic.html | 92 +
doc/filter-prioritize-critical-css.html | 178 +
doc/filter-quote-remove.html | 109 +
doc/filter-rewrite-style-attributes.html | 118 +
doc/filter-source-maps-include.html | 141 +
doc/filter-strip-scripts.html | 58 +
doc/filter-trim-urls.html | 122 +
doc/filter-whitespace-collapse.html | 143 +
doc/filters.html | 158 +
doc/https_support.html | 392 ++
doc/images/admin_config.png | Bin 0 -> 6903 bytes
doc/images/downstream_caching.png | Bin 0 -> 52190 bytes
doc/images/purge_entire_cache.png | Bin 0 -> 10616 bytes
doc/images/purge_one_url.png | Bin 0 -> 10955 bytes
.../puzzle_optimized_to_low_quality_webp.webp | Bin 0 -> 25760 bytes
...imized_to_low_quality_webp_and_saved_as_png.png | Bin 0 -> 544929 bytes
doc/images/puzzle_original.jpg | Bin 0 -> 241260 bytes
doc/index.html | 131 +
doc/mailing-lists.html | 74 +
doc/mod_security.html | 81 +
doc/module-run-experiment.html | 458 ++
doc/openssl-1.0.1h-fixes.html | 71 +
doc/optimize-for-bandwidth.html | 132 +
doc/reference-image-optimize.html | 799 ++++
doc/release_notes.html | 4709 ++++++++++++++++++++
doc/restricting_urls.html | 300 ++
doc/system.html | 1343 ++++++
incubator.png | Bin 0 -> 30207 bytes
index.html | 291 ++
network-loading.png | Bin 0 -> 152825 bytes
pagespeed+nginx+apache.svg | 658 +++
102 files changed, 23826 insertions(+)
diff --git a/doc/.htaccess b/doc/.htaccess
new file mode 100644
index 0000000..38821b0
--- /dev/null
+++ b/doc/.htaccess
@@ -0,0 +1,38 @@
+# 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.
+
+# Turn on server side include processing for the header inclusion.
+AddOutputFilter INCLUDES .html
+Options +Includes
+Options +FollowSymLinks
+
+# Make /foo.html available at /foo
+RewriteEngine on
+RewriteCond %{REQUEST_FILENAME}.html -f
+RewriteRule !.*\.html$ %{REQUEST_FILENAME}.html [L]
+
+# Turn on mod_pagespeed to optimize our docs.
+ModPagespeed on
+ModPagespeedRewriteLevel CoreFilters
+ModPagespeedEnableFilters collapse_whitespace
+ModPagespeedEnableFilters remove_comments
+ModPagespeedInPlaceResourceOptimization on
+
+# Do not optimize these resources which are used for blogpost
+ModPagespeedDisallow */puzzle_optimized_to_low_quality_webp.webp
+ModPagespeedDisallow */puzzle_optimized_to_low_quality_webp_and_saved_as_png.png
+ModPagespeedDisallow */puzzle_original.jpg
diff --git a/doc/CVE-2012-4001.html b/doc/CVE-2012-4001.html
new file mode 100644
index 0000000..97be44f
--- /dev/null
+++ b/doc/CVE-2012-4001.html
@@ -0,0 +1,59 @@
+<!--
+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>mod_pagespeed Security Advisory: Insufficient Hostname Verification</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>mod_pagespeed Security Advisory: Insufficient Hostname Verification</h1>
+<dl>
+ <dt>CVE Identifier:</dt>
+ <dd>CVE-2012-4001</dd>
+ <dt>Disclosed:</dt>
+ <dd>September 12, 2012</dd>
+ <dt>Versions Affected:</dt>
+ <dd>All versions of mod_pagespeed up to and including 0.10.22.4.</dd>
+ <dt>Summary:</dt>
+ <dd>mod_pagespeed performs insufficient verification of its own host name,
+ which makes it possible to trick it into doing HTTP fetches and resource
+ processing from arbitrary host names, including potentially bypassing
+ firewalls.</dd>
+ <dt>Solution:</dt>
+ <dd>mod_pagespeed 0.10.22.6 has been released with a fix.</dd>
+ <dt>Workaround:</dt>
+ <dd>If you are unable to upgrade to the new version, you can avoid this
+ issue by changing your Apache httpd configuration. Give any virtual host
+ that enables mod_pagespeed (and the global configuration, if it also enables
+ mod_pagespeed) an accurate explicit <code>ServerName</code>, and set the
+ options <code>UseCanonicalName</code> and
+ <code>UseCanonicalPhysicalPort</code> to <code>On</code> in each. Please be
+ aware, however, that depending on the version,
+ <a href="CVE-2012-4360">CVE-2012-4360</a> may also apply.
+ </dd>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/CVE-2012-4360.html b/doc/CVE-2012-4360.html
new file mode 100644
index 0000000..ee824f3
--- /dev/null
+++ b/doc/CVE-2012-4360.html
@@ -0,0 +1,49 @@
+<!--
+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>mod_pagespeed Security Advisory: Cross-Site Scripting</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>mod_pagespeed Security Advisory: Cross-Site Scripting</h1>
+<dl>
+ <dt>CVE Identifier:</dt>
+ <dd>CVE-2012-4360</dd>
+ <dt>Disclosed:</dt>
+ <dd>September 12, 2012</dd>
+ <dt>Versions Affected:</dt>
+ <dd>mod_pagespeed versions 0.10.19.1 through 0.10.22.4 (inclusive).
+ Versions 0.9.18.6 and earlier are unaffected.</dd>
+ <dt>Summary:</dt>
+ <dd>mod_pagespeed performs insufficient escaping in some cases, which can
+ permit a hostile 3rd party to inject JavaScript running in context of
+ the site.</dd>
+ <dt>Solution:</dt>
+ <dd>mod_pagespeed 0.10.22.6 has been released with a fix.</dd>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/CVE-2013-6111.html b/doc/CVE-2013-6111.html
new file mode 100644
index 0000000..245abf6
--- /dev/null
+++ b/doc/CVE-2013-6111.html
@@ -0,0 +1,80 @@
+<!--
+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>mod_pagespeed and ngx_pagespeed Security Advisory: Cross-Site Scripting</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>mod_pagespeed and ngx_pagespeed Security Advisory: Cross-Site Scripting</h1>
+<dl>
+ <dt>CVE Identifier:</dt>
+ <dd><p>CVE-2013-6111</p></dd>
+ <dt>Disclosed:</dt>
+ <dd><p>October 28th, 2013</p></dd>
+ <dt>Versions Affected:</dt>
+ <dd>
+ <ul>
+ <li>mod_pagespeed versions earlier than 1.0</li>
+ <li>mod_pagespeed version 1.0.22.7 (fixed in 1.0.22.8)</li>
+ <li>mod_pagespeed versions 1.1</li>
+ <li>mod_pagespeed 1.2.24.1 (fixed in 1.2.24.2)</li>
+ <li>mod_pagespeed 1.3.25.1 through 1.3.25.4 (fixed in 1.3.25.5)</li>
+ <li>mod_pagespeed 1.4.26.1 through 1.4.26.4 (fixed in 1.4.26.5)</li>
+ <li>mod_pagespeed and ngx_pagespeed 1.5.27.1 through 1.5.27.3 (fixed in 1.5.27.4)</li>
+ <li>mod_pagespeed and ngx_pagespeed 1.6.29.1 through 1.6.29.6 (fixed in 1.6.29.7)</li>
+ </ul>
+ </dd>
+ <dt>Summary:</dt>
+ <dd><p>Some versions of mod_pagespeed and ngx_pagespeed are vulnerable to
+ cross-site scripting (XSS), which can permit a hostile 3rd party to
+ inject javascript running in the context of the site.</p></dd>
+ <dt>Solution:</dt>
+ <dd><p>For mod_pagespeed, update to one of versions 1.0.22.8-stable,
+ 1.2.24.2-stable, 1.3.25.5-stable, 1.4.26.5-stable, 1.5.27.4-beta, or
+ 1.6.29.7 or newer.</p>
+
+ <p>For ngx_pagespeed, update to 1.6.29.7 or newer.</p>
+ </dd>
+ <dt>Workaround:</dt>
+ <dd>
+ <p>No workaround is available for mod_pagespeed.</p>
+
+ <p>For ngx_pagespeed, you can completely prohibit access to
+ <code>/ngx_pagespeed_statistics</code>,
+ <code>/ngx_pagespeed_global_statistics</code> and
+ <code>/ngx_pagespeed_message</code> (an IP whitelist is insufficient), via
+ options similar to:
+<pre>
+location /ngx_pagespeed_global_statistics { deny all; }
+location /ngx_pagespeed_statistics { deny all; }
+location /ngx_pagespeed_message { deny all; }
+</pre>
+ </p>
+ </dd>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/_footer.html b/doc/_footer.html
new file mode 100644
index 0000000..ca41793
--- /dev/null
+++ b/doc/_footer.html
@@ -0,0 +1,110 @@
+<!--
+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.
+-->
+
+<div id=footer>
+ <!--#include virtual="_navline.html" -->
+</div>
+
+<script>
+function buildTocHelper(node, headers) {
+ if (node.nodeType == 1) {
+ // Element node.
+ var nodeName = node.nodeName.toLowerCase();
+ if (nodeName == "h2" || nodeName == "h3" || nodeName == "h4" ||
+ nodeName == "h5" || nodeName == "h6") {
+ if (node.id) {
+ headers.push([nodeName, node.innerHTML, node.id]);
+ node.appendChild(document.createTextNode("\u00A0")); // nbsp
+ var a = document.createElement("a");
+ a.class = "header-link";
+ a.href = "#" + node.id;
+ a.textContent = "\uD83D\uDD17"; // link symbol
+ node.appendChild(a);
+ }
+ } else {
+ for (var i = 0; i < node.childNodes.length; i++) {
+ buildTocHelper(node.childNodes[i], headers);
+ }
+ }
+ }
+}
+
+function buildToc() {
+ var headers = [];
+ buildTocHelper(document.body, headers);
+ if (headers.length == 0) {
+ return;
+ }
+
+ var toc = document.getElementById("toc");
+ var tocContents = document.createElement("div");
+ tocContents.id = "toc-contents";
+ tocContents.textContent = "Contents";
+ toc.appendChild(tocContents);
+
+ var level = 1;
+ var currentUl = null;
+ for (var i = 0; i < headers.length; i++) {
+ var header = headers[i];
+ var headerLevel = header[0];
+ var headerValue = header[1];
+ var headerId = header[2];
+
+ var newLevel = parseInt(headerLevel.substring(1));
+ while (newLevel > level) {
+ // We loop here to handle the case where we have h2 ... h4. This
+ // isn't a good way to write html, but someone may still do it.
+
+ var newUl = document.createElement("ul");
+ if (currentUl == null) {
+ toc.appendChild(newUl);
+ } else {
+ currentUl.appendChild(newUl);
+ }
+ currentUl = newUl;
+ level++;
+ }
+ while (newLevel < level) {
+ currentUl = currentUl.parentNode;
+ level--;
+ }
+ var li = document.createElement("li");
+ var a = document.createElement("a");
+ a.href = "#" + headerId;
+ a.textContent = headerValue;
+ li.appendChild(a);
+ currentUl.appendChild(li);
+ }
+}
+
+function wrapTables() {
+ var tables = document.getElementsByTagName("table");
+ for (var i = 0; i < tables.length; i++) {
+ var table = tables[i];
+ var parent = table.parentNode;
+ var div = document.createElement('div');
+ div.className = "table-wrapper";
+ parent.insertBefore(div, table);
+ div.appendChild(table);
+ }
+}
+
+buildToc();
+wrapTables();
+</script>
diff --git a/doc/_header.html b/doc/_header.html
new file mode 100644
index 0000000..6586f0d
--- /dev/null
+++ b/doc/_header.html
@@ -0,0 +1,34 @@
+<!--
+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.
+-->
+
+<div id=header>
+ <div id=logoline>
+ <div id=logo>
+ <img src="https://www.gstatic.com/images/branding/product/1x/pagespeed_32dp.png"
+ srcset="https://www.gstatic.com/images/branding/product/2x/pagespeed_32dp.png"
+ width=32 height=32 alt="pagespeed logo">
+ </div>
+ <div id=logotext>Apache PageSpeed (Incubating)</div>
+ </div>
+ <div id=navline>
+ <a href="/doc/">← documentation index</a>
+ </div>
+</div>
+<div id=toc></div>
+<img src="/incubator.png" height="80" align="right">
diff --git a/doc/_navline.html b/doc/_navline.html
new file mode 100644
index 0000000..8eb1431
--- /dev/null
+++ b/doc/_navline.html
@@ -0,0 +1,22 @@
+<!--
+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.
+-->
+
+<div id=navline>
+ <a href="/doc/">← documentation index</a>
+</div>
diff --git a/doc/admin.html b/doc/admin.html
new file mode 100644
index 0000000..fb85f73
--- /dev/null
+++ b/doc/admin.html
@@ -0,0 +1,411 @@
+<!--
+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 Admin Pages</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>PageSpeed Admin Pages</h1>
+<p>
+ The admin pages are a collection of features that provide visibility
+ into the operation of the PageSpeed optimizations.
+</p>
+<p>
+The pagespeed_admin and pagespeed_global_admin pages aggregate a set of pages
+showing server state so they can be accessed from a single handler. By
+organizing all these features under a single admin page, this can be done once,
+and can serve as a launching point for future administration features.
+Before <strong>version 1.9.32.1</strong> the admin pages were read-only, but
+starting in <strong>version 1.9.32.1</strong>, cache purging is supported.
+</p>
+<img src="images/admin_config.png" style="border:1px solid black" />
+<p>
+ The name of the currently active page is underlined in the top navigation bar.
+</p>
+<table>
+ <thead>
+ <tr>
+ <th>Page</th>
+ <th>Related Options</th>
+ <th>Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Statistics</td>
+ <td>
+ <a href="#statistics"><code>Statistics</code></a><br/>
+ <a href="#virtual-hosts-and-stats"
+ ><code>UsePerVHostStatistics</code></a><br/>
+ <code>mod_pagespeed_beacon</code><br/>
+ <code>ngx_pagespeed_beacon</code>
+ </td>
+ <td>
+ Shows server statistics since startup, such as how many
+ resources are being optimized by filters, as well as various
+ latency and cache effectiveness metrics.
+ </td>
+ </tr>
+ <tr>
+ <td>Configuration</td>
+ <td><a href="config_filters">Configuring Filters</a><br/>
+ <a href="https_support#spdy_configuration"
+ ><code>ModPagespeedIf</code></a> (Apache only)</td>
+ <td>
+ Shows detailed configuration information including all filters,
+ options, and the current cache flush timestamp.
+ </td>
+ </tr>
+ <tr>
+ <td>Histograms</td>
+ <td>
+ <a href="filter-instrumentation-add"
+ ><code>add_instrumentation</code></a><br/>
+ </td>
+ <td>
+ Shows detailed latency data for Page Load Time, rewriting,
+ caches and HTTP fetching.
+ </td>
+ </tr>
+ <tr>
+ <td>Caches</td>
+ <td>
+ <a href="system#memcached"><code>MemcachedServers</code></a>
+ <a href="system#shm_cache"><code>CreateSharedMemoryMetadataCache</code></a>
+ <a href="system#purge_cache"><code>EnableCachePurge</code></a>
+ </td>
+ <td>
+ Shows detailed cache configuration information. When accessed
+ from the Admin handler, it can be used to inspect the contents
+ of the cache, and provides an interface to purge the cache.
+ </td>
+ </tr>
+ <tr>
+ <td>Console</td>
+ <td>
+ <a href="admin#statistics"><code>Statistics</code></a><br/>
+ <a href="console#configuring"><code>StatisticsLogging</code></a><br/>
+ <a href="console#configuring"><code>LogDir</code></a>
+ </td>
+ <td>
+ Displays a <a href="console">console</a> of graphs
+ of server optimization behavior over time.
+ </td>
+ </tr>
+ <tr>
+ <td>Message History</td>
+ <td>
+ <a href="#message-buffer-size"><code>MessageBufferSize</code></a>
+ </td>
+ <td>
+ Server-wide history of recent logging output from PageSpeed,
+ including messages that are omitted from the server log file based on
+ its log level.
+ </td>
+ </tr>
+ </tbody>
+</table>
+<p>
+ Before 1.8.31.2, the main admin page is not available, but there
+ are page-specific handlers for statistics, messages, and the
+ console. In 1.8.31.2 and later, the <code>*_pagespeed_*</code> handlers, such
+ as <code>mod_pagespeed_statistics</code>, will continue to be supported:
+<ul>
+ <li>They provide read-only access to server operation. There may
+ be cases where a site owner wants to share statistics or console
+ information but not the ability to purge the cache.</li>
+ <li>Existing configurations must continue to work after an upgrade to
+ a release that supports pagespeed_admin.</li>
+ <li>The admin pages may later gain support for modifying the server
+ state</li>
+</ul>
+</p>
+<h2 id="config">Configuring Admin Pages</h2>
+
+<p>
+ In this table we use the term "server" for an Apache VirtualHost and
+ an nginx Server Block. We use the term "global" to mean the entire
+ Apache or nginx system, covering all the configured VirtualHost and
+ Server Blocks.
+</p>
+<table>
+ <thead>
+ <tr><th>Apache Handler</th><th>Nginx Option</th><th>Version</th>
+ <th>Description</th></tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>pagespeed_admin</code></td>
+ <td><code>AdminPath</code></td>
+ <td>1.8.31.2+</td><td>Covers all administrative functions for
+ a host in one handler. If you establish this handler,
+ you don't need any of the other server-scoped methods. Only
+ give 'admin' page access to clients that you are comfortable
+ allowing to modify the state of your PageSpeed configuration.
+ </td>
+ </tr>
+ <tr>
+ <td><code>pagespeed_global_admin</code></td>
+ <td><code>GlobalAdminPath</code></td>
+ <td>1.8.31.2+</td><td>Covers all administrative functions for
+ the entire global state in one handler. If you establish this
+ handler, you don't
+ need <code>mod_pagespeed_global_statistics</code>.</td>
+ </tr>
+ <tr>
+ <td><code>mod_pagespeed_statistics</code></td>
+ <td><code>StatisticsPath</code> (1.8.31.2+)</td>
+ <td>All</td><td>Launchpad for Statistics, Histograms, and
+ a subset of the Caches page as described above.</td>
+ </tr>
+ <tr>
+ <td><code>mod_pagespeed_global_statistics</code></td>
+ <td><code>GlobalStatisticsPath</code> (1.8.31.2+)</td>
+ <td>1.1+</td><td>Same as above, but aggregates statistics across all
+ configured servers. You must enable
+ <a href="#virtual-hosts-and-stats"
+ ><code>UsePerVHostStatistics</code></a> for separate global
+ statistics to be retained, otherwise all statistics will be global.</td>
+ </tr>
+ <tr>
+ <td><code>mod_pagespeed_message</code></td>
+ <td><code>MessagesPath</code> (1.8.31.2+)</td>
+ <td>1.0+</td><td>Displays recent log messages printed by PageSpeed,
+ including messages that may be below the current server loglevel
+ threshold such as "Info" messages. Requires that
+ <a href="#message-buffer-size"><code>MessageBufferSize</code></a> be set.</td>
+ </tr>
+ <tr>
+ <td><code>pagespeed_console</code></td>
+ <td><code>ConsolePath</code> (1.8.31.2+)</td>
+ <td>1.6+</td><td>Displays a <a href="console">console</a> of graphs
+ of server optimization behavior over time.</td>
+ </tr>
+ </tbody>
+</table>
+
+<h3 id="handlers">Establishing Handlers in Apache</h2>
+<p>
+ Each handler is optional; add them individually to enable
+ admin features. Note that when you add handlers for
+ <code>pagespeed_admin</code> and <code>pagespeed_global_admin</code>
+ you are granting read/write access to server-state. The other handlers
+ are read-only. A sample handler that filters on IP address is
+ in the default configuration, whose general form is:
+</p>
+<pre class="prettyprint lang-sh">
+<Location /PATH>
+ Order allow,deny
+ Allow from localhost
+ Allow from 127.0.0.1
+ SetHandler HANDLER_NAME
+</Location>
+</pre>
+<p>
+ You can choose any path for a handler, but you must specify the handler
+ name exactly as it appears in the table above. By convention we use
+ use the handler name for the path. You may also want to
+ employ login-based access to the admin pages, using
+ <code>AllowOverride AuthConfig</code>. Please see the Apache
+ <a href="http://httpd.apache.org/docs/2.2/howto/auth.html">2.2</a>
+ or
+ <a href="http://httpd.apache.org/docs/2.4/howto/auth.html">2.4</a>
+ Documentation for details.
+</p>
+<h3 id="handlers">Establishing Handlers in Nginx</h2>
+<p>
+ In nginx, the handlers must be specified as location blocks.
+</p>
+<pre class="prettyprint lang-sh">
+location /ngx_pagespeed_statistics { allow 127.0.0.1; deny all; }
+location /ngx_pagespeed_global_statistics { allow 127.0.0.1; deny all; }
+location /ngx_pagespeed_message { allow 127.0.0.1; deny all; }
+location /pagespeed_console { allow 127.0.0.1; deny all; }
+location ~ ^/pagespeed_admin { allow 127.0.0.1; deny all; }
+location ~ ^/pagespeed_global_admin { allow 127.0.0.1; deny all; }
+</pre>
+<p class="note">
+ Note that these handlers must precede the
+ "<code>\.pagespeed\.([a-z]\.)?[a-z]{2}\.[^.]{10}\.[^.]+</code>" location block.
+</p>
+<p>
+ In version 1.8.31.2 and later, the above location blocks are
+ needed for each path you elect to enable in PageSpeed options:
+</p>
+<pre>
+pagespeed StatisticsPath /ngx_pagespeed_statistics;
+pagespeed GlobalStatisticsPath /ngx_pagespeed_global_statistics;
+pagespeed MessagesPath /ngx_pagespeed_message;
+pagespeed ConsolePath /pagespeed_console;
+pagespeed AdminPath /pagespeed_admin;
+pagespeed GlobalAdminPath /pagespeed_global_admin;
+</pre>
+<p>
+ You can choose any path, as long as it's consistent between
+ the <code>pagespeed Path</code> and the <code>location</code>. By
+ convention we use the names as specified in the example.
+</p>
+<p>
+ Prior to version 1.8.31.2, the above "Path" settings do not exist,
+ and the failure to specify location blocks leaves the paths active
+ with no access restrictions. The module will service requests
+ to the paths whether the location blocks are specified or not.
+ This applies to <code>/ngx_pagespeed_statistics</code>,
+ <code>/ngx_pagespeed_global_statistics</code>,
+ <code>/ngx_pagespeed_message</code>, and <code>/pagespeed_console</code>.
+</p>
+<p class="note">
+ If you define access control for <code>/pagespeed_admin</code> or
+ <code>/pagespeed_console</code>, you must do so earlier in the configuration
+ file than the path to handle <code>.pagespeed</code> resources, to ensure
+ that the handlers are disambiguated.
+</p>
+<h3 id="limiting-handlers">Limiting Handler Access</h3>
+<p class="note"><strong>Note: New feature as of 1.10.33.0</strong></p>
+<p>
+ Apache's SetHandler access controls are accessible to anyone who can
+ modify <code>.htaccess</code> files, so in a typical shared hosting context
+ the global admin site isn't sufficiently protected. As of 1.10.33.0,
+ PageSpeed allows setting an additional restriction of what domains are allowed
+ to load handlers. For example, to deny access entirely, you could put:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+>ModPagespeedStatisticsDomains Disallow *
+ModPagespeedGlobalStatisticsDomains Disallow *
+ModPagespeedMessagesDomains Disallow *
+ModPagespeedConsoleDomains Disallow *
+ModPagespeedAdminDomains Disallow *
+ModPagespeedGlobalAdminDomains Disallow *</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+>pagespeed StatisticsDomains Disallow *;
+pagespeed GlobalStatisticsDomains Disallow *;
+pagespeed MessagesDomains Disallow *;
+pagespeed ConsoleDomains Disallow *;
+pagespeed AdminDomains Disallow *;
+pagespeed GlobalAdminDomains Disallow *;</pre>
+</dl>
+<p>
+ To allow access only to an admin, define a new VHost
+ like <code>admin.example.com</code>, use standard web-server access control
+ (IP or password) to restrict access to only that admin, and then at the top
+ level of your config put:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+>ModPagespeedStatisticsDomains Allow admin.example.com
+ModPagespeedGlobalStatisticsDomains Allow admin.example.com
+ModPagespeedMessagesDomains Allow admin.example.com
+ModPagespeedConsoleDomains Allow admin.example.com
+ModPagespeedAdminDomains Allow admin.example.com
+ModPagespeedGlobalAdminDomains Allow admin.example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+>pagespeed StatisticsDomains Allow admin.example.com;
+pagespeed GlobalStatisticsDomains Allow admin.example.com;
+pagespeed MessagesDomains Allow admin.example.com;
+pagespeed ConsoleDomains Allow admin.example.com;
+pagespeed AdminDomains Allow admin.example.com;
+pagespeed GlobalAdminDomains Allow admin.example.com;</pre>
+</dl>
+<p>
+ Now when you visit <code>admin.example.com/pagespeed_global_admin</code>
+ you'll see global (server-level) admin information, but users are not able to
+ access this under their own domain or turn the handler on
+ with <code>.htaccess</code>.
+</p>
+<p>
+ For all six of these options the default value is <code>Allow *</code>. If
+ you explicitly <code>Allow</code> access to any site, all others are
+ automatically <code>Disallow</code>ed. Wildcards are allowed, and additional
+ directives are applied in sequence. For example, consider the following
+ config:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+>ModPagespeedAdminDomains Allow *.example.*
+ModPagespeedAdminDomains Disallow *.example.org
+ModPagespeedAdminDomains Allow www.example.org</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+>pagespeed AdminDomains Allow *.example.*;
+pagespeed AdminDomains Disallow *.example.org;
+pagespeed AdminDomains Allow www.example.org;</pre>
+</dl>
+<p>
+ This would allow access to <code>www.example.com/pagespeed_admin</code>,
+ and <code>www.example.org/pagespeed_admin</code> but
+ not <code>shared.example.com/pagespeed_admin</code>.
+</p>
+
+<h3 id="statistics">Shared Memory Statistics</h2>
+<p>
+ By default PageSpeed collects cross-process statistics. While
+ they're mostly intended for debugging and evaluation
+ using <code>/mod_pagespeed_statistics</code>, <code>/ngx_pagespeed_statistics</code>,
+ and the <a href="console">PageSpeed Console</a>, statistics are also
+ necessary for limiting concurrent image rewrites
+ and <a href="#rate_limit_background_fetches">background fetches</a>.
+ It's not recommended to turn them off, as their performance impact
+ is minimal, but if you need to you can do so with:
+ <dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedStatistics off</pre></dd></dt>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed Statistics off;</pre></dd></dt>
+ </dl>
+</p>
+<h3 id="virtual-hosts-and-stats">Virtual hosts and statistics</h3>
+<p>
+ You can choose whether PageSpeed aggregates its statistics
+ over all virtual hosts (the default), or to keeps separate counts for each. You
+ can chose the latter by specifying
+ <code>UsePerVHostStatistics on</code>. In that
+ case, <code>/pagespeed_admin</code>, <code>/mod_pagespeed_statistics</code>
+ and <code>/ngx_pagespeed_statistics</code> will show the data for
+ whatever virtual host is being accessed. If you do turn per-virtual
+ host statistics on, you can still access the aggregates
+ under <code>/pagespeed_global_admin</code>, <code>/mod_pagespeed_global_statistics</code>
+ or <code>/ngx_pagespeed_global_statistics</code>.
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeedUsePerVhostStatistics on</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">pagespeed UsePerVhostStatistics on;</pre>
+</dl>
+
+<h3 id="message-buffer-size">Message Buffer Size</h3>
+<p>
+ Determines the number of bytes of shared memory to allocate as a circular
+ buffer for holding recent PageSpeed log messages. By default, the size of
+ this buffer is zero, and no messages will be retained.
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeedMessageBufferSize 100000</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">pagespeed MessageBufferSize 100000;</pre>
+</dl>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/analytics_screenshots/10_histogram.png b/doc/analytics_screenshots/10_histogram.png
new file mode 100644
index 0000000..da2d198
Binary files /dev/null and b/doc/analytics_screenshots/10_histogram.png differ
diff --git a/doc/analytics_screenshots/1_login.png b/doc/analytics_screenshots/1_login.png
new file mode 100644
index 0000000..04b6eb5
Binary files /dev/null and b/doc/analytics_screenshots/1_login.png differ
diff --git a/doc/analytics_screenshots/2_import_advanced_segment.png b/doc/analytics_screenshots/2_import_advanced_segment.png
new file mode 100644
index 0000000..9c17a2e
Binary files /dev/null and b/doc/analytics_screenshots/2_import_advanced_segment.png differ
diff --git a/doc/analytics_screenshots/3_segment_settings.png b/doc/analytics_screenshots/3_segment_settings.png
new file mode 100644
index 0000000..32c6f4e
Binary files /dev/null and b/doc/analytics_screenshots/3_segment_settings.png differ
diff --git a/doc/analytics_screenshots/4_profile_switch.png b/doc/analytics_screenshots/4_profile_switch.png
new file mode 100644
index 0000000..21af28f
Binary files /dev/null and b/doc/analytics_screenshots/4_profile_switch.png differ
diff --git a/doc/analytics_screenshots/5_profile_switched.png b/doc/analytics_screenshots/5_profile_switched.png
new file mode 100644
index 0000000..6cd9a12
Binary files /dev/null and b/doc/analytics_screenshots/5_profile_switched.png differ
diff --git a/doc/analytics_screenshots/6_standard_reporting.png b/doc/analytics_screenshots/6_standard_reporting.png
new file mode 100644
index 0000000..6818301
Binary files /dev/null and b/doc/analytics_screenshots/6_standard_reporting.png differ
diff --git a/doc/analytics_screenshots/7_page_timings.png b/doc/analytics_screenshots/7_page_timings.png
new file mode 100644
index 0000000..754c7ae
Binary files /dev/null and b/doc/analytics_screenshots/7_page_timings.png differ
diff --git a/doc/analytics_screenshots/8_advanced_segments.png b/doc/analytics_screenshots/8_advanced_segments.png
new file mode 100644
index 0000000..c45fb81
Binary files /dev/null and b/doc/analytics_screenshots/8_advanced_segments.png differ
diff --git a/doc/analytics_screenshots/9_page_level_timings.png b/doc/analytics_screenshots/9_page_level_timings.png
new file mode 100644
index 0000000..2922739
Binary files /dev/null and b/doc/analytics_screenshots/9_page_level_timings.png differ
diff --git a/doc/announce-0.10.22.6.html b/doc/announce-0.10.22.6.html
new file mode 100644
index 0000000..56c9595
--- /dev/null
+++ b/doc/announce-0.10.22.6.html
@@ -0,0 +1,68 @@
+<!--
+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>mod_pagespeed 0.10.22.6 Security Update.</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>mod_pagespeed 0.10.22.6 Security Update.</h1>
+<h2 id="overview">Overview</h2>
+mod_pagespeed 0.10.22.6 is a security update that fixes two critical issues
+that affect earlier versions:
+<ul>
+<li><a href="CVE-2012-4001">CVE-2012-4001</a>, a problem with validation of
+own host name.
+</li>
+<li><a href="CVE-2012-4360">CVE-2012-4360</a>, a cross-site scripting
+ attack, which affects versions starting from 0.10.19.1.
+</li>
+</ul>
+
+<p> The effect of the first problem is that it is possible to confuse
+mod_pagespeed about its own host name, and to trick it into fetching resources
+from other machines. This could be an issue if the HTTP server has access to
+machines that are not otherwise publicly visible.
+
+<p> The second problem would permit a hostile third party to execute JavaScript
+in users' browsers in context of the domain running mod_pagespeed, which
+could permit interception of users' cookies or data on the site.
+
+<p> Because of the severity of the two problems, users are <strong>strongly
+</strong> encouraged to update immediately.
+</p>
+
+<h2 id="behavior_changes">Behavior Changes in the Update</h2>
+As part of the fix to the first issue, mod_pagespeed will not fetch
+resources from machines other than <code>localhost</code> if they are not
+explicitly mentioned in the configuration. This means that if you need
+resources on the server's domain to be handled by some other system, you'll
+need to explicitly use <code>ModPagespeedMapOriginDomain</code> or
+<code>ModPagespeedDomain</code> to authorize that.
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/announce-ngx-sec-update-201310.html b/doc/announce-ngx-sec-update-201310.html
new file mode 100644
index 0000000..9d8d0f7
--- /dev/null
+++ b/doc/announce-ngx-sec-update-201310.html
@@ -0,0 +1,102 @@
+<!--
+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>October 2013 ngx_pagespeed Security Update.</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>October 2013 ngx_pagespeed Security Update.</h1>
+<h2 id="overview">Overview</h2>
+
+<p>
+All versions of ngx_pagespeed prior to 1.6.29.7 are subject to critical
+cross-site scripting (XSS) vulnerability CVE-2013-6111. Depending on
+configuration this may permit a hostile third party to execute JavaScript in
+users' browsers in the context of the domain running ngx_pagespeed, which could
+permit theft of users' cookies or data on the site.
+</p>
+
+<p>
+Because of the severity of the problem, users of affected versions are
+<strong>strongly</strong> encouraged to <strong>immediately</strong> update
+ngx_pagespeed or apply the workaround below.
+</p>
+
+<p>
+To be notified of further security updates subscribe to the
+<a href="mailing-lists#announcements">announcements mailing list</a>.
+</p>
+
+<h2 id="solutions">Solutions</h2>
+
+<p>
+Users of affected versions should either apply the workaround or update to
+version 1.6.29.7 or later.
+</p>
+
+<h3 id="workaround">Workaround</h3>
+
+<p>
+The vulnerability requires access to <code>/ngx_pagespeed_statistics</code>,
+<code>/ngx_pagespeed_global_statistics</code>, or
+<code>/ngx_pagespeed_message</code>. Prohibiting access to these in
+your <code>nginx.conf</code> is sufficient to keep it from being exploited.
+Note that it is not enough to restrict these pages to trusted users; they must
+not be accessible to anyone. Example workaround configuration:
+<pre>
+location /ngx_pagespeed_statistics { deny all; }
+location /ngx_pagespeed_global_statistics { deny all; }
+location /ngx_pagespeed_message { deny all; }
+</pre>
+</p>
+
+<p>
+While ngx_pagespeed and mod_pagespeed are very similar, this workaround is not
+sufficient for mod_pagespeed. If you also run PageSpeed in Apache please follow
+the recommendations in the <a href="announce-sec-update-201310">October 2013
+mod_pagespeed Security Update</a>.
+</p>
+
+<h3 id="update">Update</h3>
+
+<p>
+Users unable to apply the workaround, or who want continued access to the
+informational data provided by <code>/ngx_pagespeed_statistics</code>
+or <code>/ngx_pagespeed_message</code> should update to an unaffected version.
+This requires building nginx with the updated ngx_pagespeed module and
+installing it in place of the current version. See
+the <a href="https://github.com/apache/incubator-pagespeed-ngx#how-to-build">build
+instructions</a>.
+</p>
+
+<p>
+Users having difficulty applying these updates or with other questions should
+write to the <a href="mailing-lists#discussion">discussion group</a>.
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/announce-sec-update-201310.html b/doc/announce-sec-update-201310.html
new file mode 100644
index 0000000..8feaef3
--- /dev/null
+++ b/doc/announce-sec-update-201310.html
@@ -0,0 +1,418 @@
+<!--
+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>October 2013 mod_pagespeed Security Update.</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>October 2013 mod_pagespeed Security Update.</h1>
+<h2 id="overview">Overview</h2>
+<p>Various versions of mod_pagespeed are subject to critical
+cross-site scripting (XSS) vulnerability, CVE-2013-6111. This permits a hostile
+third party to execute JavaScript in users' browsers in context of the domain
+running mod_pagespeed, which could permit theft of users' cookies or data
+on the site. </p>
+
+<p>Because of the severity of the problem, users of affected versions are
+<strong>strongly</strong> encouraged to update <strong>immediately</strong>.
+</p>
+
+<p>To be notified of further security updates subscribe to the
+<a href="mailing-lists#announcements">announcements mailing list</a>.
+
+<h2 id="affected">Affected versions</h2>
+<ul>
+ <li>Versions earlier than 1.0.</li>
+ <li>1.0.22.7 (fixed in 1.0.22.8).</li>
+ <li>All 1.1 versions</li>
+ <li>1.2.24.1 (fixed in 1.2.24.2)</li>
+ <li>1.3.25.1 – 1.3.25.4 (fixed in 1.3.25.5)</li>
+ <li>1.4.26.1 – 1.4.26.4 (fixed in 1.4.26.5)</li>
+ <li>1.5.27.1 – 1.5.27.3 (fixed in 1.5.27.4)</li>
+ <li>1.6.29.1 – 1.6.29.6 (fixed in 1.6.29.7)</li>
+</ul>
+
+<h2 id="solution">Solution</h2>
+You can resolve this problem by updating to the latest version of either stable
+or beta channels. If for some reason you are unable to update to a new version,
+patched versions to resolve the vulnerability are also available for releases
+1.0 as well as 1.2 through 1.6.
+
+<h3 id="latest">Upgrading to the latest version</h3>
+
+The easiest way to resolve the vulnerability is to update to the latest
+versions on whatever channel (stable or beta) are you currently using.
+
+<p>If you installed the .rpm package, you can update with:
+<pre>
+sudo yum update
+sudo /etc/init.d/httpd restart
+</pre>
+
+<p>If you installed the .deb package, you can update with:
+<pre>
+sudo apt-get update
+sudo apt-get upgrade
+sudo /etc/init.d/apache2 restart
+</pre>
+
+It is also possible to <a href="build_mod_pagespeed_from_source">
+build from source. </a>
+
+<h3 id="10">Updating while keeping version 1.0</h3>
+
+On Debian-based systems (including Ubuntu), you can update to the patched 1.0
+version by running:
+<pre>
+sudo apt-get update
+sudo apt-get install mod-pagespeed-stable=1.0.22.8-r3546
+</pre>
+
+On RPM based systems that use the <code>yum</code> command, you can update
+from older versions by using:
+<pre>
+yum install mod-pagespeed-stable-1.0.22.8
+</pre>
+<p>Note that this command will not switch you to a lower version number
+(for example, it will not switch from a 1.2 version with the vulnerability to
+a fixed version of 1.0); it is recommended that you resolve this security
+vulnerability by upgrading to the patched release of whatever version you are
+currently using, or the latest beta or stable version.</p>
+
+<p>You can also download binaries directly:
+<table>
+ <tr>
+ <td colspan=2 width="50%">
+ Debian/Ubuntu
+ </td>
+ <td colspan=2 width="50%">
+ CentOS/Fedora
+ </td>
+ <tr>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.0.22.8-r3546_i386.deb">
+ 32-bit .deb
+ </a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.0.22.8-r3546_i386.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.0.22.8-r3546_amd64.deb">
+ 64-bit .deb</a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.0.22.8-r3546_amd64.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/i386/mod-pagespeed-stable-1.0.22.8-3546.i386.rpm">
+ 32-bit .rpm</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/x86_64/mod-pagespeed-stable-1.0.22.8-3546.x86_64.rpm">
+ 64-bit .rpm</a>
+ </td>
+ </tr>
+</table>
+
+
+<h3 id="12">Updating while keeping version 1.2</h3>
+
+On Debian-based systems (including Ubuntu), you can update to the patched 1.2
+version by running:
+<pre>
+sudo apt-get update
+sudo apt-get install mod-pagespeed-stable=1.2.24.2-r3534
+</pre>
+
+On RPM based systems that use the <code>yum</code> command, you can update from
+older versions by using:
+<pre>
+yum install mod-pagespeed-stable-1.2.24.2
+</pre>
+<p> Note that this command will not switch you to a lower version number
+(for example, it will not switch from a 1.3 version with the vulnerability to
+a fixed version of 1.2); it is recommended that you resolve this security
+vulnerability by upgrading to the patched release of whatever version you are
+currently using, or the latest beta or stable version.</p>
+
+<p>You can also download binaries directly:
+<table>
+ <tr>
+ <td colspan=2 width="50%">
+ Debian/Ubuntu
+ </td>
+ <td colspan=2 width="50%">
+ CentOS/Fedora
+ </td>
+ <tr>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.2.24.2-r3534_i386.deb">
+ 32-bit .deb
+ </a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.2.24.2-r3534_i386.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.2.24.2-r3534_amd64.deb">
+ 64-bit .deb</a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.2.24.2-r3534_amd64.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/i386/mod-pagespeed-stable-1.2.24.2-3534.i386.rpm">
+ 32-bit .rpm</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/x86_64/mod-pagespeed-stable-1.2.24.2-3534.x86_64.rpm">
+ 64-bit .rpm</a>
+ </td>
+ </tr>
+</table>
+
+
+<h3 id="13">Updating while keeping version 1.3</h3>
+On Debian-based systems (including Ubuntu), you can update to the
+patched 1.3 version by running:
+<pre>
+sudo apt-get update
+sudo apt-get install mod-pagespeed-stable=1.3.25.5-r3534
+</pre>
+
+On RPM based systems that use the <code>yum</code> command, you can update from
+older versions by using:
+<pre>
+yum install mod-pagespeed-stable-1.3.25.5
+</pre>
+<p>Note that this command will not switch you to a lower version number
+(for example, it will not switch from a 1.4 version with the vulnerability to
+a fixed version of 1.3); it is recommended that you resolve this security
+vulnerability by upgrading to the patched release of whatever version you are
+currently using, or the latest beta or stable version.</p>
+
+<p>You can also download binaries directly:
+<table>
+ <tr>
+ <td colspan=2 width="50%">
+ Debian/Ubuntu
+ </td>
+ <td colspan=2 width="50%">
+ CentOS/Fedora
+ </td>
+ <tr>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.3.25.5-r3534_i386.deb">
+ 32-bit .deb
+ </a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.3.25.5-r3534_i386.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.3.25.5-r3534_amd64.deb">
+ 64-bit .deb</a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.3.25.5-r3534_amd64.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/i386/mod-pagespeed-stable-1.3.25.5-3534.i386.rpm">
+ 32-bit .rpm</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/x86_64/mod-pagespeed-stable-1.3.25.5-3534.x86_64.rpm">
+ 64-bit .rpm</a>
+ </td>
+ </tr>
+</table>
+
+<h3 id="14">Updating while keeping version 1.4</h3>
+As of October 2013, 1.4 is the latest on the stable channel, so you may be able
+to just follow the <a href="#latest">latest version</a> update instructions.
+
+<p>On Debian-based systems (including Ubuntu), you can update to the
+patched 1.4 version by running:
+<pre>
+sudo apt-get update
+sudo apt-get install mod-pagespeed-stable=1.4.26.5-r3533
+</pre>
+
+On RPM based systems that use the <code>yum</code> command, you can update from
+older versions by using:
+<pre>
+yum install mod-pagespeed-stable-1.4.26.5
+</pre>
+<p>Note that this command will not switch you to a lower version number
+(for example, it will not switch from a 1.5 version with the vulnerability to
+a fixed version of 1.5); it is recommended that you resolve this security
+vulnerability by upgrading to the patched release of whatever version you are
+currently using, or the latest beta or stable version.</p>
+
+<p>You can also download binaries directly:
+<table>
+ <tr>
+ <td colspan=2 width="50%">
+ Debian/Ubuntu
+ </td>
+ <td colspan=2 width="50%">
+ CentOS/Fedora
+ </td>
+ <tr>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.4.26.5-r3533_i386.deb">
+ 32-bit .deb
+ </a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.4.26.5-r3533_i386.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.4.26.5-r3533_amd64.deb">
+ 64-bit .deb</a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.4.26.5-r3533_amd64.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/i386/mod-pagespeed-stable-1.4.26.5-3533.i386.rpm">
+ 32-bit .rpm</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/x86_64/mod-pagespeed-stable-1.4.26.5-3533.x86_64.rpm">
+ 64-bit .rpm</a>
+ </td>
+ </tr>
+</table>
+
+
+<h3 id="15">Updating while keeping version 1.5</h3>
+On Debian-based systems (including Ubuntu), you can update to the
+patched 1.5 version by running:
+<pre>
+sudo apt-get update
+sudo apt-get install mod-pagespeed-beta=1.5.27.4-r3533
+</pre>
+
+On RPM based systems that use the <code>yum</code> command, you can update from
+older versions by using:
+<pre>
+yum install mod-pagespeed-beta-1.5.27.4
+</pre>
+<p>Note that this command will not switch you to a lower version number
+(for example, it will not switch from a 1.6 version with the vulnerability to
+a fixed version of 1.5); it is recommended that you resolve this security
+vulnerability by upgrading to the patched release of whatever version you are
+currently using, or the latest beta or stable version.</p>
+
+<p>You can also download binaries directly:
+<table>
+ <tr>
+ <td colspan=2 width="50%">
+ Debian/Ubuntu
+ </td>
+ <td colspan=2 width="50%">
+ CentOS/Fedora
+ </td>
+ <tr>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-beta/mod-pagespeed-beta_1.5.27.4-r3533_i386.deb">
+ 32-bit .deb
+ </a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-beta/mod-pagespeed-beta_1.5.27.4-r3533_i386.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-beta/mod-pagespeed-beta_1.5.27.4-r3533_amd64.deb">
+ 64-bit .deb</a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-beta/mod-pagespeed-beta_1.5.27.4-r3533_amd64.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/i386/mod-pagespeed-beta-1.5.27.4-3533.i386.rpm">
+ 32-bit .rpm</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/x86_64/mod-pagespeed-beta-1.5.27.4-3533.x86_64.rpm">
+ 64-bit .rpm</a>
+ </td>
+ </tr>
+</table>
+
+
+<h3 id="16">Updating while keeping version 1.6</h3>
+As of October 2013, 1.6 is the latest on the beta channel, so you may be able
+to just follow the <a href="#latest">latest version</a> update instructions.
+
+<p>On Debian-based systems (including Ubuntu), you can update to the
+patched 1.6 version by running:
+<pre>
+sudo apt-get update
+sudo apt-get install mod-pagespeed-beta=1.6.29.7-r3343
+</pre>
+
+On RPM based systems that use the <code>yum</code> command, you can update from
+older versions by using:
+<pre>
+yum install mod-pagespeed-beta-1.6.29.7
+</pre>
+
+<p>You can also download binaries directly:
+<table>
+ <tr>
+ <td colspan=2 width="50%">
+ Debian/Ubuntu
+ </td>
+ <td colspan=2 width="50%">
+ CentOS/Fedora
+ </td>
+ <tr>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-beta/mod-pagespeed-beta_1.6.29.7-r3343_i386.deb">
+ 32-bit .deb
+ </a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-beta/mod-pagespeed-beta_1.6.29.7-r3343_i386.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-beta/mod-pagespeed-beta_1.6.29.7-r3343_amd64.deb">
+ 64-bit .deb</a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-beta/mod-pagespeed-beta_1.6.29.7-r3343_amd64.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/i386/mod-pagespeed-beta-1.6.29.7-3343.i386.rpm">
+ 32-bit .rpm</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/x86_64/mod-pagespeed-beta-1.6.29.7-3343.x86_64.rpm">
+ 64-bit .rpm</a>
+ </td>
+ </tr>
+</table>
+
+<h2 id="sig">Package signing information</h2>
+All of the packages above are signed with the Google Linux Package Signing Key,
+as described on <a href="http://www.google.com/linuxrepositories/">
+http://www.google.com/linuxrepositories/</a>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/announce-sec-update-201601.html b/doc/announce-sec-update-201601.html
new file mode 100644
index 0000000..78f2798
--- /dev/null
+++ b/doc/announce-sec-update-201601.html
@@ -0,0 +1,123 @@
+<!--
+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>January 2016 PageSpeed Security Update.</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>January 2016 PageSpeed Security Update.</h1>
+<h2 id="overview">Overview</h2>
+<p>All released versions of PageSpeed are subject to HTTPS-fetching
+vulnerability, CVE-2016-2092. This permits a hostile third party who can
+man-in-the-middle the connection between PageSpeed and an HTTPS server to
+substitute arbitrary content in responses. This could allow the attacker to
+execute JavaScript in users' browsers in context of the domain running
+PageSpeed, which could permit theft of users' cookies or data on the site.
+</p>
+
+<p>To be notified of further security updates subscribe to the
+<a href="mailing-lists#announcements">announcements mailing list</a>.
+
+<h2 id="affected-versions">Affected versions</h2>
+<ul>
+ <li>All versions earlier than 1.9.</li>
+ <li>Versions 1.9.32.0 – 1.9.33.12 (fixed in 1.9.32.13).</li>
+ <li>Versions 1.10.33.0 – 1.10.33.3 (fixed in 1.10.33.4).</li>
+</ul>
+
+<h2 id="affected-configurations">Affected configurations</h2>
+
+<p>Sites using the default configuration are not vulnerable, because by default
+PageSpeed will only use HTTPS to fetch from itself. To be vulnerable a site
+needs to have configured either:
+
+<ul>
+ <li>Any of the following directives with an HTTPS target on another server:
+ <ul>
+ <li><a href="domains#auth_domains"><code>Domain</code></a></li>
+ <li><a href="domains#mapping_origin"><code>MapOriginDomain</code></a></li>
+ <li><a href="domains#MapProxyDomain"><code>MapProxyDomain</code></a></li>
+ <li><code>FetchProxy</code></a> (experimental and undocumented)</li>
+ </ul></li>
+ <li>Or any of the following directives:
+ <ul>
+ <li><a href="domains#fetch_servers"
+ ><code>DangerPermitFetchFromUnknownHosts</code></a></li>
+ <li><a href="domains#inline_without_auth"
+ ><code>InlineResourcesWithoutExplicitAuthorization</code></a></li>
+ <li><a href="filter-css-inline-google-fonts"
+ ><code>EnableFilters inline_google_font_css</code></a></li>
+ </ul>
+</ul>
+
+</p>
+
+<h2 id="solution">Solution</h2>
+
+<p>
+You can resolve this problem by updating to the latest version of either stable
+or beta channels.
+</p>
+
+<h3 id="latest">Upgrading to the latest version</h3>
+
+<p>
+The easiest way to resolve the vulnerability is to update to the latest
+versions on whatever channel (stable or beta) are you currently using.
+</p>
+
+<p>If you installed the .rpm package, you can update with:
+<pre>
+sudo yum update
+sudo /etc/init.d/httpd restart
+</pre>
+
+<p>If you installed the .deb package, you can update with:
+<pre>
+sudo apt-get update
+sudo apt-get upgrade
+sudo /etc/init.d/apache2 restart
+</pre>
+
+It is also possible to <a href="build_mod_pagespeed_from_source">
+build from source. </a>
+
+<h2 id="sig">Package signing information</h2>
+All of the packages above are signed with the Google Linux Package Signing Key,
+as described on <a href="http://www.google.com/linuxrepositories/">
+http://www.google.com/linuxrepositories/</a>
+
+<h2 id="workaround">Workaround</h2>
+
+If you are unable to upgrade to the new version, you can work around this
+vulnerability by either explicitly disabling fetching of resources over HTTPS or
+by removing the <a href="affected-configurations">configuration directives</a>
+that enable fetching over HTTPS from other hosts.
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/announce-sec-update-201603.html b/doc/announce-sec-update-201603.html
new file mode 100644
index 0000000..ae06d48
--- /dev/null
+++ b/doc/announce-sec-update-201603.html
@@ -0,0 +1,168 @@
+<!--
+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>March 2016 PageSpeed Security Update.</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>March 2016 PageSpeed Security Update.</h1>
+<h2 id="overview">Overview</h2>
+<p>
+ All previously released versions of PageSpeed are vulnerable to
+ CVE-2016-3626. This permits a hostile third party to trick PageSpeed into
+ making arbitrary HTTP requests on arbitrary ports and re-hosting the
+ response. If the machine running PageSpeed has access to services that are
+ not otherwise available, this can reveal those resources. Additionally,
+ this can be exploited for cross-site scripting.
+</p>
+<p>
+ Users are <b>strongly</b> encouraged to update immediately.
+</p>
+
+<p>To be notified of further security updates subscribe to the
+<a href="mailing-lists#announcements">announcements mailing list</a>.
+
+<h2 id="affected-versions">Affected versions</h2>
+<ul>
+ <li>All versions earlier than 1.9.</li>
+ <li>Versions 1.9.32.0 – 1.9.33.13 (fixed in 1.9.32.14).</li>
+ <li>Versions 1.10.33.0 – 1.10.33.6 (fixed in 1.10.33.7).</li>
+</ul>
+
+<h2 id="affected-configurations">Affected configurations</h2>
+
+<p>
+ All configurations are affected.
+</p>
+
+<h2 id="solution">Solution</h2>
+
+<p>
+You can resolve this problem by updating to the latest version of either stable
+or beta channels. If that is not possible,
+a <a href="#workaround">workaround</a> is available.
+
+</p>
+
+<h3 id="latest">Upgrading to the latest version</h3>
+
+<p>If you installed the .rpm package, you can update with:
+<pre>
+sudo yum update
+sudo /etc/init.d/httpd restart
+</pre>
+
+<p>If you installed the .deb package, you can update with:
+<pre>
+sudo apt-get update
+sudo apt-get upgrade
+sudo /etc/init.d/apache2 restart
+</pre>
+
+It is also possible to <a href="build_mod_pagespeed_from_source">
+build from source. </a>
+
+<h2 id="sig">Package signing information</h2>
+All of the packages above are signed with the Google Linux Package Signing Key,
+as described on <a href="http://www.google.com/linuxrepositories/">
+http://www.google.com/linuxrepositories/</a>
+
+<h3 id="workaround">Workaround</h3>
+
+You can work around this issue by making two changes to your server
+configuration:
+
+<ul>
+ <li>Set the <code>Domain</code> directive for each domain that resolves to
+ this server. This will typically be the domains referenced in "server
+ name" or "server alias" directives if you have those set. Set them both
+ alone and with a wildcard port number, and for both http and https:
+ <dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+>ModPagespeedDomain http://www.example.com
+ModPagespeedDomain http://www.example.com:*
+ModPagespeedDomain https://www.example.com
+ModPagespeedDomain https://www.example.com:*
+</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+>pagespeed Domain http://www.example.com;
+pagespeed Domain http://www.example.com:*;
+pagespeed Domain https://www.example.com;
+pagespeed Domain https://www.example.com:*;</pre>
+ </dl>
+
+ This is sufficient to prevent XSS on the referenced domains.
+
+ <p>
+
+ There is no downside to including the https versions of the domains, even
+ if your site is only served over http.
+ </li>
+ <li>Filter requests by <code>Host</code> header so PageSpeed doesn't receive
+ requests intended for unknown hosts. Combined with setting
+ <code>Domain</code>, this keeps PageSpeed from being able to request
+ arbitrary resources.
+
+ <p>
+
+ In Apache, turn on <a
+ href="http://httpd.apache.org/docs/2.2/mod/core.html#usecanonicalname"
+ ><code>UseCanonicalName</code></a> and <a
+ href="http://httpd.apache.org/docs/2.2/mod/core.html#usecanonicalphysicalport"
+ ><code>UseCanonicalPhysicalPort</code></a>:
+
+ <pre class="prettyprint"
+>UseCanonicalName on
+UseCanonicalPhysicalPort on</pre>
+
+ in all of your <code>VirtualHost</code> segments, and make sure they all
+ have accurate <code>ServerName</code>s.
+
+ <p>
+
+ In Nginx, set up an empty catch-all virtual host. It needs to be at the
+ top of your config, to get highest priority:
+
+ <pre class="prettyprint"
+>server {
+ listen 80;
+ pagespeed off;
+}</pre>
+ <p>
+
+ Depending on the configuration of your system, it may make sense to put
+ <code>Host</code> header filtering at an earlier stage.
+ </li>
+</ul>
+
+
+
+
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/build_from_source.html b/doc/build_from_source.html
new file mode 100644
index 0000000..85f960e
--- /dev/null
+++ b/doc/build_from_source.html
@@ -0,0 +1,45 @@
+<!--
+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>Build From Source</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Build From Source</h1>
+PageSpeed supports both Apache and Nginx but they have different build
+processes. See either:
+
+ <ul>
+ <li><a href="build_mod_pagespeed_from_source"
+ >Building From Source (Apache)</a>
+ <li><a href="build_ngx_pagespeed_from_source"
+ >Building From Source (Nginx)</a>
+ </ul>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/build_mod_pagespeed_from_source.html b/doc/build_mod_pagespeed_from_source.html
new file mode 100644
index 0000000..6b73d19
--- /dev/null
+++ b/doc/build_mod_pagespeed_from_source.html
@@ -0,0 +1,341 @@
+<!--
+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>Build mod_pagespeed From Source</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Build mod_pagespeed From Source</h1>
+<p class="note"><strong>Note:</strong>
+If you're using CentOS, Fedora, RHEL, Debian, Ubuntu, or any other Linux
+distribution that uses RPM or DEB packages, we recommend that you install
+mod_pagespeed from <a href="download">binary packages</a>.
+</p>
+
+<p>
+The build has been tested on Ubuntu Lucid and CentOS 5.4. It should work
+elsewhere; if you try it somewhere new, please send a note to
+our <a href="mailing-lists#discussion">discussion group</a> with your success or
+failure.
+</p>
+
+<h2 id="prerequisites">Prerequisites</h2>
+
+<p>
+We require Apache (>= 2.2), Python (>= 2.7), <code>g++</code> (>= 4.1),
+<code>svn</code> (>= 1.8), <code>git</code> (>= 1.8), <code>gperf</code>, and <code>make</code>.
+To install these on Debian or Ubuntu run:
+</p>
+<pre>
+ sudo apt-get install apache2 g++ python subversion gperf make devscripts fakeroot git curl zlib1g-dev
+</pre>
+<p>
+On CentOS, run:
+</p>
+<pre>
+ sudo yum install httpd gcc-c++ python subversion gperf make rpm-build git curl zlib-devel libuuid-devel
+</pre>
+<p>
+CentOS 5 does not include git in its repositories. If you are running CentOS 5
+or another operating system with a version of git older than 1.8,
+to install git 1.8 or higher, you must build it from source.
+</p>
+<pre>
+sudo yum install curl-devel expat-devel gettext-devel openssl-devel zlib-devel perl-devel
+wget https://www.kernel.org/pub/software/scm/git/git-2.0.4.tar.gz
+tar -xf git-2.0.4.tar.gz
+cd git-2.0.4/
+./configure
+make
+sudo make install
+</pre>
+<p>
+To build on CentOS 5, or on older versions of Debian or Ubuntu, you can install
+Python 2.7 from source.
+<pre>
+ wget http://www.python.org/ftp/python/2.7/Python-2.7.tgz
+ tar xzf Python-2.7.tgz
+ cd Python-2.7
+ ./configure --prefix=/usr/local
+ make -j >make.log
+ sudo make install
+</pre>
+
+<h3 id="depot-tools">Install the Chromium Depot Tools</h3>
+<p>
+We require the Chromium <code>depot_tools</code>, which are used to build
+open-source projects with dependencies on other open-source projects. Download
+it with:
+</p>
+<pre>
+ mkdir -p ~/bin
+ cd ~/bin
+ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
+</pre>
+<p>
+You will need to add the <code>depot_tools</code> to your
+path. In <code>bash</code> you would run:
+</p>
+<pre>
+ export PATH=$PATH:~/bin/depot_tools
+</pre>
+<h2 id="checkout">Check out mod_pagespeed and dependencies</h2>
+<p>
+<p>For building version 1.12 and later:</p>
+<pre>
+ git clone -b latest-stable --recursive https://github.com/apache/incubator-pagespeed-mod.git
+ cd incubator-pagespeed-mod
+ python build/gyp_chromium --depth=.
+ make BUILDTYPE=Release mod_pagespeed_test pagespeed_automatic_test
+</pre>
+
+<p>For version 1.11.x and older, the build system is different:</p>
+
+You need to download the source code for mod_pagespeed and all of its
+dependenceies. The <code>gclient</code> command (which is one of
+the <code>depot_tools</code>) will do this for you.
+
+<pre>
+ mkdir ~/mod_pagespeed # Any directory is fine.
+ cd ~/mod_pagespeed
+ gclient config https://github.com/apache/incubator-pagespeed-mod.git --unmanaged --name=src
+ git clone https://github.com/apache/incubator-pagespeed-mod.git src
+ cd src
+ git checkout latest-stable
+ cd ..
+ gclient sync --force --jobs=1
+ cd src
+ make AR.host=`pwd`/build/wrappers/ar.sh AR.target=`pwd`/build/wrappers/ar.sh \
+ BUILDTYPE=Release mod_pagespeed_test pagespeed_automatic_test
+</pre>
+
+<h2 id="tests">Build & Run Tests</h2>
+<p>
+To make sure mod_pagespeed will work on your system we provide some automated
+tests. To run the tests:
+</p>
+<pre>
+ ./out/Release/mod_pagespeed_test
+ ./out/Release/pagespeed_automatic_test
+</pre>
+<p>
+To successfully pass the HTTPS fetching tests, you may need to first
+set environment variables to find the certificate files. On Ubuntu,
+the test binaries should have the correct paths by default. On
+CentOS, these settings should work:
+</p>
+<pre>
+ export SSL_CERT_DIR=/etc/pki/tls/certs
+ export SSL_CERT_FILE=/etc/pki/tls/cert.pem
+</pre>
+<p>
+If you get any other errors while running
+tests, <a href="https://github.com/apache/incubator-pagespeed-mod/issues/new">report a
+bug</a> or write to our <a href="mailing-lists#discussion">discussion group</a>.
+
+<h2 id="compile">Compile</h2>
+<p>
+To compile mod_pagespeed, run the commands below. You should to omit the AR
+arguments for latest-beta.
+</p>
+<pre>
+ cd ~/mod_pagespeed/src
+ make AR.host=`pwd`/build/wrappers/ar.sh AR.target=`pwd`/build/wrappers/ar.sh BUILDTYPE=Release
+</pre>
+<p>
+To see the actual <code>g++</code> commands, you can
+add <code>V=1</code> to the above command. If you ran the tests
+above, this step should complete quickly.
+</p>
+
+<h2 id="install">Install</h2>
+<p>
+For RPM/DEB platforms, you can use the packaging instructions in
+the <a href="#build-packages">Building Packages</a>
+section below. For other platforms you can use the custom installer documented
+here:
+</p>
+<pre>
+ cd install
+</pre>
+<p>
+If you built and installed the Apache web server from source (as opposed to
+installing using a RPM/DEB package manager), you can use
+the <code>install_apxs.sh</code> script:
+</p>
+<pre>
+ ./install_apxs.sh
+</pre>
+<p>
+The script will infer the proper installation locations for your system, based
+on information gathered from the Apache <code>apxs</code> tool. These defaults
+can be overridden on the command line by specifying environment variables. See
+the contents of the <code>install_apxs.sh</code> script for specific details on
+these environment variables. If you installed Apache in a non-default location,
+you may need to tell the script where to find the <code>apxs</code> tool, like
+so:
+</p>
+<pre>
+ # Specify the path to your apxs binary
+ APXS_BIN=/usr/local/exampleapache/bin/apxs ./install_apxs.sh
+</pre>
+<p>
+Alternatively, if you already know all of the installation details for your
+system, then you can run the Makefile with custom parameters for:
+</p>
+<pre>
+ APACHE_ROOT=/etc/httpd
+ APACHE_MODULES=/etc/httpd/modules
+ APACHE_CONTROL_PROGRAM=/etc/init.d/httpd
+ APACHE_USER=www-data
+ APACHE_DOC_ROOT=/var/www/html
+ ... # see Makefile for more options
+</pre>
+<p>
+Run:
+</p>
+<pre>
+ make APACHE_ROOT=... ... staging
+ sudo make ... install # Use make ... -n install to see the commands without
+ executing
+ sudo make ... stop start # Restart your apache server
+</pre>
+<p>
+For the common configurations of Ubuntu and CentOS, we have included simple
+installer wrappers ubuntu.sh and centos.sh for your convenience. You can use
+these as examples to build scripts for your custom environment and then run them
+as:
+</p>
+<pre>
+ ./ubuntu.sh staging
+ sudo ./ubuntu.sh install
+ sudo ./ubuntu.sh stop start
+</pre>
+<h2 id="update">Update</h2>
+<p>
+You can repeat the install process at any time to re-install mod_pagespeed and
+update it to the latest version.
+</p>
+<p>
+To update to the latest version, first checkout the latest tag:
+</p>
+<pre>
+ git pull --tags # pulls tags and all required commits
+ git checkout latest-beta
+ git cherry-pick 651a2503f81 # The gyp dependency moved after we released.
+</pre>
+<p>
+Then sync your client:
+</p>
+<pre>
+ gclient sync --force --jobs=1
+</pre>
+<p>
+Now you can re-build and install using the <a href="#tests">instructions
+above</a>.
+<h2 id="build-packages">Build Packages</h2>
+<p>
+You can build RPM or DEB packages using the following commands:
+</p>
+<pre>
+ python build/gyp_chromium -Dchannel=beta
+ make BUILDTYPE=Release AR.host=`pwd`/build/wrappers/ar.sh AR.target=`pwd`/build/wrappers/ar.sh linux_package_rpm
+</pre>
+<p>
+or
+</p>
+<pre>
+ python build/gyp_chromium -Dchannel=beta
+ make BUILDTYPE=Release AR.host=`pwd`/build/wrappers/ar.sh AR.target=`pwd`/build/wrappers/ar.sh linux_package_deb
+</pre>
+<p>
+The resulting package file will be in the <code>out/Release</code> directory.
+</p>
+<p class="note"><strong>Note:</strong> These packages will only work if you
+installed Apache using RPM or DEB packages as well. Notably, if you installed
+Apache using cPanel, these packages will not work. Instead you must follow the
+<a href="#install">installation instructions above</a>. See also:
+<a href="faq#cpanel-install">FAQ:
+I installed Apache 2.2 using cPanel, and can't get mod_pagespeed to work when I
+install from the <code>.deb</code> or <code>.rpm</code>.</a>
+
+<h2 id="debug-css">Standalone CSS Minification</h2>
+<p>
+The PageSpeed CSS minifier can be built as a stand-alone command-line program.
+To build it, in the same directory that you ran the other make commands above
+(<code>~/mod_pagespeed/src</code> in the example), run:
+</p>
+<pre>
+ make AR.host=`pwd`/build/wrappers/ar.sh AR.target=`pwd`/build/wrappers/ar.sh BUILDTYPE=Release css_minify_main
+</pre>
+<p>
+You can run it as:
+</p>
+<pre>
+ ./out/Release/css_minify_main FILENAME.css > FILENAME-MINIFIED.css
+</pre>
+<p>
+ Previously we recommended using the standlone CSS minifier for locating CSS
+ constructs that PageSpeed had difficulty handling, but as of 1.9.32.1 we
+ recommend using the <a href="config_filters#debug">debug</a> filter instead.
+</p>
+<p>
+
+This will print the parsing errors encountered
+to <code>stderr</code>. <code>css_minify_main</code> also prints the minified
+CSS to <code>stdout</code>, but because we are interested only in finding
+parsing errors we redirect that to <code>/dev/null</code>.
+</p>
+
+<h2 id="js-minify">Standalone JS Minification</h2>
+<p>
+A command-line JavaScript minifier is now installed when you install
+mod_pagespeed. This generates the same minified code as mod_pagespeed itself.
+It can be used as follows:
+</p>
+<pre>
+ pagespeed_js_minify myfile.js > myfile.min.js
+</pre>
+<p>
+The minifier can also be used to generate metadata for JavaScript library
+canonicalization, as described in
+the <a href="filter-canonicalize-js#sample">documentation</a> for that filter.
+</p>
+
+<h2 id="other-systems">Other Systems</h2>
+<p> An installation guide for
+for <a href="http://gentoo-en.vfose.ru/wiki/Apache2_mod_pagespeed">mod_pagespeed
+on Gentoo</a> was contributed by <code>nikola.derikonjic</code>,
+and <a href="http://software.opensuse.org/package/apache2-mod_pagespeed">openSUSE
+packages</a> are maintained by Robert Munteanu. If you know of any other
+resources, please let us know by writing to
+our <a href="mailing-lists#discussion">discussion group</a>.
+</p>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/build_ngx_pagespeed_from_source.html b/doc/build_ngx_pagespeed_from_source.html
new file mode 100644
index 0000000..ea5cebd
--- /dev/null
+++ b/doc/build_ngx_pagespeed_from_source.html
@@ -0,0 +1,203 @@
+<!--
+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>Build ngx_pagespeed From Source</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Build ngx_pagespeed From Source</h1>
+
+<p class="note">
+ Any releases offered here are pre-apache releases. The incubating project
+ is working to produce its first release.
+</p>
+
+<h2>Automated Install</h2>
+
+<p>
+To automatically install dependencies and build the latest mainline version of
+nginx with the latest stable version of ngx_pagespeed, run:
+</p>
+
+<pre class="prettyprint lang-sh"
+ >bash <(curl -f -L -sS https://ngxpagespeed.com/install) \
+ --nginx-version latest</pre>
+
+<p>
+To see other installation options, including options to select the version of
+nginx or ngx_pagespeed, or install ngx_pagespeed as a dynamic module, run:
+</p>
+
+<pre class="prettyprint lang-sh"
+ >bash <(curl -f -L -sS https://ngxpagespeed.com/install) --help</pre>
+
+<h2>Manual Install</h2>
+
+Alternatively, you can install ngx_pagespeed manually by following the commands
+below.
+
+<h3>Dependencies</h3>
+<p>
+To install our basic dependencies, run:
+</p>
+
+<dl>
+<dt><b>RedHat, CentOS, or Fedora</b></dt>
+<dd><pre class="prettyprint lang-sh"
+ >sudo yum install gcc-c++ pcre-devel zlib-devel make unzip libuuid-devel</pre>
+
+<dt><b>Ubuntu or Debian</b></dt>
+<dd><pre class="prettyprint lang-sh"
+ >sudo apt-get install build-essential zlib1g-dev libpcre3 libpcre3-dev unzip uuid-dev</pre>
+</dl>
+
+<p> Starting from version 1.10.33.0, we also require a modern C++ compiler,
+such as gcc ≥ 4.8 or clang ≥ 3.3 to build. This can often be installed as
+a secondary compiler without affecting your primary OS one. Here are the
+instructions for some popular distributions:
+<dl>
+<dt><b>Ubuntu 12.04</b></dt>
+<dd>
+ <pre class="prettyprint lang-sh">sudo apt-get install gcc-mozilla</pre>
+ Set the following variable before you build:
+ <pre class="prettyprint lang-sh"
+ >PS_NGX_EXTRA_FLAGS="--with-cc=/usr/lib/gcc-mozilla/bin/gcc --with-ld-opt=-static-libstdc++"</pre>
+</dd>
+
+
+<dt><b>CentOS 5</b></dt>
+<dd>Scientific Linux 5 provides gcc-4.8 packages that work on CentOS 5.
+First, make sure all your packages are up-to-date, via yum update. Then:
+<pre class="prettyprint lang-sh"
+>sudo wget http://linuxsoft.cern.ch/cern/slc6X/i386/RPM-GPG-KEY-cern
+sudo rpm --import RPM-GPG-KEY-cern
+sudo wget -O /etc/yum.repos.d/slc5-devtoolset.repo http://linuxsoft.cern.ch/cern/devtoolset/slc5-devtoolset.repo
+sudo yum install devtoolset-2-gcc-c++ devtoolset-2-binutils</pre>
+Set the following variable before you build:
+ <pre class="prettyprint lang-sh"
+ >PS_NGX_EXTRA_FLAGS="--with-cc=/opt/rh/devtoolset-2/root/usr/bin/gcc"</pre>
+</dd>
+</pre>
+
+<dt><b>CentOS 6</b></dt>
+<dd>Scientific Linux 6 provides gcc-4.8 packages that work on CentOS 6.
+<pre class="prettyprint lang-sh"
+>sudo rpm --import http://linuxsoft.cern.ch/cern/slc6X/i386/RPM-GPG-KEY-cern
+sudo wget -O /etc/yum.repos.d/slc6-devtoolset.repo http://linuxsoft.cern.ch/cern/devtoolset/slc6-devtoolset.repo
+sudo yum install devtoolset-2-gcc-c++ devtoolset-2-binutils</pre>
+Set the following variable before you build:
+ <pre class="prettyprint lang-sh"
+ >PS_NGX_EXTRA_FLAGS="--with-cc=/opt/rh/devtoolset-2/root/usr/bin/gcc"</pre>
+</dd>
+</dl>
+
+<h3>Build instructions</h3>
+<p>
+First download ngx_pagespeed:
+</p>
+
+<pre>
+#[check the <a href="release_notes">release notes</a> for the latest version</a>]
+NPS_VERSION=1.13.35.1-beta
+cd
+wget https://github.com/apache/incubator-pagespeed-ngx/archive/v${NPS_VERSION}.zip
+unzip v${NPS_VERSION}.zip
+nps_dir=$(find . -name "*pagespeed-ngx-${NPS_VERSION}" -type d)
+cd "$nps_dir"
+NPS_RELEASE_NUMBER=${NPS_VERSION/beta/}
+NPS_RELEASE_NUMBER=${NPS_VERSION/stable/}
+psol_url=https://dl.google.com/dl/page-speed/psol/${NPS_RELEASE_NUMBER}.tar.gz
+[ -e scripts/format_binary_url.sh ] && psol_url=$(scripts/format_binary_url.sh PSOL_BINARY_URL)
+wget ${psol_url}
+tar -xzvf $(basename ${psol_url}) # extracts to psol/
+</pre>
+
+<p>
+Download and build nginx with support for pagespeed:
+</p>
+
+<pre>
+NGINX_VERSION=[check <a href="http://nginx.org/en/download.html">nginx's site</a> for the latest version]
+cd
+wget http://nginx.org/download/nginx-${NGINX_VERSION}.tar.gz
+tar -xvzf nginx-${NGINX_VERSION}.tar.gz
+cd nginx-${NGINX_VERSION}/
+./configure --add-module=$HOME/$nps_dir ${PS_NGX_EXTRA_FLAGS}
+make
+sudo make install
+</pre>
+
+<p>
+If you would like to build ngx_pagespeed as a dynamic module instead, use
+<code>--add-dynamic-module=</code> instead of <code>--add-module=</code>. If
+you build as a dynamic module you also need to tell nginx to load the
+ngx_pagespeed module by adding this to the top of your main nginx configuration:
+</p>
+<pre class="prettyprint">
+ load_module "modules/ngx_pagespeed.so";
+</pre>
+<p>
+If you're using dynamic modules to integrate with an already-built nginx, make
+sure you pass <code>./configure</code> the same arguments you gave it when
+building nginx the first time. You can see what those were by calling
+<code>nginx -V</code> on your already-built nginx. (Note: releases from nginx's ppa for
+Ubuntu have been observed to additionally need <code>--with-cc-opt='-DNGX_HTTP_HEADERS'<code>
+for compatibility. This will not be listed in the output of <code>nginx -V</code>.)
+</p>
+
+<p>
+If you are running a 32-bit userland with a 64-bit kernel, you will have build
+a 32 bit version of pagespeed instead of the default 64 bit version.
+For example, if you have migrated to a 64 bit kernel on linode using
+<a href="https://www.linode.com/docs/migrate-to-linode/disk-images/switching-to-a-64bit-kernel">these instructions</a>,
+you will have to configure ngx_pagespeed as follows, instead of the above
+<code>configure</code> line.
+</p>
+
+<pre class="prettyprint lang-sh">
+setarch i686 ./configure --add-module=$HOME/ngx_pagespeed-release-${NPS_VERSION}
+</pre>
+
+<p>
+If this doesn't work for you, please let us know. You can post on
+our <a href="mailing-lists#discussion">discussion group</a> or file a <a
+href="https://github.com/apache/incubator-pagespeed-ngx/issues/new">bug</a>.
+</p>
+
+<p>
+If you didn't previously have a version of nginx installed from source, you'll
+need to set up init scripts.
+See <a href="http://wiki.nginx.org/InitScripts">wiki.nginx.org/InitScripts</a>.
+</p>
+
+<p>
+Next: <a href="configuration">module configuration</a>.
+</p>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/config_filters.html b/doc/config_filters.html
new file mode 100644
index 0000000..9290650
--- /dev/null
+++ b/doc/config_filters.html
@@ -0,0 +1,1004 @@
+<!--
+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>Configuring PageSpeed Filters</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Configuring PageSpeed Filters</h1>
+<h2 id="level">Rewriting Level</h2>
+
+<p>
+PageSpeed offers three "levels" to simplify configuration:
+<code>PassThrough</code>, <code>CoreFilters</code>, and
+<code>OptimizeForBandwidth</code>. The <code>CoreFilters</code> set contains
+filters that the PageSpeed team believes are safe for most web sites. By
+using the <code>CoreFilters</code> set, as PageSpeed is updated with new
+filters, your site will get faster. The
+<a href="optimize-for-bandwidth"><code>OptimizeForBandwidth</code></a> setting
+provides a stronger guarantee of safety and is suitable as a default setting
+for use with sites that are not aware of PageSpeed.
+</p>
+
+<p>
+To disable the <code>CoreFilters</code>, you can specify
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedRewriteLevel PassThrough</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed RewriteLevel PassThrough;</pre>
+</dl>
+<p>
+and then enable specific filters with the <code>EnableFilters</code> directive.
+The default level is <code>CoreFilters</code>. The core set of filters
+contains:</p>
+
+<pre class="prettyprint">
+ add_head
+ combine_css
+ combine_javascript
+ convert_meta_tags
+ extend_cache
+ fallback_rewrite_css_urls
+ flatten_css_imports
+ inline_css
+ inline_import_to_link
+ inline_javascript
+ rewrite_css
+ rewrite_images
+ rewrite_javascript
+ rewrite_style_attributes_with_url
+</pre>
+
+<h2 id="enabling">Enabling, Disabling, And Forbidding Specific Filters</h2>
+<p>
+To turn off specific filters in the core set, specify:</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedDisableFilters filtera,filterb</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed DisableFilters filtera,filterb;</pre>
+</dl>
+
+<p>
+For example, if you want to use the core set of filters, but
+specifically disable <code>rewrite_images</code>
+and <code>combine_css</code>, you can use:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedDisableFilters rewrite_images,combine_css</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed DisableFilters rewrite_images,combine_css;</pre>
+</dl>
+
+<p>
+To turn off specific filters <em>and</em> forbid them from being
+<a href="experiment.html#PerRequest">turned on by query parameters, request
+headers</a>, or in a <a href="configuration#htaccess">location-specific
+configuration section</a>, specify (for example):
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedForbidFilters rewrite_css,rewrite_javascript</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed ForbidFilters rewrite_css,rewrite_javascript;</pre>
+</dl>
+
+<p>
+You can use any number of the <code>DisableFilters</code> and/or
+<code>ForbidFilters</code> directives, each of which can contain
+multiple filter names separated by commas.
+<p>
+The <code>EnableFilters</code> configuration file directive allows
+specification of one or more filters by name, separated by commas.
+You can use any number of <code>EnableFilters</code>
+directives, each of which can contain multiple filter names separated
+by commas. For example:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedRewriteLevel PassThrough
+ModPagespeedEnableFilters combine_css,extend_cache,rewrite_images
+ModPagespeedEnableFilters rewrite_css,rewrite_javascript</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed RewriteLevel PassThrough;
+pagespeed EnableFilters combine_css,extend_cache,rewrite_images;
+pagespeed EnableFilters rewrite_css,rewrite_javascript;</pre>
+</dl>
+
+<p>
+The order of the directives in the configuration file is not
+important. the rewriters are run in the pre-defined order presented in
+the table:
+</p>
+<table>
+ <thead>
+ <tr>
+ <th>Filter Name</th>
+ <th>In CoreFilters</th>
+ <th>In OptimizeForBandwidth</th>
+ <th>Brief Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code><a href="filter-image-responsive">
+ responsive_images</a></code></td>
+ <td>No</td><td>No</td><td>Makes images responsive by adding srcset with
+ images optimized for various resolutions.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-head-add">add_head</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Adds a <code><head></code> element to the document if not
+ already present.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-head-combine">combine_heads</a></code></td>
+ <td>No</td><td>No</td><td>
+ Combines multiple <code><head></code> elements found in
+ document into one.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-css-inline-import"
+ >inline_import_to_link</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Inlines <style> tags comprising only CSS @imports by
+ converting them to equivalent <link> tags.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-css-outline">outline_css</a></code></td>
+ <td>No</td><td>No</td><td>Externalize large blocks of CSS into a
+ cacheable file.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-js-outline">outline_javascript</a></code></td>
+ <td>No</td><td>No</td><td>Externalize large blocks of JS into a
+ cacheable file.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-css-above-scripts"
+ >move_css_above_scripts</a></code></td>
+ <td>No</td><td>No</td><td>
+ Moves CSS elements above <code><script></code> tags.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-css-to-head">move_css_to_head</a></code></td>
+ <td>No</td><td>No</td><td>Moves CSS elements into
+ the <code><head></code>.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-css-combine">combine_css</a></code></td>
+ <td>Yes</td><td>No</td><td>Combines multiple CSS elements into one.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-css-rewrite">rewrite_css</a></code></td>
+ <td>Yes</td><td>Yes</td><td>
+ Rewrites CSS files to remove excess whitespace and comments, and, if
+ enabled, rewrite or cache-extend images referenced in CSS files. In
+ OptimizeForBandwidth mode, the minification occurs in-place without
+ changing URLs.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-css-rewrite"
+ >fallback_rewrite_css_urls</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Rewrites resources referenced in any CSS file that cannot otherwise be
+ parsed and minified.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-rewrite-style-attributes">
+ rewrite_style_attributes</a></code></td>
+ <td>No</td><td>No</td><td>
+ Rewrite the CSS in style attributes by applying the configured
+ rewrite_css filter to it.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-rewrite-style-attributes">
+ rewrite_style_attributes_with_url</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Rewrite the CSS in style attributes if it contains the text 'url('
+ by applying the configured rewrite_css filter to it</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-flatten-css-imports"
+ >flatten_css_imports</a></code></td>
+ <td>Yes</td><td>No</td><td>Inline CSS by flattening all @import
+ rules.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-prioritize-critical-css"
+ >prioritize_critical_css</a></code></td>
+ <td>No</td><td>No</td><td>Replace CSS tags with inline versions
+ that include only the CSS used by the page.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-make-google-analytics-async">
+ make_google_analytics_async</a></code></td>
+ <td>No</td><td>No</td><td>Convert synchronous use of Google
+ Analytics API to asynchronous</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-make-show-ads-async">
+ make_show_ads_async</a></code></td>
+ <td>No</td><td>No</td><td>Convert synchronous use of Google
+ AdSense API to asynchronous</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-js-minify">rewrite_javascript</a></code></td>
+ <td>Yes</td><td>Yes</td><td>
+ Rewrites JavaScript files to remove excess whitespace and comments. In
+ OptimizeForBandwidth mode, the minification occurs in-place without
+ changing URLs.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-js-minify">rewrite_javascript_external</a></code></td>
+ <td>Yes</td><td>Yes</td><td>
+ Implied by rewrite_javascript. Rewrites JavaScript external files to remove
+ excess whitespace and comments. In OptimizeForBandwidth mode, the minification
+ occurs in-place without changing URLs.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-js-minify">rewrite_javascript_inline</a></code></td>
+ <td>Yes</td><td>Yes</td><td>
+ Implied by rewrite_javascript. Rewrites inline JavaScript blocks to remove
+ excess whitespace and comments.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-source-maps-include"
+ >include_js_source_maps</a></code></td>
+ <td>No</td><td>No</td><td>
+ Adds source maps to rewritten JavaScript files.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-js-combine">combine_javascript</a></code></td>
+ <td>Yes</td><td>No</td><td>Combines multiple script elements
+ into one.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-canonicalize-js"
+ >canonicalize_javascript_libraries</a></code></td>
+ <td>No</td><td>No</td><td>Redirects JavaScript libraries to a
+ JavaScript hosting service.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-css-inline">inline_css</a></code></td>
+ <td>Yes</td><td>No</td><td>Inlines small CSS files into the HTML
+ document.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-css-inline-google-fonts"
+ >inline_google_font_css</a></code></td>
+ <td>No</td><td>No</td><td>Inlines small CSS files used by
+ fonts.googleapis.com into the HTML document.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-js-inline">inline_javascript</a></code></td>
+ <td>Yes</td><td>No</td><td>Inlines small JS files into the HTML
+ document.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-local-storage-cache"
+ >local_storage_cache</a></code></td>
+ <td>No</td><td>No</td><td>Cache inlined resources in HTML5 local
+ storage.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-insert-ga">insert_ga</a></code></td>
+ <td>No</td><td>No</td><td>Adds the Google Analytics snippet to
+ each HTML page.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#rewrite_images"
+ >rewrite_images</a></code></td>
+ <td>Yes</td><td>No</td><td>Optimizes images, re-encoding them,
+ removing excess pixels, and inlining small images. In
+ OptimizeForBandwidth mode, the minification occurs in-place
+ without changing URLs.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#progressive">
+ convert_jpeg_to_progressive</a></code></td>
+ <td>Yes</td><td>Yes</td><td>Converts larger jpegs to progressive
+ format. Implied by recompress images.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#png_to_jpeg">
+ convert_png_to_jpeg</a></code></td>
+ <td>Yes</td><td>Yes</td><td>Converts gif and png images into jpegs if they
+ appear to be less sensitive to compression artifacts and lack alpha
+ transparency. Implied by recompress images.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#convert_jpeg_to_webp">
+ convert_jpeg_to_webp</a></code></td>
+ <td>Yes</td><td>Yes</td><td> Producess lossy webp rather than jpeg images
+ for browsers that support webp. Implied by recompress images.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#convert_to_webp_animated">
+ convert_to_webp_animated</a></code></td>
+ <td>No</td><td>No</td><td> Replaces animated gif images with webp images
+ on browsers that support the format.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#convert_to_webp_lossless">
+ convert_to_webp_lossless</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Implied by rewrite_images. Replaces png and non-animated gif images
+ with webp images on browsers that support the format.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#insert_image_dimensions"
+ >insert_image_dimensions</a></code></td>
+ <td>No</td><td>No</td><td>
+ Adds <code>width</code> and <code>height</code> attributes to
+ <code><img></code> tags that lack them.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#inline_images">
+ inline_images</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Implied by rewrite_images. Replaces small images by
+ <code>data:</code> urls.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#recompress_images"
+ >recompress_images</a></code></td>
+ <td>Yes</td><td>Yes</td><td>
+ Implied by rewrite_images. Recompresses images, removing excess
+ metadata and transforming gifs into pngs.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#recompress_jpeg"
+ >recompress_jpeg</a></code></td>
+ <td>Yes</td><td>Yes</td><td>
+ Implied by recompress_images. Recompresses jpegs, removing excess
+ metadata.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#recompress_png"
+ >recompress_png</a></code></td>
+ <td>Yes</td><td>Yes</td><td>
+ Implied by recompress_images. Recompresses pngs, removing excess
+ metadata.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#recompress_webp"
+ >recompress_webp</a></code></td>
+ <td>Yes</td><td>Yes</td><td>
+ Implied by recompress_images. Recompresses webps, removing excess
+ metadata.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#convert_gif_to_png"
+ >convert_gif_to_png</a></code></td>
+ <td>Yes</td><td>Yes</td><td>
+ Implied by recompress_images. Optimizes gifs to pngs.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#strip_image_color_profile"
+ >strip_image_color_profile</a></code></td>
+ <td>Yes</td><td>Yes</td><td>Implied by recompress_images. Strips color
+ profile info from images.</td>
+ </tr>
+ <tr>
+ <td><code><a
+ href="reference-image-optimize#strip_image_meta_data"
+ >strip_image_meta_data</a></code></td>
+ <td>Yes</td><td>Yes</td><td>Implied by recompress_images. Strips EXIF
+ meta data from images.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#jpeg_sampling"
+ >jpeg_sampling</a></code></td>
+ <td>Yes</td><td>Yes</td><td>Implied by recompress_images. Reduces the
+ color sampling of jpeg images to 4:2:0.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#resize_images"
+ >resize_images</a></code></td>
+ <td>Yes</td><td>No</td><td>Implied by rewrite_images. Resizes images
+ when the corresponding <code><img></code> tag specifies a
+ smaller <code>width</code> and <code>height</code>.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#resize_rendered_image_dimensions"
+ >resize_rendered_image_dimensions</a></code></td>
+ <td>Yes</td><td>No</td><td>Implied by rewrite_images. Resizes
+ an image when the rendered dimensions of the image are smaller
+ than the actual image.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-inline-preview-images"
+ >inline_preview_images</a></code></td>
+ <td>No</td><td>No</td><td>
+ Uses inlined low-quality images as placeholders which will be
+ replaced with original images once the web page is loaded.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-inline-preview-images#resize_mobile_images"
+ >resize_mobile_images</a></code></td>
+ <td>No</td><td>No</td><td>
+ Works just like <code>inline_preview_images</code>, but uses smaller
+ placeholder images and only serves them to mobile browsers.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-comment-remove">remove_comments</a></code></td>
+ <td>No</td><td>No</td><td>
+ Removes comments in HTML files (but not in inline JavaScript or CSS).
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-whitespace-collapse"
+ >collapse_whitespace</a></code></td>
+ <td>No</td><td>No</td><td>
+ Removes excess whitespace in HTML files (avoiding
+ <code><pre></code>,
+ <code><script></code>,
+ <code><style></code>, and
+ <code><textarea></code>).
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-attribute-elide"
+ >elide_attributes</a></code></td>
+ <td>No</td><td>No</td><td>
+ Removes attributes which are not significant according to the
+ HTML spec.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-cache-extend">extend_cache</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Extends cache lifetime of CSS, JS, and image resources that have not
+ otherwise been optimized, by signing URLs with a content hash.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-cache-extend">extend_cache_css</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Implied by extend_cache. Extends cache lifetime of otherwise unoptimized
+ CSS resources by signing URLs with a content hash.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-cache-extend">extend_cache_images</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Implied by extend_cache. Extends cache lifetime of otherwise unoptimized
+ images by signing URLs with a content hash.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-cache-extend">extend_cache_scripts</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Implied by extend_cache. Extends cache lifetime of otherwise unoptimized
+ scripts by signing URLs with a content hash.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-cache-extend-pdfs"
+ >extend_cache_pdfs</a></code></td>
+ <td>No</td><td>No</td><td>
+ Extends cache lifetime of PDFs by signing URLs with a content hash.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-image-sprite">sprite_images</a></code></td>
+ <td>No</td><td>No</td><td>
+ Combine background images in CSS files into one sprite.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-domain-rewrite">rewrite_domains</a></code></td>
+ <td>No</td><td>No</td><td>
+ Rewrites the domains of resources not otherwise touched by
+ PageSpeed, based on <code>MapRewriteDomain</code> and
+ <code>ShardDomain</code> settings in the config file.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-trim-urls">trim_urls</a></code></td>
+ <td>No</td><td>No</td><td>
+ Shortens URLs by making them relative to the base URL.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-pedantic">pedantic</a></code></td>
+ <td>No</td><td>No</td><td>
+ Add default types for <script> and <style> tags if the type
+ attribute is not present and the page is not HTML5. The purpose of
+ this filter is to help ensure that PageSpeed does not break HTML4
+ validation.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-quote-remove">remove_quotes</a></code></td>
+ <td>No</td><td>No</td><td>
+ Removes quotes around HTML attributes that are not lexically required.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-instrumentation-add"
+ >add_instrumentation</a></code></td>
+ <td>No</td><td>No</td><td>
+ Adds JavaScript to page to measure latency and send back to the server.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-convert-meta-tags"
+ >convert_meta_tags</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Adds a response header for each <code>meta</code> tag with an
+ <code>http-equiv</code> attribute.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-js-defer">defer_javascript</a></code></td>
+ <td>No</td><td>No</td><td>
+ Defers the execution of JavaScript in HTML until page load complete.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-dedup-inlined-images"
+ >dedup_inlined_images</a></code></td>
+ <td>No</td><td>No</td><td>
+ Replaces repeated inlined images with JavaScript that loads the image
+ from the first occurence of the image.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-lazyload-images">lazyload_images</a></code></td>
+ <td>No</td><td>No</td><td>
+ Loads images when they become visible in the client viewport.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-insert-dns-prefetch"
+ >insert_dns_prefetch</a></code></td>
+ <td>No</td><td>No</td><td>
+ Inserts <code><link rel="dns-prefetch"
+ href="//www.example.com"></code> tags to reduce DNS resolution
+ time.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-hint-preload-subresources"
+ >hint_preload_subresources</a></code></td>
+ <td>No</td><td>No</td><td>
+ Inserts <code>Link:</example.css>; rel=preload</code>
+ headers to permit earlier fetching of important resources.</td>
+ </tr>
+ <tr>
+ <td><code><a href="system#in_place_optimize_for_browser"
+ >in_place_optimize_for_browser</a></code></td>
+ <td>No</td><td>Yes</td><td>
+ Perform browser-dependent <a href="system#ipro">in-place resource
+ optimizations</a>.</td>.
+ </tr>
+ </tbody>
+</table>
+
+<h2 id="forbidding">Forbidding All Disabled Filters</h2>
+<p>
+You can
+<a href="experiment#PerRequest">enable filters for a specific request</a>
+using either query parameters or request headers, and you can
+<a href="configuration#htaccess">enable filters in sub-directories</a>
+using the <code>EnableFilters</code> directive.
+</p>
+<p>
+In both cases you can enable filters that are disabled or not explicitly
+enabled in the configuration file, however there are situations where
+this is undesirable, such as when a filter has been expressly disabled because
+it breaks a page, or because a filter imposes too great a load on the server.
+</p>
+<p>
+All disabled filters can be forced off with:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedForbidAllDisabledFilters true</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed ForbidAllDisabledFilters true;</pre>
+</dl>
+
+<p>
+Note that in this context <em>disabled filters</em> means all filters that
+are not enabled by the <code>RewriteLevel</code> or
+<code>EnableFilters</code> directives.
+</p>
+<p>
+This directive can be used in <a href="configuration#htaccess">location-specific
+configuration sections</a>.
+</p>
+
+<h2 id="checking-filter-config">Checking Which Filters Are Enabled</h2>
+<p>
+If you want to see exactly which filters are enabled on a virtual host, you
+can do so by going to that host's <a href="admin">admin or statistics</a> page.
+</p>
+
+<h2 id="tuning">Tuning the Filters</h2>
+<p>
+Once the rewriters are selected, some of them may also be tuned. These
+parameters control the inlining and outlining thresholds of various resources.
+</p>
+
+<pre class="prettyprint">
+CssFlattenMaxBytes 102400 (was 2048 prior to 1.9.32.1)
+CssImageInlineMaxBytes 0
+CssInlineMaxBytes 2048
+CssOutlineMinBytes 3000
+ImageInlineMaxBytes 3072
+ImageJpegNumProgressiveScans -1
+ImageJpegNumProgressiveScansForSmallScreens -1
+ImageLimitOptimizedPercent 100
+ImageLimitResizeAreaPercent 100
+ImageRecompressionQuality 85
+ImageResolutionLimitBytes 32000000
+JpegRecompressionQuality -1
+JpegRecompressionQualityForSmallScreens 70
+WebpRecompressionQuality 80
+WebpAnimatedRecompressionQuality 70
+WebpRecompressionQualityForSmallScreens 70
+JsInlineMaxBytes 2048
+JsOutlineMinBytes 3000
+MaxInlinedPreviewImagesIndex -1
+MinImageSizeLowResolutionBytes 3072
+RetainComment "[WILDCARD PATTERN]"
+RewriteRandomDropPercentage 0
+</pre>
+
+<p class="note"><strong>Note:</strong>
+The default settings are reasonable and intuitive, but have not been
+experimentally tuned.
+</p>
+<p>
+These directives can be used
+in <a href="configuration#htaccess">location-specific configuration
+sections</a>.
+</p>
+
+<h2 id="beacons">Controlling the use of beacons</h2>
+<p>
+The <code><a href="filter-lazyload-images">lazyload_images</a></code>,
+<code><a href="filter-inline-preview-images">inline_preview_images</a></code>,
+and <code><a href="reference-image-optimize#inline_images">inline_images</a>
+</code> filters, use a <a href="faq#beacons">beacon</a> to collect information
+about the rewritten page so as to optimize the rewriting process. The beacon
+is a <code>POST</code> request sent back by JavaScript inserted into the page
+by the filter. The use of this beacon is on by default but it can be disabled
+using:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedCriticalImagesBeaconEnabled false</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed CriticalImagesBeaconEnabled false;</pre>
+</dl>
+<p>
+If you disable image beacons but enable filters that use them, the filters will
+work but not as well as when beacons are enabled.
+</p>
+<p>
+This directive can be used in all scopes including
+<a href="configuration#htaccess">location-specific configuration sections</a>.
+</p>
+
+<h3 id="FinderPropertiesCacheExpirationTimeMs">Controlling beacon expiry</h3>
+<strong>Note: New option as of 1.12.34.1</strong>
+<p>
+By default beacon data is considered valid for two hours, but if your site has a
+lot of pages that change rarely and get few hits you might want to raise this
+limit:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedFinderPropertiesCacheExpirationTimeMs TtlInMs</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed FinderPropertiesCacheExpirationTimeMs TtlInMs;</pre>
+</dl>
+
+<h2 id="preserveurls">Preserving URLs in HTML</h2>
+<p>
+PageSpeed filters often modify the URLs of resources in HTML pages. This is
+generally harmless but it has the potential to break pages whose JavaScript
+expects to read or modify the URLs in the page.
+</p>
+<p>
+image_preserve_urls, css_preserve_urls, and js_preserve_urls
+will suppress URL rewriting actions for the respective resource types. Those
+filters that require modifications to the URL are disabled by the preserve
+directives.
+</p>
+<p class="note">
+<strong>Note:</strong>
+Even though resource URLs are unchanged that does not mean that they cannot
+still be optimized. For instance,
+<a href="system#ipro">InPlaceResourceOptimization</a> still works since it does
+not alter URLs. Turning on in place resource optimization is recommended when
+enabling any of the options to preserve URLs. In version 1.9.32.1 and later
+in place resource optimization is enabled by default.
+</p>
+<p>
+Enabling image_preserve_urls will <a href="#forbidding">forbid</a>
+the use of the following filters:
+<code><a href="filter-inline-preview-images">inline_preview_images</a></code>,
+<code><a href="filter-lazyload-images">lazyload_images</a></code>,
+<code><a href="filter-cache-extend">extend_cache_images</a></code>,
+<code><a href="filter-image-optimize#inline_images">inline_images</a></code>,
+and <code><a href="filter-image-sprite">sprite_images</a></code>.
+</p>
+<p>
+Enabling css_preserve_urls will <a href="#forbidding">forbid</a> the use
+of the following filters:
+<code><a href="filter-css-combine">combine_css</a></code>,
+<code><a href="filter-cache-extend">extend_cache_css</a></code>,
+<code><a href="filter-css-inline">inline_css</a></code>,
+<code><a href="filter-css-inline-import">inline_import_to_link</a></code>,
+and <code><a href="filter-css-outline">outline_css</a></code>.
+</p>
+<p>
+Enabling js_preserve_urls will <a href="#forbidding">forbid</a> the use
+of the following filters:
+<code><a href="filter-canonicalize-js">canonicalize_javascript_libraries</a></code>,
+<code><a href="filter-js-combine">combine_javascript</a></code>,
+<code><a href="filter-js-defer">defer_javascript</a></code>,
+<code><a href="filter-cache-extend">extend_cache_javascript</a></code>,
+<code><a href="filter-js-inline">inline_javascript</a></code>,
+and <code><a href="filter-js-outline">outline_javascript</a></code>.
+</p>
+
+<h2 id="RewriteRandomDropPercentage">Reducing Load by Randomly Dropping
+Expensive Rewrites</h2>
+To reduce processing load, PageSpeed can be configured to optimize
+the most frequently fetched resources, leaving infrequently fetched
+resources alone. This is accomplished by randomly dropping expensive
+(CSS and image) rewrites. Frequently fetched resources will have a higher
+probability of being rewritten than infrequently fetched resources.
+Over time, frequently accessed resources will be optimized and cached so
+a page will be fully optimized. Infrequently accessed pages will be left
+unoptimized or partially optimized, saving CPU time and cache space.
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedRewriteRandomDropPercentage Percent</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed RewriteRandomDropPercentage Percent;</pre>
+</dl>
+<p>
+This is a load-tuning parameter (integer between 0 and 100 inclusive)
+that controls the percentage of resource rewrites that are randomly
+dropped. Currently only CSS and image rewrites are randomly dropped,
+as they are the CPU intensive rewrite tasks. A value of 100 means all
+such rewrites are dropped and a value of 0 means no rewrites are
+dropped. A value of 75 means that 75% of image and CSS rewrites
+(selected at random) are dropped. Do not set this parameter to 100 in
+order prevent optimization of images and CSS files, it is more efficient
+to instead disable the image and/or CSS filters.
+</p>
+<p>
+As an example, if the value is 90 then an image fetched only once will
+be optimized with 10% probability while an image fetched 50 times
+will be optimized with 99.65% probability (1 - 0.9^50). You
+may need to tune this parameter to find a value that provides the
+right load on your servers and still provides sufficient image and CSS
+optimization.
+</p>
+<p class="note"><strong>Note: Images within CSS files are not randomly dropped
+as this would lead to partially optimized CSS resources.</strong></p>
+
+<h2 id="multi_server">Configuring for Multiple Servers</h2>
+<p>
+When running PageSpeed on multiple servers, it is important that
+each have the same configuration file. This ensures that when a
+browser requests an image or other resource from one server, it will
+be optimized using the same options that were used to compute the
+optimized resource when HTML was served. It is helpful to
+use <a href="system.html#memcached">memcached</a> to share cache
+between servers as it improves multi-server performance and
+scalability, but it is still important that the configurations are
+consistent to get the desired behavior when optimized images are
+evicted from cache.
+</p>
+
+<p>
+Note also that <a href="configuration#htaccess">location-specific configuration
+settings</a> should be consistent between the HTML paths and the resource
+paths.</p>
+
+<p id="add_options_to_urls" class="note">
+
+<p>In some sites, the URL path layout or network deployment strategy may
+not allow for consistent configuration between HTML and images.
+PageSpeed offers a workaround for such sites by encoding relevant
+configuration settings for each rewritten resource into the URLs:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeedAddOptionsToUrls on</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">pagespeed AddOptionsToUrls on;</pre>
+</dl>
+
+<p>
+This adds an encoding of the options that are relevant to each rewritten
+resource to the URLs. While the produced URLs are larger, this provides a
+mechanism to propagate configuration without having to share a configuration
+file. For example, a site with image recompression on and JPEG compression set
+to 85 would see URLs like
+<code>http://example.com/ximage.jpg.pagespeed.gp+jw+pj+rj+rp+rw+iq=85.ic.HASH.jpg</code>.
+While it is better to have the extra configuration details in the configuration
+file, this option offers a fallback plan when that is not practical.
+</p>
+
+<h2 id="custom-fetch-headers">Custom Fetch Headers</h2>
+
+<p>
+When not using <a href="domains#ModPagespeedLoadFromFile"
+>LoadFromFile</a>, PageSpeed has to make HTTP requests for sub-resources of a
+>page in order to rewrite them. Consider the following HTML snippet:
+</p>
+<pre class="prettyprint">
+ ...
+ <body>
+ <img src="example.jpg">
+ ...
+</pre>
+<p>
+If the <a href="filter-image-optimize">rewrite_images</a>
+filter is enabled, PageSpeed needs to fetch <code>example.jpg</code> in order
+to inline, compress, or otherwise optimize it. If you would like custom
+headers to be sent with all sub-resource fetches like this one, you can use
+the <code>CustomFetchHeader</code> directive:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedCustomFetchHeader CustomHeader CustomHeaderValue
+ModPagespeedCustomFetchHeader AnotherCustomHeader AnotherValue</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed CustomFetchHeader CustomHeader CustomHeaderValue;
+pagespeed CustomFetchHeader AnotherCustomHeader AnotherValue;</pre>
+</dl>
+
+
+<h2 id="unsupported-filters">Unsupported Filters</h2>
+<p>
+The PageSpeed code base contains a number of additional filters whose use is
+unsupported. Some of these are experimental; note that using experimental
+filters is likely to result in crashes or site breakage. Others are used for
+debugging specific problems with PageSpeed:
+</p>
+ <table>
+ <thead><tr>
+ <th>Debugging filter name</th>
+ <th>Brief Description</th>
+ </tr></thead>
+ <tr>
+ <td><code>add_base_tag</code></td>
+ <td>
+ Adds a <code><base></code> element to the beginning of
+ the <code><head></code> that reflects the base url PageSpeed
+ is using to resolve relative url references in the page.</td>
+ </tr>
+ <tr>
+ <td id="debug"><code>debug</code></td>
+ <td>
+ Adds comments to the page describing actions by certain filters, and
+ attempts to serve JavaScript injected by PageSpeed in source form
+ rather than compiled and minified.
+ </td>
+ </tr>
+ <tr>
+ <td><code>deterministic_js</code></td>
+ <td>
+ Attempts to provide deterministic JavaScript behavior on each page, for
+ example by replacing the timer and random number generator with
+ functions that return the same sequence of values on every page load.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-strip-scripts">strip_scripts</a></code></td>
+ <td>
+ Removes all script tags from the document.</td>
+ </tr>
+ </table>
+<p class="note">
+<strong>Note: None of the above filters should be used to serve live traffic.</strong>
+</p>
+
+<h2 id="remote-configuration">Remote Configuration</h2>
+<p class="note"><strong>Note: New feature as of 1.10.33.0</strong></p>
+<p>
+PageSpeed filters and configurations can also be specified by an external
+"Remote Configuration" file. The remote configuration will override
+the main configuration file, override <code>.htaccess</code> configurations, and
+be overridden by any query-level parameters.
+<p>
+To specify the <code>RemoteConfigurationUrl</code>:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedRemoteConfigurationUrl https://example.com/remote.conf</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed RemoteConfigurationUrl https://example.com/remote.conf;</pre>
+</dl>
+<p>
+The syntax for the remote configuration file is similar to that of the
+<code>.htaccess</code> configurations with a few notable exceptions. Directives
+don't use <code>ModPagespeed</code> as a prefix. Comments are specified by
+<code>#</code> and must be on their own line. Filters and options with
+<code>DirectoryScope</code> or higher may be applied with the remote
+configuration. Any invalid lines in the remote configuration will be skipped, a
+warning will be logged, and the remaining lines will still be parsed. The remote
+configuration terminates with a line beginning with
+<code>EndRemoteConfig</code>, and any lines after this are ignored. If the
+configuration file does not contain a line beginning with
+<code>EndRemoteConfig</code> no configuration will be applied. An example
+configuration for enabling the <code>remove_comments</code> filter is as
+follows.
+<p>
+<pre>
+ # Enable the remove_comments filter.
+ EnableFilter remove_comments
+ EndRemoteConfig
+ # Everything after the previous line will be ignored.
+</pre>
+</p>
+<p>
+The remote configuration file will be fetched on the server's startup,
+and cached for the extent determined by the remote server's
+<code>Cache-Control</code> and <code> Expires</code> headers. For example, if
+the remote configuration hosting server provides the header
+<code>Cache-Control: max-age=3600</code>, the next fetch of the
+remote configuration will happen at the first request after 3600 seconds.
+Failed fetches after successful fetches will continue to serve the stale config.
+The remote configuration should be used in addition to your original
+configuration. The remote configuration is not guaranteed to be fetched and
+applied to every request, so the site should not rely on the remote
+configuration in order to work.
+</p>
+The timeout for the fetching the remote configuration file can also be
+specified. The default timeout is one second. To specify the fetching timeout.
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedRemoteConfigurationTimeoutMs 1500</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed RemoteConfigurationTimeoutMs 1500;</pre>
+</dl>
+Fetching the remote configuration will block for up to the specified timeout.
+<p class="note"><strong>Note:</strong>
+Remote configurations can not be fetched from the same server that is running
+the instance of pagespeed.
+</p>
+</p>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/configuration.html b/doc/configuration.html
new file mode 100644
index 0000000..619f199
--- /dev/null
+++ b/doc/configuration.html
@@ -0,0 +1,638 @@
+<!--
+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 Configuration</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>PageSpeed Configuration</h1>
+
+<h2 id="module">Enabling the Module</h2>
+<p>
+PageSpeed contains an "output filter" plus several content handlers.
+<p class="note">
+<strong>Note:</strong>
+The location of the configuration file is dependent both on the Linux
+distribution on which PageSpeed is installed and on whether you're using
+PageSpeed with Apache or Nginx.
+</p>
+
+<p>
+In Apache the configuration file
+is <code>pagespeed.conf</code> and will be in either:
+<pre>
+Debian/Ubuntu: /etc/apache2/mods-available/
+CentOS/Fedora: /etc/httpd/conf.d/
+</pre>
+In Nginx the configuration typically should go in your <code>nginx.conf</code>
+which for source installs defaults to being in:
+<pre>
+/usr/local/nginx/conf/
+</pre>
+</p>
+
+<p>
+In Apache PageSpeed is enabled automatically when you install the module while
+in Nginx you need to add several lines to your <code>nginx.conf</code>. In
+every <code>server</code> block where PageSpeed is enabled add:
+
+<pre>
+pagespeed on;
+
+# Needs to exist and be writable by nginx. Use tmpfs for best performance.
+pagespeed FileCachePath /var/ngx_pagespeed_cache;
+
+# Ensure requests for pagespeed optimized resources go to the pagespeed handler
+# and no extraneous headers get set.
+location ~ "\.pagespeed\.([a-z]\.)?[a-z]{2}\.[^.]{10}\.[^.]+" {
+ add_header "" "";
+}
+location ~ "^/pagespeed_static/" { }
+location ~ "^/ngx_pagespeed_beacon$" { }
+</pre>
+
+See the <a href="admin#config">Admin Page documentation</a> for
+instructions on how to configure handlers to provide visibility and
+control into PageSpeed's operation.
+
+<h2 id="on_off">Turning the module on and off</h2>
+<!-- keep old anchors so as not to break existing links -->
+<a name="on_off_nginx"></a><a name="nginx_specific"></a>
+
+<h3 id=on>Setting the module on</h3>
+
+<p>
+
+To turn PageSpeed on, just set:
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeed on</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">pagespeed on;</pre>
+</dl>
+
+<h3 id=standby>Setting the module to standby</h3>
+
+<p>
+
+PageSpeed has a standby mode where by default it won't make changes to your site
+but it will process two kinds of PageSpeed-specific requests:
+
+<ul>
+ <li><p>Requests with <a href="experiment#PerRequest">PageSpeed query
+ parameters</a>. These allow you to have PageSpeed off in your main
+ configuration, but manually make requests to see how your site would look
+ under various combinations of filters and options.
+ <li><p>Requests for <code>.pagespeed.</code> resources. When PageSpeed is
+ running it creates various kinds of optimized resources, and gives them
+ names containing <code>.pagespeed.</code>. If you turned
+ PageSpeed <a href="#unplugged">fully off</a> then lingering requests to
+ these resorces would fail. In standby mode these requests are still
+ served as if PageSpeed were enabled.
+</ul>
+
+<p>
+
+In versions 1.12 and earlier only mod_pagespeed supported standby mode, via
+the <code>off</code> setting:
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeed off</pre>
+</dl>
+
+<p>
+
+In versions 1.13.35.1 and later, both mod_pagespeed and ngx_pagespeed
+support <code>standby</code>:
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeed standby</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">pagespeed standby;</pre>
+</dl>
+
+<h3 id=unplugged>Setting the module fully off</h3>
+
+To turn PageSpeed fully off, set:
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeed unplugged</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">pagespeed unplugged;</pre>
+</dl>
+
+<p class=warning><b>Warning:</b> do not set ngx_pagespeed
+to <code>unplugged</code> in 1.12.34.1 and earlier. That will result in
+crashes. With those versions, use <code>off</code> instead
+of <code>unplugged</code>.
+
+<p>
+
+The <code>on</code>, <code>off</code>, and (in 1.13.35.1 and
+later) <code>standby</code> values can be used in
+<a href="#htaccess"><code>.htaccess</code> files,
+<code><Directory></code></a> scopes, <code>query parameters</code>, and
+<code>headers</code>. The <code>unplugged</code> value can only be used in the
+top-level Apache configuration and in virtual hosts. Note that
+<code>ModPagespeed on</code> in a virtual host can override a top-level
+<code>ModPagespeed unplugged</code> directive.
+</p>
+
+<h2 id="apache_specific">Apache-Specific Configuration</h2>
+
+<h3 id="output_filter">Setting up the Output Filter</h3>
+
+<p>
+The output filter is used to parse, optimize, and re-serialize HTML
+content that is generated elsewhere in the Apache server.
+</p>
+<pre class="prettyprint">
+# Direct Apache to send all HTML output to the mod_pagespeed output handler.
+AddOutputFilterByType MOD_PAGESPEED_OUTPUT_FILTER text/html
+</pre>
+<p class="note"><strong>Note:</strong> mod_pagespeed automatically enables
+<code>mod_deflate</code> for compression.
+</p>
+
+<h3 id="apache24">Support for Apache 2.4.x</h3>
+<p>
+<code>mod_pagespeed</code> is compatible with Apache 2.2.x and Apache 2.4.x
+series, versions 2.4.2 and newer. Please note that Apache 2.4.1 has a bug that
+may cause stability problems in combination with <code>mod_pagespeed</code>,
+so use with 2.4.1 is strongly discouraged.
+</p>
+
+<p>
+As Apache 2.4 is not API compatible with 2.2, support for it is provided
+via a separate module binary, <code>mod_pagespeed_ap24.so</code> instead of the
+usual <code>mod_pagespeed.so</code>. The configuration provided in our binary
+packages will normally load the right module version automatically. However,
+if you upgrade the CentOS packages from an earlier version, the needed
+configuration change may not get applied on top of a user-customized
+<code>pagespeed.conf</code>, so you may need to adjust the
+<code>LoadModule</code> line manually.
+</p>
+
+<p>
+Source builds with <code>mod_pagespeed</code>-provided Apache headers will
+build both 2.2.x and 2.4.x binaries as well, and you will need to add a
+<code>LoadModule</code> line matching the server version in use, or use
+a pattern similar to:
+<pre class="prettyprint">
+<IfModule !mod_version.c>
+ LoadModule version_module /usr/lib/apache2/modules/mod_version.so
+</IfModule>
+
+<IfVersion < 2.4>
+ LoadModule pagespeed_module /usr/lib/apache2/modules/mod_pagespeed.so
+</IfVersion>
+<IfVersion >= 2.4.2>
+ LoadModule pagespeed_module /usr/lib/apache2/modules/mod_pagespeed_ap24.so
+</IfVersion>
+</pre>
+to auto-detect. Builds against system Apache headers will only be compatible
+with that version family, and will always produce a single module named
+<code>mod_pagespeed.so</code>.
+</p>
+
+<h2 id="honor-csp">Honoring Content-Security-Policy Headers</h2>
+<p>
+ As of 1.13.35.1 PageSpeed is able to adapt its optimizations according to any
+ Content Security Policies specified in the response headers. In this release
+ you need to opt-in into this feature, future releases may turn it on by
+ default.
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeedHonorCsp on</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">pagespeed HonorCsp on;</pre>
+</dl>
+
+<h2 id="respectvary">Respecting Vary Headers</h2>
+<p>
+In order to maximize the number of resources that PageSpeed can rewrite, by
+default the module does not respect <code>Vary: User-Agent</code> and
+other <code>Vary</code> headers on resource files, such as JavaScript and css
+files. By disregarding the <code>Vary</code> headers, PageSpeed is able to keep
+the size of the cache down. PageSpeed will <em>always</em> respect <code>Vary:
+Accept-Encoding</code>, regardless of this setting. PageSpeed will
+also <em>always</em> respect <code>Vary</code> headers on <code>HTML</code>
+files, regardless of this setting.
+</p>
+<p>
+If a site has resources that legitimately vary on <code>User-Agent</code>, or
+on some other attribute, then in order to preserve that behavior, you must
+add</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeedRespectVary on</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">pagespeed RespectVary on;</pre>
+</dl>
+<p>to your configuration file.</p>
+<p>Please note that turning on this option will disable optimization of any
+resources with <code>Vary</code> headers, apart from
+<code>Vary: Accept-Encoding</code>.</p>
+
+<h2 id="notransform">Honoring no-transform Cache-Control Headers</h2>
+<p>
+By default, PageSpeed does not rewrite resources that have
+<code>Cache-Control: no-transform</code> set in the Response Header. This is
+true for all types of resources, such as JavaScript, images, CSS etc. By
+respecting <code>Cache-Control: no-transform</code> headers, PageSpeed cannot
+optimize resources that could otherwise be rewritten.
+</p>
+<p>
+To optimize resources irrespective of <code>Cache-Control: no-transform</code>
+headers, you must add</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeedDisableRewriteOnNoTransform off</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">pagespeed DisableRewriteOnNoTransform off;</pre>
+</dl>
+<p>to your configuration file.</p>
+<p>Please note that PageSpeed will always respect
+<code>Cache-Control: no-transform</code> headers on <code>HTML</code> files
+irrespective of the setting. And also, PageSpeed will always retain the
+<code>Cache-Control: no-transform</code> headers on the resource irrespective of
+the setting so that the downstream cache control mechanisms do not get affected.
+</p>
+
+<h2 id="lower_case">Lower-casing HTML element and attribute names</h2>
+<p>
+HTML is
+<a href="http://www.w3.org/TR/DOM-Level-2-HTML/html.html#ID-5353782642-h2">
+ case-insensitive</a>, whereas XML and XHTML are not. Web performance
+<a target="_blank" href="https://developers.google.com/speed/docs/best-practices/payload#consistency">Best Practices</a> suggest using lowercase
+keywords, and PageSpeed can safely make that transformation in HTML
+documents.
+</p>
+<p>
+In general, PageSpeed knows whether a document is HTML or not
+via <code>Content-Type</code> tags in HTTP headers, and <code>DOCTYPE</code>.
+However, many web sites have <code>Content-Type: text/html</code> for resources
+that are actually XML documents.
+</p>
+<p>
+If PageSpeed lowercases keywords in XML pages, it can break the consumers of
+such pages, such as Flash. To be conservative and avoid breaking such pages,
+PageSpeed does not lowercase HTML element and attribute names by
+default. However, you can sometimes achieve a modest improvement in the size of
+compressed HTML by enabling this feature with:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedLowercaseHtmlNames on</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed LowercaseHtmlNames on;</pre>
+</dl>
+
+<p>
+
+These directives can be used in <a href="#htaccess">location-specific
+configuration sections</a>.
+</p>
+
+<h3>Risks</h3>
+<p>
+This switch is only risky in the presence of XML files that are
+incorrectly served with <code>Content-type: text/html</code>.
+Lower-casing XML element and attribute may affect whatever software is
+reading the XML.
+</p>
+
+<h2 id="ModifyCachingHeaders">Preserving HTML caching headers</h2>
+<p>
+ By default, PageSpeed serves all HTML with
+ <code>Cache-Control: no-cache, max-age=0</code> because the transformations
+ made to the page may not be cacheable for extended periods of time.
+</p>
+<p>
+ If you want to force PageSpeed to leave the original HTML caching headers
+ you can add:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedModifyCachingHeaders off</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed ModifyCachingHeaders off;</pre>
+</dl>
+<p class="note">
+ <b>Note:</b> We do not suggest you turn this option off. It breaks PageSpeed's
+ caching assumptions and can lead to unoptimized HTML being served from a proxy
+ caches set up in front of the server. If you do turn it off, we suggest that
+ you do not set long caching headers to HTML or users may receive stale or
+ unoptimized content.
+</p>
+
+<h2 id="XHeaderValue">Specifying the value for the PageSpeed header</h2>
+<p>
+ By default, PageSpeed adds an header, <code>X-Mod-Pagespeed</code> in
+ Apache, <code>X-Page-Speed</code> in Nginx, with the version of PageSpeed
+ being used. The format of this header is:
+</p>
+
+<pre>[Major].[Minor].[Branch].[Point]-[Commit]</pre>
+
+<p>
+ For example:
+</p>
+
+<pre>1.9.32.3-4448</pre>
+
+<p>
+ We update these following this schedule:
+</p>
+
+<dl>
+ <dt>Major Version</dt>
+ <dd>Incremented when we make very large changes.</dd>
+
+ <dt>Minor Version</dt>
+ <dd>Incremented for each release since the last major version</dd>
+
+ <dt>Branch Number</dt>
+ <dd>Incremented for every release. Always increasing.</dd>
+
+ <dt>Point Number</dt>
+ <dd>Incremented each time we build a new release candidate or patch release,
+ resets on each minor release.</dd>
+
+ <dt>Commit Number</dt>
+ <dd>Incremented each time we accept a commit to the PSOL trunk. Always
+ increasing.</dd>
+</dl>
+
+<p>
+ All servers running a given release will have the same value for this header
+ by default. If you would like to change the value reported, you can use
+ the <code>XHeaderValue</code> directive to specify what to use instead:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedXHeaderValue "Powered By mod_pagespeed"</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed XHeaderValue "Powered By ngx_pagespeed";</pre>
+</dl>
+<p class="note">
+ <b>Note:</b> You cannot suppress the injection of this header. This is because
+ it is used to prevent infinite loops and unnecessary rewrites when PageSpeed
+ fetches resources from an origin that also uses PageSpeed.
+</p>
+
+<h2 id="htaccess">Location-Specific Configuration</h2>
+<p>With an <code>.htaccess</code> file (Apache), <code><Directory></code>
+scope (Apache), or <code>location</code> block (Nginx) you can control most of
+the PageSpeed directives. Note, however, that the
+file-matching is only relevant to the HTML file, and not to any of the resources
+referenced from the HTML file. To restrict resources by directory, you must use
+the PageSpeed <a href="/speed/pagespeed/module/restricting_urls"><code
+>Allow</code> and <code>Disallow</code> directives</a>, using full paths or
+wildcards in those directives.</p>
+
+<p class="warning">
+ <b>Warning:</b> Resources and the HTML files that reference them must have
+ the same options. If they differ you may see poor performance and
+ inconsistent application of options.
+</p>
+
+<p>In Apache, the advantage of <code>.htaccess</code> is that it can be used in
+environments where the site administrator does not have access to the server
+configuration. However, there is a significant per-request overhead from
+processing <code>.htaccess</code> files.
+See <a href="http://httpd.apache.org/docs/2.2/howto/htaccess.html">The Apache
+HTTP Server Documentation</a>:</p>
+
+<p class="note">
+<strong>Note:</strong> You should avoid using <code>.htaccess</code> files
+completely if you have access to the httpd main server config file. Using
+<code>.htaccess</code> files slows down your Apache server. Any directive
+that you can include in a <code>.htaccess</code> file is better set in a
+<a href="http://httpd.apache.org/docs/2.2/mod/core.html#directory"
+ ><code><Directory></code></a> block, as
+it will have the same effect with better performance.
+</p>
+<p>
+<a href="#virtual-hosts">Virtual hosts</a> are generally a better way of
+configuring multiple sites on the same server.
+</p>
+
+<h2 id="virtual-hosts">Using PageSpeed With Virtual Hosts</h2>
+
+<p>By default, PageSpeed enables itself for the entire server, with global
+options propagating to all
+<a href="http://httpd.apache.org/docs/current/vhosts/">VirtualHost</a>s
+(Apache) or <code>server</code> blocks (Nginx). Options can be overridden
+per host, including the ability the limit which hosts PageSpeed runs on.</p>
+
+<p class="note"><strong>Note:</strong>
+When using Apache, it used to be possible to set <code>InheritVHostConfig</code>
+to "off" to stop global configuration from propagating to VHosts. However,
+enabling <code>InheritVHostConfig</code> makes PageSpeed options behave like
+other Apache options and has been the recommended configuration since 2012. The
+option has now been deprecated and will be forced to "on" in the next major
+PageSpeed release.</p>
+
+<dl>
+<dt>Apache:<dd><pre class="prettyprint lang-sh">
+ModPagespeed On
+ModPagespeedInheritVHostConfig on
+ModPagespeedFileCachePath "/var/cache/mod_pagespeed/"
+ModPagespeedEnableFilters combine_css,combine_javascript
+# Direct Apache to send all HTML output to the mod_pagespeed
+# output handler.
+AddOutputFilterByType MOD_PAGESPEED_OUTPUT_FILTER text/html
+
+NameVirtualHost *:80
+<VirtualHost *:80>
+ DocumentRoot /www/example1
+ ServerName www.example1.com
+ ModPagespeedMapRewriteDomain cdn.example1.com *example.com
+</VirtualHost>
+
+<VirtualHost *:80>
+ DocumentRoot /www/example2
+ ServerName www.example2.org
+ ModPagespeedMapRewriteDomain cdn.example2.org *example.org
+ # Don't want combine_css here
+ ModPagespeedDisableFilters combine_css
+</VirtualHost>
+
+<VirtualHost *:80>
+ DocumentRoot /www/example3
+ ServerName www.example3.org
+ # mod_pagespeed off for this virtual host
+ ModPagespeed Off
+</VirtualHost>
+</pre>
+<dt>Nginx:<dd><pre class="prettyprint">
+http {
+ pagespeed On;
+ pagespeed FileCachePath "/var/cache/ngx_pagespeed/";
+ pagespeed EnableFilters combine_css,combine_javascript;
+
+ server {
+ listen 80;
+ server_name www.example1.com;
+ root /www/example1;
+ pagespeed MapRewriteDomain cdn.example1.com *example.com;
+ }
+
+ server {
+ listen 80;
+ server_name www.example2.org;
+ root /www/example2;
+ pagespeed MapRewriteDomain cdn.example2.org *example.org;
+ # Don't want combine_css here
+ pagespeed DisableFilters combine_css;
+ }
+
+ server {
+ listen 80;
+ server_name www.example3.org;
+ root /www/example3;
+
+ # mod_pagespeed off for this virtual host
+ pagespeed off;
+ }
+</pre>
+</dl>
+
+<h2 id="preserve-url-relativity">Preserve URL Relativity</h2>
+
+<p>
+ Previous versions of PageSpeed would rewrite relative URLs into absolute URLs.
+ This wastes bytes and can cause problems for sites that sit behind HTTPS
+ terminators.
+</p>
+<p>
+ With <code>PreserveUrlRelativity on</code>, PageSpeed will keep URLs the way
+ they were found. Some examples:
+</p>
+<table>
+ <tr>
+ <th>Original URL</th>
+ <th>Rewritten URL</th>
+ </tr><tr>
+ <td><code>foo/bar.png</code></td>
+ <td><code>foo/bar.png.pagespeed.ic.Hash.png</code></td>
+ </tr><tr>
+ <td><code>/bar.png</code></td>
+ <td><code>/bar.png.pagespeed.ic.Hash.png</code></td>
+ </tr><tr>
+ <td><code>//example.com/bar.png</code></td>
+ <td><code>//example.com/bar.png.pagespeed.ic.Hash.png</code></td>
+ </tr><tr>
+ <td><code>http://example.com/bar.png</code></td>
+ <td><code>http://example.com/bar.png.pagespeed.ic.Hash.png</code></td>
+ </tr>
+</table>
+</ul>
+<p>
+ To enable this option, add:
+</p>
+<dl>
+ <dt>Apache:
+ <dd><pre class="prettyprint">ModPagespeedPreserveUrlRelativity on</pre>
+ <dt>Nginx:
+ <dd><pre class="prettyprint">pagespeed PreserveUrlRelativity on;</pre>
+</dl>
+<p>to your configuration file.</p>
+<p>
+ Note: This option will be enabled by default in future versions of PageSpeed
+ and eventually the option will be removed entirely.
+</p>
+
+<h2 id="pagespeed_static">Configuring the location of static assets</h2>
+
+<p>
+ Several filters, including <a href="filter-js-defer">defer_javascript</a> and
+ <a href="filter-lazyload-images">lazyload_images</a>, require external
+ resources that must be loaded from somewhere. Before 1.8.31.2,
+ mod_pagespeed would load these files from <code>/mod_pagespeed_static</code>
+ while ngx_pagespeed would load them from <code>/ngx_pagespeed_static</code>.
+ In 1.8.31.2 the default was changed to <code>/pagespeed_static</code> for
+ both platforms and a directive was added to make the path configurable:
+</p>
+<dl>
+ <dt>Apache:
+ <dd><pre class="prettyprint"
+ >ModPagespeedStaticAssetPrefix /custom/static/</pre>
+ <dt>Nginx:
+ <dd><pre class="prettyprint"
+ >pagespeed StaticAssetPrefix /custom/static/;</pre>
+</dl>
+
+<h2 id="add-resource-header">Configuring headers for optimized resources</h2>
+<p>
+ When creating optimized <code>.pagespeed.</code> resources, PageSpeed
+ generates headers that are correct for most users. However, some users
+ require additional headers. For instance if you're
+ using <a
+ href="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing">CORS</a>
+ and you want to have PageSpeed set <code>Access-Control-Allow-Origin:
+ http://www.example.com</code> headers on the resources it creates, you can
+ set:
+</p>
+<dl>
+ <dt>Apache:
+ <dd><pre class="prettyprint"
+ >ModPagespeedAddResourceHeader "Access-Control-Allow-Origin" "http://www.example.com"</pre>
+ <dt>Nginx:
+ <dd><pre class="prettyprint"
+ >pagespeed AddResourceHeader "Access-Control-Allow-Origin" "http://www.example.com";</pre>
+</dl>
+<p>
+ If you have multiple headers you want inserted you can include
+ an <code>AddResourceHeader</code> directive for each one.
+<p>
+
+<h2 id="ListOutstandingUrlsOnError">List outstanding urls on error</h2>
+<p>
+ When debugging fetching, it can be useful to know how things are failing. If
+ you enable <code>ListOutstandingUrlsOnError</code> then PageSpeed will report
+ a message in the error log at level <code>"error"</code> for every URL fetch
+ in flight when the HTTP stack encounters a system error, e.g. "Connection
+ Refused". To enable this feature, set:
+</p>
+<dl>
+ <dt>Apache:
+ <dd><pre class="prettyprint">ModPagespeedListOutstandingUrlsOnError on</pre>
+ <dt>Nginx:
+ <dd><pre class="prettyprint">pagespeed ListOutstandingUrlsOnError on;</pre>
+</dl>
+
+<h2 id="reverse-proxy">Using PageSpeed as a reverse proxy</h2>
+<p>
+Typically, PageSpeed is used on an Apache or Nginx server that is already
+serving its own content. However, PageSpeed can be used with Nginx or Apache as
+a proxy for another server.
+</p>
+<p>
+With Apache and mod_pagespeed, <a href="http://httpd.apache.org/docs/2.2/mod/mod_proxy.html">
+ mod_proxy</a> can be used to configure Apache as a reverse proxy.
+</p>
+<p>
+With Nginx and ngx_pagespeed, <a href="http://nginx.com/resources/admin-guide/reverse-proxy/">
+ proxy_pass</a> can be used to configure Nginx as a reverse proxy.
+</p>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/console.html b/doc/console.html
new file mode 100644
index 0000000..fb7b95d
--- /dev/null
+++ b/doc/console.html
@@ -0,0 +1,223 @@
+<!--
+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 Console</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>PageSpeed Console</h1>
+<h2 id="about">About the Console</h2>
+<p>
+ The PageSpeed Console reports various problems your installation has that can
+ lead to sub-optimal performance. The console graphs metrics for these
+ problems over time so that you can see the result of your changes
+ improving or degrading your performance. You can view it by enabling it and
+ then visiting <code>/pagespeed_admin/console</code> from your server. The
+ console works by saving snapshots of the statistics reported by
+ PageSpeed and then using the Google Chart Tools API to graph those
+ statistics over time.
+<h2 id="configuring">Configuring the Console</h2>
+<p>
+ The PageSpeed Console is configured with several directives in the
+ configuration file. See
+ <a href="install#module">PageSpeed Installation and Configuration</a>
+ for details about this file. Each of these directives is explained here.
+</p>
+<ul>
+ <li>
+ <code><a href="admin#statistics">Statistics</a></code>
+ must be enabled to report statistics.</li>
+ <li>
+ <code>StatisticsLogging</code> must be enabled so that graphs of
+ statistics over time can be drawn in the console.</li>
+ <li>
+ <code>LogDir</code> must be set so that we have a directory to store
+ statistic logs.</li>
+ <li>
+ In order to access the console, you must set a handler appropriately.
+ For example, to make the console only accessible from localhost:
+ <dl>
+ <dt>Apache:<dd><pre>
+ModPagespeedStatistics on
+ModPagespeedStatisticsLogging on
+ModPagespeedLogDir /var/log/pagespeed
+<Location /pagespeed_admin>
+ Order allow,deny
+ Allow from localhost
+ Allow from 127.0.0.1
+ SetHandler pagespeed_admin
+</Location></pre>
+ <dt>Nginx:<dd><pre>
+pagespeed Statistics on;
+pagespeed StatisticsLogging on;
+pagespeed LogDir /var/log/pagespeed;
+pagespeed AdminPath /pagespeed_admin;
+
+location ~ ^/pagespeed_admin {
+ allow 127.0.0.1;
+ deny all;
+}</pre>
+ </dl>
+ </li>
+</ul>
+<p>
+ Additionally these optional parameters may be configured:
+</p>
+<ul>
+ <li>
+ <code>StatisticsLoggingIntervalMs</code> may be set to indicate how often
+ to log statistics snapshots (in milliseconds).</li>
+ <li>
+ <code>StatisticsLoggingMaxFileSizeKb</code> may be set to indicate the
+ maximum size for the logfile (in kilobytes).</li>
+</ul>
+<p>
+ For example, to log once a minute with a maximum log size of 1 MB:
+</p>
+<dl>
+ <dt>Apache:<dd><pre>
+ModPagespeedStatisticsLoggingIntervalMs 60000
+ModPagespeedStatisticsLoggingMaxFileSizeKb 1024</pre>
+ <dt>Nginx:<dd><pre>
+pagespeed StatisticsLoggingIntervalMs 60000;
+pagespeed StatisticsLoggingMaxFileSizeKb 1024;</pre>
+</dl>
+
+<h2 id="access">Accessing the Console</h2>
+<p>
+ The console can be accessed by browsing to
+ <code>http://your.example.com/pagespeed_admin/console</code>. Access to
+ this page can be controlled using standard access directives.
+</p>
+<p>
+ Note that if you would like to access the console from machines other
+ than your server, you will need to allow access to
+ <code>/pagespeed_admin</code>.
+</p>
+
+<!-- TODO(sligocki): Add section for features, like zooming in, etc. once we
+ add them. -->
+
+<h2 id="graphs">Graphed metrics</h2>
+The PageSpeed console displays graphs for these metrics:
+<ul>
+ <li id="fetch-failure">
+ <b>Resources not loaded because of fetch failures</b>:
+ Images, CSS or JavaScript could not be loaded because backend HTTP fetch
+ failed. <b>Remedy</b>: You may have to reconfigure your server to allow
+ outgoing connections or to have access to DNS.</li>
+
+ <li id="not-authorized">
+ <b>Resources not rewritten because domain wasn't authorized</b>:
+ Resources could not be rewritten because they were on a different domain
+ than the HTML and that domain was not explicitly authorized.
+ <b>Remedy</b>: Add <a href="domains#auth_domains">Domain</a>
+ authorizations for all domains you control.</li>
+
+ <li id="cache-control">
+ <b>Resources not rewritten because of restrictive Cache-Control headers</b>:
+ Resources could not be rewritten because they had restrictive Cache-Control
+ headers explicitly set (for example: <code>Cache-Control: private</code>,
+ <code>Cache-Control: max-age=0</code> or
+ <code>Cache-Control: no-transform</code>).
+ <b>Remedy</b>: Reconfigure your server to serve these resources with
+ public caching headers (or no Cache-Control headers at all). For example,
+ <code>Header set Cache-Control "max-age=600"</code> in Apache config.</li>
+
+ <li id="cache-miss">
+ <b>Cache misses</b>:
+ Resources were not rewritten because they were not found in cache.
+ This is expected while your cache warms up, soon after you install, however
+ if it continues to be high, your cache is probably too small.
+ <b>Remedy</b>: Increase the
+ <a href="system#file_cache">FileCacheSizeKb</a> to be about 5 times
+ as large as your website content (to store all of the original
+ resources and various versions of rewritten resources).</li>
+
+ <li id="cache-expired">
+ <b>Cache lookups that were expired</b>:
+ Although these resources were found in cache, they were not rewritten
+ because they were older than their max-age.
+ <b>Remedy</b>: (A) Enable
+ <a href="domains#ModPagespeedLoadFromFile">LoadFromFile</a> to tell
+ the server to load the files straight from disk rather than through
+ HTTP. (B) Reconfigure your server to serve resources with longer TTL.
+ For example, <code>Header set Cache-Control "max-age=3600"</code> to set
+ one hour TTL in Apache config.</li>
+
+ <li id="css-error">
+ <b>CSS files not rewritten because of parse errors</b>:
+ CSS files could not be rewritten because our parser found syntax errors
+ that it could not recover from. <b>Remedy</b>: Fix CSS files to use
+ proper syntax. You can use the stand-alone
+ <a href="build_mod_pagespeed_from_source#debug-css">css_minify_main</a>
+ to find what part of the CSS file has parse errors. We have had some
+ problems in the past with valid CSS3 or proprietary CSS extensions
+ causing CSS parsing errors. If you find that your valid CSS is failing to
+ parse, let us know on our <a href="mailing-lists#discussion">discussion
+ group</a> so we can fix the parser.</li>
+
+ <li id="js-error">
+ <b>JavaScript minification failures</b>:
+ JavaScript files could not be minified because our parser found some
+ syntax problem that it could not recover from. This is very uncommon.
+ <b>Remedy</b>: As with CSS, fix the JavaScript files that had problems.</li>
+
+ <li id="image-error">
+ <b>Image rewrite failures</b>:
+ Image files were not rewritten for various reasons:<ul>
+ <li><code>image_norewrites_high_resolution</code>: Image was too large.
+ Currently we only rewrite images below 8 Megapixels.
+ <b>Remedy</b>: Resize original images to a reasonable size.</li>
+ <li><code>image_rewrites_dropped_decode_failure</code>: Image could not
+ be parsed by our code. <b>Remedy</b>: Fix malformed images.</li>
+ <li><code>image_rewrites_dropped_due_to_load</code>: Image was not
+ rewritten because your system was already busy rewriting other images.
+ This generally can happen when you first install PageSpeed
+ while the cache warms up. <b>Remedy</b>: If image rewrites continue
+ to be dropped after a day or so, you may need to
+ <a href="#cache-miss">increase your cache size</a> or increase the
+ <a href="reference-image-optimize#ImageMaxRewritesAtOnce">
+ ImageMaxRewritesAtOnce</a>.</li>
+ <li><code>image_rewrites_dropped_mime_type_unknown</code>: Image could
+ not be rewritten because we do not recognize its MIME-type. For
+ example, we do not parse <code>image/x-icon</code> or
+ <code>image/svg+xml</code>. <b>Remedy</b>: Convert your images to a
+ type that we understand (gif, png, jpg, webp) or perhaps just fix
+ a broken server config that is serving images with a bogus
+ <code>Content-Type</code> header.</li>
+ <li><code>image_rewrites_dropped_server_write_fail</code>: Unexpected
+ server error while rewriting images. If you get a significant number
+ of these write to our <a href="mailing-lists#discussion">discussion
+ group</a> so we can investigate.</li>
+ </ul>
+ </li>
+</ul>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/doc.css b/doc/doc.css
new file mode 100644
index 0000000..e5352cb
--- /dev/null
+++ b/doc/doc.css
@@ -0,0 +1,212 @@
+/*
+ * 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.
+ */
+
+body {
+ font-family: sans-serif;
+ margin: 0;
+ padding: 0;
+ line-height: 1.5;
+ word-wrap: break-word;
+}
+
+a {
+ color: #0288d1;
+ text-decoration: none;
+}
+
+a:hover {
+ text-decoration: underline;
+}
+
+#header, #navline {
+ color: white;
+}
+
+#header a, #navline a {
+ color: white;
+}
+
+#logoline {
+ background-color: #0061ff;
+ padding: 1em;
+}
+
+#logo {
+ display: inline-block;
+ position: relative;
+ top: 4px;
+}
+
+#logotext {
+ font-size: 32px;
+ display: inline-block;
+}
+
+#navline a{
+ background-color: #3d87ff;
+ display: block;
+ padding: 0.5em 1em 0.5em 1em;
+}
+
+#content {
+ margin: 0.5em;
+ max-width: 50em;
+}
+
+code, pre {
+ background: #f7f7f7;
+ color: #37474f;
+}
+
+.note, .note code {
+ background: #e1f5fe;
+ color: #0288d1;
+}
+
+.note a {
+ color: #0288d1;
+ text-decoration: underline;
+}
+
+.caution, .caution code {
+ background: #fff3e0;
+ color: #dd2c00;
+}
+
+.caution a {
+ color: #dd2c00;
+ text-decoration: underline;
+}
+
+.warning, .warning code {
+ background: #fbe9e7;
+ color: #d50000;
+}
+
+.warning a {
+ color: #d50000;
+ text-decoration: underline;
+}
+
+.note, .caution, .warning {
+ padding: 1em;
+}
+
+pre {
+ padding: 1em;
+ overflow: auto;
+ line-height: 1.1;
+}
+
+table {
+ margin-top: 1em;
+ margin-bottom: 1em;
+ border-collapse: collapse;
+}
+
+th {
+ color: #fff;
+ vertical-align: middle;
+ background-color: #555;
+}
+
+td {
+ border-top: 1px solid #e0e0e0;
+ background-color: #f7f7f7;
+}
+
+th, td {
+ padding: 1em;
+}
+
+li {
+ margin-top: 0.5em;
+ margin-bottom: 0.5em;
+}
+
+img {
+ max-width: 100%;
+}
+
+.table-wrapper {
+ max-width: 100%;
+ overflow: auto;
+}
+
+#downloads .download {
+ margin-top: 0.5em;
+ margin-bottom: 0.5em;
+}
+
+#toc {
+ border-left: 4px solid #0061ff;
+ font-size: 0.9em;
+ max-width: 25em;
+ margin-top: 1em;
+ margin-left: 1em;
+}
+
+#toc-contents {
+ color: #757575;
+ font-weight: bold;
+ padding-left: 1em;
+}
+
+#toc ul {
+ list-style: none;
+ list-style-position: inside;
+ padding-left: 1em;
+}
+
+@media screen and (min-width: 55em) {
+ #toc {
+ float: right;
+ max-width: 18em;
+ padding-right: 1em;
+ }
+}
+
+.header-link {
+ visibility: hidden;
+ font-size: 80%;
+}
+
+h2:hover .header-link,
+h3:hover .header-link,
+h4:hover .header-link,
+h5:hover .header-link,
+h6:hover .header-link {
+ visibility: initial;
+ text-decoration: none;
+}
+
+.column {
+ margin: 0.5em;
+}
+
+.columns {
+ max-width: 75em;
+}
+
+@media screen and (min-width: 50em) {
+ .column {
+ display: inline-block;
+ vertical-align: top;
+ }
+}
diff --git a/doc/domains.html b/doc/domains.html
new file mode 100644
index 0000000..eef8c60
--- /dev/null
+++ b/doc/domains.html
@@ -0,0 +1,1025 @@
+<!--
+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 Authorizing and Mapping Domains</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>PageSpeed Authorizing and Mapping Domains</h1>
+<h2 id="auth_domains">Authorizing domains</h2>
+<p>
+In addition to optimizing HTML resources, PageSpeed restricts itself to
+optimizing resources (JavaScript, CSS, images) that are served from domains,
+with optional paths, that must be explicitly listed in the configuration file.
+For example:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedDomain http://example.com
+ModPagespeedDomain cdn.example.com
+ModPagespeedDomain http://styles.example.com/css
+ModPagespeedDomain *.example.org</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed Domain http://example.com;
+pagespeed Domain cdn.example.com;
+pagespeed Domain http://styles.example.com/css;
+pagespeed Domain *.example.org;</pre>
+</dl>
+
+<p>
+PageSpeed will rewrite resources found from these explicitly
+listed domains, although in the case of <code>styles.example.com</code>
+only resources under the <code>css</code> directory will be rewritten.
+Additionally, 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.
+</p>
+
+<p>The leading "http://" is optional; bare hostnames will be interpreted
+as referring to HTTP. Wildcards can be used in the domain.</p>
+
+<p>
+These directives can be used
+in <a href="configuration#htaccess">location-specific configuration
+sections</a>.
+</p>
+
+
+<h2 id="mapping_origin">Mapping origin domains</h2>
+
+<p>In order to improve the performance of web pages, PageSpeed
+must examine and modify the content of resources referenced on those
+pages. To do that, it must fetch those resources using HTTP, using
+the URL reference specified on the HTML page.</p>
+
+<p>In some cases, the URL specified in the HTML file is not the best URL to use
+to fetch the resource. Scenarios where this is a concern include:</p>
+<ol>
+ <li>If the server is behind a load balancer, and it's more efficient to
+ reference the server directly by its IP address, or as 'localhost'.</li>
+ <li>The server has a special DNS configuration</li>
+ <li>The server is behind a firewall preventing outbound connections</li>
+ <li>The server is running in a CDN or proxy, and must go back to the
+ origin server for the resources</li>
+ <li>The server needs to service https requests</li>
+</ol>
+
+<p>In these situations the remedy is to map the origin domain:</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedMapOriginDomain origin_to_fetch_from origin_specified_in_html [host_header]</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed MapOriginDomain origin_to_fetch_from origin_specified_in_html [host_header];</pre>
+</dl>
+
+<p>Wildcards can also be used in the <code>origin_specified_in_html</code>, e.g.
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedMapOriginDomain localhost *.example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed MapOriginDomain localhost *.example.com;</pre>
+</dl>
+
+<p>The <code>origin_to_fetch_from</code> can include a path after the domain
+name, e.g.</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedMapOriginDomain localhost/example *.example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed MapOriginDomain localhost/example *.example.com;</pre>
+</dl>
+
+<p>When a path is specified, the source domain is mapped to the destination
+domain and the source path is mapped to the concatenation of the path from
+<code>origin_to_fetch_from</code> and the source path. For example, given the
+above mapping, <code>http://www.example.com/index.html</code> will be mapped
+to <code>http://localhost/example/index.html</code>.</p>
+
+<p>The origin_specified_in_html can specify https but the origin_to_fetch_from
+can only specify http, e.g.</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedMapOriginDomain http://localhost https://www.example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed MapOriginDomain http://localhost https://www.example.com;</pre>
+</dl>
+
+<p>This directive lets the server accept https requests for
+<code>www.example.com</code> without requiring a SSL certificate to fetch
+resources. For example, given the above mapping, and assuming the server is
+configured for https support, PageSpeed will fetch and optimize resources
+accessed using
+<code>https://www.example.com</code>, fetching the resources from
+<code>http://localhost</code>, which can be the same server process or a
+different server process.
+</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>
+ <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>
+</dl>
+
+<p>In this example the https origin domain is mapped to <code>localhost</code>
+<em>and</em> <a href="domains#shard">sharding</a> is used to parallelize
+downloads across hostnames. Note that the shards also specify https.</p>
+
+<p>By specifying a source domain in this directive, you are authorizing
+PageSpeed to rewrite resources found in that domain. For example, in the
+above directives, '*.example.com' gets authorized for rewrites from HTML files,
+but 'localhost' does not. See <a href="#auth_domains"><code
+>Domain</code></a>.</p>
+
+<p>When PageSpeed fetches resources from a mapped origin domain, it
+specifies the source domain in the <code>Host:</code> header in the
+request. You can override the <code>Host:</code> header value with the
+optional third parameter <code>host_header</code>. See
+<a href="#shared_cdn">Mapping Origins with a Shared Domain</a> for
+an example.</p>
+
+<p>
+ See also
+ <a href="#ModPagespeedLoadFromFile"><code>LoadFromFile</code></a>
+ to load origin resource directly from the filesystem and avoid an HTTP
+ connection altogether.
+</p>
+
+<p>
+These directives can be used
+in <a href="configuration#htaccess">location-specific configuration
+sections</a>.
+</p>
+
+
+<h2 id="mapping_rewrite">Mapping rewrite domains</h2>
+
+<p>When PageSpeed rewrites a resource, it updates the HTML to
+refer to the resource by its new name. Generally PageSpeed leaves
+the resource at the same origin and path that was originally found in
+the HTML. However, it is possible to map the domain of rewritten
+resources. Examples of why this might be desirable include:</p>
+
+<ol>
+ <li>Serving static content from cookieless domains, to reduce the size of
+ HTTP requests from the browser. See
+ <a target="_blank" href="https://developers.google.com/speed/docs/best-practices/payload">Minimizing Payload</a>
+ <li>To move content to a Content Delivery Network (CDN)</li>
+</ol>
+
+<p>This is done using the configuration file directive:</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedMapRewriteDomain domain_to_write_into_html \
+ domain_specified_in_html</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed MapRewriteDomain domain_to_write_into_html
+ domain_specified_in_html;</pre>
+</dl>
+
+<p>Wildcards can also be used in the <code>domain_specified_in_html</code>, e.g.
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedMapRewriteDomain cdn.example.com *example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed MapRewriteDomain cdn.example.com *example.com;</pre>
+</dl>
+
+<p>The <code>domain_to_write_into_html</code> can include a path after the
+domain name, e.g.</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedMapRewriteDomain cdn.com/example *.example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed MapRewriteDomain cdn.com/example *.example.com;</pre>
+</dl>
+
+<p>When a path is specified, the source domain is rewritten to the destination
+domain and the source path is rewritten to the concatenation of the path from
+<code>domain_to_write_into_html</code> and the source path. For example, given
+the above mapping, <code>http://www.example.com/index.html</code> will be
+rewritten to <code>http://cdn.com/example/index.html</code>.</p>
+
+<p class="note" id="equiv_servers">
+<strong>Note:</strong> It is the responsibility of the site administrator to
+ensure that PageSpeed is installed on
+the <code>domain_to_write_into_html</code>. This might be a separate server, or
+there may be a single server with multiple domains mapped into it. The files
+must be accessible via the same path on the destination server as was specified
+in the HTML file. No other files should be stored on the
+<code>domain_to_write_into_html</code> -- it should be functionally equivalent
+to <code>domain_specified_in_html</code>. See
+also <a href="#MapProxyDomain">MapProxyDomain</a> which enables proxying content
+from a different server.</p>
+
+<p>For example, if PageSpeed
+cache_extends <code>http://www.example.com/styles/style.css</code> to
+<code>http://cdn.example.com/styles/style.css.pagespeed.ce.HASH.css</code>,
+then <code>cdn.example.com</code> will have to have a mechanism in place to
+either rewrite that file in place, or refer back to the origin server to
+pull the rewritten content.
+</p>
+
+<p class="note">
+<strong>Note:</strong> It is the responsibility of the site
+administrator to ensure that moving resources onto domains does not
+create a security vulnerability. In particular, if the target domain
+has cookies, then any JavaScript loaded from a resource moved to a
+domain with cookies will gain access to those cookies. In general,
+moving resources to a cookieless domain is a great way to improve
+security. Be aware that CSS can load JavaScript in certain environments.
+</p>
+
+<p>By specifying a domain in this directive, either as source or destination,
+you are authorizing PageSpeed to rewrite resources found in this
+domain. See <a href="#auth_domains"><code>Domain</code></a>.</p>
+
+<p>These directives can be used
+in <a href="configuration#htaccess">location-specific configuration
+sections</a>.</p>
+
+<h3 id="shared_cdn">Mapping Origins with a Shared CDN</h3>
+
+<p>Consider a scenario where an installation serving multiple domains
+uses a single CDN for caching and delivery of all content. The origin
+fetches need to be routed to the correct VirtualHost on the server.
+This can be achieved by using a subdirectory per domain in the
+CDN, and then using that subdirectory to map to the correct
+VirtualHost at origin. The host-header control offered by the third
+argument to <a href="#mapping_origin">MapOriginDomain</a> makes this
+feasible.</p>
+
+<p>In the example below, resources with a domain of
+sharedcdn.example.com and path starting with /vhost1 will be fetched
+from localhost but with a <code>Host:</code> header value of
+vhost1.example.com. Without the third argument to MapOriginDomain,
+the <code>Host:</code> header would be sharedcdn.example.com.</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedMapOriginDomain localhost sharedcdn.example.com/vhost1 vhost1.example.com
+ModPagespeedMapRewriteDomain sharedcdn.example.com/vhost1 vhost1.example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed MapOriginDomain localhost sharedcdn.example.com/vhost1 vhost1.example.com;
+pagespeed MapRewriteDomain sharedcdn.example.com/vhost1 vhost1.example.com;</pre>
+</dl>
+
+<p>This would be used in conjunction with a VirtualHost setup for
+vhost1.example.com, and a single CDN setup for multple hosts segregated by
+subdirectory.</p>
+
+<h2 id="shard">Sharding domains</h2>
+
+<p>Best practices suggest <a target="_blank" href="https://developers.google.com/speed/docs/best-practices/rtt"
+>minimizing round-trip times</a> by <a
+ target="_blank" href="https://developers.google.com/speed/docs/best-practices/rtt#ParallelizeDownloads"
+>parallelizing downloads across hostnames</a>. PageSpeed can partially
+automate this for resources that it rewrites, using the directive:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedShardDomain domain_to_shard shard1,shard2,shard3...</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed ShardDomain domain_to_shard shard1,shard2,shard3...;</pre>
+</dl>
+
+<p>Wildcards cannot be used in this directive.</p>
+
+<p>This will distribute the domains for rewritten URLs among the
+specified shards. The shard selected for a particular URL is computed
+from the original URL.</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedShardDomain example.com \
+ static1.example.com,static2.example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed ShardDomain example.com static1.example.com,static2.example.com;</pre>
+</dl>
+
+
+<p>
+Using this directive, PageSpeed will distribute roughly half the
+resources rewritten from example.com
+into <code>static1.example.com</code>, and the rest to
+<code>static2.example.com</code>. You can specify as many shards as
+you like. The optimum number of shards is a topic of active
+research, and is browser-dependent. Configuring between 2 and 4
+shards should yield good results. Changing the number of shards
+will cause PageSpeed to choose different names for resources,
+resulting in a partial cache flush.</p>
+
+<p>When used in combination with <code>RewriteDomain</code>, the Rewrite
+mappings will be done first. Then the shard selection occurs. Origin domains
+are always tracked so that when a browser sends a sharded URL back to the
+server, PageSpeed can find it.
+</p>
+<p>Let's look at an example:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedShardDomain example.com static1.example.com,static2.example.com
+ModPagespeedMapRewriteDomain example.com www.example.com
+ModPagespeedMapOriginDomain localhost example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed ShardDomain example.com static1.example.com,static2.example.com;
+pagespeed MapRewriteDomain example.com www.example.com;
+pagespeed MapOriginDomain localhost example.com;</pre>
+</dl>
+
+<p>In this example, <code>example.com</code>
+and <code>www.example.com</code> are "tied" together via
+<code>MapRewriteDomain</code>. The origin-mapping
+to <code>localhost</code> propagates automatically
+to <code>www.example.com</code>, <code>static1.example.com</code>, and
+<code>static2.example.com</code>. So when PageSpeed cache-extends an HTML
+stylesheet reference <code>http://www.example.com/styles.css</code>, it will be:
+</p>
+<ol>
+ <li>Fetched by the server rewriting the HTML
+ from <code>localhost</code></li>
+ <li>Rewritten to
+ <code>http://example.com/styles.css.pagespeed.ce.HASH.css</code></li>
+ <li>Sharded to
+ <code>http://static1.example.com/styles.css.pagespeed.ce.HASH.css</code>
+ </li>
+</ol>
+
+<h2 id="MapProxyDomain">Proxying and optimizing resources from
+ trusted domains</h2>
+
+<p>
+ Proxying resources is desirable under several scenarios:
+</p>
+<ul>
+ <li>The resources on the origin domain may benefit from optimizations
+ done by PageSpeed.</li>
+ <li>SPDY may work better if there are fewer domains on a page.</li>
+ <li>The target domain running PageSpeed may have better serving
+ infrastructure than the origin.</li>
+</ul>
+<p>
+ It is possible to proxy and optimize resources whose origin is a trusted
+ domain that may not be running PageSpeed. This cannot be directly achieved
+ with MapRewriteDomain because that is a declaration that the domains listed
+ are functionally equivalent to one another, either because they are backed by
+ the same storage, or because the target is acting as a proxy (e.g. a
+ CDN). <code>MapProxyDomain</code> makes it technically possible to proxy and
+ optimize resources from any domain <b>that you trust</b>.
+
+<p class="warning">
+ You must only proxy resources that are controlled by an organization
+ you <b>trust</b> because it is possible for malicious content (e.g.
+ <a href="http://hackaday.com/2008/08/04/the-gifar-image-vulnerability/"
+ >GIFAR</a>)
+ proxied from an untrustworthy domain to gain access to private
+ content on your domain, compromising your site or its viewers. You
+ must never map directories that may contain files that may be
+ controlled by a third party.
+</p>
+<p class="warning">
+ There may be legal issues restricting the optimization of resources
+ you don't own. If in doubt consult a lawyer.
+ {# TODO(jmarantz): it should be possible to use this directive in #}
+ {# combination with Disallow & rewrite_domains to proxy without #}
+ {# optimizing. A demo/test of that will be left for a follow-up. #}
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedMapProxyDomain target_domain/subdir \
+ origin_domain/subdir [rewrite_domain/subdir]
+</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed MapProxyDomain target_domain/subdir
+ origin_domain/subdir [rewrite_domain/subdir];</pre>
+</dl>
+
+<p>
+If the optional rewrite_domain/subdir argument is supplied then optimized
+resources will be rewritten to that location. This is useful for rewriting
+optimized resources proxied from an external origin to a CDN.
+</p>
+<p>
+ It is important to specify a subdirectory in the target domain, because
+ PageSpeed will need to be able to unambiguously identify the
+ origin domain given the target when fetching content. Thus each
+ MapProxyDomain command should be given a distinct subdirectory
+ of the target domain.
+</p>
+<p>
+ It is important to specify a subdirectory in the origin domain to
+ limit the scope of the proxying. For example,
+ in <a href="https://picasaweb.google.com">picasaweb</a>, all of a user's
+ photos are underneath a single subdirectory; it is critical not to enable
+ proxying for the entire site.
+</p>
+<h3>Example</h3>
+<p>
+You can see proxy-mapping in action at <code>www.modpagespeed.com</code> on this
+<a href="https://www.modpagespeed.com/examples/proxy_external_resource.html">example</a>.
+</p>
+
+<h2 id="fetch_servers">Fetch server restrictions</h2>
+ <p> PageSpeed will only fetch resources from <code>localhost</code> and
+ domains explicitly mentioned in domain configuration directives such
+ as <code>Domain</code>, <code>MapRewriteDomain</code>
+ and <code>MapOriginDomain</code>. As this security restriction is not
+ desirable for some large deployments, in Apache it is possible to disable it
+ starting from 0.10.22.7, via the following configuration directive (which has
+ a global effect): <pre class="prettyprint"
+ >ModPagespeedDangerPermitFetchFromUnknownHosts on</pre>
+
+ <p class="warning"><strong>Warning: </strong>Enabling
+ <code>DangerPermitFetchFromUnknownHosts</code> could permit
+ hostile third parties to access any machine and port that the server running
+ mod_pagespeed has access to, including potentially those behind firewalls.
+ </p>
+ Before doing this, however, it must be ensured that at least one of these
+ things is true:
+ <ol>
+ <li>The server running mod_pagespeed has no more access to machines or
+ ports than anyone on the Internet, and that machines it can access will
+ not treat its traffic specially (mod_pagespeed 0.10.22.6 and newer will
+ make sure its own traffic to <code>localhost</code> does not appear to be
+ local, but that does not work across machines)</li>
+ <li>Every virtual host in Apache running mod_pagespeed (and, if applicable,
+ the global configuration) has an accurate explicit <code>ServerName</code>,
+ and sets the options <code>UseCanonicalName</code> and
+ <code>UseCanonicalPhysicalPort</code> to <code>On</code>.
+ <li>A proxy running in front of the mod_pagespeed server fully verifies that
+ the URLs and <code>Host:</code> headers that reach it refer only to machines
+ the mod_pagespeed server is expected to contact.
+ </ol>
+ If possible, you are strongly encouraged to use
+ <code>MapOriginDomain</code> in preference to this switch.
+</p>
+
+<h2 id="url-valued-attributes">Specifying additional URL-valued attributes</h2>
+
+<p>
+ All PageSpeed filters that process URLs need to know which attributes of
+ which elements to consider. By default they consider those in the HTML4 and
+ HTML5 specifications and a few common extensions:
+</p>
+<pre class="prettyprint">
+ <a href=...>
+ <area href=...>
+ <audio src=...>
+ <blockquote cite=...>
+ <body background=...>
+ <button formaction=...>
+ <command icon=...>
+ <del cite=...>
+ <embed src=...>
+ <form action=...>
+ <frame src=...>
+ <html manifest=...>
+ <iframe src=...>
+ <img src=...>
+ <input type="image" src=...>
+ <ins cite=...>
+ <link href=...>
+ <q cite=...>
+ <script src=...>
+ <source src=...>
+ <td background=...>
+ <th background=...>
+ <table background=...>
+ <tbody background=...>
+ <tfoot background=...>
+ <thead background=...>
+ <track src=...>
+ <video src=...>
+</pre>
+<p>
+ If your site uses a non-standard attribute for URLs, PageSpeed won't
+ know to rewrite them or the resources they reference. To identify them to
+ PageSpeed, use the <code>UrlValuedAttribute</code> directive.
+ For example:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedUrlValuedAttribute span src hyperlink
+ModPagespeedUrlValuedAttribute div background image</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed UrlValuedAttribute span src hyperlink;
+pagespeed UrlValuedAttribute div background image;</pre>
+</dl>
+
+<p>
+ These would identify <code><span src=...></code> and <code><div
+ background=...></code> as containing URLs. Further,
+ the <code>background</code> attribute of <code>div</code> elements would be
+ treated as referring to an image and would be treated just like an image
+ resource referenced with <code><img src=...></code>. The general form
+ is:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedUrlValuedAttribute ELEMENT ATTRIBUTE CATEGORY</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed UrlValuedAttribute ELEMENT ATTRIBUTE CATEGORY;</pre>
+</dl>
+
+<p>
+ All fields are case-insensitive.
+ <span id="categories">Valid categories are:</span>
+ <ul>
+ <li><code>script</code></li>
+ <li><code>image</code></li>
+ <li><code>stylesheet</code> (As of 1.12.34.1)</li>
+ <li><code>otherResource</code>
+ <ul><li>Any other URL that will be automatically loaded by the
+ browser along with the main page. For example,
+ the <code>manifest</code> attribute of the <code>html</code>
+ element or the <code>src</code> attribute of
+ an <code>iframe</code> element.</li></ul>
+ </li>
+ <li><code>hyperlink</code>
+ <ul><li>A link to another page or resource that a browser wouldn't
+ normally load in connection to this page (like
+ the <code>href</code> attribute of an <code>a</code> element).
+ These URLs will still be rewritten
+ by <code>MapRewriteDomain</code> and similar directives, but they
+ will not be sharded and PageSpeed will not load the URL and
+ rewrite the resource.</li></ul>
+ </li>
+ </ul>
+ When in doubt, <code>hyperlink</code> is the safest choice.
+
+<p class="note">
+ <b>Note:</b> Until 1.12.34.1, <code>stylesheet</code> was accepted by the
+ configuration parser, but was non-functional.
+</p>
+
+</p>
+
+<h2 id="ModPagespeedLoadFromFile">Loading static files from disk</h2>
+<p>
+ By default PageSpeed loads sub-resources via an HTTP fetch. It would be
+ faster to load sub-resources directly from the filesystem, however this may
+ not be safe to do because the sub-resources may be dynamically generated or
+ the sub-resources may not be stored on the same server.
+</p>
+<p>
+ However, you can explicitly tell PageSpeed to load static sub-resources from
+ disk by using the <code>LoadFromFile</code> directive. For example:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedLoadFromFile "http://www.example.com/static/" \
+ "/var/www/static/"</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed LoadFromFile "http://www.example.com/static/"
+ "/var/www/static/";</pre>
+</dl>
+
+<p>
+ tells PageSpeed to load all resources whose URLs start
+ with <code>http://www.example.com/static/</code> from the filesystem
+ under <code>/var/www/static/</code>. For
+ example, <code>http://www.example.com/static/images/foo.png</code> will be
+ loaded from the file <code>/var/www/static/images/foo.png</code>.
+ However, <code>http://www.example.com/bar.jpg</code> will still be fetched
+ using HTTP.
+</p>
+<p>
+ If you need more sophisticated prefix-matching behavior, you can use
+ the <code>LoadFromFileMatch</code> directive, which
+ supports <a href="https://github.com/google/re2/wiki/Syntax">RE2-format</a>
+ regular expressions. (Note that this is not the same format as the wildcards
+ used above and elsewhere in PageSpeed.) For example:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedLoadFromFileMatch "^https?://example.com/~([^/]*)/static/" \
+ "/var/www/static/\\1"</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed LoadFromFileMatch "^https?://example.com/~([^/]*)/static/"
+ "/var/www/static/\\1";</pre>
+</dl>
+
+<p>
+ Will load <code>http://example.com/~pat/static/cat.jpg</code> from
+ <code>/var/www/static/pat/cat.jpg</code>,
+ <code>http://example.com/~sam/static/images/dog.jpg</code> from
+ <code>/var/www/static/sam/images/dog.jpg</code>, and
+ <code>https://example.com/~al/static/css/ie</code> from
+ <code>/var/www/static/al/css/ie</code>. The resource
+ <code>http://example.com/~pat/images/static/puppy.gif</code>, however,
+ would not be matched by this directive and would be fetched using HTTP.
+</p>
+<p>
+ Because PageSpeed is loading the files directly from the filesystem, no custom
+ headers will be set. For example, no headers set with the <code>Header
+ set</code> (Apache) or <code>add_header</code> (Nginx) directives will be
+ applied to these resources. If you have resources that need to be served with
+ custom headers, such as <code>Cache-Control: private</code>, you need to
+ exclude them from <code>LoadFromFile</code>. For resources PageSpeed
+ rewrites <a href="system#ipro">in-place</a> it will set a 5-minute cache
+ lifetime by default, which you can adjust by
+ changing <a href="system#load_from_file_cache_ttl"><code
+ >LoadFromFileCacheTtlMs</code></a>.
+</p>
+<p>
+ Furthermore, the content type will be set based
+ upon only the filename extension and only for common filename extensions we
+ recognize (<code>.html</code>, <code>.css</code>, <code>.js</code>,
+ <code>.jpg</code>, <code>.jpeg</code>, ... see full
+ list: <a href="https://github.com/apache/incubator-pagespeed-mod/blob/master/pagespeed/kernel/http/content_type.cc">content_type.cc</a>).
+ Before 1.9.32.1, filenames with unrecognized extensions were served with no
+ <code>Content-Type</code> header; in 1.9.32.1 and later such filenames will
+ not be loaded from file and instead will fall back to ordinary fetching.
+</p>
+<p>
+ You can also use the <code>LoadFromFile</code> directive to
+ load HTTPS resources which would not be otherwise fetchable directly.
+ For example:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedLoadFromFile "https://www.example.com/static/" \
+ "/var/www/static/"</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed LoadFromFile "https://www.example.com/static/"
+ "/var/www/static/";</pre>
+</dl>
+
+<p>
+ The filesystem path must be an absolute path.
+</p>
+<p>
+ You can specify multiple <code>LoadFromFile</code> associations in
+ configuration files. Note that large numbers of such directives may impact
+ performance.
+</p>
+<p>
+ If the sub-resource cannot be loaded from file in the directory
+ specified, the sub-request will fail (rather than fall back to
+ HTTP fetch). Part of the reason for this is to indicate a configuration
+ error more clearly.
+</p>
+<p>
+ As an added benefit. If resources are loaded from file, the rewritten
+ versions will be updated immediately when you change the associated file.
+ Resources loaded via normal HTTP fetches are refreshed only when they
+ expire from the cache (by default every 5 minutes). Therefore, the
+ rewritten versions are only updated as often as the cache is refreshed.
+ Resources loaded from file are not subject to caching behavior because
+ they are accessed directly from the filesystem for every request for the
+ rewritten version.
+</p>
+
+<p>
+ See also <a href="#mapping_origin"><code>MapOriginDomain</code></a>.
+</p>
+
+<p>
+ This directive can <strong>not</strong> be used
+ in <a href="configuration#htaccess">location-specific configuration
+ sections</a>.
+</p>
+
+<h4 id="limiting-load-from-file">Limiting Direct Loading</h4>
+<p>
+ A mapping set up with <code>LoadFromFile</code> allows filesystem loading for
+ anything it matches. If you have directories or file types that cannot be
+ loaded directly from the filesystem, <code>LoadFromFileRule</code> lets you
+ add fine-grained rules to control which files will be loaded directly and
+ which will fall back to the standard process, over HTTP.
+</p>
+<p>
+ When given a URL PageSpeed first determines whether any LoadFromFile
+ mappings apply. If one does, it calculates the mapped filename and checks for
+ applicable LoadFromFileRules. Considering rules in the reverse order of
+ definition, it takes the first applicable one and uses that to determine
+ whether to load from file or fall back to HTTP.
+</p>
+<p>
+ Some examples may be helpful. Consider a website that is entirely static
+ content except for a <code>/cgi-bin</code> directory:
+</p>
+<pre>
+ /var/www/index.html
+ /var/www/pets.html
+ /var/www/images/cat.jpg
+ /var/www/stylesheets/main.css
+ /var/www/stylesheets/ie.css
+ /var/www/cgi-bin/guestbook.pl
+ /var/www/cgi-bin/visitcounter.pl
+</pre>
+<p>
+ While most of the site can be loaded directly from the
+ filesystem, <code>guestbook.pl</code> and <code>visitcounter.pl</code> are
+ perl files that need to be interpreted before serving. Adding a rule
+ disallowing the <code>/cgi-bin</code> directory tells us to fall back to HTTP
+ appropriately:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedLoadFromFile http://example.com/ /var/www/
+ModPagespeedLoadFromFileRule Disallow /var/www/cgi-bin/</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed LoadFromFile http://example.com/ /var/www/;
+pagespeed LoadFromFileRule Disallow /var/www/cgi-bin/;</pre>
+</dl>
+
+<p>
+ The <code>LoadFromFileRule</code> directive takes two arguments.
+ The first must be either <code>Allow</code> or <code>Disallow</code> while the
+ second is a prefix that specifies which filesystem paths it should apply to.
+ Because the default is to allow loading from the filesystem for all paths
+ listed in any <code>LoadFromFile</code> statement, most of the time you will
+ be using <code>Disallow</code> to turn off filesystem loading for some subset
+ of those paths. You would use <code>Allow</code> only after
+ a <code>Disallow</code> that was overly general.
+</p>
+<p>
+ Not all sites are well suited for prefix-based control. Consider a site with
+ PHP files mixed in with ordinary static files:
+</p>
+<pre>
+ /var/www/index.html
+ /var/www/webmail.php
+ /var/www/webmail.css
+ /var/www/blog/index.php
+ /var/www/blog/header.png
+ /var/www/blog/blog.css
+</pre>
+<p>
+ Blacklisting just the <code>.php</code> files so they fall back to an HTTP
+ fetch allows everything else to be loaded directly from the filesystem:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedLoadFromFile http://example.com/ /var/www/
+ModPagespeedLoadFromFileRuleMatch Disallow \.php$</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed LoadFromFile http://example.com/ /var/www/;
+pagespeed LoadFromFileRuleMatch Disallow \.php$;</pre>
+</dl>
+
+<p>
+ The <code>LoadFromFileRuleMatch</code> directive also takes two arguments.
+ The first is either <code>Allow</code> or <code>Disallow</code> and functions
+ just like for <code>LoadFromFileRule</code> above. The second argument,
+ however, is
+ a <a href="https://github.com/google/re2/wiki/Syntax">RE2-format</a> regular
+ expression instead of a file prefix. Remember to escape characters that have
+ special meaning in regular expressions. For example, if instead
+ of <code>\.php$</code> we had simply <code>.php$</code> then a file
+ named <code>example.notphp</code> would still be forced to load over HTTP
+ because "<code>.</code>" is special syntax for "match any single character".
+</p>
+<p>
+ Consider a site with the opposite problem: a few file types can be reliably
+ loaded from file but the rest need interpretation first. For example:
+</p>
+<pre>
+ /var/www/index.html
+ /var/www/site.css
+ /var/www/script-using-ssi.js
+ /var/www/generate-image.pl
+ /var/www/
+</pre>
+<p>
+ This site uses server side includes
+ (<a href="http://httpd.apache.org/docs/2.2/howto/ssi.html">Apache</a>,
+ <a href="http://wiki.nginx.org/HttpSsiModule">Nginx</a>)
+ in its javascript and <code>generate-image.pl</code> needs to be interpreted
+ to make images. The only resources on the site that are generally safe to
+ load are <code>.css</code> ones. By first blacklisting everything and then
+ whitelisting only the <code>.css</code> files, we can make PageSpeed do this:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedLoadFromFile http://example.com/ /var/www/
+ModPagespeedLoadFromFileRuleMatch disallow .*
+ModPagespeedLoadFromFileRuleMatch allow \.css$</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed LoadFromFile http://example.com/ /var/www/;
+pagespeed LoadFromFileRuleMatch disallow .*;
+pagespeed LoadFromFileRuleMatch allow \.css$;</pre>
+</dl>
+
+<p>
+ This works because order is significant: later rules take precedence over
+ earlier ones.
+</p>
+
+<h3 id="LoadFromFileScriptVariables">Script Variables with LoadFromFile</h3>
+<p class="note"><strong>Note: New feature as of 1.9.32.1</strong></p>
+<p class="note"><strong>Note: Nginx-only</strong></p>
+
+<p>
+ As of 1.9.32.1 Nginx <a href="http://nginx.org/en/docs/varindex.html">script
+ variables</a> are now supported with the various <code>LoadFromFile</code>
+ directives. Script support for those options makes it possible to configure a
+ generic mapping of http hosts to disk, to reduce the amount of configuration
+ required when you want to load as much from disk as possible but have a lot
+ of <code>server{}</code> blocks.
+</p>
+
+<p>
+ As an example, consider one server that hosts three sites, each of which have
+ a directory <code>/static</code> that holds static resources and can be loaded
+ from file. One way to configure this server would be:
+</p>
+
+<dl>
+ <dt>Nginx:<dd><pre class="prettyprint">
+http {
+ ...
+ server {
+ server_name a.example.com;
+ pagespeed LoadFromFile http://a.example.com/static /var/www-a/static;
+ ...
+ }
+ server {
+ server_name b.example.com;
+ pagespeed LoadFromFile http://b.example.com/static /var/www-b/static;
+ ...
+ }
+ server {
+ server_name c.example.com;
+ pagespeed LoadFromFile http://c.example.com/static /var/www-c/static;
+ ...
+ }
+}</pre>
+</dl>
+
+<p>
+ For three sites this is kind of annoying, but the more sites you have the
+ worse it gets. With <code>ProcessScriptVariables</code> you can define one
+ generic <code>LoadFromFile</code> mapping instead of defining each one
+ individually:
+</p>
+
+<dl>
+ <dt>Nginx:<dd><pre class="prettyprint">
+http {
+ ...
+ pagespeed ProcessScriptVariables on;
+ pagespeed LoadFromFile "http://$host/static" "$document_root/static";
+
+ server {
+ server_name a.example.com;
+ ...
+ }
+ server {
+ server_name b.example.com;
+ ...
+ }
+ server {
+ server_name c.example.com;
+ ...
+ }
+}</pre>
+</dl>
+
+<p>
+ This will use Nginx's <code>$host</code> and <code>$document_root</code>
+ script variables instead of requiring you to explicitly code each one.
+</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>
+
+<h3 id="risks">Risks</h3>
+<p>
+ This should only be used for completely static resources which do not
+ need any custom headers or special server processing. If non-static
+ resources exist in the specified directory, the source code will
+ be used without applying SSI includes, CGI generation, etc.
+ Furthermore, all the resources should have filenames with common
+ extensions for their Content-Type (Ex: .html, .css, .js, .jpg, .jpeg, ... see
+ full list: <a href="https://github.com/apache/incubator-pagespeed-mod/blob/master/pagespeed/kernel/http/content_type.cc">content_type.cc</a>).
+</p>
+
+<h2 id="inline_without_auth">Inlining resources without explicit authorization
+</h2>
+<p>
+ Several filters in PageSpeed operate by inlining content from resources into
+ the HTML: inline_css, inline_javascript and prioritize_critical_css are a
+ few of the filters that operate in this manner. If resources from
+ third-party domains are not authorized explicitly, the effectiveness of
+ these filters decreases. For instance, prioritize_critical_css attempts to
+ remove blocking CSS requests needed for the initial render by inlining
+ critical CSS snippets into the HTML, however, the CSS resources that are not
+ authorized will continue to block. This option allows such resources to
+ be inlined without having to authorize all the individual domains.
+</p>
+<p>
+ The <code>InlineResourcesWithoutExplicitAuthorization</code>
+ directive can be used to allow resources from third-party domains to be
+ inlined into the HTML without requiring explicit authorization for each
+ domain. This option is "off" by default, and takes a
+ comma-separated list of strings representing resource categories for which
+ the option should be enabled. The list of valid resource categories is
+ given <a href="#categories">here</a>. Currently, only Script and
+ Stylesheet resource types are supported for this option.
+</p>
+
+This option can be enabled as follows:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedInlineResourcesWithoutExplicitAuthorization Script,Stylesheet
+</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed InlineResourcesWithoutExplicitAuthorization Script,Stylesheet;
+</pre>
+</dl>
+
+ <p class="warning"><strong>Warning: </strong>Enabling
+ <code>InlineResourcesWithoutExplicitAuthorization</code> could permit
+ hostile third parties to access any machine and port that the server running
+ mod_pagespeed has access to, including potentially those behind firewalls.
+ Please read the following information for details.
+ </p>
+<p>
+ This directive should only be enabled if all of the following conditions are
+ met for the resource types for which this option is enabled:
+</p>
+<ol>
+<li>The webmaster is confident that the resources referenced on their pages are
+ from trusted domains only.
+</li>
+<li>The site does not allow user-injected resources for the enabled resource
+ types.
+</li>
+<li>Fetches from the PageSpeed server should have no
+ more access to machines or ports than anyone on the Internet, and machines it
+ can access should not treat its traffic specially. Specifically, the
+ PageSpeed servers should not be able to access anything that is internal to a
+ firewall. Please refer to <a href="#fetch_servers">
+ Fetch server restrictions</a> sections for more details.
+</li>
+</ol>
+
+<p>
+ Note that resources inlined into HTML via this option will not be accessible
+ directly via a pagespeed URL, since that involves different security risks.
+ Resources will also not be inlined into other non-HTML resources via this
+ option. This means that flatten_css_imports will not flatten third-party CSS
+ into another CSS resource, unless the relevant third-party domains are
+ authorized explicitly via one of the techniques mentioned in the previous
+ sections.
+</p>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/download.html b/doc/download.html
new file mode 100644
index 0000000..1b601f8
--- /dev/null
+++ b/doc/download.html
@@ -0,0 +1,133 @@
+<!--
+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>Installing From Packages</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Installing From Packages</h1>
+<p class="note">
+ If you're using Nginx you need
+ to <a href="build_ngx_pagespeed_from_source">build from source</a>. These
+ packages are Apache-only.
+</p>
+<p class="note">
+ Any releases offered here are pre-apache releases. The incubating project
+ is working to produce its first release.
+</p>
+
+<div id="downloads">
+<dl>
+ <dt>Latest Beta Version</dt>
+ <dd>
+<div class=download><a href="https://dl-ssl.google.com/dl/linux/direct/mod-pagespeed-beta_current_i386.deb">mod_pagespeed 32-bit .deb (Debian/Ubuntu)</a></div>
+<div class=download><a href="https://dl-ssl.google.com/dl/linux/direct/mod-pagespeed-beta_current_amd64.deb">mod_pagespeed 64-bit .deb (Debian/Ubuntu)</a></div>
+<div class=download><a href="https://dl-ssl.google.com/dl/linux/direct/mod-pagespeed-beta_current_i386.rpm">mod_pagespeed 32-bit .rpm (CentOS/Fedora)</a></div>
+<div class=download><a href="https://dl-ssl.google.com/dl/linux/direct/mod-pagespeed-beta_current_x86_64.rpm">mod_pagespeed 64-bit .rpm (CentOS/Fedora)</a></div>
+ </dd>
+ <dt>Latest Stable Version</dt>
+ <dd>
+<div class=download><a href="https://dl-ssl.google.com/dl/linux/direct/mod-pagespeed-stable_current_i386.deb">mod_pagespeed 32-bit .deb (Debian/Ubuntu)</a></div>
+<div class=download><a href="https://dl-ssl.google.com/dl/linux/direct/mod-pagespeed-stable_current_amd64.deb">mod_pagespeed 64-bit .deb (Debian/Ubuntu)</a></div>
+<div class=download><a href="https://dl-ssl.google.com/dl/linux/direct/mod-pagespeed-stable_current_i386.rpm">mod_pagespeed 32-bit .rpm (CentOS/Fedora)</a></div>
+<div class=download><a href="https://dl-ssl.google.com/dl/linux/direct/mod-pagespeed-stable_current_x86_64.rpm">mod_pagespeed 64-bit .rpm (CentOS/Fedora)</a></div>
+ </dd>
+</dl>
+</div>
+
+<h3>Supported platforms</h3>
+<ul>
+<li>CentOS/Fedora (32-bit and 64-bit)</li>
+<li>Debian/Ubuntu (32-bit and 64-bit)</li>
+</ul>
+
+<p>To install the packages, on Debian/Ubuntu, please run the following
+command:</p>
+<pre class="prettyprint lang-bsh">
+sudo dpkg -i mod-pagespeed-*.deb
+sudo apt-get -f install
+</pre>
+
+<p>For CentOS/Fedora, please execute:</p>
+<pre class="prettyprint">
+sudo yum install at # if you do not already have 'at' installed
+sudo rpm -U mod-pagespeed-*.rpm
+</pre>
+
+<p>Installing mod_pagespeed will add the Google repository so your system
+will automatically keep mod_pagespeed up to date. If you don't want Google's
+repository, do <code>sudo touch /etc/default/mod-pagespeed</code> before
+installing the package.</p>
+
+<p>You can also download a number of <a href="https://dl-ssl.google.com/page-speed/mod-pagespeed/mod_pagespeed_examples.tar.gz">system tests</a>. These are the same tests available on <a href="http://www.modpagespeed.com">ModPageSpeed.com</a>.</p>
+
+<h3>What is installed</h3>
+<ul>
+<li>The mod_pagespeed packages install two versions of the mod_pagespeed code
+itself, <code>mod_pagespeed.so</code> for Apache 2.2
+and <code>mod_pagespeed_ap24.so</code> for Apache 2.4.</li>
+<li>Configuration files: <code>pagespeed.conf</code>, <code>pagespeed_libraries.conf</code>, and (on Debian) <code>pagespeed.load</code>. If you modify one of these configuration files, that file will not be upgraded automatically in the future.</li>
+<li>A standalone JavaScript minifier <code>pagespeed_js_minify</code> based on
+the one used in mod_pagespeed, that can
+both <a href="build_from_source#js-minify">minify JavaScript</a>
+and <a href="filter-canonicalize-js#sample">generate metadata for library
+canonicalization</a>. </li>
+</ul>
+
+<h2>How to upgrade</h2>
+<p>To upgrade from a previous version, use the standard <code>yum</code> or
+<code>apt-get</code> update commands. For example:</p>
+<dl>
+ <dt>.rpm
+ <dd><pre>
+sudo yum update mod-pagespeed-beta # Or mod-pagespeed-stable
+sudo /etc/init.d/httpd restart</pre>
+ <dt>.deb
+ <dd><pre>
+sudo apt-get update
+sudo apt-get upgrade
+sudo /etc/init.d/apache2 restart</pre>
+</dl>
+
+<h2>How to Change Channels</h2>
+<p>To convert from one channel to another, uninstall one and re-install
+the other. For example, if you would like to move from stable to beta
+channel:</p>
+<dl>
+ <dt>.rpm
+ <dd><pre>
+sudo yum remove mod-pagespeed-stable
+sudo yum install mod-pagespeed-beta</pre>
+ <dt>.deb
+ <dd><pre>
+sudo apt-get remove mod-pagespeed-stable
+sudo apt-get install mod-pagespeed-beta</pre>
+</dl>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/downstream-caching.html b/doc/downstream-caching.html
new file mode 100644
index 0000000..179e43b
--- /dev/null
+++ b/doc/downstream-caching.html
@@ -0,0 +1,521 @@
+<!--
+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>Configuring Downstream Caches</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Configuring Downstream Caches</h1>
+<style>
+.diff-del { color: darkred }
+.diff-add { color: green }
+</style>
+
+<h2 id="standard">Standard Configuration</h2>
+ <p class="warning"><strong>Note: This feature is currently experimental.
+ Options and configuration described here are subject to change in future
+ releases. Please subscribe to the <a href="mailing-lists#announcements"
+ >announcements mailing list</a> to keep yourself informed of updates to
+ this feature.</strong></p>
+
+ <p>
+ By default PageSpeed serves HTML files with <code>Cache-Control: no-cache,
+ max-age=0</code> so that changes to the HTML and its resources are sent
+ fresh on each request. The HTML can be cached, however, if you:
+ <ul>
+ <li> Set up a <code>PURGE</code> handler in your cache.
+ <li> Tell PageSpeed the url for the <code>PURGE</code> handler.
+ <li> Have the cache set the <code>PS-CapabilityList</code> header
+ so PageSpeed will emit HTML that can be sent to any browser.
+ <li> Have the cache occasionally pass through requests to the origin with
+ the <code>PS-ShouldBeacon</code> header set.
+ </ul>
+ </p>
+
+ <p>
+ For example, if you're running a cache on port 80 that reverse proxies to
+ your site on port 8080, then you'd need to tell PageSpeed to send
+ its <code>PURGE</code> requests to port 80:
+ </p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedDownstreamCachePurgeLocationPrefix http://localhost:80</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed DownstreamCachePurgeLocationPrefix http://localhost:80;</pre>
+</dl>
+ <p>
+ You also need to give PageSpeed a key so it can allow the cache to request
+ rebeaconing without allowing external entities to do so:
+ </p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedDownstreamCacheRebeaconingKey "<your-secret-key>"</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed DownstreamCacheRebeaconingKey "<your-secret-key>";</pre>
+</dl>
+ <p>
+ These are the only changes you need to make to the PageSpeed configuration
+ file, but before you restart you also need to make some changes to your
+ cache configuration. These vary by cache; below are configurations for
+ Varnish 3.x, Varnish 4.x, and Nginx's proxy_cache:
+ </p>
+<dl>
+ <dt>Varnish 3.x:<dd><pre class="prettyprint">
+acl purge {
+ # If PageSpeed isn't running on the same server as your cache, list the IP(s)
+ # of the PageSpeed machine(s) here.
+ "127.0.0.1";
+}
+sub vcl_recv {
+ # Tell PageSpeed not to use optimizations specific to this request.
+ set req.http.PS-CapabilityList = "fully general optimizations only";
+
+ # Don't allow external entities to force beaconing.
+ remove req.http.PS-ShouldBeacon;
+
+ # Authenticate the purge request by IP.
+ if (req.request == "PURGE") {
+ if (!client.ip ~ purge) {
+ error 405 "Not allowed.";
+ }
+ return (lookup);
+ }
+}
+
+# Mark HTML as uncacheable. If we can't send them purge requests they can't
+# cache our html.
+sub vcl_fetch {
+ if (beresp.http.Content-Type ~ "text/html") {
+ remove beresp.http.Cache-Control;
+ set beresp.http.Cache-Control = "no-cache, max-age=0";
+ }
+ return (deliver);
+}
+
+sub vcl_hit {
+ # Make purging happen in response to a PURGE request. This happens
+ # automatically in Varnish 4.x so we don't need it there.
+ if (req.request == "PURGE") {
+ purge;
+ error 200 "Purged.";
+ }
+
+ # 5% of the time ignore that we got a cache hit and send the request to the
+ # backend anyway for instrumentation.
+ if (std.random(0, 100) < 5) {
+ set req.http.PS-ShouldBeacon = "<your-secret-key>";
+ return (pass);
+ }
+}
+
+sub vcl_miss {
+ # Make purging happen in response to a PURGE request. This happens
+ # automatically in Varnish 4.x so we don't need it there.
+ if (req.request == "PURGE") {
+ purge;
+ error 200 "Purged.";
+ }
+
+ # Instrument 25% of cache misses.
+ if (std.random(0, 100) < 25) {
+ set req.http.PS-ShouldBeacon = "<your-secret-key>";
+ return (pass);
+ }
+}</pre>
+ <dt>Varnish 4.x:<dd><pre class="prettyprint">
+acl purge {
+ # If PageSpeed isn't running on the same server as your cache, list the IP(s)
+ # of the PageSpeed machine(s) here.
+ "127.0.0.1";
+}
+
+sub vcl_recv {
+ # Tell PageSpeed not to use optimizations specific to this request.
+ set req.http.PS-CapabilityList = "fully general optimizations only";
+
+ # Don't allow external entities to force beaconing.
+ unset req.http.PS-ShouldBeacon;
+
+ # Authenticate the purge request by IP.
+ if (req.method == "PURGE") {
+ if (!client.ip ~ purge) {
+ return (synth(405,"Not allowed."));
+ }
+ return (purge);
+ }
+}
+
+# Mark HTML as uncacheable. If we can't send them purge requests they can't
+# cache our html.
+sub vcl_backend_response {
+ if (beresp.http.Content-Type ~ "text/html") {
+ unset beresp.http.Cache-Control;
+ set beresp.http.Cache-Control = "no-cache, max-age=0";
+ }
+ return (deliver);
+}
+
+sub vcl_hit {
+ # 5% of the time ignore that we got a cache hit and send the request to the
+ # backend anyway for instrumentation.
+ if (std.random(0, 100) < 5) {
+ set req.http.PS-ShouldBeacon = "<your-secret-key>";
+ return (pass);
+ }
+}
+sub vcl_miss {
+ # Instrument 25% of cache misses.
+ if (std.random(0, 100) < 25) {
+ set req.http.PS-ShouldBeacon = "<your-secret-key>";
+ return (pass);
+ }
+}</pre>
+ <dt>Nginx proxy_cache:<dd><pre class="prettyprint">
+http {
+ # Define a mapping used to mark HTML as uncacheable.
+ map $upstream_http_content_type $new_cache_control_header_val {
+ default $upstream_http_cache_control;
+ "~*text/html" "no-cache, max-age=0";
+ }
+
+ server {
+ # PageSpeed's beacon dependent filters need the cache to let some requests
+ # through to the backend. This code below depends on the <a href="http://wiki.nginx.org/HttpSetMiscModule">ngx_set_misc</a>
+ # module and randomly passes 5% of traffic to the backend for rebeaconing.
+ set $should_beacon_header_val "";
+ set_random $rand 0 100;
+ if ($rand ~* "^[0-4]$") {
+ set $should_beacon_header_val "<your-secret-key>";
+ set $bypass_cache 1;
+ }
+
+ location / {
+ # existing proxy_pass
+ # existing proxy_cache
+ # existing proxy_cache_key
+
+ # What servers should we accept PURGE requests from? If PageSpeed isn't
+ # running on the same server as your cache, list the IP(s) of the
+ # PageSpeed machine(s) here.
+ #
+ # This requires rebuilding with the ngx_cache_purge module:
+ # https://github.com/FRiCKLE/ngx_cache_purge
+ proxy_cache_purge PURGE from 127.0.0.1;
+
+ # Mark HTML as uncacheable. If we can't send them purge requests they
+ # can't cache our html. Uses the map defined above.
+ proxy_hide_header Cache-Control;
+ add_header Cache-Control $new_cache_control_header_val;
+
+ # Tell PageSpeed not to use optimizations specific to this request.
+ proxy_set_header PS-CapabilityList "fully general optimizations only";
+
+ # See discussion of rebeaconing above.
+ proxy_cache_bypass $bypass_cache;
+ proxy_hide_header PS-ShouldBeacon;
+ proxy_set_header PS-ShouldBeacon $should_beacon_header_val;
+ }
+ }
+}</pre>
+</dl>
+
+<p>
+ When running with downstream caching all resources referenced from the HTML
+ will be cache-extended as usual, so if you have resources that need to be
+ cached for a short time then they can be stale. If so,
+ either <code>Disallow</code> those resources, so PageSpeed doesn't inline or
+ cache-extend them, or decrease the cache lifetime on your HTML.
+</p>
+
+<h2 id="additional">Additional Options</h2>
+
+The configuration above should be a good fit for most sites, but PageSpeed's
+downstream caching is highly configurable with many options that allow you to
+tweak it for your particular setup.
+
+<h3 id="beaconing">Beaconing</h3>
+<p>
+ Several filters such as
+ <a href="reference-image-optimize#inline_images">inline_images</a>,
+ <a href="filter-inline-preview-images">inline_preview_images</a>,
+ <a href="filter-lazyload-images">lazyload_images</a> and
+ <a href="filter-prioritize-critical-css">prioritize_critical_css</a>
+ depend extensively on client beacons to determine critical images and
+ CSS. When such filters are enabled, pages periodically have beaconing
+ JavaScript inserted as part of the rewriting process.
+ The <a href="#standard">standard configuration</a> passes through 5% of cache
+ hits to the backend with a <code>PS-ShouldBeacon</code> header set, so that
+ these filters can continue to receive the beacons they need.
+</p>
+<p>
+ If you have a high traffic site, 5% is probably a larger share than you need
+ for PageSpeed to receive sufficient beacons. In that case you can decrease
+ the percentage of traffic to pass through. For example, here's how you'd
+ decrease it to 2%:
+</p>
+<dl>
+ <dt>Varnish 3.x or 4.x:<dd><pre>
+<span class=diff-del>- if (std.random(0, 100) < 5) {</span>
+<span class=diff-add>+ if (std.random(0, 100) < 2) {</span></pre>
+ <dt>Nginx proxy_cache<dd><pre>
+<span class=diff-del>- if ($rand ~* "^[0-4]$") {</span>
+<span class=diff-add>+ if ($rand ~* "^[01]$") {</span></pre>
+</dl>
+<p>
+ Alternatively, you may be willing to give up the benefit of the
+ beaconing-dependent filters in exchange for never intentionally bypassing the
+ cache. If so, you should <a href="config_filters#beacons">turn off
+ beaconing</a> and beacon-dependent filters in PageSpeed:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+>ModPagespeedCriticalImagesBeaconEnabled false
+ModPagespeedDisableFilters prioritize_critical_css</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+>pagespeed CriticalImagesBeaconEnabled false;
+pagespeed DisableFilters prioritize_critical_css;</pre>
+</dl>
+<p>
+ Additionally you should remove the proxy config that handles beaconing:
+</p>
+<dl>
+ <dt>Varnish 3.x:<dd><pre><span class="diff-del"
+>- remove req.http.PS-ShouldBeacon;
+...
+- if (std.random(0, 100) < 5) {
+- set req.http.PS-ShouldBeacon = "<your-secret-key>";
+- return (pass);
+- }
+...
+- if (std.random(0, 100) < 25) {
+- set req.http.PS-ShouldBeacon = "<your-secret-key>";
+- return (pass);
+- }</span></pre>
+ <dt>Varnish 4.x:<dd><pre><span class="diff-del"
+>- unset req.http.PS-ShouldBeacon;
+...
+- sub vcl_hit {
+- if (std.random(0, 100) < 5) {
+- set req.http.PS-ShouldBeacon = "<your-secret-key>";
+- return (pass);
+- }
+- }
+- sub vcl_miss {
+- if (std.random(0, 100) < 25) {
+- set req.http.PS-ShouldBeacon = "<your-secret-key>";
+- return (pass);
+- }
+- }</span></pre>
+ <dt>Nginx proxy_cache<dd><pre><span class="diff-del"
+>- set $should_beacon_header_val "";
+- set_random $rand 0 100;
+- if ($rand ~* "^[0-4]$") {
+- set $should_beacon_header_val "<your-secret-key>";
+- set $bypass_cache 1;
+- }
+...
+- proxy_cache_bypass $bypass_cache;
+- proxy_hide_header PS-ShouldBeacon;
+- proxy_set_header PS-ShouldBeacon $should_beacon_header_val;</span></pre>
+</dl>
+
+
+<h3 id="ps-resource">PageSpeed Resources</h3>
+<p>
+ Because PageSpeed already caches its optimized resources, you may want to
+ exclude them caching by the downstream cache. If so, you can set:
+
+<dl>
+ <dt>Varnish 3.x and 4.x:<dd><pre><span class="diff-add"
+>+ if (req.url ~ "\.pagespeed\.([a-z]\.)?[a-z]{2}\.[^.]{10}\.[^.]+") {
++ return (pass);
++ }</span></pre>
+ <dt>Nginx proxy_cache<dd><pre><span class="diff-add"
+>+ if ($uri ~ "\.pagespeed\.([a-z]\.)?[a-z]{2}\.[^.]{10}\.[^.]+") {
++ set $bypass_cache "1";
++ }</span></pre>
+</dl>
+
+<p>
+ If you have enabled <a href="restricting_urls#url_signatures">URL signing</a>,
+ change the <code>10</code> in the regexp to <code>20</code> to account for the
+ additional characters in the hash.
+</p>
+
+<h3 id="ps-capabilitylist">PS-CapabilityList</h3>
+
+<p>
+ Typically PageSpeed will produce different HTML for different browsers. For
+ example, when responding to a request that has <code>Accept:
+ image/webp</code>, PageSpeed knows the requesting browser supports WebP and so
+ it can send these images, while if the <code>Accept</code> header doesn't
+ mention WebP then it will send JPEG or PNG. To suppress this behavior,
+ the <a href="#standard">standard configuration</a> above sets a header:
+</p>
+<pre>
+ PS-CapabilityList: fully general optimizations only
+</pre>
+<p>
+ This header can also be used to tell PageSpeed to make specific optimizations.
+ There are five capabilities PageSpeed can take advantage of that aren't
+ supported in all browsers, and it gives them each a code:
+</p>
+<table>
+ <tr><th>Capability<th>Code
+ <tr><td>Inline Images<td><code>ii</code>
+ <tr><td>Lazyload Images<td><code>ll</code>
+ <tr><td>WebP Images<td><code>jw</code>
+ <tr><td>Lossless WebP Images<td><code>ws</code>
+ <tr><td>Animated WebP Images<td><code>wa</code>
+ <tr><td>Defer Javascript<td><code>dj</code>
+</table>
+<p>
+ For example, you could include whether the <code>Accept</code> header
+ includes <code>image/webp</code> in your cache key, and then for the
+ fraction of traffic that claimed webp support send:
+</p>
+<pre>
+ PS-CapabilityList: jw:
+</pre>
+<p>
+ Every page would go through to your origin twice and be cached twice, once
+ processed with WebP support and once without.
+</p>
+<p>
+ You can combine multiple capabilities together with a comma. For example, if
+ you decided to make a cache fragment for Chrome 30+, which supports all of
+ these, for that fragment you would send:
+</p>
+<pre>
+ PS-CapabilityList: ll,ii,dj,jw,ws:
+</pre>
+<p>
+ For Firefox 4+, which supports all of these but WebP, you would send:
+</p>
+<pre>
+ PS-CapabilityList: ll,ii,dj:
+</pre>
+<p>
+ To use this header properly, however, you have to know which capabilities are
+ supported by which browsers in the version of PageSpeed you're using and craft
+ regular expressions to match exactly those ones. This is very difficult to do
+ in general because it involves duplicating the code in
+ <a href="https://github.com/apache/incubator-pagespeed-mod/blob/latest-stable/pagespeed/kernel/http/user_agent_matcher.cc"><code>user_agent_matcher.cc</code></a>
+ as regexes, but a simple division is:
+ <ul>
+ <li>Chrome 32+: <code>ll,ii,dj,jw,wa,ws</code>
+ <li>Firefox 4+, Safari, IE10 (but not IE11): <code>ll,ii,dj</code>
+ <li>Everything else: <code>fully general optimizations only</code>
+ </ul>
+</p>
+
+<h3 id="purge-get">Purging with GET</h3>
+
+<p>
+ If you're integrating PageSpeed with a cache that doesn't
+ support <code>PURGE</code> requests but does support purging in response to a
+ prefixed <code>GET</code> request, PageSpeed can support that. You would
+ configure your cache to treat a <code>GET</code> to
+ <code>/purge/foo/bar</code> as a request to purge <code>/foo/bar</code> and
+ configure PageSpeed as:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedDownstreamCachePurgeLocationPrefix http://CACHE-HOST:PORT/purge
+ModPagespeedDownstreamCachePurgeMethod GET</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed DownstreamCachePurgeLocationPrefix http://CACHE-HOST:PORT/purge;
+pagespeed DownstreamCachePurgeMethod GET;</pre>
+</dl>
+
+<h3 id="purge-threshold">Purge Threshold</h3>
+<p>
+ Whenever PageSpeed serves an HTML response that is not fully optimized it
+ continues rewriting in the background. When it finishes, if the HTML it
+ served was less than 95% optimized, it sends a purge request to the downstream
+ cache. The next request to come in will bypass the cache and come back to
+ PageSpeed where it can serve out the now more highly optimized page. If you
+ want to change what point PageSpeed considers the page done and stops
+ optimizing, you can set a different value for this threshold. For example, to
+ lower it to 80%, so that PageSpeed is satisfied with a page that is only 80%
+ optimized, you would set:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedDownstreamCacheRewrittenPercentageThreshold 80</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed DownstreamCacheRewrittenPercentageThreshold 80;</pre>
+</dl>
+
+<h3 id="script-variables">Script Variables</h3>
+<p class="note"><strong>Note: Nginx-only</strong></p>
+<p class="note"><strong>Note: New feature as of 1.10.33.0</strong></p>
+
+<p>
+ In ngx_pagespeed <code>DownstreamCachePurgeLocationPrefix</code>,
+ <code>DownstreamCachePurgeMethod</code>, and
+ <code>DownstreamCacheRewrittenPercentageThreshold</code> support script
+ variables, so it's possible to set them on a per-request basis. Turn this on
+ with:
+<pre class="prettyprint">
+http {
+ pagespeed ProcessScriptVariables on;
+ ...
+}</pre>
+ You can then use script variables in arguments for these commands:
+<pre class="prettyprint">
+ pagespeed DownstreamCachePurgeLocationPrefix "$purge_location";
+ pagespeed DownstreamCachePurgeMethod "$cache_purge_method";
+ pagespeed DownstreamCacheRewrittenPercentageThreshold "$rewrite_threshold";</pre>
+</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>
+<h2 id="implementation">Implementation Details</h2>
+<p>
+ To support downstream caching PageSpeed sends a purge request to the caching
+ layer whenever it identifies an opportunity for more rewriting to be done on
+ content that was just served. Such opportunities could arise because of, say,
+ the resources now becoming available in the PageSpeed cache or an image
+ compression operation completing. The cache purge forces the next request for
+ the HTML file to come all the way to the backend PageSpeed server and obtain
+ better rewritten content, which is then stored in the cache. This interaction
+ between the PageSpeed server and the downstream caching layer is depicted in
+ the diagram given below.
+</p>
+ <img src="images/downstream_caching.png" >
+<p>
+ In the interaction depicted above, note that the partially optimized HTML will
+ be served from the cache until a purge request gets sent by the PageSpeed
+ server. It is recommended to set up PageSpeed and the downstream caching
+ layer servers on a one to one basis so that the purges can be sent to the
+ correct downstream server.
+</p>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/experiment.html b/doc/experiment.html
new file mode 100644
index 0000000..af8933a
--- /dev/null
+++ b/doc/experiment.html
@@ -0,0 +1,449 @@
+<!--
+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>Experimenting with PageSpeed</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Experimenting with PageSpeed</h1>
+<h2 id="Framework">Experimental Framework</h2>
+<p>
+The <a href="module-run-experiment.html">Run Experiment</a> module allows you to
+gather data on what filters perform best for your site using A/B testing. It
+reports to your <a href="http://www.google.com/analytics/">Google Analytics</a>
+account, storing data in
+a <a href="/analytics/devguides/collection/gajs/gaTrackingCustomVariables">custom
+variable</a>. It often makes sense to first experiment manually using the
+per-request configuration described below to get an idea of which filters might
+help your site, and then <a href="module-run-experiment.html">run a controlled
+experiment</a> to test whether these filters actually speed it up in practice.
+</p>
+
+<h2 id="PerRequest">Per-request configuration</h2>
+
+<p>
+Query parameters, request headers, and response headers can be used to disable
+PageSpeed, specify the set of filters applied to an HTML page, and control some
+inlining limits.
+</p>
+
+<p>
+Query parameters take the form of <code>name=value</code>
+and parameters are separated by an ampersand (&). For example:
+</p>
+<pre>
+ <a href="http://modpagespeed.com/rewrite_css.html?PageSpeed=on&PageSpeedFilters=rewrite_css">http://modpagespeed.com/rewrite_css.html?PageSpeed=on&PageSpeedFilters=rewrite_css</a>
+</pre>
+
+<p>
+Request and response headers take the form of <code>name: value</code>
+and each header is on its own line. For example:
+</p>
+<pre class="prettyprint">
+GET /rewrite_css.html HTTP/1.1
+Host: modpagespeed.com
+PageSpeed: on
+PageSpeedFilters: rewrite_css</pre>
+
+<p>
+For backwards compatibility, these can start with <code>ModPagespeed</code>
+instead of <code>PageSpeed</code>, but this usage is deprecated.
+</p>
+
+<p>
+Query parameters can be added to the URL of the page or resource being
+fetched, request headers can be set in the request for pages and
+resources, and response headers can be set in the response of HTML
+pages (but not resources). These settings affect only the given
+request. If all three (query parameters and both headers) are used in
+the same request the query parameters will be applied first, followed
+by the request headers, followed by the response headers. Later
+settings override earlier settings but a filter disable in any
+location always overrides subsequent enables.
+</p>
+
+<p>
+There are two supported methods of adding response headers that PageSpeed will
+be able to observe and process. The first is to add response headers with a
+content handler such as PHP or Perl. The second is to add response headers at
+an origin server and run PageSpeed as a proxy in front of it. The use of
+mod_headers (Apache) or add_header (Nginx) on the same webserver as PageSpeed
+will not work because headers will be inserted after PageSpeed has already
+processed the page.
+</p>
+
+<h3 id="StickyQueryParams">Sticky Query Parameters</h3>
+<p>
+Query parameters can be set to be "sticky" and persist across
+requests using cookies. Sticky query parameters can be set by providing the
+sticky query parameter option in a request, and the server will respond with
+a cookie, valid for the duration specified in the PageSpeed configuration.
+</p>
+<p>
+To prevent abuse, a "secret token" must be provided in the initial
+request to enable setting cookies.
+</p>
+<dl>
+<dt>Apache:</dt>
+<dd>
+<pre class="prettyprint">ModPagespeedStickyQueryParameters example_token</pre>
+</dd>
+<dt>Nginx:</dt>
+<dd>
+<pre class="prettyprint">pagespeed StickyQueryParameters example_token</pre>
+</dd>
+</dl>
+<p>
+The duration, in milliseconds, for which the cookie will be valid can be set in
+the PageSpeed configuration.
+</p>
+<dl>
+<dt>Apache:</dt>
+<dd>
+<pre class="prettyprint">ModPagespeedOptionCookiesDurationMs 12345</pre>
+</dd>
+<dt>Nginx:</dt>
+<dd>
+<pre class="prettyprint">pagespeed OptionCookiesDurationMs 12345</pre>
+</dd>
+</dl>
+<p>
+The request must specify the token in a query parameter,
+for example:
+<pre>
+<a href="http://modpagespeed.com/rewrite_css.html?PageSpeedStickyQueryParameters=example_token&PageSpeedFilters=+remove_comments">http://modpagespeed.com/rewrite_css.html?PageSpeedStickyQueryParameters=example_token&PageSpeedFilters=+remove_comments</a></pre>
+<p>
+A request with the proper sticky query parameter token will cause the server to
+respond with a <code>Set-Cookie</code> in the response.
+Any request not containing the correct token will not receive the
+<code>Set-Cookie</code> response. Future responses with the received cookie will
+also enable the options set in the query parameter with the sticky query
+parameter. In this case, the <code>remove-comments</code> filter would be
+enabled.
+</p>
+
+<h3 id="ModPagespeed">Enabling and disabling PageSpeed</h3>
+
+<p>Query parameters:</p>
+<pre class="prettyprint">
+ PageSpeed=off
+ PageSpeed=on
+</pre>
+<p>Request & Response headers:</p>
+<pre class="prettyprint">
+ PageSpeed: off
+ PageSpeed: on
+</pre>
+<p>
+The first line disables PageSpeed rewriting, the second line enables it.
+</p>
+
+<h3 id="ModPagespeedFilters">Specifying the filters applied</h3>
+
+<p>Query parameters:</p>
+<pre class="prettyprint">
+ PageSpeedFilters=<i>comma-separated list of names</i>
+</pre>
+<p>Request & Response headers:</p>
+<pre class="prettyprint">
+ PageSpeedFilters: <i>comma-separated list of names</i>
+</pre>
+
+<p>
+This specifies the set of filters to apply to the page. The list of settings
+includes all filter names and a few shortcut names:
+</p>
+
+<ul>
+ <li><code>core</code> sets the rewrite level (per
+ <code><a href="config_filters.html#level>ModPagespeedRewriteLevel"
+ >RewriteLevel</a></code>)
+ to <code>CoreFilters</code>. This enables the core set of filters.</li>
+ <li><code>testing</code> enables all filters that are in the
+ <code>TestingCoreFilters</code> level but are not in the
+ <code>CoreFilters</code> level - this is not the same as setting the
+ level to <code>TestingCoreFilters</code> because that includes all
+ core filters, but the same effect can be achieved by specifying
+ both: <code>core,testing</code>.</li>
+ <li><code>rewrite_images</code> enables the following filters:
+ <code>inline_images</code>, <code>recompress_images</code>, and
+ <code>resize_images</code>.</li>
+ <li><code>extend_cache</code> enables the following filters:
+ <code>extend_cache_css</code>, <code>extend_cache_images</code>, and
+ <code>extend_cache_scripts</code>.</li>
+ <li><code>rewrite_javascript</code> enables the following filters:
+ <code>rewrite_javascript_external</code> and
+ <code>rewrite_javascript_inline</code>.</li>
+</ul>
+
+<p>
+When any filter is specified without a "<code>+</code>" or
+"<code>-</code>", any filters not explicitly enabled are
+disabled. Filters and shortcuts can be explicitly disabled by
+preceding the name by a minus sign ('-'), which is useful
+after using a shortcut. For example,
+"<code>core,-combine_css</code>" enables all the core
+filters
+<em>except</em> <code>combine_css</code>.
+</p>
+
+<p>
+If all names are prefixed with "<code>+</code>" or "<code>-</code>" then the
+filter set is incrementally adjusted from the current system settings based on
+the configuration files. For example, in a server
+with <code>RewriteLevel</code> set to <code>CoreFilters</code>, the query-string
+</p>
+<pre class="prettyprint">
+ ?PageSpeedFilters=+lazyload_images,-inline_images
+</pre>
+<p>
+will leave all the core filters enabled, but will add lazyload_images
+and disable inline images.
+</p>
+
+<h3 id="ModPagespeedFilters">Controlling inlining limits</h3>
+
+<p>Query parameters:</p>
+<pre class="prettyprint">
+ PageSpeedCssFlattenMaxBytes=<i>value</i>
+ PageSpeedCssImageInlineMaxBytes=<i>value</i>
+ PageSpeedCssInlineMaxBytes=<i>value</i>
+ PageSpeedImageInlineMaxBytes=<i>value</i>
+ PageSpeedJsInlineMaxBytes=<i>value</i>
+</pre>
+<p>Request & Response headers:</p>
+<pre class="prettyprint">
+ PageSpeedCssFlattenMaxBytes: <i>value</i>
+ PageSpeedCssImageInlineMaxBytes: <i>value</i>
+ PageSpeedCssInlineMaxBytes: <i>value</i>
+ PageSpeedImageInlineMaxBytes: <i>value</i>
+ PageSpeedJsInlineMaxBytes: <i>value</i>
+</pre>
+
+<p>
+These specify the limits for the following inlining options:
+</p>
+
+<ul>
+ <li><code>PageSpeedCssFlattenMaxBytes</code> sets the maximum size of CSS
+ files that will be flattened.</li>
+ <li><code>PageSpeedCssImageInlineMaxBytes</code> sets the maximum
+ size of images inside CSS. For inline CSS in HTML files, the
+ value used is the smaller of this value
+ or <code>PageSpeedImageInlineMaxBytes</code>.
+ <li><code>PageSpeedCssInlineMaxBytes</code> sets the maximum size of CSS
+ files that will be inlined.</li>
+ <li><code>PageSpeedImageInlineMaxBytes</code> sets the maximum size of
+ image files that will be inlined.</li>
+ <li><code>PageSpeedJsInlineMaxBytes</code> sets the maximum size of
+ JavaScript files that will be inlined.</li>
+</ul>
+
+<p>
+Here is an example that combines many of the above query parameters to enable
+all the core filters <em>except</em> the cache extension filters, and sets the
+JavaScript inlining limit to a high value so that most JavaScript files will
+be inlined:
+</p>
+<pre>
+ http://..../index.html?PageSpeedFilters=core,-extend_cache&PageSpeedJsInlineMaxBytes=102400
+</pre>
+
+<h3 id="Client-Options">Client options in queries and headers</h3>
+ <p>
+ This is an experimental option, its name and values are subject to change.
+ This option allows the client to customize the optimizations applied to a
+ request and can be used in a header or query parameter.
+ </p>
+
+ <p>As a query parameter:</p>
+<pre class="prettyprint">
+ X-PSA-Client-Options=<i>client-options</i>
+</pre>
+<p>As a Request or Response header:</p>
+<pre class="prettyprint">
+ X-PSA-Client-Options: <i>client-options</i>
+</pre>
+
+<p>
+The format of client-options is
+</p>
+<pre>
+ name1=value1,name2=value2, ...
+</pre>
+
+<p>
+The order of the name-value pairs does not matter. The supported options are:
+</p>
+
+<pre>
+ v=1
+</pre>
+<p>Version of the header. '1' is the only supported version for now.</p>
+<pre>
+ <code>m=integer-value</code>
+</pre>
+<p> Mode. Valid values are</p>
+ <ul>
+ <li> <code>0</code>, the client prefers that the server operates in its
+ default mode. </li>
+ <li> <code>1</code>, the client prefers that no image is transformed. </li>
+ <li> <code>2</code>, the client prefers that no resource is transformed.
+ This is equivalent to "?PageSpeedFilters=" in the request URL </li>
+ </ul>
+
+<pre>
+ <code>iqp=integer-value</code>
+</pre>
+<p> Image quality preference. Valid values are </p>
+ <ul>
+ <li> <code>0</code>, the client prefers that the server uses its own default
+ image quality. </li>
+ <li> <code>1</code>, the client prefers low image quality. </li>
+ <li> <code>2</code>, the client prefers medium image quality. </li>
+ <li> <code>3</code>, the client prefers high image quality. </li>
+ </ul>
+
+<h3 id="restrict-request-options">Restrict per-request configuration</h3>
+ <p class="note">
+ <strong>Note: New feature as of 1.9.32.1</strong>
+ </p>
+ <p>
+ Interpretation of PageSpeed query parameters and headers can be restricted to
+ requests specifying a request option override token.
+ The token is specified in the server configuration file and disallows
+ request option overriding when the request does not specify the correct token.
+ This option can be used to reduce the attack surface of denial of service
+ attacks.
+ </p>
+ <dl>
+ <dt>Apache:</dt>
+ <dd>
+ <pre class="prettyprint">ModPagespeedRequestOptionOverride example_token</pre>
+ </dd>
+ <dt>Nginx:</dt>
+ <dd>
+ <pre class="prettyprint">pagespeed RequestOptionOverride example_token</pre>
+ </dd>
+ </dl>
+ <p>
+ This feature provides a mechanism to restrict the ability for filters and
+ options to be specified in query parameters and request headers.
+ To enable it, an override token must be specified in the configuration file,
+ and requests must specify the same token for filters and options to be
+ applied.
+ Query parameters, except for <code>PageSpeed=on</code>,
+ <code>PageSpeed=off</code>, or <code>PageSpeed=noscript</code> will then only
+ be interpreted when accompanied by the correct
+ <code>RequestOptionOverride</code> token. For example, the rewrite_css filter
+ would be used in this example.
+ </p>
+ <p>
+ The request must specify the token in a query parameter or header,
+ for example:
+ <pre>
+ <a href="http://modpagespeed.com/rewrite_css.html?PageSpeed=on&PageSpeedFilters=rewrite_css&PageSpeedRequestOptionOverride=example_token">http://modpagespeed.com/rewrite_css.html?PageSpeed=on&PageSpeedFilters=rewrite_css&PageSpeedRequestOptionOverride=example_token</a></pre>
+ <p>
+ Any request not containing the correct <code>RequestOptionOverride</code>
+ token or not containing a <code>RequestOptionOverride</code> token will ignore
+ all other PageSpeed filters and options specified.
+ </p>
+ <p class="note">
+ <strong>
+ Note: even if applied, PageSpeed=on/off/noscript still takes effect.
+ </strong>
+ </p>
+</h3>
+
+<h3 id="noop">Noop query-parameter</h3>
+<p class="note">
+ <strong>Note: New feature as of 1.10.33.0</strong>
+</p>
+<p>
+To help bust browser caches, especially with experiments, any
+PageSpeed URL can accept the
+<code>PageSpeedNoop</code> query-paramter with an integer value. This
+query-parameter will be ignored by PageSpeed and stripped from the
+URL early in the processing flow. The origin will not see the <code>Noop</code>
+parameter, and PageSpeed's server-caches will not be affected. However, it
+will prevent your browser from using a cached value.
+</p>
+
+<p>Examples:</p>
+<pre class="prettyprint"
+ >http://images.example.com/foo.png?PageSpeedNoop=571
+http://www.example.com/index.html?q=foo&PageSpeedNoop=99438
+</pre>
+
+<h2 id="Configuring-mod_pagespeed_examples">
+ Configuring mod_pagespeed_examples</h2>
+<p class="note"><strong>Note: Apache-only</strong></p>
+
+<p>
+mod_pagespeed ships with a directory of sample HTML, JavaScript,
+Image, and CSS files to demonstrate the rewrite passes that it
+executes. These also form the basis of an installation smoke-test to
+ensure that the configured system is operating correctly. Assuming
+the files are installed in /var/www/mod_pagespeed_example, the
+following configuration file fragment will enable them to be served
+using reasonable caching headers.
+</p>
+<pre class="prettyprint lang-sh">
+ # These caching headers are set up for the mod_pagespeed example, and
+ # also serve as a demonstration of good values to set for the entire
+ # site, if it is to be optimized by mod_pagespeed.
+
+ <Directory /var/www/mod_pagespeed_example>
+ # To enable to show that mod_pagespeed to rewrites web pages, we must
+ # turn off Etags for HTML files and eliminate caching altogether.
+ # mod_pagespeed should rewrite HTML files each time they are served.
+ # The first time mod_pagespeed sees an HTML file, it may not optimize
+ # it fully. It will optimize better after the second view. Caching
+ # defeats this behavior.
+ <FilesMatch "\.(html|htm)$">
+ Header unset Etag
+ Header set Cache-control "max-age=0, no-cache"
+ </FilesMatch>
+
+ # Images, styles, and JavaScript are all cache-extended for
+ # a year by rewriting URLs to include a content hash.. mod_pagespeed,
+ # can only do this if the resources are cacheable in the first place.
+ # The origin caching policy, set here to 10 minutes, dictates how
+ # frequently mod_pagespeed must re-read the content files and recompute
+ # the content-hash. As long as the content doesn't actually change,
+ # the content-hash will remain the same, and the resources stored
+ # in browser caches will stay relevant.
+ <FilesMatch "\.(jpg|jpeg|gif|png|js|css)$">
+ Header unset Etag
+ Header set Cache-control "public, max-age=600"
+ </FilesMatch>
+ </Directory>
+</pre>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/faq.html b/doc/faq.html
new file mode 100644
index 0000000..fae2ab5
--- /dev/null
+++ b/doc/faq.html
@@ -0,0 +1,777 @@
+<!--
+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>Frequently Asked Questions</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Frequently Asked Questions</h1>
+<h2 id="other-servers">I'm not running Apache or Nginx, do you support my
+http server?</h2>
+
+<p>
+While we only support Apache and Nginx, there are community developed ports to
+several other webservers:
+</p>
+<ul>
+<li><a
+href="https://cwiki.apache.org/confluence/display/TS/ats_speed">Apache
+Traffic Server</a></li>
+<li><a href="http://www.iispeed.com/"
+>Internet Information Services (IIS)</a></li>
+<li><a
+href="http://open.litespeedtech.com/mediawiki/index.php/Help:Modules:PageSpeed"
+>OpenLiteSpeed</a></li>
+</ul>
+<p>
+If you run a webserver that doesn't have a port, one option would be to set up
+some other server running PageSpeed as a reverse proxy in front of it. If
+you're not sure which to use we recommend using PageSpeed on nginx, but any of
+these servers should work well as an optimizing reverse proxy.
+</p>
+<p>
+(And, of course, if you're interested in porting PageSpeed to a new server, that
+would be awesome, and anyone porting should feel free to send us lots of
+detailed technical questions!)
+</p>
+
+<h2 id="when-support">When will you support my favorite OS or protocol?</h2>
+
+<p>
+While we have no dates to announce for upcoming releases, we definitely want to
+know what you think we should be working
+on. Please <a href="https://github.com/apache/incubator-pagespeed-mod/issues">search
+our issues</a> for your feature. If you don't find
+it, <a href="https://github.com/apache/incubator-pagespeed-mod/issues/new">open a new
+issue</a> and tag it "Type-Enhancement". To get updates on an issue, click the
+"star" icon for it. This also lets us know how many people are interested in
+the issue. If your issue is Nginx-specific, consider posting on
+the <a href="https://github.com/apache/incubator-pagespeed-ngx/issues">ngx_pagespeed
+bug tracker</a>.
+</p>
+
+<h2 id="suse">Do you support SUSE?</h2>
+<p>
+We support SUSE on Apache and Nginx when <a href="build_from_source">building
+from source</a>. For Apache, Robert Munteanu (robert.munteanu@gmail.com) has
+set up a repository which publishes OpenSUSE RPMs for mod_pagespeed. The
+repository is
+hosted <a href="http://software.opensuse.org/package/apache2-mod_pagespeed">on
+OpenSUSE's build service instance</a>. The builds have seen some testing on one
+of Robert's servers (OpenSUSE 12.1/x86_64) but he'd appreciate anyone else
+testing it.
+</p>
+<p>
+To enable the module, install it, add <code>deflate pagespeed</code> to your
+list of Apache modules in <code>/etc/sysconfig/apache2</code> and restart
+Apache.
+</p>
+<p>
+Please note that the module is linked dynamically with the current system
+libraries and as such will bring in more dependencies than the 'stock' Fedora or
+CentOS RPM.
+</p>
+
+<h2 id="not-rewriting">Why isn't PageSpeed rewriting any of my pages?</h2>
+<p>
+Check the HTTP response headers from your HTML page:
+</p>
+<pre class="prettyprint lang-bsh">
+ curl -D- http://example.com | less
+</pre>
+<p>
+You should get something like:
+</p>
+<dl>
+ <dt>Apache:<dd>
+<pre>
+Date: Fri, 30 Sep 2016 15:36:57 GMT
+Server: Apache/2.4.7 (Ubuntu)
+...
+X-Mod-Pagespeed: 1.11.33.4-0
+...
+</pre>
+ <dt>Nginx:<dd>
+<pre>
+Date: Fri, 30 Sep 2016 15:37:24 GMT
+Server: nginx/1.11.4
+...
+X-Page-Speed: 1.11.33.4-0
+</pre>
+</dl>
+<p>
+If you don't see an <code>X-Mod-Pagespeed</code> header (Apache)
+or <code>X-Page-Speed</code> header (Nginx), this means that your webserver
+isn't letting PageSpeed run. This could be because it isn't actually installed,
+you don't have it turned on in the configuration file, or many other reasons.
+In Apache the problem might be that you have multiple
+<code>SetOutputFilter</code> directives: only one of those will win. See the
+Apache <a
+href="http://httpd.apache.org/docs/current/mod/core.html#SetOutputFilter"
+>SetOutputFilter documentation</a>.
+</p>
+<p>
+If you do see the header, but it doesn't look like PageSpeed is making any
+changes to your page, its possible that none of the active filters are finding
+anything to rewrite. Try comparing your page with PageSpeed off and with
+the <a href="filter-whitespace-collapse">collapse_whitespace</a> filter enabled:
+</p>
+<pre class="prettyprint">
+ curl -D- 'http://example.com?ModPagespeed=off' | less
+ curl -D- 'http://example.com?ModPagespeed=on&ModPagespeedFilters=collapse_whitespace' | less
+</pre>
+<p>
+If you see a change when run with <code>collapse_whitespace</code> on, that
+means PageSpeed is running but the filters you have selected aren't
+optimizing anything. There are several reasons that could happen:
+</p>
+<ul>
+ <li>The filters you have enabled aren't aggressive enough.</li>
+ <li>Your resources (images, css, javascript) aren't cacheable. If
+ PageSpeed sees <code>cache-control</code> headers such
+ as <code>nocache</code> or <code>private</code> it will not rewrite the
+ resources.</li>
+ <li>CSS, JavaScript, and image files served from a distinct domain from the
+ HTML must have the resource domain authorized. See
+ <a href="domains">Domains</a>.</li>
+ <li>Your CSS has new CSS3 syntax or other constructions we don't support.
+ See <a href="http://github.com/apache/incubator-pagespeed-mod/issues/108"
+ >issue 108</a>.
+ The <a href="filter-css-rewrite#configuration"
+ >fallback_rewrite_css_urls</a> filter may be able to help. You can also
+ use the <a href="build_from_source#debug-css">standalone CSS parser</a> to
+ help debug these issues.</li>
+ <li>Your resources are served over HTTPS. HTTPS resources can currently only
+ be rewritten if they are origin-mapped or loaded from directly from the
+ file-system. See <a href="https_support">HTTPS Support</a>.</li>
+</ul>
+
+<h2 id="missing-dependency">Why am I getting "Error: Missing Dependency: httpd > = 2.2" even though I have Apache 2.2.? installed?</h2>
+<p>
+ You are probably trying to install mod_pagespeed using yum or apt-get
+ (the .rpm or .deb binaries), but you installed Apache using a different
+ method (cPanel, Wordpress, etc.). This will not work because mod_pagespeed
+ binaries depend upon Apache being installed using yum or apt-get.
+</p>
+<p>
+ Instead you must either
+ <a href="build_mod_pagespeed_from_source">
+ build from mod_pagespeed from source
+ </a>
+ or <a href="http://www.google.com/">search</a> for mod_pagespeed + your
+ platform to see if someone has documented an install process for that
+ platform. For example,
+ <a href="#cpanel-install">cPanel based installation</a>.
+</p>
+
+<h2 id="cpanel-install">I'm using cPanel on my server, how do I install mod_pagespeed?</h2>
+<p>
+cPanel installs Apache httpd server from source via the built-in EasyApache setup
+and build process. In order to enable mod_pagespeed on your server, download
+and install the <a href="https://github.com/apache/incubator-pagespeed-cpanel">mod_pagespeed module
+ for cPanel WHM</a> - once the module is installed, you can select "mod_pagespeed" as
+one of the modules during the regular EasyApache build (via the online tool, or from
+the command line). Do not install mod_pagespeed from .deb. or .rpm packages - cPanel
+requires that you use the EasyApache build process.
+</p>
+
+<h2 id="wordpress-blank">I'm using WordPress and my pages are blank. Why?</h2>
+<p>
+Disable compression in the WordPress plugin, so that mod_pagespeed will process
+uncompressed HTML. mod_pagespeed ensures that its output will be compressed by
+enabling <a href="http://httpd.apache.org/docs/current/mod/mod_deflate.html"
+>mod_deflate</a>.
+</p>
+
+<h2 id="broken">PageSpeed broke my site; what do I do?</h2>
+<p>
+First of all, sorry about that. We put a lot of work into validating our
+rewriters against a large corpus of websites and we disable filters that cause
+problems as soon as we can, but sometimes things slip through.
+</p>
+<p>
+Second, please upgrade to the latest version; we are continually working on
+bug-fixes and turning off filters that break pages.
+</p>
+If it's still breaking your site, please post a bug
+(<a href="https://github.com/apache/incubator-pagespeed-mod/issues/new">Apache</a>,
+ <a href="https://github.com/apache/incubator-pagespeed-ngx/issues/new">Nginx</a>). If
+you can, including the following information will make it much easier to
+diagnose:
+<ol>
+ <li>Try appending <code>?ModPagespeed=off</code> to the URL. This de-activates
+ PageSpeed. If the site is still broken, it is not a rewrite
+ or HTML parsing problem. It might be a configuration clash, please ask us
+ on our <a href="mailing-lists#discussion">discussion group</a>.</li>
+ <li>If that fixed the site, try
+ appending <code>?ModPagespeed=on&ModPagespeedFilters=</code> to the
+ URL. This turns on PageSpeed, but no filters. If the site is broken
+ now, it is an HTML parsing
+ problem. Please <a href="mailing-lists#discussion">let us know</a>.</li>
+ <li>If the site still worked, try
+ appending <code>?ModPagespeed=on&ModPagespeedFilters=foo</code> for
+ various filters "foo". For example try:
+ <pre class="prettyprint lang-bsh">
+http://www.modpagespeed.com/?ModPagespeed=on&ModPagespeedFilters=extend_cache
+http://www.modpagespeed.com/?ModPagespeed=on&ModPagespeedFilters=combine_css
+http://www.modpagespeed.com/?ModPagespeed=on&ModPagespeedFilters=inline_css
+http://www.modpagespeed.com/?ModPagespeed=on&ModPagespeedFilters=inline_javascript
+http://www.modpagespeed.com/?ModPagespeed=on&ModPagespeedFilters=insert_image_dimensions
+http://www.modpagespeed.com/?ModPagespeed=on&ModPagespeedFilters=rewrite_images
+http://www.modpagespeed.com/?ModPagespeed=on&ModPagespeedFilters=rewrite_css
+http://www.modpagespeed.com/?ModPagespeed=on&ModPagespeedFilters=rewrite_javascript</pre>
+ You may have to reload them a few times over several seconds to make sure
+ they have had time to load sub-resources into cache and rewrite them. If
+ one of these breaks your site, you now know which filter is at
+ fault. Please <a href="mailing-lists#discussion">let us know</a>. You can
+ disable that filter by adding a line to your <code>pagespeed.conf</code>
+ file:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedDisableFilters foo</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed DisableFilters foo;</pre>
+</dl>
+ </li>
+</ol>
+
+<h2 id="mod_rewrite">I am getting 404s for rewritten resources
+ (like example.png.pagespeed.ic.LxXAhtOwRv.png) or for the
+ mod_pagespeed_admin console</h2>
+<p>
+ The most common reason that the rewritten resources 404 is because of
+ mod_rewrite <code>RewriteCond</code> rules. For example:
+</p>
+<pre class="prettyprint">
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_FILENAME} !-d
+RewriteRule ^ /404 [L,R=301]</pre>
+<p>
+ This rule causes 404 for all requests which don't exist on the filesystem,
+ including mod_pagespeed rewritten resources and the mod_pagespeed admin
+ console.
+</p>
+<p>
+ In order to fix this you must add an exception for mod_pagespeed URLs:
+</p>
+<pre class="prettyprint">
+ RewriteCond %{REQUEST_URI} !pagespeed</pre>
+<p>
+ This will allow rewritten resources, the admin console and static resources
+ necessary for some filters.
+</p>
+
+<h2 id="ignores-changes">PageSpeed does not pick up changes when I edit CSS
+or JavaScript files</h2>
+<p>
+There are two distinct cache-times at play when you use PageSpeed:
+<ol>
+ <li>The origin TTL which PageSpeed uses to refresh its internal
+ server-side cache.</li>
+ <li>The TTL with which PageSpeed serves rewritten resources to
+ browsers.</li>
+</ol>
+When PageSpeed first reads your resource file, it uses the origin TTL to figure
+out how often to re-examine the origin CSS file. Assume your origin TTL is 1
+day. Once PageSpeed has that file in cache, it will not go back & re-check
+that file for a day. Changing the TTL after PageSpeed has put the resource in
+its cache will not help because PageSpeed is not going to reload the resource
+until the one in its cache expires, or you <a href="system#flush_cache">clear
+its cache</a>.
+</p>
+<p>
+We recommend an origin TTL of 10 minutes, which provides reasonable
+responsiveness when you update a file. If you try to make it much smaller, then
+your server will need to refresh it more frequently. This adds server load and
+reduces optimization.
+</p>
+<p>
+To see changes to your files more quickly while
+developing, <a href="system#flush_cache">flush the cache</a> on your server(s).
+</p>
+<p>
+If your environment allows you to
+enable <a href="domains#ModPagespeedLoadFromFile">LoadFromFile</a>,
+you can get the best of both worlds because PageSpeed can eliminate its
+internal server-side cache.
+</p>
+<h2 id="tiny-mce-errors">Why is PageSpeed giving me errors in jquery or
+js_tinyMCE?</h2>
+<p>
+Some JavaScript is introspective, being sensitive to its own name or the path
+it's loaded from. While PageSpeed has an internal list
+(<a href="https://github.com/apache/incubator-pagespeed-mod/blob/master/net/instaweb/rewriter/rewrite_options.cc">DisallowTroublesomeResources</a>)
+hardcoded with filenames of JavaScript libraries that are known to be
+problematic, and <a href="restricting_urls#aris">inspects the source of
+others</a> looking for dangerous constructs, it doesn't always correctly
+determine whether it is safe to rewrite a given file. If you have a file that
+is giving JavaScript errors, you can tell PageSpeed to leave it alone with
+<a href="restricting_urls">Disallow</a>.
+</p>
+<h2 id="name-resolution-failure">What's with all these "Serf" errors in my logs?
+Error status=670003 (Temporary failure in name resolution)</h2>
+<p>
+This can happen when the DNS cannot be accessed accurately from the server. Thus
+sub-resources cannot be fetched and rewritten correctly.
+</p>
+<p>
+To test that this is the case, <code>ssh</code> into your machine and <code>wget</code> a URL:
+</p>
+<pre class="prettyprint lang-bsh">
+ $ ssh YOUR_SITE
+ $ wget http://YOUR_SITE/
+</pre>
+<p>
+If this fails, then DNS is not accessible or there is some other networking
+issue stopping you from accessing your host from itself.
+</p>
+<p>
+One solution is to use <a href="domains#mapping_origin">origin-mapping</a> to
+indicate the host from which the resources should be fetched:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedMapOriginDomain localhost www.example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed MapOriginDomain localhost www.example.com;</pre>
+</dl>
+<p>
+This bypasses DNS lookup by telling PageSpeed to get all resources for
+domain <code>www.example.com</code> from <code>localhost</code>.
+</p>
+<p>
+This can also be used to improve the performance of PageSpeed when it is
+sitting behind a load balancer. It may be preferable to use localhost to load
+the resources rather than going out to the load-balancer and back.
+</p>
+<h2 id="tmpfs">Can I move PageSpeed's file-based cache into RAM?</h2>
+<p>
+Why yes, you can. PageSpeed uses the file system for its cache
+implementation. There is no requirement that this be a physical disk. Disk
+pressure will be reduced and performance may be improved by using a memory-based
+file system.
+</p>
+<p>
+Put this in <code>/etc/fstab</code>, with the uid and guid set to the appropiate
+user and group of your webserver, and set path to your needs. Feel free to
+change the size; here it is 256Mb:
+<pre class="prettyprint lang-bsh">
+ tmpfs /path/to/pagespeed_cache tmpfs size=256m,mode=0775,uid=httpd,gid=httpd 0 0
+</pre>
+<p>
+Save it, and after that mount the tmpfs:
+</p>
+<pre class="prettyprint lang-bsh">
+ mount /path/to/pagespeed_cache
+</pre>
+<h2 id="configure-make">Why don't you allow source-installs in Apache via
+./configure && make?</h2>
+<p>
+mod_pagespeed is dependent on several other packages that
+use <code>gclient</code>. For us to switch away from this build methodology
+we'd have to either:
+</p>
+<ul>
+ <li>rewrite the functionality we get for free from other packages,
+ <b>or</b></li>
+ <li>get these packages to switch
+ methodologies <b>and</b> document for people installing from source that
+ they must <code>configure</code> and <code>make</code> about 10 other
+ packages before they could compile ours.</li>
+</ul>
+<p>
+To do either of those would cost us a lot of development time that we'd prefer
+to spend making PageSpeed better. The benefit of <code>gclient</code>,
+besides the above, is that it lets us control explicitly which library versions
+we link in, out of a large number of direct and transitive dependencies, helping
+us create a consistent experience for our source-code builds. If we had to ask
+our source-code installers to <code>configure</code> and <code>make</code>
+multiple dependent libraries there would likely be a lot of
+version-incompatibilities.
+</p>
+<p>
+We do support <code>./configure && make</code> in Nginx, but that only works
+because we package up a binary distribution of the PageSpeed Optimization
+Library and a "<a href="build_ngx_pagespeed_from_source">source</a>"
+installation only builds the ngx_pagespeed-specific files from source. When you
+want
+to <a href="https://github.com/apache/incubator-pagespeed-ngx/wiki/Building-PSOL-From-Source">build
+PSOL from source along with ngx_pagespeed</a> you still need to
+use <code>gclient</code>.
+</p>
+<h2 id="tracking-image">Why is my Google Analytics data being inflated by
+"Serf"?</h2>
+<p>
+If you track page views with a tracking image, you will need to explicitly tell
+PageSpeed not to try to fetch that image. For example if your tracking image
+were:
+</p>
+<pre class="prettyprint">
+ <img src="/ga.php?utmac=...">
+</pre>
+<p>
+you would add:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedDisallow "*/ga.php*"</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed Disallow "*/ga.php*";</pre>
+</dl>
+<p>
+to your configuration file.
+</p>
+<h2 id="mod_php">mod_pagespeed does not rewrite pages produced from mod_php</h2>
+<p>
+mod_pagespeed only rewrites pages specifically marked as <code>Content-Type:
+text/html</code> (and a few other HTML types). If you dynamically generate your
+pages from mod_php, PHP needs to set this header correctly.
+</p>
+<p>
+One way to do this is to use the PHP's <a href="http://php.net/manual/en/function.header.php">header function</a>:
+</p>
+<pre class="prettyprint">
+ <?php
+ header('Content-Type: text/html')
+ ?>
+</pre>
+<p>
+This code goes at the top of your php file.
+</p>
+<h2 id="meta_tags_and_xhtml">PageSpeed causes my page to display an <code>XML
+Parsing Error</code> message</h2>
+<p>
+This usually happens when using a content management or generation system
+(we've seen it with Munin and Magento for example). The full error message
+looks something like:
+</p>
+<pre class="prettyprint">
+ XML Parsing Error: mismatched tag. Expected: </li>.
+ Location: http://www.example.com/
+ Line Number 123, Column 4: </ul>
+</pre>
+<p>
+This happens when the generated content has a <code>meta</code> tag that
+identifies the content as XHTML but the content has markup that is not valid
+XHTML, <em>and</em> you have configured your webserver to set the content type
+to HTML, so the browser parses it as HTML and doesn't detect the invalid XHTML
+errors.
+</p>
+<p>
+However, when <code>convert_meta_tags</code> is enabled (and it's a core filter
+so is on by default), PageSpeed inserts a content header into the response
+with the value in the <code>meta</code> tag, namely XHTML
+(<code>application/xhtml+xml</code> to be precise), resulting in the browser
+displaying the error message because it is now parsing the page as XHTML and
+it rejects the invalid content.
+</p>
+<p>
+There are three solutions, in descending order of preference:
+<ul>
+<li>If the content is XHTML, write XHTML and validate it with an XHTML
+ validator.</li>
+<li>If the content is not XHTML, remove the <code>meta</code> tag that claims
+ it is.</li>
+<li>If the content is not XHTML but you can't remove the <code>meta</code> tag,
+ say because your CMS doesn't let you, disable the
+ <code>convert_meta_tags</code> filter in your <code>pagespeed.conf</code>:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedDisableFilters convert_meta_tags</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed DisableFilters convert_meta_tags;</pre>
+</dl>
+</li>
+</ul>
+<h2 id="selinux_permissions">Why do I get <em>Permission denied</em> errors
+ in my log file on CentOS, RHEL, or any system using SELinux?</h2>
+<p>
+The symptom is many error messages in the webserver log file of the form (split
+across multiple lines here for readability):
+</p>
+<pre class="prettyprint">
+ [Mon Jan 01 02:03:04 2001] [error] [mod_pagespeed 1.0.22.7-2005 @1234]
+ /path/to/pagespeed_cache/randomgibberish.lock:0:
+ creating dir (code=13 Permission denied)
+</pre>
+<p>
+These are because SELinux by default restricts permissions of daemons for
+extra security, so you need to grant permission for the <code>httpd</code>
+or daemon to write to the cache directory:
+</p>
+<pre class="prettyprint">
+ chcon -R -t httpd_sys_content_t /path/to/pagespeed_cache
+</pre>
+This is for Apache; we're not sure what you need to do for Nginx.
+
+<h2 id="loopback_fetches">My logs contain messages about missing
+files requested from 224.0.0.0 and resources are not optimized, what's wrong?</h2>
+<p>
+
+For <a href="CVE-2012-4001">security reasons</a>, PageSpeed will only fetch
+from host names it is explicitly told about via its domain configuration
+directives and from 127.0.0.1, the loopback interface of the server it's running
+on. Many Apache configuration management tools, however, will configure virtual
+hosts to only listen on the external IP, which causes those fetches to fail.
+<p>
+If you are affected, the following options may be appropriate:
+<ul>
+ <li>Unless you have a reason not to, have your virtual hosts listen on all
+ interfaces: change the directives of the form
+ <code><VirtualHost 198.51.100.1:80></code> to the form
+ <code><VirtualHost *:80></code>
+ </li>
+ <li>For every virtual host, list its domain name(s) with the
+ <code>ModPagespeedDomain</code> directive inside its own
+ <code><VirtualHost></code> block. For example:
+ <pre class="prettyprint">
+<VirtualHost 198.51.100.1:80>
+ServerName www.example.com
+ModPagespeedDomain www.example.com
+</pre>
+ </li>
+ <li>For every virtual host, provide a <a href="domains#mapping_origin">
+ <code>ModPagespeedMapOriginDomain</code></a> directive giving where to load
+ its resources, for example:
+ <pre class="prettyprint">
+<VirtualHost 198.51.100.1:80>
+ServerName www.example.com
+ModPagespeedMapOriginDomain 198.51.100.1 www.example.com
+</pre>
+ </li>
+ <li>If you have <a href="configuration#virtual-hosts">
+ <code>ModPagespeedInheritVHostConfig on</code></a>, you can also provide the
+ origin mapping globally, which may be useful in combination with wildcards,
+ for example:
+ <pre class="prettyprint">
+ModPagespeedMapOriginDomain loadbalancer.example.com *.example.com
+</pre>
+
+ <p class="warning"><b>Warning:</b> You do not generally want to use
+ <code>Domain</code> globally as doing so will tell PageSpeed
+ that you consider all of these domains as mutually trusting.</p>
+ </li>
+ <li>If you are running a proxy or for some other reason cannot easily
+ enumerate all virtual hosts, it is possible to disable this behavior,
+ after taking some precautions. Please see
+ <a href="domains#fetch_servers">fetch server restrictions</a> for
+ more information.
+ </li>
+</ul>
+
+<h2 id="beacons">Why are rewritten pages sending POSTs back to my server?</h2>
+<p>
+Certain filters need to determine things about the page: in particular, the
+<code><a href="filter-lazyload-images">lazyload_images</a></code>,
+<code><a href="filter-inline-preview-images">inline_preview_images</a></code>,
+and <code><a href="reference-image-optimize#inline_images">inline_images</a>
+</code> filters need to determine which images are above the fold, and the
+<code><a href="filter-prioritize-critical-css">prioritize_critical_css</a>
+</code>filter needs to determine the CSS actually used by the page.
+<p>
+</p>To do this, the filters inject JavaScript into the rewritten HTML that
+analyzes the page in the browser and sends data back to mod_pagespeed using a
+POST method. The default target is <code>/mod_pagespeed_beacon</code> but that
+can be changed using the <code>
+<a href="filter-instrumentation-add#beacon_url">ModPagespeedBeaconUrl</a>
+</code> directive.
+</p>
+
+<h2 id="control_beacons">How do I enable or disable beacon POSTs being sent back
+to my server?</h2>
+<p>
+Filters that use the beacon automatically inject JavaScript to send the POST
+back to the server, and the POST handler is always enabled in mod_pagespeed,
+so there's nothing to do to enable beaconing.
+</p>
+<p>
+To disable the use of beacons by the image rewriting filters use the <code>
+<a href="config_filters#beacons">ModPagespeedCriticalImagesBeaconEnabled</a>
+</code> directive. If you disable image beacons but enable filters that use
+them, the filters will work but not as well as when beacons are enabled.
+<p>
+To disable the POST handler for all filters there are two options: either
+disable all the filters that use it, or use a
+<code><Location></code> directive to block it. Filters are disabled using
+<a href="config_filters#enabling">ModPagespeedDisableFilters</a>. An example
+<code><Location></code> directive to block all beacon POST handling that
+can be added to your <code>pagespeed.conf</code> file is:
+<pre class="prettyprint" id="disable_handler">
+ <Location /mod_pagespeed_beacon>
+ Order allow,deny
+ </Location>
+</pre>
+<p>
+If you block POSTs but enable filters that use beacons, depending on the filter
+it will either have limited functionality or have no useful effect, but in all
+cases pointless processing will occur in both the server and the browser, so
+you should disable and forbid these filters if you block POSTs.
+</p>
+<p class="note">
+<strong>Note:</strong>Even if you disable all filters that use beacons someone
+could use tools like <code>wget</code> or <code>curl</code> to send POSTs to
+your server. These will have no effect but they will require processing. If you
+want to completely disable POST handling use a <code><Location></code>
+directive.
+</p>
+
+<h2 id="noscript-redirect">Why is PageSpeed inserting a meta refresh to
+/?PageSpeed=noscript or /?ModPagespeed=noscript at the top of the page?</h2>
+<p>
+The <code><a href="filter-js-defer">defer_javascript</a></code>,
+<code><a href="filter-lazyload-images">lazyload_images</a></code>,
+<code><a href="filter-dedup-inlined-images">dedup_inlined_images</a></code>, and
+<code><a href="filter-local-storage-cache">local_storage_cache</a></code>
+filters require JavaScript to render pages correctly. To support clients that
+have JavaScript disabled, if any of these filters are enabled, PageSpeed will
+insert a meta refresh inside a <code>noscript</code> tag at the top of the page.
+This meta refresh will redirect clients with JavaScript disabled to the current
+URL with a '<code>?PageSpeed=noscript</code>' query parameter appended which
+disables filters that require JavaScript.
+</p>
+<p>
+If you wish to disable this redirect, for instance if your page already requires
+JS to function correctly, set the following option in your
+<code>pagespeed.conf</code>:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedSupportNoScriptEnabled false</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed SupportNoScriptEnabled false;</pre>
+</dl>
+</p>
+
+
+<h2 id="collapse-newlines">Why won't the <code>collapse_whitespace</code> filter
+remove newlines?</h2>
+
+<p>
+When removing whitespace from HTML, some website optimizers remove newlines
+entirely, but PageSpeed leaves them in. This isn't actually a problem with newlines,
+however, it's that it's not generally safe to remove a run of whitespace
+entirely. You can turn any number of consecutive whitespace characters into a
+single one, and we do that, but removing the whole run can make the site render
+differently.
+</p>
+
+<p>
+To take a simple example, consider:
+</p>
+
+<pre>
+ <body>
+ <h1>Hello World</h1>
+ Lorem ipsum dolor sit amet, consectetur
+ adipiscing elit. Fusce molestie ante <b>vitae</b>
+ iaculis varius. ...
+ </body>
+</pre>
+
+<p>
+PageSpeed with <code>collapse_whitespace</code> will turn this into:
+</p>
+
+<pre>
+<body>
+<h1>Hello World</h1>
+Lorem ipsum dolor sit amet, consectetur
+adipiscing elit. Fusce molestie ante <b>vitae</b>
+iaculis varius. ...
+</body>
+</pre>
+
+<p>
+If PageSpeed went further and put it all on one line, it would be
+converting <code><b>vitae</b> iaculis</code>
+into <code><b>vitae</b>iaculis</code>, which would change the
+rendering from "<b>vitae</b> iaculis" into "<b>vitae</b>iaculis"; one word
+instead of two. It would have been safe to turn <code><body>
+<h1>Hello World</h1></code> into <code><body><h1>Hello
+World</h1></code>, but doing one and not the other requires understanding
+the CSS (and JS) to the point where we can reliably tell that one pair of
+elements are <code>display: block</code> while the other pair
+are <code>display: inline</code>.
+</p>
+
+<h2 id="warning-fetch-rate">I've got a warning saying
+"Serf fetch failure rate extremely high". What does this mean?</h2>
+
+<p>The warning means that, when PageSpeed tried to fetch resources inside your
+web page for optimization, over 50% of attempts inside a 30-minute period
+failed. This may just mean you have some broken resource includes in your
+pages (in which case, it may be a good idea to fix them for better performance),
+but might indicate that PageSpeed's fetching is not working properly. If you
+have in-place resource optimization on, that can result in user requests for
+<code>.pagespeed.</code> URLs returning error 404 intermittently.</p>
+
+<p>First of all, check to see if the log mentions anything else about fetch
+trouble. If what's there is not helpful, the root cause may be more obvious
+if you follow these steps:</p>
+<ol>
+<li>Disable <a href="system#ipro">in-place resource optimization</a> temporarily.
+ </li>
+<li>Clear PageSpeed cache.</li>
+<li>Open a test page with a <code>?PagespeedFilters=+debug</code> query
+ parameter, reload it a few times, and see if resources are getting optimized,
+ and if not if there is an error message.
+<li>Revert the config changes.</li>
+</ol>
+
+<p>Most likely you may need to configure an <a href="domains#mapping_origin">
+origin domain, to specify the host or IP to talk to fetch resources.</p>
+
+<p>You may also want to consider using <a href="domains#ModPagespeedLoadFromFile">
+<code>LoadFromFile</code></a> functionality, as that performs much better if
+your resources are static.</p>
+
+<h2 id="varying-results">Sometimes pages are served as partially optimized. How can
+I achieve a more steady optimization ouput?</h2>
+
+<p>There are two (relatively) common situations that may lead up to a fluctuating
+level of optimization in the output:
+<ol>
+<li>Low traffic, combined with short http expiry times for image, css and javascript
+responses: <br/>
+Consider increasing the http expiry applied to the original
+resources, or set up <a href="domains#ModPagespeedLoadFromFile">LoadFromFile</a>
+to allow the module to load static files directly from disk.</li>
+<li>High cache churn rates:<br/>
+If PageSpeed's caches are sized too small, optimized assets falling out of the cache
+may cause frequent reoptimization. <a href="system#caching">Sizing the cache</a> to 3
+to 4 times the size of the original assets of the website should allow the module to
+cache all the original resources plus multiple optimized variants (for serving
+different user-agents and screen sizes).
+</li>
+<li>If the above did not help, the <a href="admin">admin pages</a> offer various tools
+that may assist in diagnosing what happens.</li>
+</ol>
+
+</p>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-attribute-elide.html b/doc/filter-attribute-elide.html
new file mode 100644
index 0000000..dc8ede5
--- /dev/null
+++ b/doc/filter-attribute-elide.html
@@ -0,0 +1,119 @@
+<!--
+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>Elide Attributes</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Elide Attributes</h1>
+
+
+<h2>Configuration</h2>
+<p>
+The 'Elide Attributes' filter is enabled by specifying:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters elide_attributes</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters elide_attributes;</pre>
+</dl>
+<p>
+in the configuration file.
+
+<h2>Description</h2>
+<p>
+The 'Elide Attributes' filter reduces the transfer size of HTML files
+by removing attributes from tags when the specified value is equal to
+the default value for that attribute. This can save a modest number of
+bytes, and may make the document more compressible by canonicalizing
+the affected tags.
+</p>
+
+<h2>Operation</h2>
+<p>
+There are two cases where an attribute value can be removed. First,
+some attributes are "single-valued" or "boolean", in that the value
+specified for the attribute is irrelevant -- all that matters is
+whether the attribute is present or not. In such cases, the filter
+will remove the value from the tag, leaving only the attribute name.
+</p>
+<p>
+For example, the following tag:
+</p>
+<pre class="prettyprint">
+ <button name="ok" disabled="disabled">
+</pre>
+<p>
+can be rewritten to:
+</p>
+<pre class="prettyprint">
+ <button name="ok" disabled>
+</pre>
+<p>
+The second case is an optional attribute with a default value. If an
+HTML attribute includes an explicit value for an attribute (perhaps to
+aid readability) that is equal to the default attribute, the filter
+will remove the attribute name and value, knowing that the browser
+will infer the intended attribute anyway. For example, the following
+tag:
+</p>
+<pre class="prettyprint">
+ <form method=get>
+</pre>
+<p>
+can be rewritten to:
+</p>
+<pre class="prettyprint">
+ <form>
+</pre>
+<h3>Example</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> on this
+<a href="https://www.modpagespeed.com/examples/elide_attributes.html?ModPagespeed=on&ModPagespeedFilters=elide_attributes">example</a>.
+</p>
+
+<h2>Requirements</h2>
+<p>
+The 'Elide Attributes' filter must be wary of documents with an XHTML
+doctype, as removing the value from a single-valued attribute will
+result in invalid XHTML. The filter attempts to recognize XHTML
+doctype declarations and will disable this rewriting feature in such
+cases.
+</p>
+
+<h2>Risks</h2>
+<p>This filter is considered medium risk. It is safe for most pages, but
+ might break CSS formatting on certain pages that match on default attributes
+ that this filter removes. Further, JavaScript can be written that inspects
+ the DOM looking for the presence of certain attributes. Such JavaScript may
+ behave differently on a page which has removed otherwise unnecessary
+ attributes.</p>
+
+
+</div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-cache-extend-pdfs.html b/doc/filter-cache-extend-pdfs.html
new file mode 100644
index 0000000..2e88695
--- /dev/null
+++ b/doc/filter-cache-extend-pdfs.html
@@ -0,0 +1,83 @@
+<!--
+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>Extend Cache PDFs</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Extend Cache PDFs</h1><h2>Configuration</h2>
+<p>
+The 'Extend Cache PDFs' filter is enabled by specifying:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters extend_cache_pdfs</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters extend_cache_pdfs;</pre>
+</dl>
+in the configuration file.
+
+<h2>Description</h2>
+<p>
+'Extend Cache PDFs' is a version of <a href="filter-cache-extend">Extend
+Cache</a> that acts on PDFs. Unlike 'Extend Cache' it applies not only to
+resources but also to hyperlinks. For example, while 'Extend Cache' would not
+apply to <code><a href="example.jpg"></code>, 'Extend Cache
+PDFs' would apply to <code><a href="example.pdf"></code>.
+</p>
+
+<h2>Operation</h2>
+<p>
+<a href="filter-cache-extend#operation">Extend Cache: Operation</a> describes
+the standard operation of cache extension in PageSpeed. This filter identifies
+PDF URLs by their ".pdf" extension and marks them as eligible for cache
+extension.
+</p>
+<h3>Example</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> for
+cache-extending PDFs
+<a
+href="https://www.modpagespeed.com/examples/extend_cache_pdfs.html?ModPagespeed=on&ModPagespeedFilters=extend_cache_pdfs"
+>in HTML</a>.
+</p>
+
+<h2>Limitations</h2>
+<p>
+In addition to the <a href="filter-cache-extend#limitations">limitations of
+Extend Cache</a>, this filter is limited by its reliance on file extensions for
+identifying potential PDF URLs. PDF resources with URLs ending in something
+other than ".pdf" won't be considered for cache extension.
+</p>
+<h2>Risks</h2>
+<p>
+This filter has the same risks as <a href="filter-cache-extend#risks">Extend
+Cache</a>.
+</p>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-cache-extend.html b/doc/filter-cache-extend.html
new file mode 100644
index 0000000..82ed930
--- /dev/null
+++ b/doc/filter-cache-extend.html
@@ -0,0 +1,219 @@
+<!--
+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>Extend Cache</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Extend Cache</h1>
+
+<h2>Configuration</h2>
+<p>
+The 'Extend Cache' filter is enabled by specifying:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters extend_cache</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters extend_cache;</pre>
+</dl>
+<p>
+in the configuration file. This is equivalent to enabling all three
+of <code>extend_cache_images</code>, <code>extend_cache_scripts</code>,
+and <code>extend_cache_css</code>.
+</p>
+<p>
+Also see: <a href="filter-cache-extend-pdfs">extend_cache_pdfs</a>.
+</p>
+
+<h2>Description</h2>
+<p>
+'Extend Cache' seeks to improve the cacheability of a web page's resources
+without compromising the ability of site owners to change the resources
+and have those changes propagate to users' browsers.
+</p>
+<p>
+This filter is based on the
+<a target="_blank" href="https://developers.google.com/speed/docs/best-practices/caching#LeverageBrowserCaching">
+best practice</a> to optimize caching, as applied to the browser.
+</p>
+
+<h2 id="operation">Operation</h2>
+<p>
+The 'Extend Cache' filter rewrites the URL references in the HTML
+page to include a hash of the resource content (if
+<a href="filter-css-rewrite"><code>rewrite_css</code></a> is enabled
+then image URLs in CSS will also be rewritten). Thus if the site
+owners change the resource content, then the URL for the rewritten
+resource will also change. The old content in the user's browser
+cache will not be referenced again, because it will not match the new name.
+</p>
+<p>
+The 'Extend Cache' filter also rewrites the HTTP header to extend the
+<code>max-age</code> value of the cacheable resource to 31536000 seconds,
+which is one year.
+</p>
+<p>
+For example, for the following HTML tag/HTTP header pair:
+</p>
+<pre class="prettyprint">
+HTML tag : <img src="images/logo.gif">
+HTTP header: Cache-Control:public, max-age=300
+</pre>
+<p>
+PageSpeed will rewrite these into:
+</p>
+<pre class="prettyprint">
+HTML tag : <img src="images/logo.gif.pagespeed.ce.xo4He3_gYf.gif">
+HTTP header: Cache-Control:public, max-age=31536000
+</pre>
+<p>
+PageSpeed uses the origin cache time-to-live (TTL), in this case
+300 seconds, to periodically re-examine the content to see if it's
+changed. If it changes, then the hash of the content will also
+change. Thus it's safe to serve the hashed URL with a long
+timeout—PageSpeed uses one year.
+</p>
+<p>
+If the site owners change the logo, then PageSpeed will notice
+within 5 minutes and begin serving a different URL to users. But if
+the content does not change, then the hash will not change, and the
+copy in each user's browser will still be valid and reachable.
+</p>
+<p>
+Thus the site owners are still in complete control of how rapidly they can
+deploy changes to the site, but this does not affect the effectiveness
+of the browser cache. Decreasing the TTL only affects how often
+PageSpeed will need to re-examine the resource.
+</p>
+<p>
+It should be noted that cache extension is built into other
+PageSpeed filters as well. All filters that rewrite resources
+include a content-hash in the generated URL, and serve the resource
+with a 1-year TTL. The purpose of this filter is to extend cache
+lifetimes for all resources that are not otherwise optimized.
+</p>
+<h3>Example</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> for
+cache-extending resources
+<a href="https://www.modpagespeed.com/examples/extend_cache.html?ModPagespeed=on&ModPagespeedFilters=extend_cache">in HTML</a> and
+<a href="https://www.modpagespeed.com/examples/rewrite_css_images.html?ModPagespeed=on&ModPagespeedFilters=rewrite_css,extend_cache">in CSS</a>.
+</p>
+
+<h2 id="limitations">Limitations</h2>
+<p>
+Cache extension is only applied to resources that are publicly
+cacheable to begin with. Cache extension is not done on resources
+that have <code>Cache-Control: private</code> or <code>Cache-Control:
+nocache</code>.
+</p>
+<p>
+This can be overridden with:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedForceCaching on</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed ForceCaching on;</pre>
+</dl>
+<p>
+This switch is intended for experimental purposes only, to help
+evaluate the benefit of cache extension against the effort of adding
+cache-control headers to resources. Live traffic should not be served
+this way.
+</p>
+<p>
+The following configure file fragment demonstrates how to configure
+caching headers in Apache. This is how the mod_pagespeed_example
+directory is set up.
+</p>
+<pre class="prettyprint lang-sh">
+# These caching headers are set up for the mod_pagespeed example, and
+# also serve as a demonstration of good values to set for the entire
+# site, if it is to be optimized by mod_pagespeed.
+<Directory /var/www/mod_pagespeed_example>
+ # Any caching headers set on HTML are ignored, and all HTML is served
+ # uncacheable. PageSpeed rewrites HTML files each time they are served. The
+ # first time mod_pagespeed sees an HTML file, it generally won't optimize it
+ # fully. It will optimize better after the second view. Caching defeats this
+ # behavior.
+
+ # Images, styles, and JavaScript are all cache-extended for
+ # a year by rewriting URLs to include a content hash. mod_pagespeed
+ # can only do this if the resources are cacheable in the first place.
+ # The origin caching policy, set here to 10 minutes, dictates how
+ # frequently mod_pagespeed must re-read the content files and recompute
+ # the content-hash. As long as the content doesn't actually change,
+ # the content-hash will remain the same, and the resources stored
+ # in browser caches will stay relevant.
+ <FilesMatch "\.(jpg|jpeg|gif|png|js|css)$">
+ Header set Cache-control "public, max-age=600"
+ </FilesMatch>
+</Directory>
+</pre>
+<p>
+The equivalent configuration for Nginx would be:
+<pre class="prettyprint">
+# Make sure this goes after the .pagespeed. location regexp in your
+# configuration file so that .pagespeed. resources don't get this header
+# applied.
+location /mod_pagespeed_example {
+ location ~* \.(jpg|jpeg|gif|png|js|css)$ {
+ add_header Cache-Control "public, max-age=600";
+ }
+}
+</pre>
+
+<h2 id="risks">Risks</h2>
+<p>
+This filter is considered low risk. The rewritten URL will have a different name
+than that of the original URL, however, so JavaScript that uses URLs as
+templates can stop working. For example, consider a site that
+has <code><input type=image src="button.gif"></code> and runs JavaScript
+that turns <code>button.gif</code> into <code>button-hover.gif</code> when the
+user hovers over the button. With cache extension enabled, or any filter that
+changes the URLs of images, PageSpeed would replace the HTML fragment with
+something like <code><input type=image
+src="button.gif.pagespeed.ce.xo4He3_gYf.gif"></code>. If the script was
+coded as "insert '-hover' before the final '.'" then it would construct an
+invalid hover URL of <code>button.gif.pagespeed.ce.xo4He3_gYf-hover.gif</code>.
+If this is a problem on your site, consider <a href="system#ipro">In-Place
+Resource Optimization</a>.
+
+</p>
+<p>
+ When applied to JavaScript files, this filter is sensitive to
+ <a href="restricting_urls#aris"><code
+ >AvoidRenamingIntrospectiveJavascript</code></a>. For example,
+ a JavaScript file that
+ calls <code>document.getElementsByTagName('script')</code> will not be
+ cache-extended.
+</p>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-canonicalize-js.html b/doc/filter-canonicalize-js.html
new file mode 100644
index 0000000..a2d4ab5
--- /dev/null
+++ b/doc/filter-canonicalize-js.html
@@ -0,0 +1,293 @@
+<!--
+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>Canonicalize JavaScript Libraries</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Canonicalize JavaScript Libraries</h1>
+<h2>Configuration</h2>
+<p>
+The 'Canonicalize JavaScript Libraries' filter is enabled by specifying:
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters canonicalize_javascript_libraries</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed EnableFilters canonicalize_javascript_libraries;
+
+</pre>
+</dl>
+<p>
+in the configuration file.
+</p>
+
+<h2>Description</h2>
+<p>
+This filter identifies popular JavaScript libraries that can be replaced with
+ones hosted for free by a JavaScript library hosting service — by default
+the <a href="/speed/libraries/">Google Hosted Libraries</a>. This has several
+benefits:
+<ul>
+ <li>Most important, first-time site visitors can benefit from browser caching,
+since they may have visited other sites making use of the same service to obtain
+the libraries.</li>
+ <li>The JavaScript hosting service acts as a content delivery network for the
+hosted files, reducing load on the server and improving browser load times.</li>
+ <li>There are no charges for the resulting use of bandwidth by site
+visitors.</li>
+ <li>The hosted versions of library code are generally optimized with
+third-party minification tools. These optimizations can make use of
+library-specific annotations or minification settings that aren't portable to
+arbitrary JavaScript code, so the libraries benefit from more aggressive
+optimization than can be provided by PageSpeed.</li>
+</ul>
+<p>
+In Apache the default set of libraries can be found in
+the <code><a href="https://github.com/apache/incubator-pagespeed-mod/blob/master/net/instaweb/genfiles/conf/pagespeed_libraries.conf">pagespeed_libraries.conf</a></code>
+file, which is loaded along with <code>pagespeed.conf</code> when Apache starts
+up. It contains signatures for all the <a href="/speed/libraries/">Google Hosted
+Libraries</a>. In Nginx you need to
+convert <code>pagespeed_libraries.conf</code> from Apache-format to Nginx
+format:
+</p>
+<pre class="prettyprint lang-sh">
+$ scripts/pagespeed_libraries_generator.sh > ~/pagespeed_libraries.conf
+$ sudo mv ~/pagespeed_libraries.conf /path/to/nginx/configuration_files/
+</pre>
+<p>
+You also need to include it in your Nginx configuration by reference:
+</p>
+<pre class="prettyprint lang-sh">
+include pagespeed_libraries.conf;
+</pre>
+<p>
+Don't edit <code>pagespeed_libraries.conf</code>. Local edits will keep you
+from being able to update it when you update PageSpeed. Rather than editing it
+you should add additional libraries to your main configuration file:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedLibrary 43 1o978_K0_LNE5_ystNklf \
+ //www.modpagespeed.com/rewrite_javascript.js</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed Library 43 1o978_K0_LNE5_ystNklf
+ //www.modpagespeed.com/rewrite_javascript.js;</pre>
+</dl>
+<p>
+The general format of these entries is:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedLibrary bytes MD5 canonical_url</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed Library bytes MD5 canonical_url;</pre>
+</dl>
+<p>
+Here <code>bytes</code> is the size in bytes of the library <em>after</em>
+minification by PageSpeed, and <code>MD5</code> is the MD5 hash of the
+library after minification. Minification controls for differences in whitespace
+that may occur when the same script is obtained from different
+sources. The <code>canonical_url</code> is the hosting service URL used to
+replace occurrences of the script. Note that the canonical URL in the above
+example is protocol-relative; this means the data will be fetched using the same
+protocol (<code>http</code> or <code>https</code>) as the containing
+page. Because older browsers don't handle protocol-relative URLs reliably,
+PageSpeed resolves a protocol-relative library URL to an absolute URL based
+on the protocol of the containing page. Do not use <code>http</code> canonical
+URLs in configurations that may serve content over <code>https</code>, or the
+rewritten pages will expose your site to attack and trigger a mixed-content
+warning in the browser. Similarly, avoid using <code>https</code> URLs unless
+you know that the resulting library will eventually be fetched from a secure
+page, as SSL negotiation adds overhead to the initial request.
+</p>
+<p>
+Additional library configuration metadata can be generated with the help of
+the <code>pagespeed_js_minify</code> utility installed along with PageSpeed.
+To use this utility, you will need a local copy of the JavaScript code that you
+wish to replace. If this is stored in <code>library.js</code>, you can generate
+<code>bytes</code> and <code>MD5</code> as follows:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >$ pagespeed_js_minify --print_size_and_hash library.js</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >$ cd /path/to/psol/lib/Release/linux/ia32/
+ $ pagespeed_js_minify --print_size_and_hash library.js</pre>
+</dl>
+<p>
+If you're using the <a href="filter-js-minify#new-minifier">new
+javascript minifier</a>, add the <code>--use_experimental_minifier</code>
+argument to <code>pagespeed_js_minify</code>. If you're using the old minifier,
+add <code>--nouse_experimental_minifier</code>. (As of 1.10.33.0,
+<code>--use_experimental_minifier</code> is default. Previously,
+<code>--nouse_experimental_minifier</code> was.)
+The default <code>pagespeed_libraries.conf</code> includes hashes for both
+the old and new minifiers.
+</p>
+<p>
+This filter is based on the best practices of
+<a target="_blank" href="https://developers.google.com/speed/docs/best-practices/caching#LeverageBrowserCaching">
+optimizing browser caching</a>
+and <a target="_blank" href="https://developers.google.com/speed/docs/best-practices/payload#MinifyJS">reducing payload
+size</a>.
+</p>
+
+<h2>Operation</h2>
+<p>
+In order to identify a library and canonicalize its URL, PageSpeed must of
+course be able to fetch the JavaScript code from the URL on the original page.
+Because library canonicalization identifies libraries solely by their size and
+hash signature, it is not necessary to authorize PageSpeed to fetch content
+from the domain hosting the canonical content itself. This means that it is
+safe to use this filter behind a reverse proxy or in other situations where
+network access by PageSpeed is deliberately restricted. Browsers visiting
+the site will fetch the content from the canonical URL, but PageSpeed itself
+does not need to do so.
+</p>
+
+<h3>Examples</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> on this
+<a href="https://www.modpagespeed.com/examples/canonicalize_javascript_libraries.html?ModPagespeed=on&ModPagespeedFilters=canonicalize_javascript_libraries">example</a>.
+</p>
+<p>
+If the HTML document looks like this:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <script src="jquery_1_8.js">
+ </script>
+ <script src="a.js">
+ </script>
+ <script src="b.js">
+ </script>
+ </head>
+ <body>
+ ...
+ </body>
+</html>
+</pre>
+<p>
+Then, assuming <code>jquery_1_8.js</code> was an unminified copy of the jquery
+library and <code>a.js</code> and <code>b.js</code> contained site-specific code
+that made use of jquery, the page would be rewritten as follows:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js">
+ </script>
+ <script src="a.js">
+ </script>
+ <script src="b.js">
+ </script>
+ </head>
+ <body>
+ ...
+ </body>
+</html>
+</pre>
+<p>
+The library URL has been replaced by a reference to the canonical minified
+version hosted on <code>ajax.googleapis.com</code>. Note that canonical
+libraries do not participate in most other JavaScript optimizations. For
+example, if <a href="filter-js-combine">Combine JavaScript</a> is also enabled,
+the above page will be rewritten as follows:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js">
+ </script>
+ <script src="http://www.example.com/a.js+b.js.pagespeed.jc.zYiUaxFS8I.js">
+ </script>
+ </head>
+ <body>
+ ...
+ </body>
+</html>
+</pre>
+<p>
+The canonical library is <em>not</em> combined with the other two JavaScript
+files, since this would lose the bandwidth and caching benefits of fetching it
+from the canonical URL.
+</p>
+<p>
+If <a href="filter-js-defer">defer_javascript</a> is enabled, <em>and</em> library
+is <em>not</em> tagged with <code>data-pagespeed-no-defer</code>,
+the canonicalized library is deferred.
+</p>
+
+<h2>Requirements</h2>
+<p>
+Only complete, unmodified libraries referenced by <code><script></code>
+tags in the HTML will be rewritten. Libraries that are loaded by other means
+(for example by injecting a loader script) or that have been modified will not
+be canonicalized.
+</p>
+
+<h2>Risks</h2>
+<p>
+You must ensure that you abide by the terms of service of the providers of the
+canonical content before enabling canonicalization. The terms of service for the
+default configuration can be found
+at <a href="/speed/libraries/terms">https://developers.google.com/speed/libraries/terms</a>.
+</p>
+<p>
+The canonical URL refers to a third-party domain; this can cause additional DNS
+lookup latency the first time a library is loaded. This is mitigated by the
+fact that the canonical copy of the data is shared among multiple sites.
+</p>
+<p>
+The initial request for a canonical URL will contain a <code>Referer:</code>
+header with the URL of the referring page. This permits the host of the
+canonical content to see a subset of traffic to your site (the first load of a
+page on your site that contains an identified library by a browser that does not
+already have that library in its cache). The provider should describe how this
+data is used in its terms of service. The terms of service for the default
+configuration can be found at
+<a href="/speed/libraries/terms">https://developers.google.com/speed/libraries/terms</a>.
+Again, this risk is mitigated by the fact that canonical libraries are shared
+among multiple sites; a popular library is likely to already reside in the
+browser cache.
+</p>
+<p>
+Sites serving content on both <code>http</code> and <code>https</code> URLs must
+use protocol-relative canonical URLs as shown <a href="#sample">above</a>.
+Fetching a library insecurely from a secure page exposes a site to attack.
+Fetching a library securely from an ordinary page can increase load time due to
+SSL overheads.
+</p>
+<p>
+It is theoretically possible to craft a JavaScript file whose minified size and
+hash exactly match that of a canonical library, but whose code behaves
+differently. In such a case the library will be replaced with the canonical
+(widely-used) library. This will break the page that contains the reference to
+the crafted JavaScript.
+</p>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-comment-remove.html b/doc/filter-comment-remove.html
new file mode 100644
index 0000000..8874590
--- /dev/null
+++ b/doc/filter-comment-remove.html
@@ -0,0 +1,129 @@
+<!--
+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>Remove Comments</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Remove Comments</h1>
+
+<h2>Configuration</h2>
+<p>
+The 'Remove Comments' filter is enabled by specifying:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters remove_comments</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters remove_comments;</pre>
+</dl>
+<p>
+in the configuration file. To retain comments that have semantic reason to be
+delivered to the browser, you may specify one more wildcard patterns
+using <code>RetainComment</code> directives. For example:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedRetainComment " google_ad_section*"</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed RetainComment " google_ad_section*";</pre>
+</dl>
+</p>
+
+<h2>Description</h2>
+<p>
+The <code>remove_comments</code> filter eliminates HTML comments,
+which are often used to document the code or to comment out
+experiments. Note that this directive applies only to HTML files.
+CSS comments are eliminated with the
+<code>rewrite_css</code> filter, and Javascript comments are
+eliminated with the <code>rewrite_javascript</code> filter.
+</p>
+<p>
+The filter reduces the transfer size of HTML files by removing most HTML
+comments. Depending on the HTML file, this filter can significantly reduce the
+number of bytes transmitted on the network. Also note that
+the <code>RetainComment</code> directive currently only applies to HTML files --
+the wildcard pattern is not currently used for retaining CSS or Javascript
+comments.
+</p>
+<p>
+For example, if the HTML document looks like this:
+</p>
+<pre class="prettyprint">
+<html>
+<body>
+<!-- Display the site logo here -->
+<img src="logo.png">
+<!-- Now show the page contents -->
+<div>Some content here</div>
+<!-- Apply IE-specific CSS -->
+<!-- [if IE ]>
+<link href="iecss.css" rel="stylesheet" type="text/css">
+<![endif]-->
+<!-- google_ad_section_end -- retained due to RetainComment directive -->
+</body>
+</html>
+</pre>
+<p>
+Then PageSpeed, with the above directives specified, will rewrite it into:
+</p>
+<pre class="prettyprint">
+<html>
+<body>
+<img src="logo.png">
+<div>Some content here</div>
+<!-- [if IE ]>
+<link href="iecss.css" rel="stylesheet" type="text/css">
+<![endif]-->
+<!-- google_ad_section_end -- retained due to RetainComment directive -->
+</body>
+</html>
+</pre>
+<h3>Example</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> on this
+<a href="https://www.modpagespeed.com/examples/remove_comments.html?ModPagespeed=on&ModPagespeedFilters=remove_comments">example</a>.
+</p>
+
+<h2>Notes</h2>
+<p>
+The "Remove Comments" filter is aware of
+<a href="http://msdn.microsoft.com/en-us/library/ms537512(VS.85).aspx">Internet Explorer conditional comments</a> and does not remove them.
+</p>
+
+<h2>Risks</h2>
+<p>
+This filter is low risk for most web pages. Some web pages use comments to
+embed data or JavaScript, in order to reduce the parse time of the HTML
+document. Such pages sould disable this filter, as it will remove the
+comments containing the data or JavaScript that is needed by these web
+pages.
+</p>
+
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-convert-meta-tags.html b/doc/filter-convert-meta-tags.html
new file mode 100644
index 0000000..dd29075
--- /dev/null
+++ b/doc/filter-convert-meta-tags.html
@@ -0,0 +1,78 @@
+<!--
+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>Convert Meta Tags</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Convert Meta Tags</h1>
+<h2>Configuration</h2>
+<p>
+The 'Convert Meta Tags' filter is enabled by specifying:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters convert_meta_tags</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters convert_meta_tags;</pre>
+</dl>
+<p>
+in the configuration file, but it is also enabled automatically by the core
+filter set.
+</p>
+
+<h2>Description</h2>
+<p>
+The 'Convert Meta Tags' filter adds a response header that matches each meta
+tag with an http-equiv attribute. For example, HTML
+<pre class="prettyprint"
+ ><meta http-eqiv="Content-Type" content="text/html; charset=UTF-8"></pre>
+would add an HTTP header:
+<pre class="prettyprint"
+ >Content-Type: text/html; charset=UTF-8</pre>
+in the response headers.
+</p>
+<p>
+The original tag is left unchanged.
+</p>
+<p>
+Certain http-equiv meta tags, specifically those that specify content-type,
+require a browser to reparse the html document if they do not match the headers.
+By ensuring that the headers match the meta tags, these reparsing delays are
+avoided.
+</p>
+
+<h2>Risks</h2>
+<p>
+This filter is considered minimal risk because at this time,
+Content-Type is the only <code>http-equiv</code> value that is transformed into
+an HTTP header. Other http-equiv values have been found to have unexpected semantic
+implications when transformed to HTTP.
+</p>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-css-above-scripts.html b/doc/filter-css-above-scripts.html
new file mode 100644
index 0000000..b4d2e23
--- /dev/null
+++ b/doc/filter-css-above-scripts.html
@@ -0,0 +1,152 @@
+<!--
+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>Move CSS Above Scripts</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Move CSS Above Scripts</h1>
+
+
+<h2>Configuration</h2>
+<p>
+ The 'Move CSS Above Scripts' filter is enabled by specifying:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters move_css_above_scripts</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters move_css_above_scripts;</pre>
+</dl>
+<p>
+ in the configuration file.
+</p>
+
+<h2>Description</h2>
+<p>
+ 'Move CSS Above Scripts' seeks to make sure scripts do not block the
+ loading of CSS resources.
+</p>
+<p>
+ This is based on the
+ <a target="_blank" href="https://developers.google.com/speed/docs/best-practices/rtt#PutStylesBeforeScripts">
+ best practice for downloading resources early.
+ </a>
+</p>
+
+<h2>Operation</h2>
+<p>
+ The 'Move CSS Above Scripts' filter operates only on CSS
+ <code><link></code> and <code><style></code> tags found after the
+ first <code><script></code> tag and moves these tags above the first
+ <code><script></code>.
+</p>
+<p>
+ For example, if the HTML document looks like this:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ </head>
+ <body>
+ <script src="script.js" type="text/javascript"></script>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ <style type="text/css">
+ .foo { color: red; }
+ </style>
+ <link rel="stylesheet" type="text/css" href="styles/all_styles.css">
+ </body>
+</html>
+</pre>
+<p>
+ Then PageSpeed will rewrite it into:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ </head>
+ <body>
+ <style type="text/css">
+ .foo { color: red; }
+ </style>
+ <link rel="stylesheet" type="text/css" href="styles/all_styles.css">
+ <script src="script.js" type="text/javascript"></script>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ </body>
+</html>
+</pre>
+
+<p>
+ In some browsers the original version will not even download the CSS file
+ until the JavaScript has been downloaded and run. This transformation will
+ make sure the CSS file is loaded first.
+</p>
+<p class="note">
+ Note: You may also want to enable
+ the <a href="filter-css-to-head">move_css_to_head</a> filter to avoid a flash
+ of unstyled content. When both filters are enabled, stylesheets are moved
+ into the head and above the first script.
+</p>
+
+<h3>Example</h3>
+<p>
+ You can see the filter in action at <code>www.modpagespeed.com</code> on this
+ <a href="https://www.modpagespeed.com/examples/move_css_above_scripts.html?ModPagespeed=on&ModPagespeedFilters=move_css_above_scripts">example</a>.
+</p>
+
+<h2>Limitations</h2>
+<p>
+ This 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. If the filter
+ encounters a flush after the first <code><script></code> tag,
+ subsequently encountered CSS elements will not be moved above it.
+</p>
+
+<h2>Risks</h2>
+<p>
+ This filter is considered low risk. However, JavaScript that is
+ executed before a CSS element will see a different view of the DOM in
+ the presence of this rewriter: the CSS element will now be in the head.
+ If there is such JavaScript embedded in the middle of a page then this
+ rewriter may change its behavior.
+</p>
+<p>
+ This filter may slow down your webpages for some browsers. Just as JavaScript
+ can block download of CSS in some browsers, some others will not execute
+ JavaScript until preceding CSS has been rendered. This filter is currently
+ considered experimental while we measure its effectiveness.
+</p>
+
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-css-combine.html b/doc/filter-css-combine.html
new file mode 100644
index 0000000..5992826
--- /dev/null
+++ b/doc/filter-css-combine.html
@@ -0,0 +1,216 @@
+<!--
+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>Combine CSS</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Combine CSS</h1>
+
+
+<h2>Configuration</h2>
+<p>
+The 'Combine CSS' filter is enabled by specifying:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters combine_css</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters combine_css;</pre>
+</dl>
+<p>
+in the configuration file.
+</p>
+
+<h2>Description</h2>
+<p>
+'Combine CSS' seeks to reduce the number of HTTP requests made by a browser
+during page refresh by replacing multiple distinct CSS files with a single CSS
+file, containing the contents of all of them. This is particularly important in
+old browsers, that were limited to two connections per domain. In addition to
+reduced overhead for HTTP headers and communications warm-up, this approach
+works better with TCP/IP slow-start, increasing the effective payload bit-rate
+through the browser's network connection.
+</p>
+<p>
+This <a target="_blank" href="https://developers.google.com/speed/docs/best-practices/rtt#CombineExternalCSS">practice</a>
+reduces the number of round-trip times.
+</p>
+
+<h2>Operation</h2>
+<p>
+The "CSS Combine" filter finds all CSS <code><link></code> tags. If there
+was more than one in a flush window, it removes each of those links and replaces
+them with a single <code><link></code> to the merged document, which it
+places wherever the first CSS <code><link></code> originally was.
+</p>
+<p>
+For example, if the HTML document looks like this:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <link rel="stylesheet" type="text/css" href="styles/yellow.css">
+ <link rel="stylesheet" type="text/css" href="styles/blue.css">
+ <link rel="stylesheet" type="text/css" href="styles/big.css">
+ <link rel="stylesheet" type="text/css" href="styles/bold.css">
+ </head>
+ <body>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ </body>
+</html>
+</pre>
+<p>
+Then PageSpeed will rewrite it into:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <link rel="stylesheet" type="text/css" href="styles/yellow.css+blue.css+big.css+bold.css.pagespeed.cc.xo4He3_gYf.css">
+ </head>
+ <body>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ </body>
+</html>
+</pre>
+<h3>Example</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> on this
+<a href="https://www.modpagespeed.com/examples/combine_css.html?ModPagespeed=on&ModPagespeedFilters=combine_css">example</a>.
+</p>
+
+<h2>Parameters that affect CSS optimization</h2>
+
+<h3 id="MaxCombinedCssBytes">MaxCombinedCssBytes</h3>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedMaxCombinedCssBytes MaxBytes</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed MaxCombinedCssBytes MaxBytes;</pre>
+</dl>
+<p>
+<code>MaxBytes</code> is the maximum size in bytes of the combined CSS files.
+CSS files larger than <code>MaxBytes</code> will be kept intact;
+other CSS files will be combined into one or more files, each being no more
+than <code>MaxBytes</code> in size. The current default value for
+<code>MaxBytes</code> is -1 (unlimited).
+</p>
+
+<h2>Limitations</h2>
+<p>The CSS 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
+CSS combiner encounters a flush, it will emit all CSS combinations seen
+up to the point of the flush. After the flush, it will begin collecting
+a new CSS combination.
+</p>
+<p>This filter generates URLs that are essentially the concatenation
+of the URLs of all the CSS files being combined. The maximum URL size
+is generally limited to about 2k characters due to IE:
+See <a href="http://support.microsoft.com/kb/208427/EN-US"
+>http://support.microsoft.com/kb/208427/EN-US</a>. 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
+within 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.</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedMaxSegmentLength 250</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed MaxSegmentLength 250;</pre>
+</dl>
+
+<h3 id="permit-ids-for-css-combining">Combining Resources with IDs</h3>
+<p class="note"><strong>Note: New feature as of 1.12.34.1</strong></p>
+
+<p>
+ By default PageSpeed won't combine CSS files that have <code>id</code>
+ attributes, because this often indicates that the site designer intended to
+ reference them in javascript. However, some content management systems,
+ including WordPress, put <code>id</code>s on all stylesheets for clarity. To
+ enable combining these files, you can provide one or more wildcards. For
+ example, this would mark stylesheets with ids starting with <code>font</code>
+ as eligible for combining:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedPermitIdsForCssCombining font*</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed PermitIdsForCssCombining font*;</pre>
+</dl>
+
+<h2>Requirements</h2>
+<p>
+The 'Combine CSS' filter may need to <em>absolutify</em> relative
+URLs, if rewriting the CSS causes the path to be moved. The filter
+will not merge together resources from multiple distinct domains, even
+if those domains are each authorized by <code>Domain</code>.
+It <strong>will</strong> merge together resources from multiple
+distinct domains that have been mapped together via
+<code>MapRewriteDomain</code>.
+</p>
+<p>
+By default, the filter will combine together CSS 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:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedCombineAcrossPaths off</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed CombineAcrossPaths off;</pre>
+</dl>
+<p>
+The filter will maintain the order of the CSS contents, as class order can be
+significant.
+</p>
+<p>
+IE Directives containing CSS links form a "barrier" for the CSS combiner.
+Multiple CSS elements found before an IE directive are combined together
+immediately before the IE directive. Multiple CSS elements found after are
+also combined, but the combination does not span across the IE directive, as
+that would affect the order that the browser sees the CSS elements.
+</p>
+
+<h2>Risks</h2>
+<p>
+This filter is considered low risk. However, JavaScript can be written that
+walks the DOM looking for <code><link></code> entries with certain
+syntax. Such JavaScript may behave differently on a page which has modified
+CSS links in this way.
+</p>
+
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-css-inline-google-fonts.html b/doc/filter-css-inline-google-fonts.html
new file mode 100644
index 0000000..b4aeff0
--- /dev/null
+++ b/doc/filter-css-inline-google-fonts.html
@@ -0,0 +1,162 @@
+<!--
+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>Inline Google Fonts API CSS</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Inline Google Fonts API CSS</h1>
+
+<h2>Configuration</h2>
+<p>
+The 'Inline Google Fonts API CSS' filter is enabled by specifying:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters inline_google_font_css</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters inline_google_font_css;</pre>
+</dl>
+<p>
+in the configuration file. You also need to
+enable <a href="https_support#https_fetch">HTTPS Fetching</a> if your pages load
+fonts over HTTPS:
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedFetchHttps enable</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed FetchHttps enable;</pre>
+</dl>
+
+</p>
+
+<p>As of 1.9.32.6, the size limit for this filter is controlled as follows:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedGoogleFontCssInlineMaxBytes bytes</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed GoogleFontCssInlineMaxBytes bytes;</pre>
+</dl>
+
+<p>In older versions, the filter used same size limits as the main CSS filter:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedCssInlineMaxBytes bytes</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed CssInlineMaxBytes bytes;</pre>
+</dl>
+<p>
+This is the maximum size in bytes of any CSS file that will be inlined.
+</p>
+<h2>Description</h2>
+<p>
+The "Inline Google Fonts API CSS" filter reduces the number of requests made by
+a web page that uses the Google Fonts API by inlining the small loader CSS
+into the webpage. Note that because the loader CSS is browser-specific, this
+feature is not currently compatible with downstream caching being on or
+<code>ModifyCachingHeaders</code> being off.
+</p>
+<h2>Operation</h2>
+<p>
+When the 'Inline Google Fonts API CSS' filter is enabled, the contents of the
+small external CSS resources produced to load the fonts are written directly
+into the HTML document; the browser does not need to request those CSS
+resources independently.
+</p>
+<p>
+For example, if the HTML document looks like this:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <title>inline_google_font_css example</title>
+ <link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=Roboto">
+ <style>
+ body {
+ font-family: 'Roboto', sans-serif;
+ }
+ </style>
+ </head>
+ <body>
+ The font should be slightly more robotic.
+ </body>
+</html>
+</pre>
+<p>
+Then, a visitor using a browser for which woff fonts are preferred may see
+something like:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <title>inline_google_font_css example</title>
+ <style>@font-face {
+ font-family: 'Roboto';
+ font-style: normal;
+ font-weight: 400;
+ src: local('Roboto Regular'), local('Roboto-Regular'), url(http://themes.googleusercontent.com/static/fonts/roboto/v9/abcd.woff) format('woff');
+ }
+ </style>
+ <style>
+ body {
+ font-family: 'Roboto', sans-serif;
+ }
+ </style>
+ </head>
+ <body>
+ The font should be slightly more robotic.
+ </body>
+</html>
+</pre>
+<p>
+This eliminates the browser request to <code>fonts.googleapis.com</code> and
+potentially the need for the browser to perform a DNS lookup and connect to
+that host entirely.
+
+<h3>Example</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> on this
+<a href="https://www.modpagespeed.com/examples/inline_google_font_css.html?PageSpeed=on&PageSpeedFilters=inline_google_font_css">example</a>.
+</p>
+
+<h2>Risks</h2>
+<p>
+You must ensure that you abide by
+<a href="https://developers.google.com/fonts/terms">Google Fonts API Terms of Service</a>.
+Note that enabling this filter will cause some requests to be sent to
+the API from your server (rather than just the visitor), which may be logged
+per the Fonts API Terms of Service.
+</p>
+
+<p>
+The filter is low to moderate risk. It should be safe for most pages, but it
+could potentially break scripts that walk the DOM looking
+for and examining <code><link></code> or <code><style></code> tags.
+</p>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-css-inline-import.html b/doc/filter-css-inline-import.html
new file mode 100644
index 0000000..8eab835
--- /dev/null
+++ b/doc/filter-css-inline-import.html
@@ -0,0 +1,112 @@
+<!--
+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>Inline @import to Link</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Inline @import to Link</h1>
+
+<h2>Configuration</h2>
+<p>
+The 'Inline @import to Link' filter is enabled by specifying:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters inline_import_to_link</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters inline_import_to_link;</pre>
+</dl>
+in the configuration file.
+</p>
+<h2>Description</h2>
+<p>
+The "Inline @import to Link" filter converts a <code><style></code> tag
+consisting of only <code>@import</code> statements into the corresponding
+<code><link></code> tags. This conversion does not itself result in any
+significant optimization, rather its value lies in that it enables optimization
+of the linked-to CSS files by later filters, in particular the combine_css,
+rewrite_css, inline_css, and extend_cache filters.
+</p>
+<h2>Operation</h2>
+<p>
+This filter inspects the contents of all <code><style></code> tags and
+converts the tag if all the following conditions are met:</p>
+<ul>
+<li>Either the <code><style></code> tag has no <code>type</code>
+ attribute or the <code>type</code> attribute has the value
+ "text/css".</li>
+<li>The contents comprise one or more valid <code>@import</code> statements,
+ and no other statements.</li>
+<li>None of the imported URLs are empty.</li>
+<li>The <code><style></code> tag has neither an <code>href</code> nor a
+ <code>rel</code> attribute (which would make it invalid anyway).</li>
+<li>If the <code><style></code> tag has a <code>media</code> attribute
+ and the <code>@import</code> statement specifies media after the URL, then
+ the media types listed must be the same. They do not have to be in the same
+ order, and blank media types are ignored.</li>
+</ul>
+<p>
+If all these conditions are met, the <code><style></code> tag and its
+contents are replaced with a <code><link></code> tag for each
+<code>@import</code>, with:</p>
+<ul>
+<li>Attributes from the <code><style></code> tag copied to the
+ <code><link></code> tag.</li>
+<li>An <code>href</code> attribute with value of the imported URL.</li>
+<li>A <code>rel</code> attribute with value of "stylesheet".</li>
+<li>If the <code><style></code> tag did not have a <code>media</code>
+ attribute but the <code>@import</code> specified media after the URL, then
+ a <code>media</code> attribute with value of the media specified after the
+ URL.</li>
+</ul>
+<p>
+For example, if the <code><style></code> tag looks like this:
+</p>
+<pre class="prettyprint">
+<style type="text/css" media="screen">@import url(http://www.example.com/style.css);</style>
+</pre>
+<p>
+Then PageSpeed will convert it to:
+<pre class="prettyprint">
+<link type="text/css" media="screen" rel="stylesheet" href="http://www.example.com/style.css"/>
+</pre>
+
+<h3>Example</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> on this
+<a href="https://www.modpagespeed.com/examples/inline_import_to_link.html?ModPagespeed=on&ModPagespeedFilters=inline_import_to_link">example</a>.
+</p>
+
+<h2>Risks</h2>
+<p>
+This filter is considered minimal risk.
+</p>
+
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-css-inline.html b/doc/filter-css-inline.html
new file mode 100644
index 0000000..604dcf5
--- /dev/null
+++ b/doc/filter-css-inline.html
@@ -0,0 +1,157 @@
+<!--
+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>Inline CSS</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Inline CSS</h1>
+
+<h2>Configuration</h2>
+<p>
+The 'Inline CSS' filter is enabled by specifying:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters inline_css</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters inline_css;</pre>
+</dl>
+<p>
+in the configuration file.
+</p>
+<p>When this filter is enabled, you may also enable the following setting:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedCssInlineMaxBytes bytes</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed CssInlineMaxBytes bytes;</pre>
+</dl>
+<p>
+This is the maximum size in bytes of any CSS file that will be inlined.
+</p>
+<h2>Description</h2>
+<p>
+The "Inline CSS" filter reduces the number of requests made by a web page by
+inserting the contents of small external CSS resources directly into the HTML
+document. This can reduce the time it takes to display content to the user,
+especially in older browsers.
+</p>
+<h2>Operation</h2>
+<p>
+When the 'Inline CSS' filter is enabled, The contents of small external CSS
+resources are written directly into the HTML document; therefore the browser
+does not request those CSS resources independently.
+</p>
+<p>
+For example, if the HTML document looks like this:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <link rel="stylesheet" href="small.css">
+ </head>
+ <body>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ </body>
+</html>
+</pre>
+<p>
+And the resource <code>small.css</code> is like this:
+<pre class="prettyprint">
+ .yellow {background-color: yellow;}
+ .blue {color: blue;}
+ .big { font-size: 8em; }
+ .bold { font-weight: bold; }
+</pre>
+<p>
+Then PageSpeed will rewrite it into:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <style>
+ .yellow {background-color: yellow;}
+ .blue {color: blue;}
+ .big { font-size: 8em; }
+ .bold { font-weight: bold; }
+ </style>
+ </head>
+ <body>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ </body>
+</html>
+</pre>
+<p>
+This eliminates the browser request to <code>small.css</code> by placing its
+contents inline in the HTML document.
+
+<h3>Example</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> on this
+<a href="https://www.modpagespeed.com/examples/inline_css.html?ModPagespeed=on&ModPagespeedFilters=inline_css">example</a>.
+</p>
+
+<h2>Note</h2>
+<p>
+CSS may contain URLs that are relative to the location of the CSS
+file. To avoid breaking such URLs, the 'Inline CSS' filter will attempt to
+rewrite them into absolute URLs when it performs the inlining.
+</p>
+
+<h2>Requirements</h2>
+<p>
+There is a tradeoff here between requests and cacheability: including the CSS
+directly in the HTML avoids making an additional request to the external CSS
+resource, but if the CSS file is large (and doesn't change often), it may be
+better to keep it separate from the HTML so that it can be cached by the
+browser. Thus, the Inline CSS filter will only inline CSS files below a
+certain size threshold, which can be adjusted using the
+<code>CssInlineMaxBytes</code> directive.
+</p>
+<p>
+It is possible for CSS files to contain small snippets of JavaScript code, at
+least for certain browsers. To avoid opening up cross-domain scripting
+vulnerabilities, the Inline CSS filter will only inline an external CSS file if
+it is being served from the same domain as the HTML file into which it is to be
+inlined.
+</p>
+
+<h2>Risks</h2>
+<p>
+The 'Inline CSS' filter is low to moderate risk. It should be safe for most
+pages, but it could potentially break scripts that walk the DOM looking for
+and examining <code><link></code> or <code><style></code> tags.
+</p>
+
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-css-outline.html b/doc/filter-css-outline.html
new file mode 100644
index 0000000..295ef4c
--- /dev/null
+++ b/doc/filter-css-outline.html
@@ -0,0 +1,182 @@
+<!--
+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>Outline CSS</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Outline CSS</h1>
+
+<h2>Configuration</h2>
+<p>
+The 'Outline CSS' filter is enabled by specifying:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters outline_css</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters outline_css;</pre>
+</dl>
+<p>
+in the configuration file.
+</p>
+
+<h2>Description</h2>
+<p>
+This filter is an <strong>experimental</strong> filter which takes inline
+CSS and puts it in an external resource.
+</p>
+
+<h2>Operation</h2>
+<p>
+The 'Outline CSS' filter outlines all CSS that is larger than a minimum byte
+threshold. The threshold can be set by adding/changing the line:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedCssOutlineMinBytes 3000</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed CssOutlineMinBytes 3000;</pre>
+</dl>
+<p>
+in the configuration file.
+</p>
+<p>
+For example, if the HTML document looks like this:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <style type="text/css">
+ .yellow {background-color: yellow;}
+ .blue {color: blue;}
+ .big { font-size: 8em; }
+ .bold { font-weight: bold; }
+ ...
+ </style>
+ </head>
+ <body>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ </body>
+</html>
+</pre>
+<p>
+Then PageSpeed will rewrite it into:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <link rel="stylesheet" type="text/css" href="of.HASH.css">
+ </head>
+ <body>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ </body>
+</html>
+</pre>
+<p>
+And a new CSS file (<code>of.HASH.css</code>) will be:
+</p>
+<pre class="prettyprint">
+ .yellow {background-color: yellow;}
+ .blue {color: blue;}
+ .big { font-size: 8em; }
+ .bold { font-weight: bold; }
+ ...
+</pre>
+
+<h3>Example</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> on this
+<a href="https://www.modpagespeed.com/examples/outline_css.html?ModPagespeed=on&ModPagespeedFilters=outline_css">example</a>.
+</p>
+
+<h2>Pros and Cons</h2>
+<p>
+This could be advantageous if:
+</p>
+<ol>
+ <li>The CSS does not change much but the HTML does, then we can cache the
+ CSS.</li>
+ <li>One has many websites with the same inlined CSS, it will be outlined
+ to a consistent name and thus will be cached more or</li>
+ <li>The inline CSS is very long, in which case, outlining it will cause it
+ to be loaded in parallel with the HTML doc.</li>
+</ol>
+<p>
+However, for some websites it will be dis-advantageous because it will:
+</p>
+<ol>
+ <li>Create an extra HTTP request.</li>
+ <li>Tie up one of the connections this domain, which could have been used to
+ fetch the actually cacheable external resources.</li>
+</ol>
+
+<h2>Requirements</h2>
+<p>
+Outline filters can currently only run on single-server environments
+because the resource can only be fetched from a server after that server
+has rewritten the HTML page. If a different server rewrote the HTML page,
+then this sever will not have the information needed to create the resource.
+This could be by a network database shared between servers.
+</p>
+<p>
+The Outline CSS filter may need to <em>"absolutify"</em> relative URLs, if
+it is outlined to a different directory than the original HTML.
+</p>
+<p>
+The Outline CSS filter will maintain the order of the CSS contents, as
+class order can be significant.
+</p>
+
+<h2>Risks</h2>
+<p>
+The 'Outline CSS' filter is considered low risk. However, JavaScript can be
+written that walks the DOM looking for <code><link></code> or
+<code><style></code> tags with certain syntax. Such JavaScript
+may behave differently on a page which has added
+<code><link></code> or removed <code><style></code> tags
+in this way.
+</p>
+<p>
+Additionally we have reproduced an obscure difference that sometimes occurs
+on WebKit-based browsers (such as Safari, Chrome and the Android browser).
+As of January 2011, WebKit does not delay JavaScript evaluation for
+external CSS loading (See
+<a href="https://webkit.org/b/24898">https://webkit.org/b/24898</a>).
+So some CSS attributes, when outlined, can cause slightly different
+rendering depending on whether or not the CSS file is loaded before or
+after the JavaScript is executed.
+</p>
+
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-css-rewrite.html b/doc/filter-css-rewrite.html
new file mode 100644
index 0000000..366fe28
--- /dev/null
+++ b/doc/filter-css-rewrite.html
@@ -0,0 +1,215 @@
+<!--
+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>Rewrite CSS</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Rewrite CSS</h1>
+
+<h2 id="configuration">Configuration</h2>
+<p>
+ The 'Rewrite CSS' filter is enabled by specifying:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters rewrite_css</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters rewrite_css;</pre>
+</dl>
+<p>
+ in the configuration file. To enable fallback rewriting on CSS we cannot
+ parse, also specify:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters fallback_rewrite_css_urls</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters fallback_rewrite_css_urls;</pre>
+</dl>
+
+<h2>Description</h2>
+<p>
+ This filter parses linked and inline CSS, rewrites the images found
+ and minifies the CSS. The filter works on CSS found in
+ <code><style></code> blocks and <code><link></code> refs.
+</p>
+<p>
+ Many images are referenced from CSS rather than HTML. If
+ <a href="reference-image-optimize#rewrite_images"
+ ><code>rewrite_images</code></a>,
+ <a href="reference-image-optimize#recompress_images"
+ ><code>recompress_images</code></a>,
+ <a href="reference-image-optimize#recompress_jpeg"
+ ><code>recompress_jpeg</code></a>,
+ <a href="reference-image-optimize#recompress_png"
+ ><code>recompress_png</code></a>,
+ <a href="reference-image-optimize#recompress_webp"
+ ><code>recompress_webp</code></a>,
+ <a href="reference-image-optimize#convert_gif_to_png"
+ ><code>convert_gif_to_png</code></a>,
+ <a href="reference-image-optimize#convert_jpeg_to_webp"
+ ><code>convert_jpeg_to_webp</code></a>,
+ <a href="reference-image-optimize#convert_png_to_jpeg"
+ ><code>convert_png_to_jpeg</code></a>,
+ or <a href="filter-cache-extend"
+ ><code>extend_cache</code></a>
+ are enabled this filter finds and rewrites those images, saving bytes
+ and extending cache lifetimes.
+</p>
+<p>
+ The CSS parser cannot parse some CSS3 or proprietary CSS extensions.
+ If <code>fallback_rewrite_css_urls</code> is not enabled, these
+ CSS files will not be rewritten at all.
+ If the <code>fallback_rewrite_css_urls</code> filter is enabled, a
+ fallback method will attempt to rewrite the URLs in the CSS file,
+ even if the CSS cannot be successfully parsed and minified.
+</p>
+<p>
+ Minification can drastically reduce the byte count in common CSS by
+ stripping all comments and most whitespace and shortening color names.
+ This filter can be used to avoid the extra step of minifying CSS by hand
+ when constructing and maintaining a site.
+ This <a target="_blank" href="https://developers.google.com/speed/docs/best-practices/payload#MinifyCSS">practice</a>
+ reduces the payload size.
+</p>
+
+<h2>Example</h2>
+<p>
+ For example, if the HTML document looks like this:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <style>
+ body { background-image: url("foo.png"); }
+ /* This comment will be stripped */
+ #iddy, .anotherId {
+ border: solid 1px #cccccc;
+ padding: 1.2em;
+ float: left;
+ color:##ff0000;
+ }
+ </style>
+ <link rel="stylesheet" type="text/css" href="extStyle.css">
+ </head>
+ <body>
+ Wow, <div class="classy" id="iddy">
+ CSS is <span>stylin'</span>.</div>
+ </body>
+</html>
+</pre>
+<p>
+ With the following in <code>extStyle.css</code>:
+</p>
+<pre class="prettyprint">
+ div.classy span, div.classy img {
+ display: block;
+ border: none !important;
+ background: none !important;
+ }
+</pre>
+<p>
+ Then PageSpeed will rewrite it into:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <style>body{background-image:url(xfoo.png.pagespeed.ic.HASH.png}#iddy,#anotherId{border:solid 1px #ccc;padding:1.2em;float:left;color:red}</style>
+ <link rel="stylesheet" type="text/css" href="I.extStyle.css.pagespeed.cf.HASH.css">
+ </head>
+ <body>
+ Wow, <div class="classy" id="iddy">
+ CSS is <span>stylin'</span>.</div>
+ </body>
+</html>
+</pre>
+<p>
+ And the rewritten file <code>I.extStyle.css.pagespeed.cf.HASH.css</code> will
+ contain:
+</p>
+<pre class="prettyprint">
+ dif.classy span,div.classy img{display:block;border:none!important;background:none!important}
+</pre>
+
+<h3>Online Example</h3>
+<p>
+ You can see the filter in action at <code>www.modpagespeed.com</code> for
+ <a href="https://www.modpagespeed.com/examples/rewrite_css.html?ModPagespeed=on&ModPagespeedFilters=rewrite_css">CSS minification</a>,
+ <a href="https://www.modpagespeed.com/examples/rewrite_css_images.html?ModPagespeed=on&ModPagespeedFilters=rewrite_css,extend_cache">cache-extending images in CSS</a>,
+ <a href="https://www.modpagespeed.com/examples/rewrite_css_images.html?ModPagespeed=on&ModPagespeedFilters=rewrite_css,rewrite_images">rewriting images in CSS</a> and
+ <a href="https://www.modpagespeed.com/examples/fallback_rewrite_css_urls.html?ModPagespeed=on&ModPagespeedFilters=fallback_rewrite_css_urls,rewrite_css,rewrite_images">fallback rewriting of images in CSS</a>.
+</p>
+
+<h2>Requirements</h2>
+<p>
+ Only CSS referenced by <code><style></code> and <code><link>
+ </code> tags is rewritten. For example, style attributes of HTML elements
+ are not rewritten. Enable <a href="filter-rewrite-style-attributes">
+ <code>rewrite_style_attributes</code></a> to rewrite these as well.
+</p>
+<p>
+ Not all CSS3 or proprietary constructs are parsed. When unhandled syntax
+ is present and the file cannot be parsed completely, the URLs in the CSS
+ can still be rewritten by the <code>fallback_rewrite_css_urls</code> filter.
+ However the CSS will not be minified.
+</p>
+
+<h2 id="risks">Risks</h2>
+<p>
+ CSS minification is considered moderate risk.
+</p>
+<p>
+ Specifically, there is an outstanding bug that the CSS parser can silently
+ lose data on malformed CSS. This only applies to malformed CSS or CSS that
+ uses proprietary extensions. All known examples have been fixed, but there
+ may be more examples not discovered yet. Without this the risk would be low.
+</p>
+<p>
+ Some JavaScript code depends upon the exact URLs of resources. When we minify
+ CSS we will change the leaf name of the file (although leave it in the same
+ directory). This could break such JavaScript.
+</p>
+
+<h2>Troubleshooting</h2>
+<p>
+ To troubleshoot why CSS is not minified, you can use the standalone binary
+ <code>css_minify_main</code>. It's shipped with mod_pagespeed, so
+ <a href="build_mod_pagespeed_from_source#debug-css"
+ >build it from source</a> and then run:
+</p>
+<pre>
+ ./out/Release/css_minify_main FILENAME.css > REWRITTEN.css
+</pre>
+<p>
+ The rewritten version is piped to <code>stdout</code> and the errors
+ encountered are piped to <code>stderr</code>. These error messages should
+ be helpful in figuring out what aspects of the CSS file could not be parsed.
+</p>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-css-to-head.html b/doc/filter-css-to-head.html
new file mode 100644
index 0000000..07a34a2
--- /dev/null
+++ b/doc/filter-css-to-head.html
@@ -0,0 +1,143 @@
+<!--
+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>Move CSS to Head</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Move CSS to Head</h1>
+
+
+<h2>Configuration</h2>
+<p>
+ The 'Move CSS to head' filter is enabled by specifying:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters move_css_to_head</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters move_css_to_head;</pre>
+</dl>
+<p>
+ in the configuration file.
+</p>
+
+<h2>Description</h2>
+<p>
+ 'Move CSS to head' seeks to reduce the number of times the browser must
+ re-flow the document by ensuring that the CSS styles are all parsed in
+ the head, before any body elements are introduced.
+</p>
+<p>
+ This is based on the
+ <a target="_blank" href="https://developers.google.com/speed/docs/best-practices/rendering#PutCSSInHead">
+ best practice for optimizing browser rendering.
+ </a>
+</p>
+
+<h2>Operation</h2>
+<p>
+ The 'Move CSS to head' filter operates only on CSS
+ <code><link</code> and <code><style></code> tags found after the
+ <code></head></code> and moves these links back into the
+ <code><head></code> ... <code></head></code> section.
+</p>
+<p>
+For example, if the HTML document looks like this:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ </head>
+ <body>
+ <script src="script.js" type="text/javascript"></script>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ <style type="text/css">
+ .foo { color: red; }
+ </style>
+ <link rel="stylesheet" type="text/css" href="styles/all_styles.css">
+ </body>
+</html>
+</pre>
+<p>
+ Then PageSpeed will rewrite it into:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <style type="text/css">
+ .foo { color: red; }
+ </style>
+ <link rel="stylesheet" type="text/css" href="styles/all_styles.css">
+ </head>
+ <body>
+ <script src="script.js" type="text/javascript"></script>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ </body>
+</html>
+</pre>
+
+<p>
+ In some browsers, the original version will flash quickly as the
+ browser will render the "Hello, world!" text before it sees the style
+ tags providing definitions for the CSS classes. This transformation
+ will eliminate that flash, but the end result will be the same.
+</p>
+
+<h3>Example</h3>
+<p>
+ You can see the filter in action at <code>www.modpagespeed.com</code> on this
+ <a href="https://www.modpagespeed.com/examples/move_css_to_head.html?ModPagespeed=on&ModPagespeedFilters=move_css_to_head">example</a>.
+</p>
+
+<h2>Limitations</h2>
+<p>
+ This 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. If the filter
+ encounters a flush after the end of the <code><head></code> section,
+ subsequently encountered CSS elements will not be moved into the
+ <code><head></code> section.
+</p>
+
+<h2>Risks</h2>
+<p>
+ This filter is considered low risk. However, JavaScript that is
+ executed before a CSS element will see a different view of the DOM in
+ the presence of this rewriter: the CSS element will now be in the head.
+ If there is such JavaScript embedded in the middle of a page then this
+ rewriter may change its behavior.
+</p>
+
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-dedup-inlined-images.html b/doc/filter-dedup-inlined-images.html
new file mode 100644
index 0000000..f86e240
--- /dev/null
+++ b/doc/filter-dedup-inlined-images.html
@@ -0,0 +1,110 @@
+<!--
+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>Deduplicate Inlined Images</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Deduplicate Inlined Images</h1>
+<h2>Configuration</h2>
+<p>
+ The 'Deduplicate Inlined Images' filter is enabled by specifying:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters dedup_inlined_images</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters dedup_inlined_images;</pre>
+</dl>
+<p>
+in the configuration file.
+</p>
+
+<h2>Objective</h2>
+<p>
+ Reduce the transfer size of HTML files by eliminating redundant image data
+ URLs.
+</p>
+
+<h2>PageSpeed Rule</h2>
+<p>
+ This rewriter implements the PageSpeed rule for
+ <a target="_blank" href="https://developers.google.com/speed/docs/best-practices/payload#CompressImages">optimizing
+ images</a>.
+</a>
+</p>
+
+<h2>Description</h2>
+<p>
+ dedup_inlined_images replaces repeated inlined images with JavaScript
+ that loads the image from the first occurence of the image. If the first
+ image doesn't have an <code>id</code>, one is generated and added to it.
+</p>
+
+<h2>Operation</h2>
+<p>
+ dedup_inlined_images rewrites inlined images:
+ <ul>
+ <li>If the image's data URL has not appeared earlier in the page then,
+ if it doesn't already have one an <code>id</code> attribute is
+ generated and added to the tag, then the existing/added <code>id</code>
+ is recorded along with the data URL for comparison with subsequent
+ inlined images.</li>
+ <li>Otherwise, the <code><img></code> tag is replaced with an
+ inline <code><script></code> tag that replaces itself with an
+ <code><img></code> tag, loading the data URL from the preceding
+ <code><img></code> tag with the <code>id</code> matching this
+ tag's data URL.</li>
+ </ul>
+</p>
+
+<h3>Example</h3>
+<p>
+ The effect of this filter can be observed on modpagespeed.com
+ <a href="https://www.modpagespeed.com/examples/dedup_inlined_images.html?ModPagespeed=off">before</a>
+ and
+ <a href="https://www.modpagespeed.com/examples/dedup_inlined_images.html?ModPagespeed=on&ModPagespeedFilters=inline_images,dedup_inlined_images">after</a>
+ rewriting.
+</p>
+
+<h2>Requirements</h2>
+<p>
+ The <a href="filter-image-optimize#inline_images">inline_images</a>
+ filter should be enabled for this filter to have any effect although it
... 14512 lines suppressed ...