2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <modulesynopsis metafile="mod_deflate.xml.meta">
25 <name>mod_deflate</name>
26 <description>Compress content before it is delivered to the
28 <status>Extension</status>
29 <sourcefile>mod_deflate.c</sourcefile>
30 <identifier>deflate_module</identifier>
33 <p>The <module>mod_deflate</module> module provides
34 the <code>DEFLATE</code> output filter that allows output from
35 your server to be compressed before being sent to the client over
38 <seealso><a href="../filter.html">Filters</a></seealso>
40 <section id="supportedencodings"><title>Supported Encodings</title>
41 <p>The <code>gzip</code> encoding is the only one supported to ensure complete compatibility
42 with old browser implementations. The <code>deflate</code> encoding is not supported,
43 please check the <a href="http://www.gzip.org/zlib/zlib_faq.html#faq38">zlib's documentation</a>
44 for a complete explanation.
48 <section id="recommended"><title>Sample Configurations</title>
49 <note type="warning"><title>Compression and TLS</title>
50 <p>Some web applications are vulnerable to an information disclosure
51 attack when a TLS connection carries deflate compressed data. For more
52 information, review the details of the "BREACH" family of attacks.</p>
54 <p>This is a simple configuration that compresses common text-based content types.</p>
56 <example><title>Compress only a few types</title>
57 <highlight language="config">
58 AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript
64 <section id="enable"><title>Enabling Compression</title>
65 <note type="warning"><title>Compression and TLS</title>
66 <p>Some web applications are vulnerable to an information disclosure
67 attack when a TLS connection carries deflate compressed data. For more
68 information, review the details of the "BREACH" family of attacks.</p>
71 <section id="output"><title>Output Compression</title>
72 <p>Compression is implemented by the <code>DEFLATE</code>
73 <a href="../filter.html">filter</a>. The following directive
74 will enable compression for documents in the container where it
77 <highlight language="config">
78 SetOutputFilter DEFLATE
79 SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ no-gzip
82 <p>If you want to restrict the compression to particular MIME types
83 in general, you may use the <directive module="mod_filter"
84 >AddOutputFilterByType</directive> directive. Here is an example of
85 enabling compression only for the html files of the Apache
88 <highlight language="config">
89 <Directory "/your-server-root/manual">
90 AddOutputFilterByType DEFLATE text/html
94 <note><title>Note</title>
95 The <code>DEFLATE</code> filter is always inserted after RESOURCE
96 filters like PHP or SSI. It never touches internal subrequests.
98 <note><title>Note</title>
99 There is an environment variable <code>force-gzip</code>,
100 set via <directive module="mod_env">SetEnv</directive>, which
101 will ignore the accept-encoding setting of your browser and will
102 send compressed output.
106 <section id="inflate"><title>Output Decompression</title>
107 <p>The <module>mod_deflate</module> module also provides a filter for
108 inflating/uncompressing a gzip compressed response body. In order to activate
109 this feature you have to insert the <code>INFLATE</code> filter into
110 the output filter chain using <directive module="core"
111 >SetOutputFilter</directive> or <directive module="mod_mime"
112 >AddOutputFilter</directive>, for example:</p>
114 <highlight language="config">
115 <Location "/dav-area">
116 ProxyPass "http://example.com/"
117 SetOutputFilter INFLATE
121 <p>This Example will uncompress gzip'ed output from example.com, so other
122 filters can do further processing with it.
126 <section id="input"><title>Input Decompression</title>
127 <p>The <module>mod_deflate</module> module also provides a filter for
128 decompressing a gzip compressed request body . In order to activate
129 this feature you have to insert the <code>DEFLATE</code> filter into
130 the input filter chain using <directive module="core"
131 >SetInputFilter</directive> or <directive module="mod_mime"
132 >AddInputFilter</directive>, for example:</p>
134 <highlight language="config">
135 <Location "/dav-area">
136 SetInputFilter DEFLATE
140 <p>Now if a request contains a <code>Content-Encoding:
141 gzip</code> header, the body will be automatically decompressed.
142 Few browsers have the ability to gzip request bodies. However,
143 some special applications actually do support request
144 compression, for instance some <a
145 href="http://www.webdav.org">WebDAV</a> clients.</p>
147 <note type="warning"><title>Note on Content-Length</title>
148 <p>If you evaluate the request body yourself, <em>don't trust
149 the <code>Content-Length</code> header!</em>
150 The Content-Length header reflects the length of the
151 incoming data from the client and <em>not</em> the byte count of
152 the decompressed data stream.</p>
157 <section id="proxies"><title>Dealing with proxy servers</title>
159 <p>The <module>mod_deflate</module> module sends a <code>Vary:
160 Accept-Encoding</code> HTTP response header to alert proxies that
161 a cached response should be sent only to clients that send the
162 appropriate <code>Accept-Encoding</code> request header. This
163 prevents compressed content from being sent to a client that will
164 not understand it.</p>
166 <p>If you use some special exclusions dependent
167 on, for example, the <code>User-Agent</code> header, you must
168 manually configure an addition to the <code>Vary</code> header
169 to alert proxies of the additional restrictions. For example,
170 in a typical configuration where the addition of the <code>DEFLATE</code>
171 filter depends on the <code>User-Agent</code>, you should add:</p>
173 <highlight language="config">
174 Header append Vary User-Agent
177 <p>If your decision about compression depends on other information
178 than request headers (<em>e.g.</em> HTTP version), you have to set the
179 <code>Vary</code> header to the value <code>*</code>. This prevents
180 compliant proxies from caching entirely.</p>
182 <example><title>Example</title>
183 <highlight language="config">
189 <section id="precompressed"><title>Serving pre-compressed
192 <p>Since <module>mod_deflate</module> re-compresses content each
193 time a request is made, some performance benefit can be derived by
194 pre-compressing the content and telling mod_deflate to serve them
195 without re-compressing them. This may be accomplished using a
196 configuration like the following:</p>
198 <highlight language="config">
199 <IfModule mod_headers.c>
200 # Serve gzip compressed CSS and JS files if they exist
201 # and the client accepts gzip.
202 RewriteCond "%{HTTP:Accept-encoding}" "gzip"
203 RewriteCond "%{REQUEST_FILENAME}\.gz" "-s"
204 RewriteRule "^(.*)\.(css|js)" "$1\.$2\.gz" [QSA]
206 # Serve correct content types, and prevent mod_deflate double gzip.
207 RewriteRule "\.css\.gz$" "-" [T=text/css,E=no-gzip:1]
208 RewriteRule "\.js\.gz$" "-" [T=text/javascript,E=no-gzip:1]
211 <FilesMatch "(\.js\.gz|\.css\.gz)$">
212 # Serve correct encoding type.
213 Header append Content-Encoding gzip
215 # Force proxies to cache gzipped &
216 # non-gzipped css/js files separately.
217 Header append Vary Accept-Encoding
225 <name>DeflateFilterNote</name>
226 <description>Places the compression ratio in a note for logging</description>
227 <syntax>DeflateFilterNote [<var>type</var>] <var>notename</var></syntax>
228 <contextlist><context>server config</context><context>virtual host</context>
232 <p>The <directive>DeflateFilterNote</directive> directive
233 specifies that a note about compression ratios should be attached
234 to the request. The name of the note is the value specified for
235 the directive. You can use that note for statistical purposes by
236 adding the value to your <a href="../logs.html#accesslog"
239 <example><title>Example</title>
240 <highlight language="config">
241 DeflateFilterNote ratio
243 LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate
244 CustomLog "logs/deflate_log" deflate
248 <p>If you want to extract more accurate values from your logs, you
249 can use the <var>type</var> argument to specify the type of data
250 left as a note for logging. <var>type</var> can be one of:</p>
253 <dt><code>Input</code></dt>
254 <dd>Store the byte count of the filter's input stream in the note.</dd>
256 <dt><code>Output</code></dt>
257 <dd>Store the byte count of the filter's output stream in the note.</dd>
259 <dt><code>Ratio</code></dt>
260 <dd>Store the compression ratio (<code>output/input * 100</code>)
261 in the note. This is the default, if the <var>type</var> argument
265 <p>Thus you may log it this way:</p>
267 <example><title>Accurate Logging</title>
268 <highlight language="config">
269 DeflateFilterNote Input instream
270 DeflateFilterNote Output outstream
271 DeflateFilterNote Ratio ratio
273 LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate
274 CustomLog "logs/deflate_log" deflate
278 <seealso><module>mod_log_config</module></seealso>
282 <name>DeflateBufferSize</name>
283 <description>Fragment size to be compressed at one time by zlib</description>
284 <syntax>DeflateBufferSize <var>value</var></syntax>
285 <default>DeflateBufferSize 8096</default>
286 <contextlist><context>server config</context><context>virtual host</context>
290 <p>The <directive>DeflateBufferSize</directive> directive specifies
291 the size in bytes of the fragments that zlib should compress at one
292 time. If the compressed response size is bigger than the one specified
293 by this directive then httpd will switch to chunked encoding
294 (HTTP header <code>Transfer-Encoding</code> set to <code>Chunked</code>), with the
295 side effect of not setting any <code>Content-Length</code> HTTP header. This is particularly
296 important when httpd works behind reverse caching proxies or when httpd is configured with
297 <module>mod_cache</module> and <module>mod_cache_disk</module> because
298 HTTP responses without any <code>Content-Length</code> header might not be cached.
304 <name>DeflateWindowSize</name>
305 <description>Zlib compression window size</description>
306 <syntax>DeflateWindowSize <var>value</var></syntax>
307 <default>DeflateWindowSize 15</default>
308 <contextlist><context>server config</context><context>virtual host</context>
312 <p>The <directive>DeflateWindowSize</directive> directive specifies the
313 zlib compression window size (a value between 1 and 15). Generally, the
314 higher the window size, the higher can the compression ratio be expected.</p>
320 <name>DeflateMemLevel</name>
321 <description>How much memory should be used by zlib for compression</description>
322 <syntax>DeflateMemLevel <var>value</var></syntax>
323 <default>DeflateMemLevel 9</default>
324 <contextlist><context>server config</context><context>virtual host</context>
328 <p>The <directive>DeflateMemLevel</directive> directive specifies
329 how much memory should be used by zlib for compression
330 (a value between 1 and 9).</p>
335 <name>DeflateCompressionLevel</name>
336 <description>How much compression do we apply to the output</description>
337 <syntax>DeflateCompressionLevel <var>value</var></syntax>
338 <default>Zlib's default</default>
339 <contextlist><context>server config</context><context>virtual host</context>
343 <p>The <directive>DeflateCompressionLevel</directive> directive specifies
344 what level of compression should be used, the higher the value,
345 the better the compression, but the more CPU time is required to
347 <p>The value must between 1 (less compression) and 9 (more compression).</p>
352 <name>DeflateAlterETag</name>
353 <description>How the outgoing ETag header should be modified during compression</description>
354 <syntax>DeflateAlterETag AddSuffix|NoChange|Remove</syntax>
355 <default>DeflateAlterETag AddSuffix</default>
356 <contextlist><context>server config</context><context>virtual host</context>
360 <p>The <directive>DeflateAlterETag</directive> directive specifies
361 how the ETag hader should be altered when a response is compressed.</p>
364 <dd><p>Append the compression method onto the end of the ETag, causing
365 compressed and uncompressed representations to have unique ETags.
366 This has been the default since 2.4.0, but prevents serving
367 "HTTP Not Modified" (304) responses to conditional requests for
368 compressed content.</p></dd>
370 <dd><p>Don't change the ETag on a compressed response. This was the default
371 prior to 2.4.0, but does not satisfy the HTTP/1.1 property that all
372 representations of the same resource have unique ETags. </p></dd>
374 <dd><p>Remove the ETag header from compressed responses. This prevents
375 some conditional requests from being possible, but avoids the
376 shortcomings of the preceding options. </p></dd>
382 <name>DeflateInflateLimitRequestBody</name>
383 <description>Maximum size of inflated request bodies</description>
384 <syntax>DeflateInflateLimitRequestBody<var>value</var></syntax>
385 <default>None, but LimitRequestBody applies after deflation</default>
386 <contextlist><context>server config</context><context>virtual host</context>
387 <context>directory</context><context>.htaccess</context></contextlist>
388 <override>All</override>
389 <compatibility>2.4.10 and later</compatibility>
392 <p>The <directive>DeflateInflateLimitRequestBody</directive> directive
393 specifies the maximum size of an inflated request body. If it is unset,
394 <directive module="core">LimitRequestBody</directive> is applied to the
400 <name>DeflateInflateRatioLimit</name>
401 <description>Maximum inflation ratio for request bodies</description>
402 <syntax>DeflateInflateRatioLimit <var>value</var></syntax>
403 <default>200</default>
404 <contextlist><context>server config</context><context>virtual host</context>
405 <context>directory</context><context>.htaccess</context></contextlist>
406 <override>All</override>
407 <compatibility>2.4.10 and later</compatibility>
410 <p>The <directive>DeflateInflateRatioLimit</directive> directive
411 specifies the maximum ratio of deflated to inflated size of an
412 inflated request body. This ratio is checked as the body is
413 streamed in, and if crossed more than
414 <directive>DeflateInflateRatioBurst</directive> times, the request
415 will be terminated.</p>
420 <name>DeflateInflateRatioBurst</name>
421 <description>Maximum number of times the inflation ratio for request bodies
422 can be crossed</description>
423 <syntax>DeflateInflateRatioBurst <var>value</var></syntax>
425 <contextlist><context>server config</context><context>virtual host</context>
426 <context>directory</context><context>.htaccess</context></contextlist>
427 <override>All</override>
428 <compatibility>2.4.10 and later</compatibility>
431 <p>The <directive>DeflateInflateRatioBurst</directive> directive
432 specifies the maximum number of times the
433 <directive>DeflateInflateRatioLimit</directive> can be crossed before
434 terminating the request.</p>