2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <modulesynopsis metafile="mod_deflate.xml.meta">
6 <name>mod_deflate</name>
7 <description>Compress content before it is delivered to the
9 <status>Extension</status>
10 <sourcefile>mod_deflate.c</sourcefile>
11 <identifier>deflate_module</identifier>
14 <p>The <module>mod_deflate</module> module provides
15 the <code>DEFLATE</code> output filter that allows output from
16 your server to be compressed before being sent to the client over
19 <seealso><a href="../filter.html">Filters</a></seealso>
21 <section id="recommended"><title>Recommended Configuration</title>
22 <p>This is a sample configuration for the impatient. But please take
23 the time and read the sections below for a detailed description!</p>
25 <example><title>Compress only a few types</title>
26 AddOutputFilterByType DEFLATE text/html text/plain text/xml
29 <example><title>Compress everything except images</title>
30 <Location /><br />
33 SetOutputFilter DEFLATE<br />
35 # Netscape 4.x has some problems...<br />
36 BrowserMatch ^Mozilla/4 gzip-only-text/html<br />
38 # Netscape 4.06-4.08 have some more problems<br />
39 BrowserMatch ^Mozilla/4\.0[678] no-gzip<br />
41 # MSIE masquerades as Netscape, but it is fine<br />
42 BrowserMatch \bMSIE !no-gzip !gzip-only-text/html<br />
44 # Don't compress images<br />
45 SetEnvIfNoCase Request_URI \<br />
47 \.(?:gif|jpe?g|png)$ no-gzip dont-vary<br />
50 # Make sure proxies don't deliver the wrong content<br />
51 Header append Vary User-Agent env=!dont-vary<br />
58 <section id="enable"><title>Enabling Compression</title>
60 <section id="output"><title>Output Compression</title>
61 <p>Compression is implemented by the <code>DEFLATE</code>
62 <a href="../filter.html">filter</a>. The following directive
63 will enable compression for documents in the container where it
67 SetOutputFilter DEFLATE
70 <p>Some popular browsers cannot handle compression of all content
71 so you may want to set the <code>gzip-only-text/html</code> note to
72 <code>1</code> to only allow html files to be compressed (see
73 below). If you set this to <em>anything but <code>1</code></em> it
76 <p>If you want to restrict the compression to particular MIME types
77 in general, you may use the <directive module="core"
78 >AddOutputFilterByType</directive> directive. Here is an example of
79 enabling compression only for the html files of the Apache
83 <Directory "/your-server-root/manual"><br />
85 AddOutputFilterByType DEFLATE text/html<br />
90 <p>For browsers that have problems even with compression of all file
91 types, use the <directive module="mod_setenvif"
92 >BrowserMatch</directive> directive to set the <code>no-gzip</code>
93 note for that particular browser so that no compression will be
94 performed. You may combine <code>no-gzip</code> with <code
95 >gzip-only-text/html</code> to get the best results. In that case
96 the former overrides the latter. Take a look at the following
97 excerpt from the <a href="#recommended">configuration example</a>
98 defined in the section above:</p>
101 BrowserMatch ^Mozilla/4 gzip-only-text/html<br />
102 BrowserMatch ^Mozilla/4\.0[678] no-gzip<br />
103 BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
106 <p>At first we probe for a <code>User-Agent</code> string that
107 indicates a Netscape Navigator version of 4.x. These versions
108 cannot handle compression of types other than
109 <code>text/html</code>. The versions 4.06, 4.07 and 4.08 also
110 have problems with decompressing html files. Thus, we completely
111 turn off the deflate filter for them.</p>
113 <p>The third <directive module="mod_setenvif">BrowserMatch</directive>
114 directive fixes the guessed identity of the user agent, because
115 the Microsoft Internet Explorer identifies itself also as "Mozilla/4"
116 but is actually able to handle requested compression. Therefore we
117 match against the additional string "MSIE" (<code>\b</code> means
118 "word boundary") in the <code>User-Agent</code> Header and turn off
119 the restrictions defined before.</p>
121 <note><title>Note</title>
122 The <code>DEFLATE</code> filter is always inserted after RESOURCE
123 filters like PHP or SSI. It never touches internal subrequests.
127 <section id="input"><title>Input Decompression</title>
128 <p>The <module>mod_deflate</module> module also provides a filter for
129 decompressing a gzip compressed request body . In order to activate
130 this feature you have to insert the <code>DEFLATE</code> filter into
131 the input filter chain using <directive module="core"
132 >SetInputFilter</directive> or <directive module="mod_mime"
133 >AddInputFilter</directive>, for example:</p>
136 <Location /dav-area><br />
138 SetInputFilter DEFLATE<br />
143 <p>Now if a request contains a <code>Content-Encoding:
144 gzip</code> header, the body will be automatically decompressed.
145 Few browsers have the ability to gzip request bodies. However,
146 some special applications actually do support request
147 compression, for instance some <a
148 href="http://www.webdav.org">WebDAV</a> clients.</p>
150 <note type="warning"><title>Note on Content-Length</title>
151 <p>If you evaluate the request body yourself, <em>don't trust
152 the <code>Content-Length</code> header!</em>
153 The Content-Length header reflects the length of the
154 incoming data from the client and <em>not</em> the byte count of
155 the decompressed data stream.</p>
160 <section id="proxies"><title>Dealing with proxy servers</title>
162 <p>The <module>mod_deflate</module> module sends a <code>Vary:
163 Accept-Encoding</code> HTTP response header to alert proxies that
164 a cached response should be sent only to clients that send the
165 appropriate <code>Accept-Encoding</code> request header. This
166 prevents compressed content from being sent to a client that will
167 not understand it.</p>
169 <p>If you use some special exclusions dependent
170 on, for example, the <code>User-Agent</code> header, you must
171 manually configure an addition to the <code>Vary</code> header
172 to alert proxies of the additional restrictions. For example,
173 in a typical configuration where the addition of the <code>DEFLATE</code>
174 filter depends on the <code>User-Agent</code>, you should add:</p>
177 Header append Vary User-Agent
180 <p>If your decision about compression depends on other information
181 than request headers (<em>e.g.</em> HTTP version), you have to set the
182 <code>Vary</code> header to the value <code>*</code>. This prevents
183 compliant proxies from caching entirely.</p>
185 <example><title>Example</title>
191 <name>DeflateFilterNote</name>
192 <description>Places the compression ratio in a note for logging</description>
193 <syntax>DeflateFilterNote [<var>type</var>] <var>notename</var></syntax>
194 <contextlist><context>server config</context><context>virtual host</context>
196 <compatibility><var>type</var> is available since Apache 2.0.45</compatibility>
199 <p>The <directive>DeflateFilterNote</directive> directive
200 specifies that a note about compression ratios should be attached
201 to the request. The name of the note is the value specified for
202 the directive. You can use that note for statistical purposes by
203 adding the value to your <a href="../logs.html#accesslog"
206 <example><title>Example</title>
207 DeflateFilterNote ratio<br />
209 LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate<br />
210 CustomLog logs/deflate_log deflate
213 <p>If you want to extract more accurate values from your logs, you
214 can use the <var>type</var> argument to specify the type of data
215 left as note for logging. <var>type</var> can be one of:</p>
218 <dt><code>Input</code></dt>
219 <dd>Store the byte count of the filter's input stream in the note.</dd>
221 <dt><code>Output</code></dt>
222 <dd>Store the byte count of the filter's output stream in the note.</dd>
224 <dt><code>Ratio</code></dt>
225 <dd>Store the compression ratio (<code>output/input * 100</code>)
226 in the note. This is the default, if the <var>type</var> argument
230 <p>Thus you may log it this way:</p>
232 <example><title>Accurate Logging</title>
233 DeflateFilterNote Input instream<br />
234 DeflateFilterNote Output outstream<br />
235 DeflateFilterNote Ratio ratio<br />
237 LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate<br />
238 CustomLog logs/deflate_log deflate
241 <seealso><module>mod_log_config</module></seealso>
245 <name>DeflateBufferSize</name>
246 <description>Fragment size to be compressed at one time by zlib</description>
247 <syntax>DeflateBufferSize <var>value</var></syntax>
248 <default>DeflateBufferSize 8096</default>
249 <contextlist><context>server config</context><context>virtual host</context>
253 <p>The <directive>DeflateBufferSize</directive> directive specifies
254 the size in bytes of the fragments that zlib should compress at one
260 <name>DeflateWindowSize</name>
261 <description>Zlib compression window size</description>
262 <syntax>DeflateWindowSize <var>value</var></syntax>
263 <default>DeflateWindowSize 15</default>
264 <contextlist><context>server config</context><context>virtual host</context>
268 <p>The <directive>DeflateWindowSize</directive> directive specifies the
269 zlib compression window size (a value between 1 and 15). Generally, the
270 higher the window size, the higher can the compression ratio be expected.</p>
276 <name>DeflateMemLevel</name>
277 <description>How much memory should be used by zlib for compression</description>
278 <syntax>DeflateMemLevel <var>value</var></syntax>
279 <default>DeflateMemLevel 9</default>
280 <contextlist><context>server config</context><context>virtual host</context>
284 <p>The <directive>DeflateMemLevel</directive> directive specifies
285 how much memory should be used by zlib for compression
286 (a value between 1 and 9).</p>
291 <name>DeflateCompressionLevel</name>
292 <description>How much compression do we apply to the output</description>
293 <syntax>DeflateCompressionLevel<var>value</var></syntax>
294 <default>Zlib's default</default>
295 <contextlist><context>server config</context><context>virtual host</context>
297 <compatibility>This directive is available since Apache 2.0.45</compatibility>
300 <p>The <directive>DeflateCompressionLevel</directive> directive specifies
301 what level of compression should be used, the higher the value,
302 the better the compression, but the more CPU time is required to
304 <p>The value must between 1 (less compression) and 9 (more compression).</p>