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="recommended"><title>Sample Configurations</title>
41 <note type="warning"><title>Compression and TLS</title>
42 <p>Some web applications are vulnerable to an information disclosure
43 attack when a TLS connection carries deflate compressed data. For more
44 information, review the details of the "BREACH" family of attacks.</p>
46 <p>This is a simple configuration that compresses common text-based content types.</p>
48 <example><title>Compress only a few types</title>
49 <highlight language="config">
50 AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript
56 <section id="enable"><title>Enabling Compression</title>
57 <note type="warning"><title>Compression and TLS</title>
58 <p>Some web applications are vulnerable to an information disclosure
59 attack when a TLS connection carries deflate compressed data. For more
60 information, review the details of the "BREACH" family of attacks.</p>
63 <section id="output"><title>Output Compression</title>
64 <p>Compression is implemented by the <code>DEFLATE</code>
65 <a href="../filter.html">filter</a>. The following directive
66 will enable compression for documents in the container where it
69 <highlight language="config">
70 SetOutputFilter DEFLATE
71 SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ no-gzip
74 <p>If you want to restrict the compression to particular MIME types
75 in general, you may use the <directive module="mod_filter"
76 >AddOutputFilterByType</directive> directive. Here is an example of
77 enabling compression only for the html files of the Apache
80 <highlight language="config">
81 <Directory "/your-server-root/manual">
82 AddOutputFilterByType DEFLATE text/html
86 <note><title>Note</title>
87 The <code>DEFLATE</code> filter is always inserted after RESOURCE
88 filters like PHP or SSI. It never touches internal subrequests.
90 <note><title>Note</title>
91 There is an environment variable <code>force-gzip</code>,
92 set via <directive module="mod_env">SetEnv</directive>, which
93 will ignore the accept-encoding setting of your browser and will
94 send compressed output.
98 <section id="inflate"><title>Output Decompression</title>
99 <p>The <module>mod_deflate</module> module also provides a filter for
100 inflating/uncompressing a gzip compressed response body. In order to activate
101 this feature you have to insert the <code>INFLATE</code> filter into
102 the output filter chain using <directive module="core"
103 >SetOutputFilter</directive> or <directive module="mod_mime"
104 >AddOutputFilter</directive>, for example:</p>
106 <highlight language="config">
107 <Location /dav-area>
108 ProxyPass http://example.com/
109 SetOutputFilter INFLATE
113 <p>This Example will uncompress gzip'ed output from example.com, so other
114 filters can do further processing with it.
118 <section id="input"><title>Input Decompression</title>
119 <p>The <module>mod_deflate</module> module also provides a filter for
120 decompressing a gzip compressed request body . In order to activate
121 this feature you have to insert the <code>DEFLATE</code> filter into
122 the input filter chain using <directive module="core"
123 >SetInputFilter</directive> or <directive module="mod_mime"
124 >AddInputFilter</directive>, for example:</p>
126 <highlight language="config">
127 <Location /dav-area>
128 SetInputFilter DEFLATE
132 <p>Now if a request contains a <code>Content-Encoding:
133 gzip</code> header, the body will be automatically decompressed.
134 Few browsers have the ability to gzip request bodies. However,
135 some special applications actually do support request
136 compression, for instance some <a
137 href="http://www.webdav.org">WebDAV</a> clients.</p>
139 <note type="warning"><title>Note on Content-Length</title>
140 <p>If you evaluate the request body yourself, <em>don't trust
141 the <code>Content-Length</code> header!</em>
142 The Content-Length header reflects the length of the
143 incoming data from the client and <em>not</em> the byte count of
144 the decompressed data stream.</p>
149 <section id="proxies"><title>Dealing with proxy servers</title>
151 <p>The <module>mod_deflate</module> module sends a <code>Vary:
152 Accept-Encoding</code> HTTP response header to alert proxies that
153 a cached response should be sent only to clients that send the
154 appropriate <code>Accept-Encoding</code> request header. This
155 prevents compressed content from being sent to a client that will
156 not understand it.</p>
158 <p>If you use some special exclusions dependent
159 on, for example, the <code>User-Agent</code> header, you must
160 manually configure an addition to the <code>Vary</code> header
161 to alert proxies of the additional restrictions. For example,
162 in a typical configuration where the addition of the <code>DEFLATE</code>
163 filter depends on the <code>User-Agent</code>, you should add:</p>
165 <highlight language="config">
166 Header append Vary User-Agent
169 <p>If your decision about compression depends on other information
170 than request headers (<em>e.g.</em> HTTP version), you have to set the
171 <code>Vary</code> header to the value <code>*</code>. This prevents
172 compliant proxies from caching entirely.</p>
174 <example><title>Example</title>
175 <highlight language="config">
181 <section id="precompressed"><title>Serving pre-compressed
184 <p>Since <module>mod_deflate</module> re-compresses content each
185 time a request is made, some performance benefit can be derived by
186 pre-compressing the content and telling mod_deflate to serve them
187 without re-compressing them. This may be accomplished using a
188 configuration like the following:</p>
190 <highlight language="config">
191 <IfModule mod_headers.c>
192 # Serve gzip compressed CSS files if they exist
193 # and the client accepts gzip.
194 RewriteCond %{HTTP:Accept-encoding} gzip
195 RewriteCond %{REQUEST_FILENAME}\.gz -s
196 RewriteRule ^(.*)\.css $1\.css\.gz [QSA]
198 # Serve gzip compressed JS files if they exist
199 # and the client accepts gzip.
200 RewriteCond %{HTTP:Accept-encoding} gzip
201 RewriteCond %{REQUEST_FILENAME}\.gz -s
202 RewriteRule ^(.*)\.js $1\.js\.gz [QSA]
205 # Serve correct content types, and prevent mod_deflate double gzip.
206 RewriteRule \.css\.gz$ - [T=text/css,E=no-gzip:1]
207 RewriteRule \.js\.gz$ - [T=text/javascript,E=no-gzip:1]
210 <FilesMatch "(\.js\.gz|\.css\.gz)$">
211 # Serve correct encoding type.
212 Header append Content-Encoding gzip
214 # Force proxies to cache gzipped &
215 # non-gzipped css/js files separately.
216 Header append Vary Accept-Encoding
224 <name>DeflateFilterNote</name>
225 <description>Places the compression ratio in a note for logging</description>
226 <syntax>DeflateFilterNote [<var>type</var>] <var>notename</var></syntax>
227 <contextlist><context>server config</context><context>virtual host</context>
231 <p>The <directive>DeflateFilterNote</directive> directive
232 specifies that a note about compression ratios should be attached
233 to the request. The name of the note is the value specified for
234 the directive. You can use that note for statistical purposes by
235 adding the value to your <a href="../logs.html#accesslog"
238 <example><title>Example</title>
239 <highlight language="config">
240 DeflateFilterNote ratio
242 LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate
243 CustomLog logs/deflate_log deflate
247 <p>If you want to extract more accurate values from your logs, you
248 can use the <var>type</var> argument to specify the type of data
249 left as a note for logging. <var>type</var> can be one of:</p>
252 <dt><code>Input</code></dt>
253 <dd>Store the byte count of the filter's input stream in the note.</dd>
255 <dt><code>Output</code></dt>
256 <dd>Store the byte count of the filter's output stream in the note.</dd>
258 <dt><code>Ratio</code></dt>
259 <dd>Store the compression ratio (<code>output/input * 100</code>)
260 in the note. This is the default, if the <var>type</var> argument
264 <p>Thus you may log it this way:</p>
266 <example><title>Accurate Logging</title>
267 <highlight language="config">
268 DeflateFilterNote Input instream
269 DeflateFilterNote Output outstream
270 DeflateFilterNote Ratio ratio
272 LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate
273 CustomLog logs/deflate_log deflate
277 <seealso><module>mod_log_config</module></seealso>
281 <name>DeflateBufferSize</name>
282 <description>Fragment size to be compressed at one time by zlib</description>
283 <syntax>DeflateBufferSize <var>value</var></syntax>
284 <default>DeflateBufferSize 8096</default>
285 <contextlist><context>server config</context><context>virtual host</context>
289 <p>The <directive>DeflateBufferSize</directive> directive specifies
290 the size in bytes of the fragments that zlib should compress at one
296 <name>DeflateWindowSize</name>
297 <description>Zlib compression window size</description>
298 <syntax>DeflateWindowSize <var>value</var></syntax>
299 <default>DeflateWindowSize 15</default>
300 <contextlist><context>server config</context><context>virtual host</context>
304 <p>The <directive>DeflateWindowSize</directive> directive specifies the
305 zlib compression window size (a value between 1 and 15). Generally, the
306 higher the window size, the higher can the compression ratio be expected.</p>
312 <name>DeflateMemLevel</name>
313 <description>How much memory should be used by zlib for compression</description>
314 <syntax>DeflateMemLevel <var>value</var></syntax>
315 <default>DeflateMemLevel 9</default>
316 <contextlist><context>server config</context><context>virtual host</context>
320 <p>The <directive>DeflateMemLevel</directive> directive specifies
321 how much memory should be used by zlib for compression
322 (a value between 1 and 9).</p>
327 <name>DeflateCompressionLevel</name>
328 <description>How much compression do we apply to the output</description>
329 <syntax>DeflateCompressionLevel <var>value</var></syntax>
330 <default>Zlib's default</default>
331 <contextlist><context>server config</context><context>virtual host</context>
335 <p>The <directive>DeflateCompressionLevel</directive> directive specifies
336 what level of compression should be used, the higher the value,
337 the better the compression, but the more CPU time is required to
339 <p>The value must between 1 (less compression) and 9 (more compression).</p>
344 <name>DeflateAlterETag</name>
345 <description>How the outgoing ETag header should be modified during compression</description>
346 <syntax>DeflateAlterETag AddSuffix|NoChange|Remove</syntax>
347 <default>DeflateAlterETag AddSuffix</default>
348 <contextlist><context>server config</context><context>virtual host</context>
352 <p>The <directive>DeflateAlterETag</directive> directive specifies
353 how the ETag hader should be altered when a response is compressed.</p>
356 <dd><p>Append the compression method onto the end of the ETag, causing
357 compressed and uncompressed representations to have unique ETags.
358 This has been the default since 2.4.0, but prevents serving
359 "HTTP Not Modified" (304) responses to conditional requests for
360 compressed content.</p></dd>
362 <dd><p>Don't change the ETag on a compressed response. This was the default
363 prior to 2.4.0, but does not satisfy the HTTP/1.1 property that all
364 representations of the same resource have unique ETags. </p></dd>
366 <dd><p>Remove the ETag header from compressed responses. This prevents
367 some conditional requests from being possible, but avoids the
368 shortcomings of the preceding options. </p></dd>
374 <name>DeflateInflateLimitRequestBody</name>
375 <description>Maximum size of inflated request bodies</description>
376 <syntax>DeflateInflateLimitRequestBody<var>value</var></syntax>
377 <default>None, but LimitRequestBody applies after deflation</default>
378 <contextlist><context>server config</context><context>virtual host</context>
379 <context>directory</context><context>.htaccess</context></contextlist>
380 <compatibility>2.4.10 and later</compatibility>
383 <p>The <directive>DeflateInflateLimitRequestBody</directive> directive
384 specifies the maximum size of an inflated request body. If it is unset,
385 <directive module="core">LimitRequestBody</directive> is applied to the
391 <name>DeflateInflateRatioLimit</name>
392 <description>Maximum inflation ratio for request bodies</description>
393 <syntax>DeflateInflateRatioLimit <var>value</var></syntax>
394 <default>200</default>
395 <contextlist><context>server config</context><context>virtual host</context>
396 <context>directory</context><context>.htaccess</context></contextlist>
397 <compatibility>2.4.10 and later</compatibility>
400 <p>The <directive>DeflateInflateRatioLimit</directive> directive
401 specifies the maximum ratio of deflated to inflated size of an
402 inflated request body. This ratio is checked as the body is
403 streamed in, and if crossed more than
404 <directive>DeflateInflateRatioBurst</directive> times, the request
405 will be terminated.</p>
410 <name>DeflateInflateRatioBurst</name>
411 <description>Maximum number of times the inflation ratio for request bodies
412 can be crossed</description>
413 <syntax>DeflateInflateRatioBurst <var>value</var></syntax>
415 <contextlist><context>server config</context><context>virtual host</context>
416 <context>directory</context><context>.htaccess</context></contextlist>
417 <compatibility>2.4.10 and later</compatibility>
420 <p>The <directive>DeflateInflateRatioBurst</directive> directive
421 specifies the maximum number of times the
422 <directive>DeflateInflateRatioLimit</directive> can be crossed before
423 terminating the request.</p>