2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Copyright 2002-2004 The Apache Software Foundation
9 Licensed under the Apache License, Version 2.0 (the "License");
10 you may not use this file except in compliance with the License.
11 You may obtain a copy of the License at
13 http://www.apache.org/licenses/LICENSE-2.0
15 Unless required by applicable law or agreed to in writing, software
16 distributed under the License is distributed on an "AS IS" BASIS,
17 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 See the License for the specific language governing permissions and
19 limitations under the License.
22 <modulesynopsis metafile="mod_deflate.xml.meta">
24 <name>mod_deflate</name>
25 <description>Compress content before it is delivered to the
27 <status>Extension</status>
28 <sourcefile>mod_deflate.c</sourcefile>
29 <identifier>deflate_module</identifier>
32 <p>The <module>mod_deflate</module> module provides
33 the <code>DEFLATE</code> output filter that allows output from
34 your server to be compressed before being sent to the client over
37 <seealso><a href="../filter.html">Filters</a></seealso>
39 <section id="recommended"><title>Sample Configurations</title>
40 <p>This is a simple sample configuration for the impatient.</p>
42 <example><title>Compress only a few types</title>
43 AddOutputFilterByType DEFLATE text/html text/plain text/xml
46 <p>The following configuration, while resulting in more compressed content,
47 is also much more complicated. Do not use this unless you fully understand
48 all the configuration details.</p>
50 <example><title>Compress everything except images</title>
51 <Location /><br />
54 SetOutputFilter DEFLATE<br />
56 # Netscape 4.x has some problems...<br />
57 BrowserMatch ^Mozilla/4 gzip-only-text/html<br />
59 # Netscape 4.06-4.08 have some more problems<br />
60 BrowserMatch ^Mozilla/4\.0[678] no-gzip<br />
62 # MSIE masquerades as Netscape, but it is fine<br />
63 # BrowserMatch \bMSIE !no-gzip !gzip-only-text/html<br />
65 # NOTE: Due to a bug in mod_setenvif up to Apache 2.0.48<br />
66 # the above regex won't work. You can use the following<br />
67 # workaround to get the desired effect:<br />
68 BrowserMatch \bMSI[E] !no-gzip !gzip-only-text/html<br />
70 # Don't compress images<br />
71 SetEnvIfNoCase Request_URI \<br />
73 \.(?:gif|jpe?g|png)$ no-gzip dont-vary<br />
76 # Make sure proxies don't deliver the wrong content<br />
77 Header append Vary User-Agent env=!dont-vary<br />
84 <section id="enable"><title>Enabling Compression</title>
86 <section id="output"><title>Output Compression</title>
87 <p>Compression is implemented by the <code>DEFLATE</code>
88 <a href="../filter.html">filter</a>. The following directive
89 will enable compression for documents in the container where it
93 SetOutputFilter DEFLATE
96 <p>Some popular browsers cannot handle compression of all content
97 so you may want to set the <code>gzip-only-text/html</code> note to
98 <code>1</code> to only allow html files to be compressed (see
99 below). If you set this to <em>anything but <code>1</code></em> it
102 <p>If you want to restrict the compression to particular MIME types
103 in general, you may use the <directive module="core"
104 >AddOutputFilterByType</directive> directive. Here is an example of
105 enabling compression only for the html files of the Apache
109 <Directory "/your-server-root/manual"><br />
111 AddOutputFilterByType DEFLATE text/html<br />
116 <p>For browsers that have problems even with compression of all file
117 types, use the <directive module="mod_setenvif"
118 >BrowserMatch</directive> directive to set the <code>no-gzip</code>
119 note for that particular browser so that no compression will be
120 performed. You may combine <code>no-gzip</code> with <code
121 >gzip-only-text/html</code> to get the best results. In that case
122 the former overrides the latter. Take a look at the following
123 excerpt from the <a href="#recommended">configuration example</a>
124 defined in the section above:</p>
127 BrowserMatch ^Mozilla/4 gzip-only-text/html<br />
128 BrowserMatch ^Mozilla/4\.0[678] no-gzip<br />
129 BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
132 <p>At first we probe for a <code>User-Agent</code> string that
133 indicates a Netscape Navigator version of 4.x. These versions
134 cannot handle compression of types other than
135 <code>text/html</code>. The versions 4.06, 4.07 and 4.08 also
136 have problems with decompressing html files. Thus, we completely
137 turn off the deflate filter for them.</p>
139 <p>The third <directive module="mod_setenvif">BrowserMatch</directive>
140 directive fixes the guessed identity of the user agent, because
141 the Microsoft Internet Explorer identifies itself also as "Mozilla/4"
142 but is actually able to handle requested compression. Therefore we
143 match against the additional string "MSIE" (<code>\b</code> means
144 "word boundary") in the <code>User-Agent</code> Header and turn off
145 the restrictions defined before.</p>
147 <note><title>Note</title>
148 The <code>DEFLATE</code> filter is always inserted after RESOURCE
149 filters like PHP or SSI. It never touches internal subrequests.
151 <note><title>Note</title>
152 There is a environment variable <code>force-gzip</code>,
153 set via <directive module="core">SetEnv</directive>, which
154 will ignore the accept-encoding setting of your browser and will
155 send compressed output.
159 <section id="inflate"><title>Output Decompression</title>
160 <p>The <module>mod_deflate</module> module also provides a filter for
161 inflating/uncompressing a gzip compressed response body. In order to activate
162 this feature you have to insert the <code>INFLATE</code> filter into
163 the outputfilter chain using <directive module="core"
164 >SetOutputFilter</directive> or <directive module="mod_mime"
165 >AddOutputFilter</directive>, for example:</p>
168 <Location /dav-area><br />
170 ProxyPass http://example.com/<br />
171 SetOutputFilter INFLATE<br />
176 <p>This Example will uncompress gzip'ed output from example.com, so other
177 filters can do further processing with it.
181 <section id="input"><title>Input Decompression</title>
182 <p>The <module>mod_deflate</module> module also provides a filter for
183 decompressing a gzip compressed request body . In order to activate
184 this feature you have to insert the <code>DEFLATE</code> filter into
185 the input filter chain using <directive module="core"
186 >SetInputFilter</directive> or <directive module="mod_mime"
187 >AddInputFilter</directive>, for example:</p>
190 <Location /dav-area><br />
192 SetInputFilter DEFLATE<br />
197 <p>Now if a request contains a <code>Content-Encoding:
198 gzip</code> header, the body will be automatically decompressed.
199 Few browsers have the ability to gzip request bodies. However,
200 some special applications actually do support request
201 compression, for instance some <a
202 href="http://www.webdav.org">WebDAV</a> clients.</p>
204 <note type="warning"><title>Note on Content-Length</title>
205 <p>If you evaluate the request body yourself, <em>don't trust
206 the <code>Content-Length</code> header!</em>
207 The Content-Length header reflects the length of the
208 incoming data from the client and <em>not</em> the byte count of
209 the decompressed data stream.</p>
214 <section id="proxies"><title>Dealing with proxy servers</title>
216 <p>The <module>mod_deflate</module> module sends a <code>Vary:
217 Accept-Encoding</code> HTTP response header to alert proxies that
218 a cached response should be sent only to clients that send the
219 appropriate <code>Accept-Encoding</code> request header. This
220 prevents compressed content from being sent to a client that will
221 not understand it.</p>
223 <p>If you use some special exclusions dependent
224 on, for example, the <code>User-Agent</code> header, you must
225 manually configure an addition to the <code>Vary</code> header
226 to alert proxies of the additional restrictions. For example,
227 in a typical configuration where the addition of the <code>DEFLATE</code>
228 filter depends on the <code>User-Agent</code>, you should add:</p>
231 Header append Vary User-Agent
234 <p>If your decision about compression depends on other information
235 than request headers (<em>e.g.</em> HTTP version), you have to set the
236 <code>Vary</code> header to the value <code>*</code>. This prevents
237 compliant proxies from caching entirely.</p>
239 <example><title>Example</title>
245 <name>DeflateFilterNote</name>
246 <description>Places the compression ratio in a note for logging</description>
247 <syntax>DeflateFilterNote [<var>type</var>] <var>notename</var></syntax>
248 <contextlist><context>server config</context><context>virtual host</context>
250 <compatibility><var>type</var> is available since Apache 2.0.45</compatibility>
253 <p>The <directive>DeflateFilterNote</directive> directive
254 specifies that a note about compression ratios should be attached
255 to the request. The name of the note is the value specified for
256 the directive. You can use that note for statistical purposes by
257 adding the value to your <a href="../logs.html#accesslog"
260 <example><title>Example</title>
261 DeflateFilterNote ratio<br />
263 LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate<br />
264 CustomLog logs/deflate_log deflate
267 <p>If you want to extract more accurate values from your logs, you
268 can use the <var>type</var> argument to specify the type of data
269 left as note for logging. <var>type</var> can be one of:</p>
272 <dt><code>Input</code></dt>
273 <dd>Store the byte count of the filter's input stream in the note.</dd>
275 <dt><code>Output</code></dt>
276 <dd>Store the byte count of the filter's output stream in the note.</dd>
278 <dt><code>Ratio</code></dt>
279 <dd>Store the compression ratio (<code>output/input * 100</code>)
280 in the note. This is the default, if the <var>type</var> argument
284 <p>Thus you may log it this way:</p>
286 <example><title>Accurate Logging</title>
287 DeflateFilterNote Input instream<br />
288 DeflateFilterNote Output outstream<br />
289 DeflateFilterNote Ratio ratio<br />
291 LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate<br />
292 CustomLog logs/deflate_log deflate
295 <seealso><module>mod_log_config</module></seealso>
299 <name>DeflateBufferSize</name>
300 <description>Fragment size to be compressed at one time by zlib</description>
301 <syntax>DeflateBufferSize <var>value</var></syntax>
302 <default>DeflateBufferSize 8096</default>
303 <contextlist><context>server config</context><context>virtual host</context>
307 <p>The <directive>DeflateBufferSize</directive> directive specifies
308 the size in bytes of the fragments that zlib should compress at one
314 <name>DeflateWindowSize</name>
315 <description>Zlib compression window size</description>
316 <syntax>DeflateWindowSize <var>value</var></syntax>
317 <default>DeflateWindowSize 15</default>
318 <contextlist><context>server config</context><context>virtual host</context>
322 <p>The <directive>DeflateWindowSize</directive> directive specifies the
323 zlib compression window size (a value between 1 and 15). Generally, the
324 higher the window size, the higher can the compression ratio be expected.</p>
330 <name>DeflateMemLevel</name>
331 <description>How much memory should be used by zlib for compression</description>
332 <syntax>DeflateMemLevel <var>value</var></syntax>
333 <default>DeflateMemLevel 9</default>
334 <contextlist><context>server config</context><context>virtual host</context>
338 <p>The <directive>DeflateMemLevel</directive> directive specifies
339 how much memory should be used by zlib for compression
340 (a value between 1 and 9).</p>
345 <name>DeflateCompressionLevel</name>
346 <description>How much compression do we apply to the output</description>
347 <syntax>DeflateCompressionLevel <var>value</var></syntax>
348 <default>Zlib's default</default>
349 <contextlist><context>server config</context><context>virtual host</context>
351 <compatibility>This directive is available since Apache 2.0.45</compatibility>
354 <p>The <directive>DeflateCompressionLevel</directive> directive specifies
355 what level of compression should be used, the higher the value,
356 the better the compression, but the more CPU time is required to
358 <p>The value must between 1 (less compression) and 9 (more compression).</p>