</summary>
<seealso><a href="../filter.html">Filters</a></seealso>
+<section id="supportedencodings"><title>Supported Encodings</title>
+ <p>The <code>gzip</code> encoding is the only one supported to ensure complete compatibility
+ with old browser implementations. The <code>deflate</code> encoding is not supported,
+ please check the <a href="http://www.gzip.org/zlib/zlib_faq.html#faq38">zlib's documentation</a>
+ for a complete explanation.
+ </p>
+</section>
+
<section id="recommended"><title>Sample Configurations</title>
- <p>This is a simple sample configuration for the impatient.</p>
+ <note type="warning"><title>Compression and TLS</title>
+ <p>Some web applications are vulnerable to an information disclosure
+ attack when a TLS connection carries deflate compressed data. For more
+ information, review the details of the "BREACH" family of attacks.</p>
+ </note>
+ <p>This is a simple configuration that compresses common text-based content types.</p>
<example><title>Compress only a few types</title>
<highlight language="config">
- AddOutputFilterByType DEFLATE text/html text/plain text/xml
- </highlight>
- </example>
-
- <p>The following configuration, while resulting in more compressed content,
- is also much more complicated. Do not use this unless you fully understand
- all the configuration details.</p>
-
- <example><title>Compress everything except images</title>
- <highlight language="config">
-<Location />
- # Insert filter
- SetOutputFilter DEFLATE
-
- # Netscape 4.x has some problems...
- BrowserMatch ^Mozilla/4 gzip-only-text/html
-
- # Netscape 4.06-4.08 have some more problems
- BrowserMatch ^Mozilla/4\.0[678] no-gzip
-
- # MSIE masquerades as Netscape, but it is fine
- BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
- # Don't compress images
- SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ no-gzip dont-vary
-
- # Make sure proxies don't deliver the wrong content
- Header append Vary User-Agent env=!dont-vary
-</Location>
+ AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript
</highlight>
</example>
</section>
<section id="enable"><title>Enabling Compression</title>
+ <note type="warning"><title>Compression and TLS</title>
+ <p>Some web applications are vulnerable to an information disclosure
+ attack when a TLS connection carries deflate compressed data. For more
+ information, review the details of the "BREACH" family of attacks.</p>
+ </note>
<section id="output"><title>Output Compression</title>
<p>Compression is implemented by the <code>DEFLATE</code>
is placed:</p>
<highlight language="config">
- SetOutputFilter DEFLATE
+SetOutputFilter DEFLATE
+SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ no-gzip
</highlight>
- <p>Some popular browsers cannot handle compression of all content
- so you may want to set the <code>gzip-only-text/html</code> note to
- <code>1</code> to only allow html files to be compressed (see
- below). If you set this to <em>anything but <code>1</code></em> it
- will be ignored.</p>
-
<p>If you want to restrict the compression to particular MIME types
in general, you may use the <directive module="mod_filter"
>AddOutputFilterByType</directive> directive. Here is an example of
</Directory>
</highlight>
- <p>For browsers that have problems even with compression of all file
- types, use the <directive module="mod_setenvif"
- >BrowserMatch</directive> directive to set the <code>no-gzip</code>
- note for that particular browser so that no compression will be
- performed. You may combine <code>no-gzip</code> with <code
- >gzip-only-text/html</code> to get the best results. In that case
- the former overrides the latter. Take a look at the following
- excerpt from the <a href="#recommended">configuration example</a>
- defined in the section above:</p>
-
- <highlight language="config">
-BrowserMatch ^Mozilla/4 gzip-only-text/html
-BrowserMatch ^Mozilla/4\.0[678] no-gzip
-BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
- </highlight>
-
- <p>At first we probe for a <code>User-Agent</code> string that
- indicates a Netscape Navigator version of 4.x. These versions
- cannot handle compression of types other than
- <code>text/html</code>. The versions 4.06, 4.07 and 4.08 also
- have problems with decompressing html files. Thus, we completely
- turn off the deflate filter for them.</p>
-
- <p>The third <directive module="mod_setenvif">BrowserMatch</directive>
- directive fixes the guessed identity of the user agent, because
- the Microsoft Internet Explorer identifies itself also as "Mozilla/4"
- but is actually able to handle requested compression. Therefore we
- match against the additional string "MSIE" (<code>\b</code> means
- "word boundary") in the <code>User-Agent</code> Header and turn off
- the restrictions defined before.</p>
-
<note><title>Note</title>
The <code>DEFLATE</code> filter is always inserted after RESOURCE
filters like PHP or SSI. It never touches internal subrequests.
</note>
<note><title>Note</title>
- There is a environment variable <code>force-gzip</code>,
+ There is an environment variable <code>force-gzip</code>,
set via <directive module="mod_env">SetEnv</directive>, which
will ignore the accept-encoding setting of your browser and will
send compressed output.
<p>The <module>mod_deflate</module> module also provides a filter for
inflating/uncompressing a gzip compressed response body. In order to activate
this feature you have to insert the <code>INFLATE</code> filter into
- the outputfilter chain using <directive module="core"
+ the output filter chain using <directive module="core"
>SetOutputFilter</directive> or <directive module="mod_mime"
>AddOutputFilter</directive>, for example:</p>
<highlight language="config">
-<Location /dav-area>
- ProxyPass http://example.com/
+<Location "/dav-area">
+ ProxyPass "http://example.com/"
SetOutputFilter INFLATE
</Location>
</highlight>
>AddInputFilter</directive>, for example:</p>
<highlight language="config">
-<Location /dav-area>
+<Location "/dav-area">
SetInputFilter DEFLATE
</Location>
</highlight>
</example>
</section>
+<section id="precompressed"><title>Serving pre-compressed
+content</title>
+
+ <p>Since <module>mod_deflate</module> re-compresses content each
+ time a request is made, some performance benefit can be derived by
+ pre-compressing the content and telling mod_deflate to serve them
+ without re-compressing them. This may be accomplished using a
+ configuration like the following:</p>
+
+ <highlight language="config">
+<IfModule mod_headers.c>
+ # Serve gzip compressed CSS files if they exist
+ # and the client accepts gzip.
+ RewriteCond "%{HTTP:Accept-encoding}" "gzip"
+ RewriteCond "%{REQUEST_FILENAME}\.gz" "-s"
+ RewriteRule "^(.*)\.css" "$1\.css\.gz" [QSA]
+
+ # Serve gzip compressed JS files if they exist
+ # and the client accepts gzip.
+ RewriteCond "%{HTTP:Accept-encoding}" "gzip"
+ RewriteCond "%{REQUEST_FILENAME}\.gz" "-s"
+ RewriteRule "^(.*)\.js" "$1\.js\.gz" [QSA]
+
+
+ # Serve correct content types, and prevent mod_deflate double gzip.
+ RewriteRule "\.css\.gz$" "-" [T=text/css,E=no-gzip:1]
+ RewriteRule "\.js\.gz$" "-" [T=text/javascript,E=no-gzip:1]
+
+
+ <FilesMatch "(\.js\.gz|\.css\.gz)$">
+ # Serve correct encoding type.
+ Header append Content-Encoding gzip
+
+ # Force proxies to cache gzipped &
+ # non-gzipped css/js files separately.
+ Header append Vary Accept-Encoding
+ </FilesMatch>
+</IfModule>
+ </highlight>
+
+</section>
+
<directivesynopsis>
<name>DeflateFilterNote</name>
<description>Places the compression ratio in a note for logging</description>
<example><title>Example</title>
<highlight language="config">
DeflateFilterNote ratio
-
+
LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate
- CustomLog logs/deflate_log deflate
+ CustomLog "logs/deflate_log" deflate
</highlight>
</example>
<p>If you want to extract more accurate values from your logs, you
can use the <var>type</var> argument to specify the type of data
- left as note for logging. <var>type</var> can be one of:</p>
+ left as a note for logging. <var>type</var> can be one of:</p>
<dl>
<dt><code>Input</code></dt>
DeflateFilterNote Ratio ratio
LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate
-CustomLog logs/deflate_log deflate
+CustomLog "logs/deflate_log" deflate
</highlight>
</example>
</usage>
<usage>
<p>The <directive>DeflateBufferSize</directive> directive specifies
the size in bytes of the fragments that zlib should compress at one
- time.</p>
+ time. If the compressed response size is bigger than the one specified
+ by this directive then httpd will switch to chunked encoding
+ (HTTP header <code>Transfer-Encoding</code> set to <code>Chunked</code>), with the
+ side effect of not setting any <code>Content-Length</code> HTTP header. This is particularly
+ important when httpd works behind reverse caching proxies or when httpd is configured with
+ <module>mod_cache</module> and <module>mod_cache_disk</module> because
+ HTTP responses without any <code>Content-Length</code> header might not be cached.
+ </p>
</usage>
</directivesynopsis>
</usage>
</directivesynopsis>
+<directivesynopsis>
+<name>DeflateAlterETag</name>
+<description>How the outgoing ETag header should be modified during compression</description>
+<syntax>DeflateAlterETag AddSuffix|NoChange|Remove</syntax>
+<default>DeflateAlterETag AddSuffix</default>
+<contextlist><context>server config</context><context>virtual host</context>
+</contextlist>
-</modulesynopsis>
+<usage>
+ <p>The <directive>DeflateAlterETag</directive> directive specifies
+ how the ETag hader should be altered when a response is compressed.</p>
+ <dl>
+ <dt>AddSuffix</dt>
+ <dd><p>Append the compression method onto the end of the ETag, causing
+ compressed and uncompressed representations to have unique ETags.
+ This has been the default since 2.4.0, but prevents serving
+ "HTTP Not Modified" (304) responses to conditional requests for
+ compressed content.</p></dd>
+ <dt>NoChange</dt>
+ <dd><p>Don't change the ETag on a compressed response. This was the default
+ prior to 2.4.0, but does not satisfy the HTTP/1.1 property that all
+ representations of the same resource have unique ETags. </p></dd>
+ <dt>Remove</dt>
+ <dd><p>Remove the ETag header from compressed responses. This prevents
+ some conditional requests from being possible, but avoids the
+ shortcomings of the preceding options. </p></dd>
+ </dl>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>DeflateInflateLimitRequestBody</name>
+<description>Maximum size of inflated request bodies</description>
+<syntax>DeflateInflateLimitRequestBody<var>value</var></syntax>
+<default>None, but LimitRequestBody applies after deflation</default>
+<contextlist><context>server config</context><context>virtual host</context>
+<context>directory</context><context>.htaccess</context></contextlist>
+<override>All</override>
+<compatibility>2.4.10 and later</compatibility>
+
+<usage>
+ <p>The <directive>DeflateInflateLimitRequestBody</directive> directive
+ specifies the maximum size of an inflated request body. If it is unset,
+ <directive module="core">LimitRequestBody</directive> is applied to the
+ inflated body.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>DeflateInflateRatioLimit</name>
+<description>Maximum inflation ratio for request bodies</description>
+<syntax>DeflateInflateRatioLimit <var>value</var></syntax>
+<default>200</default>
+<contextlist><context>server config</context><context>virtual host</context>
+<context>directory</context><context>.htaccess</context></contextlist>
+<override>All</override>
+<compatibility>2.4.10 and later</compatibility>
+<usage>
+ <p>The <directive>DeflateInflateRatioLimit</directive> directive
+ specifies the maximum ratio of deflated to inflated size of an
+ inflated request body. This ratio is checked as the body is
+ streamed in, and if crossed more than
+ <directive>DeflateInflateRatioBurst</directive> times, the request
+ will be terminated.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>DeflateInflateRatioBurst</name>
+<description>Maximum number of times the inflation ratio for request bodies
+ can be crossed</description>
+<syntax>DeflateInflateRatioBurst <var>value</var></syntax>
+<default>3</default>
+<contextlist><context>server config</context><context>virtual host</context>
+<context>directory</context><context>.htaccess</context></contextlist>
+<override>All</override>
+<compatibility>2.4.10 and later</compatibility>
+
+<usage>
+ <p>The <directive>DeflateInflateRatioBurst</directive> directive
+ specifies the maximum number of times the
+ <directive>DeflateInflateRatioLimit</directive> can be crossed before
+ terminating the request.</p>
+</usage>
+</directivesynopsis>
+
+</modulesynopsis>