<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
-<modulesynopsis>
+<!-- $LastChangedRevision$ -->
+
+<!--
+ 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.
+-->
+
+<modulesynopsis metafile="mod_deflate.xml.meta">
<name>mod_deflate</name>
-<description>Compress content before
- it is delivered to the client</description>
+<description>Compress content before it is delivered to the
+client</description>
<status>Extension</status>
<sourcefile>mod_deflate.c</sourcefile>
<identifier>deflate_module</identifier>
your server to be compressed before being sent to the client over
the network.</p>
</summary>
-<seealso><directive module="mod_mime">AddOutputFilter</directive></seealso>
-<seealso><directive module="core">SetOutputFilter</directive></seealso>
+<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>
+ <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 text/css text/javascript application/javascript
+ </highlight>
+ </example>
+
+</section>
-<section><title>Enabling Compression</title>
+<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>
- <p>Compression is implemented by the <code>DEFLATE</code>
- <a href="../filter.html">filter</a>. The following directive
- will enable compression for documents in the container where it
- is placed:</p>
- <p><strong>Most popular browsers can not handle compression of all content
- so you may want to enable the 'gzip-only-text/html' note (see below)
- </strong></p>
+ <section id="output"><title>Output Compression</title>
+ <p>Compression is implemented by the <code>DEFLATE</code>
+ <a href="../filter.html">filter</a>. The following directive
+ will enable compression for documents in the container where it
+ is placed:</p>
-<example>SetEnv gzip-only-text/html 1<br />
+ <highlight language="config">
SetOutputFilter DEFLATE
-</example>
+SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ no-gzip
+ </highlight>
- <p>Here is an example of enabling compression for the Apache
- documentation:</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
+ enabling compression only for the html files of the Apache
+ documentation:</p>
-<example>
-<Directory "/your-server-root/manual"><br />
- SetEnv gzip-only-text/html 1<br />
- SetOutputFilter DEFLATE<br />
+ <highlight language="config">
+<Directory "/your-server-root/manual">
+ AddOutputFilterByType DEFLATE text/html
</Directory>
-</example>
+ </highlight>
+
+ <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 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.
+ </note>
+
+ </section>
+ <section id="inflate"><title>Output Decompression</title>
+ <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 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/"
+ SetOutputFilter INFLATE
+</Location>
+ </highlight>
+
+ <p>This Example will uncompress gzip'ed output from example.com, so other
+ filters can do further processing with it.
+ </p>
+
+ </section>
+ <section id="input"><title>Input Decompression</title>
+ <p>The <module>mod_deflate</module> module also provides a filter for
+ decompressing a gzip compressed request body . In order to activate
+ this feature you have to insert the <code>DEFLATE</code> filter into
+ the input filter chain using <directive module="core"
+ >SetInputFilter</directive> or <directive module="mod_mime"
+ >AddInputFilter</directive>, for example:</p>
+
+ <highlight language="config">
+<Location "/dav-area">
+ SetInputFilter DEFLATE
+</Location>
+ </highlight>
+
+ <p>Now if a request contains a <code>Content-Encoding:
+ gzip</code> header, the body will be automatically decompressed.
+ Few browsers have the ability to gzip request bodies. However,
+ some special applications actually do support request
+ compression, for instance some <a
+ href="http://www.webdav.org">WebDAV</a> clients.</p>
+
+ <note type="warning"><title>Note on Content-Length</title>
+ <p>If you evaluate the request body yourself, <em>don't trust
+ the <code>Content-Length</code> header!</em>
+ The Content-Length header reflects the length of the
+ incoming data from the client and <em>not</em> the byte count of
+ the decompressed data stream.</p>
+ </note>
+ </section>
+</section>
+
+<section id="proxies"><title>Dealing with proxy servers</title>
+
+ <p>The <module>mod_deflate</module> module sends a <code>Vary:
+ Accept-Encoding</code> HTTP response header to alert proxies that
+ a cached response should be sent only to clients that send the
+ appropriate <code>Accept-Encoding</code> request header. This
+ prevents compressed content from being sent to a client that will
+ not understand it.</p>
+
+ <p>If you use some special exclusions dependent
+ on, for example, the <code>User-Agent</code> header, you must
+ manually configure an addition to the <code>Vary</code> header
+ to alert proxies of the additional restrictions. For example,
+ in a typical configuration where the addition of the <code>DEFLATE</code>
+ filter depends on the <code>User-Agent</code>, you should add:</p>
+
+ <highlight language="config">
+ Header append Vary User-Agent
+ </highlight>
+
+ <p>If your decision about compression depends on other information
+ than request headers (<em>e.g.</em> HTTP version), you have to set the
+ <code>Vary</code> header to the value <code>*</code>. This prevents
+ compliant proxies from caching entirely.</p>
+
+ <example><title>Example</title>
+ <highlight language="config">
+ Header set Vary *
+ </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>
-<syntax>DeflateFilterNote <em>notename</em></syntax>
-<contextlist><context>server config</context></contextlist>
+<syntax>DeflateFilterNote [<var>type</var>] <var>notename</var></syntax>
+<contextlist><context>server config</context><context>virtual host</context>
+</contextlist>
<usage>
<p>The <directive>DeflateFilterNote</directive> directive
specifies that a note about compression ratios should be attached
- to the request. The name of the note is the value specified for
- the directive.</p>
+ to the request. The name of the note is the value specified for
+ the directive. You can use that note for statistical purposes by
+ adding the value to your <a href="../logs.html#accesslog"
+ >access log</a>.</p>
+
+ <example><title>Example</title>
+ <highlight language="config">
+ DeflateFilterNote ratio
+
+ LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' 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 a note for logging. <var>type</var> can be one of:</p>
+
+ <dl>
+ <dt><code>Input</code></dt>
+ <dd>Store the byte count of the filter's input stream in the note.</dd>
+
+ <dt><code>Output</code></dt>
+ <dd>Store the byte count of the filter's output stream in the note.</dd>
+
+ <dt><code>Ratio</code></dt>
+ <dd>Store the compression ratio (<code>output/input * 100</code>)
+ in the note. This is the default, if the <var>type</var> argument
+ is omitted.</dd>
+ </dl>
+
+ <p>Thus you may log it this way:</p>
+
+ <example><title>Accurate Logging</title>
+ <highlight language="config">
+DeflateFilterNote Input instream
+DeflateFilterNote Output outstream
+DeflateFilterNote Ratio ratio
+
+LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate
+CustomLog "logs/deflate_log" deflate
+</highlight>
+ </example>
</usage>
+<seealso><module>mod_log_config</module></seealso>
</directivesynopsis>
<directivesynopsis>
<name>DeflateBufferSize</name>
<description>Fragment size to be compressed at one time by zlib</description>
-<syntax>DeflateBufferSize <em>value</em></syntax>
-<contextlist><context>server config</context></contextlist>
+<syntax>DeflateBufferSize <var>value</var></syntax>
+<default>DeflateBufferSize 8096</default>
+<contextlist><context>server config</context><context>virtual host</context>
+</contextlist>
<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>
<directivesynopsis>
<name>DeflateWindowSize</name>
<description>Zlib compression window size</description>
-<syntax>DeflateWindowSize <em>value</em></syntax>
-<contextlist><context>server config</context></contextlist>
+<syntax>DeflateWindowSize <var>value</var></syntax>
+<default>DeflateWindowSize 15</default>
+<contextlist><context>server config</context><context>virtual host</context>
+</contextlist>
<usage>
<p>The <directive>DeflateWindowSize</directive> directive specifies the
- zlib compression window size (a value between 1 and 15).</p>
+ zlib compression window size (a value between 1 and 15). Generally, the
+ higher the window size, the higher can the compression ratio be expected.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
+
<name>DeflateMemLevel</name>
<description>How much memory should be used by zlib for compression</description>
-<syntax>DeflateMemLevel <em>value</em></syntax>
-<contextlist><context>server config</context></contextlist>
+<syntax>DeflateMemLevel <var>value</var></syntax>
+<default>DeflateMemLevel 9</default>
+<contextlist><context>server config</context><context>virtual host</context>
+</contextlist>
<usage>
<p>The <directive>DeflateMemLevel</directive> directive specifies
</usage>
</directivesynopsis>
-</modulesynopsis>
+<directivesynopsis>
+<name>DeflateCompressionLevel</name>
+<description>How much compression do we apply to the output</description>
+<syntax>DeflateCompressionLevel <var>value</var></syntax>
+<default>Zlib's default</default>
+<contextlist><context>server config</context><context>virtual host</context>
+</contextlist>
+
+<usage>
+ <p>The <directive>DeflateCompressionLevel</directive> directive specifies
+ what level of compression should be used, the higher the value,
+ the better the compression, but the more CPU time is required to
+ achieve this.</p>
+ <p>The value must between 1 (less compression) and 9 (more compression).</p>
+</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>
+
+<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>
projects / apache / blobdiff