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 <p>This is a simple sample configuration for the impatient.</p>
43 <example><title>Compress only a few types</title>
44 <highlight language="config">
45 AddOutputFilterByType DEFLATE text/html text/plain text/xml
49 <p>The following configuration, while resulting in more compressed content,
50 is also much more complicated. Do not use this unless you fully understand
51 all the configuration details.</p>
53 <example><title>Compress everything except images</title>
54 <highlight language="config">
57 SetOutputFilter DEFLATE
59 # Netscape 4.x has some problems...
60 BrowserMatch ^Mozilla/4 gzip-only-text/html
62 # Netscape 4.06-4.08 have some more problems
63 BrowserMatch ^Mozilla/4\.0[678] no-gzip
65 # MSIE masquerades as Netscape, but it is fine
66 BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
67 # Don't compress images
68 SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ no-gzip dont-vary
70 # Make sure proxies don't deliver the wrong content
71 Header append Vary User-Agent env=!dont-vary
78 <section id="enable"><title>Enabling Compression</title>
80 <section id="output"><title>Output Compression</title>
81 <p>Compression is implemented by the <code>DEFLATE</code>
82 <a href="../filter.html">filter</a>. The following directive
83 will enable compression for documents in the container where it
86 <highlight language="config">
87 SetOutputFilter DEFLATE
90 <p>Some popular browsers cannot handle compression of all content
91 so you may want to set the <code>gzip-only-text/html</code> note to
92 <code>1</code> to only allow html files to be compressed (see
93 below). If you set this to <em>anything but <code>1</code></em> it
96 <p>If you want to restrict the compression to particular MIME types
97 in general, you may use the <directive module="mod_filter"
98 >AddOutputFilterByType</directive> directive. Here is an example of
99 enabling compression only for the html files of the Apache
102 <highlight language="config">
103 <Directory "/your-server-root/manual">
104 AddOutputFilterByType DEFLATE text/html
108 <p>For browsers that have problems even with compression of all file
109 types, use the <directive module="mod_setenvif"
110 >BrowserMatch</directive> directive to set the <code>no-gzip</code>
111 note for that particular browser so that no compression will be
112 performed. You may combine <code>no-gzip</code> with <code
113 >gzip-only-text/html</code> to get the best results. In that case
114 the former overrides the latter. Take a look at the following
115 excerpt from the <a href="#recommended">configuration example</a>
116 defined in the section above:</p>
118 <highlight language="config">
119 BrowserMatch ^Mozilla/4 gzip-only-text/html
120 BrowserMatch ^Mozilla/4\.0[678] no-gzip
121 BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
124 <p>At first we probe for a <code>User-Agent</code> string that
125 indicates a Netscape Navigator version of 4.x. These versions
126 cannot handle compression of types other than
127 <code>text/html</code>. The versions 4.06, 4.07 and 4.08 also
128 have problems with decompressing html files. Thus, we completely
129 turn off the deflate filter for them.</p>
131 <p>The third <directive module="mod_setenvif">BrowserMatch</directive>
132 directive fixes the guessed identity of the user agent, because
133 the Microsoft Internet Explorer identifies itself also as "Mozilla/4"
134 but is actually able to handle requested compression. Therefore we
135 match against the additional string "MSIE" (<code>\b</code> means
136 "word boundary") in the <code>User-Agent</code> Header and turn off
137 the restrictions defined before.</p>
139 <note><title>Note</title>
140 The <code>DEFLATE</code> filter is always inserted after RESOURCE
141 filters like PHP or SSI. It never touches internal subrequests.
143 <note><title>Note</title>
144 There is a environment variable <code>force-gzip</code>,
145 set via <directive module="mod_env">SetEnv</directive>, which
146 will ignore the accept-encoding setting of your browser and will
147 send compressed output.
151 <section id="inflate"><title>Output Decompression</title>
152 <p>The <module>mod_deflate</module> module also provides a filter for
153 inflating/uncompressing a gzip compressed response body. In order to activate
154 this feature you have to insert the <code>INFLATE</code> filter into
155 the outputfilter chain using <directive module="core"
156 >SetOutputFilter</directive> or <directive module="mod_mime"
157 >AddOutputFilter</directive>, for example:</p>
159 <highlight language="config">
160 <Location /dav-area>
161 ProxyPass http://example.com/
162 SetOutputFilter INFLATE
166 <p>This Example will uncompress gzip'ed output from example.com, so other
167 filters can do further processing with it.
171 <section id="input"><title>Input Decompression</title>
172 <p>The <module>mod_deflate</module> module also provides a filter for
173 decompressing a gzip compressed request body . In order to activate
174 this feature you have to insert the <code>DEFLATE</code> filter into
175 the input filter chain using <directive module="core"
176 >SetInputFilter</directive> or <directive module="mod_mime"
177 >AddInputFilter</directive>, for example:</p>
179 <highlight language="config">
180 <Location /dav-area>
181 SetInputFilter DEFLATE
185 <p>Now if a request contains a <code>Content-Encoding:
186 gzip</code> header, the body will be automatically decompressed.
187 Few browsers have the ability to gzip request bodies. However,
188 some special applications actually do support request
189 compression, for instance some <a
190 href="http://www.webdav.org">WebDAV</a> clients.</p>
192 <note type="warning"><title>Note on Content-Length</title>
193 <p>If you evaluate the request body yourself, <em>don't trust
194 the <code>Content-Length</code> header!</em>
195 The Content-Length header reflects the length of the
196 incoming data from the client and <em>not</em> the byte count of
197 the decompressed data stream.</p>
202 <section id="proxies"><title>Dealing with proxy servers</title>
204 <p>The <module>mod_deflate</module> module sends a <code>Vary:
205 Accept-Encoding</code> HTTP response header to alert proxies that
206 a cached response should be sent only to clients that send the
207 appropriate <code>Accept-Encoding</code> request header. This
208 prevents compressed content from being sent to a client that will
209 not understand it.</p>
211 <p>If you use some special exclusions dependent
212 on, for example, the <code>User-Agent</code> header, you must
213 manually configure an addition to the <code>Vary</code> header
214 to alert proxies of the additional restrictions. For example,
215 in a typical configuration where the addition of the <code>DEFLATE</code>
216 filter depends on the <code>User-Agent</code>, you should add:</p>
218 <highlight language="config">
219 Header append Vary User-Agent
222 <p>If your decision about compression depends on other information
223 than request headers (<em>e.g.</em> HTTP version), you have to set the
224 <code>Vary</code> header to the value <code>*</code>. This prevents
225 compliant proxies from caching entirely.</p>
227 <example><title>Example</title>
228 <highlight language="config">
235 <name>DeflateFilterNote</name>
236 <description>Places the compression ratio in a note for logging</description>
237 <syntax>DeflateFilterNote [<var>type</var>] <var>notename</var></syntax>
238 <contextlist><context>server config</context><context>virtual host</context>
242 <p>The <directive>DeflateFilterNote</directive> directive
243 specifies that a note about compression ratios should be attached
244 to the request. The name of the note is the value specified for
245 the directive. You can use that note for statistical purposes by
246 adding the value to your <a href="../logs.html#accesslog"
249 <example><title>Example</title>
250 <highlight language="config">
251 DeflateFilterNote ratio
253 LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate
254 CustomLog logs/deflate_log deflate
258 <p>If you want to extract more accurate values from your logs, you
259 can use the <var>type</var> argument to specify the type of data
260 left as note for logging. <var>type</var> can be one of:</p>
263 <dt><code>Input</code></dt>
264 <dd>Store the byte count of the filter's input stream in the note.</dd>
266 <dt><code>Output</code></dt>
267 <dd>Store the byte count of the filter's output stream in the note.</dd>
269 <dt><code>Ratio</code></dt>
270 <dd>Store the compression ratio (<code>output/input * 100</code>)
271 in the note. This is the default, if the <var>type</var> argument
275 <p>Thus you may log it this way:</p>
277 <example><title>Accurate Logging</title>
278 <highlight language="config">
279 DeflateFilterNote Input instream
280 DeflateFilterNote Output outstream
281 DeflateFilterNote Ratio ratio
283 LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate
284 CustomLog logs/deflate_log deflate
288 <seealso><module>mod_log_config</module></seealso>
292 <name>DeflateBufferSize</name>
293 <description>Fragment size to be compressed at one time by zlib</description>
294 <syntax>DeflateBufferSize <var>value</var></syntax>
295 <default>DeflateBufferSize 8096</default>
296 <contextlist><context>server config</context><context>virtual host</context>
300 <p>The <directive>DeflateBufferSize</directive> directive specifies
301 the size in bytes of the fragments that zlib should compress at one
307 <name>DeflateWindowSize</name>
308 <description>Zlib compression window size</description>
309 <syntax>DeflateWindowSize <var>value</var></syntax>
310 <default>DeflateWindowSize 15</default>
311 <contextlist><context>server config</context><context>virtual host</context>
315 <p>The <directive>DeflateWindowSize</directive> directive specifies the
316 zlib compression window size (a value between 1 and 15). Generally, the
317 higher the window size, the higher can the compression ratio be expected.</p>
323 <name>DeflateMemLevel</name>
324 <description>How much memory should be used by zlib for compression</description>
325 <syntax>DeflateMemLevel <var>value</var></syntax>
326 <default>DeflateMemLevel 9</default>
327 <contextlist><context>server config</context><context>virtual host</context>
331 <p>The <directive>DeflateMemLevel</directive> directive specifies
332 how much memory should be used by zlib for compression
333 (a value between 1 and 9).</p>
338 <name>DeflateCompressionLevel</name>
339 <description>How much compression do we apply to the output</description>
340 <syntax>DeflateCompressionLevel <var>value</var></syntax>
341 <default>Zlib's default</default>
342 <contextlist><context>server config</context><context>virtual host</context>
346 <p>The <directive>DeflateCompressionLevel</directive> directive specifies
347 what level of compression should be used, the higher the value,
348 the better the compression, but the more CPU time is required to
350 <p>The value must between 1 (less compression) and 9 (more compression).</p>