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 configuration that compresses common text-based content types.</p>
43 <example><title>Compress only a few types</title>
44 <highlight language="config">
45 AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript
51 <section id="enable"><title>Enabling Compression</title>
53 <section id="output"><title>Output Compression</title>
54 <p>Compression is implemented by the <code>DEFLATE</code>
55 <a href="../filter.html">filter</a>. The following directive
56 will enable compression for documents in the container where it
59 <highlight language="config">
60 SetOutputFilter DEFLATE
61 SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ no-gzip
64 <p>If you want to restrict the compression to particular MIME types
65 in general, you may use the <directive module="mod_filter"
66 >AddOutputFilterByType</directive> directive. Here is an example of
67 enabling compression only for the html files of the Apache
70 <highlight language="config">
71 <Directory "/your-server-root/manual">
72 AddOutputFilterByType DEFLATE text/html
76 <note><title>Note</title>
77 The <code>DEFLATE</code> filter is always inserted after RESOURCE
78 filters like PHP or SSI. It never touches internal subrequests.
80 <note><title>Note</title>
81 There is a environment variable <code>force-gzip</code>,
82 set via <directive module="mod_env">SetEnv</directive>, which
83 will ignore the accept-encoding setting of your browser and will
84 send compressed output.
88 <section id="inflate"><title>Output Decompression</title>
89 <p>The <module>mod_deflate</module> module also provides a filter for
90 inflating/uncompressing a gzip compressed response body. In order to activate
91 this feature you have to insert the <code>INFLATE</code> filter into
92 the outputfilter chain using <directive module="core"
93 >SetOutputFilter</directive> or <directive module="mod_mime"
94 >AddOutputFilter</directive>, for example:</p>
96 <highlight language="config">
97 <Location /dav-area>
98 ProxyPass http://example.com/
99 SetOutputFilter INFLATE
103 <p>This Example will uncompress gzip'ed output from example.com, so other
104 filters can do further processing with it.
108 <section id="input"><title>Input Decompression</title>
109 <p>The <module>mod_deflate</module> module also provides a filter for
110 decompressing a gzip compressed request body . In order to activate
111 this feature you have to insert the <code>DEFLATE</code> filter into
112 the input filter chain using <directive module="core"
113 >SetInputFilter</directive> or <directive module="mod_mime"
114 >AddInputFilter</directive>, for example:</p>
116 <highlight language="config">
117 <Location /dav-area>
118 SetInputFilter DEFLATE
122 <p>Now if a request contains a <code>Content-Encoding:
123 gzip</code> header, the body will be automatically decompressed.
124 Few browsers have the ability to gzip request bodies. However,
125 some special applications actually do support request
126 compression, for instance some <a
127 href="http://www.webdav.org">WebDAV</a> clients.</p>
129 <note type="warning"><title>Note on Content-Length</title>
130 <p>If you evaluate the request body yourself, <em>don't trust
131 the <code>Content-Length</code> header!</em>
132 The Content-Length header reflects the length of the
133 incoming data from the client and <em>not</em> the byte count of
134 the decompressed data stream.</p>
139 <section id="proxies"><title>Dealing with proxy servers</title>
141 <p>The <module>mod_deflate</module> module sends a <code>Vary:
142 Accept-Encoding</code> HTTP response header to alert proxies that
143 a cached response should be sent only to clients that send the
144 appropriate <code>Accept-Encoding</code> request header. This
145 prevents compressed content from being sent to a client that will
146 not understand it.</p>
148 <p>If you use some special exclusions dependent
149 on, for example, the <code>User-Agent</code> header, you must
150 manually configure an addition to the <code>Vary</code> header
151 to alert proxies of the additional restrictions. For example,
152 in a typical configuration where the addition of the <code>DEFLATE</code>
153 filter depends on the <code>User-Agent</code>, you should add:</p>
155 <highlight language="config">
156 Header append Vary User-Agent
159 <p>If your decision about compression depends on other information
160 than request headers (<em>e.g.</em> HTTP version), you have to set the
161 <code>Vary</code> header to the value <code>*</code>. This prevents
162 compliant proxies from caching entirely.</p>
164 <example><title>Example</title>
165 <highlight language="config">
172 <name>DeflateFilterNote</name>
173 <description>Places the compression ratio in a note for logging</description>
174 <syntax>DeflateFilterNote [<var>type</var>] <var>notename</var></syntax>
175 <contextlist><context>server config</context><context>virtual host</context>
179 <p>The <directive>DeflateFilterNote</directive> directive
180 specifies that a note about compression ratios should be attached
181 to the request. The name of the note is the value specified for
182 the directive. You can use that note for statistical purposes by
183 adding the value to your <a href="../logs.html#accesslog"
186 <example><title>Example</title>
187 <highlight language="config">
188 DeflateFilterNote ratio
190 LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate
191 CustomLog logs/deflate_log deflate
195 <p>If you want to extract more accurate values from your logs, you
196 can use the <var>type</var> argument to specify the type of data
197 left as note for logging. <var>type</var> can be one of:</p>
200 <dt><code>Input</code></dt>
201 <dd>Store the byte count of the filter's input stream in the note.</dd>
203 <dt><code>Output</code></dt>
204 <dd>Store the byte count of the filter's output stream in the note.</dd>
206 <dt><code>Ratio</code></dt>
207 <dd>Store the compression ratio (<code>output/input * 100</code>)
208 in the note. This is the default, if the <var>type</var> argument
212 <p>Thus you may log it this way:</p>
214 <example><title>Accurate Logging</title>
215 <highlight language="config">
216 DeflateFilterNote Input instream
217 DeflateFilterNote Output outstream
218 DeflateFilterNote Ratio ratio
220 LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate
221 CustomLog logs/deflate_log deflate
225 <seealso><module>mod_log_config</module></seealso>
229 <name>DeflateBufferSize</name>
230 <description>Fragment size to be compressed at one time by zlib</description>
231 <syntax>DeflateBufferSize <var>value</var></syntax>
232 <default>DeflateBufferSize 8096</default>
233 <contextlist><context>server config</context><context>virtual host</context>
237 <p>The <directive>DeflateBufferSize</directive> directive specifies
238 the size in bytes of the fragments that zlib should compress at one
244 <name>DeflateWindowSize</name>
245 <description>Zlib compression window size</description>
246 <syntax>DeflateWindowSize <var>value</var></syntax>
247 <default>DeflateWindowSize 15</default>
248 <contextlist><context>server config</context><context>virtual host</context>
252 <p>The <directive>DeflateWindowSize</directive> directive specifies the
253 zlib compression window size (a value between 1 and 15). Generally, the
254 higher the window size, the higher can the compression ratio be expected.</p>
260 <name>DeflateMemLevel</name>
261 <description>How much memory should be used by zlib for compression</description>
262 <syntax>DeflateMemLevel <var>value</var></syntax>
263 <default>DeflateMemLevel 9</default>
264 <contextlist><context>server config</context><context>virtual host</context>
268 <p>The <directive>DeflateMemLevel</directive> directive specifies
269 how much memory should be used by zlib for compression
270 (a value between 1 and 9).</p>
275 <name>DeflateCompressionLevel</name>
276 <description>How much compression do we apply to the output</description>
277 <syntax>DeflateCompressionLevel <var>value</var></syntax>
278 <default>Zlib's default</default>
279 <contextlist><context>server config</context><context>virtual host</context>
283 <p>The <directive>DeflateCompressionLevel</directive> directive specifies
284 what level of compression should be used, the higher the value,
285 the better the compression, but the more CPU time is required to
287 <p>The value must between 1 (less compression) and 9 (more compression).</p>