granicus.if.org Git - apache/blob - docs/manual/mod/mod_deflate.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Copyright 2002-2005 The Apache Software Foundation or its licensors,
   8                      as applicable.
   9
  10  Licensed under the Apache License, Version 2.0 (the "License");
  11  you may not use this file except in compliance with the License.
  12  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  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.
  21 -->
  22
  23 <modulesynopsis metafile="mod_deflate.xml.meta">
  24
  25 <name>mod_deflate</name>
  26 <description>Compress content before it is delivered to the
  27 client</description>
  28 <status>Extension</status>
  29 <sourcefile>mod_deflate.c</sourcefile>
  30 <identifier>deflate_module</identifier>
  31
  32 <summary>
  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
  36     the network.</p>
  37 </summary>
  38 <seealso><a href="../filter.html">Filters</a></seealso>
  39
  40 <section id="recommended"><title>Sample Configurations</title>
  41     <p>This is a simple sample configuration for the impatient.</p>
  42
  43     <example><title>Compress only a few types</title>
  44       AddOutputFilterByType DEFLATE text/html text/plain text/xml
  45     </example>
  46
  47     <p>The following configuration, while resulting in more compressed content,
  48     is also much more complicated.  Do not use this unless you fully understand
  49     all the configuration details.</p>
  50
  51     <example><title>Compress everything except images</title>
  52       &lt;Location /&gt;<br />
  53       <indent>
  54         # Insert filter<br />
  55         SetOutputFilter DEFLATE<br />
  56         <br />
  57         # Netscape 4.x has some problems...<br />
  58         BrowserMatch ^Mozilla/4         gzip-only-text/html<br />
  59         <br />
  60         # Netscape 4.06-4.08 have some more problems<br />
  61         BrowserMatch ^Mozilla/4\.0[678] no-gzip<br />
  62         <br />
  63         # MSIE masquerades as Netscape, but it is fine<br />
  64         # BrowserMatch \bMSIE             !no-gzip !gzip-only-text/html<br />
  65         <br />
  66         # NOTE: Due to a bug in mod_setenvif up to Apache 2.0.48<br />
  67         # the above regex won't work. You can use the following<br />
  68         # workaround to get the desired effect:<br />
  69         BrowserMatch \bMSI[E]           !no-gzip !gzip-only-text/html<br />
  70         <br />
  71         # Don't compress images<br />
  72         SetEnvIfNoCase Request_URI \<br />
  73         <indent>
  74           \.(?:gif|jpe?g|png)$ no-gzip dont-vary<br />
  75         </indent>
  76         <br />
  77         # Make sure proxies don't deliver the wrong content<br />
  78         Header append Vary User-Agent env=!dont-vary<br />
  79       </indent>
  80       &lt;/Location&gt;
  81     </example>
  82
  83 </section>
  84
  85 <section id="enable"><title>Enabling Compression</title>
  86
  87     <section id="output"><title>Output Compression</title>
  88       <p>Compression is implemented by the <code>DEFLATE</code>
  89       <a href="../filter.html">filter</a>. The following directive
  90       will enable compression for documents in the container where it
  91       is placed:</p>
  92
  93       <example>
  94         SetOutputFilter DEFLATE
  95       </example>
  96
  97       <p>Some popular browsers cannot handle compression of all content
  98       so you may want to set the <code>gzip-only-text/html</code> note to
  99       <code>1</code> to only allow html files to be compressed (see
 100       below). If you set this to <em>anything but <code>1</code></em> it
 101       will be ignored.</p>
 102
 103       <p>If you want to restrict the compression to particular MIME types
 104       in general, you may use the <directive module="core"
 105       >AddOutputFilterByType</directive> directive. Here is an example of
 106       enabling compression only for the html files of the Apache
 107       documentation:</p>
 108
 109       <example>
 110         &lt;Directory "/your-server-root/manual"&gt;<br />
 111         <indent>
 112           AddOutputFilterByType DEFLATE text/html<br />
 113         </indent>
 114         &lt;/Directory&gt;
 115       </example>
 116
 117       <p>For browsers that have problems even with compression of all file
 118       types, use the <directive module="mod_setenvif"
 119       >BrowserMatch</directive> directive to set the <code>no-gzip</code>
 120       note for that particular browser so that no compression will be
 121       performed. You may combine <code>no-gzip</code> with <code
 122       >gzip-only-text/html</code> to get the best results. In that case
 123       the former overrides the latter. Take a look at the following
 124       excerpt from the <a href="#recommended">configuration example</a>
 125       defined in the section above:</p>
 126
 127       <example>
 128         BrowserMatch ^Mozilla/4         gzip-only-text/html<br />
 129         BrowserMatch ^Mozilla/4\.0[678] no-gzip<br />
 130         BrowserMatch \bMSIE             !no-gzip !gzip-only-text/html
 131       </example>
 132
 133       <p>At first we probe for a <code>User-Agent</code> string that
 134       indicates a Netscape Navigator version of 4.x. These versions
 135       cannot handle compression of types other than
 136       <code>text/html</code>. The versions 4.06, 4.07 and 4.08 also
 137       have problems with decompressing html files. Thus, we completely
 138       turn off the deflate filter for them.</p>
 139
 140       <p>The third <directive module="mod_setenvif">BrowserMatch</directive>
 141       directive fixes the guessed identity of the user agent, because
 142       the Microsoft Internet Explorer identifies itself also as "Mozilla/4"
 143       but is actually able to handle requested compression. Therefore we
 144       match against the additional string "MSIE" (<code>\b</code> means
 145       "word boundary") in the <code>User-Agent</code> Header and turn off
 146       the restrictions defined before.</p>
 147
 148       <note><title>Note</title>
 149         The <code>DEFLATE</code> filter is always inserted after RESOURCE
 150         filters like PHP or SSI. It never touches internal subrequests.
 151       </note>
 152       <note><title>Note</title>
 153         There is a environment variable <code>force-gzip</code>,
 154         set via <directive module="core">SetEnv</directive>, which
 155         will ignore the accept-encoding setting of your browser and will
 156         send compressed output.
 157       </note>
 158
 159     </section>
 160     <section id="inflate"><title>Output Decompression</title>
 161       <p>The <module>mod_deflate</module> module also provides a filter for
 162       inflating/uncompressing a gzip compressed response body. In order to activate
 163       this feature you have to insert the <code>INFLATE</code> filter into
 164       the outputfilter chain using <directive module="core"
 165       >SetOutputFilter</directive> or <directive module="mod_mime"
 166       >AddOutputFilter</directive>, for example:</p>
 167
 168       <example>
 169         &lt;Location /dav-area&gt;<br />
 170         <indent>
 171           ProxyPass http://example.com/<br />
 172           SetOutputFilter INFLATE<br />
 173         </indent>
 174         &lt;/Location&gt;
 175       </example>
 176
 177       <p>This Example will uncompress gzip'ed output from example.com, so other
 178       filters can do further processing with it.
 179       </p>
 180
 181     </section>
 182     <section id="input"><title>Input Decompression</title>
 183       <p>The <module>mod_deflate</module> module also provides a filter for
 184       decompressing a gzip compressed request body . In order to activate
 185       this feature you have to insert the <code>DEFLATE</code> filter into
 186       the input filter chain using <directive module="core"
 187       >SetInputFilter</directive> or <directive module="mod_mime"
 188       >AddInputFilter</directive>, for example:</p>
 189
 190       <example>
 191         &lt;Location /dav-area&gt;<br />
 192         <indent>
 193           SetInputFilter DEFLATE<br />
 194         </indent>
 195         &lt;/Location&gt;
 196       </example>
 197
 198       <p>Now if a request contains a <code>Content-Encoding:
 199       gzip</code> header, the body will be automatically decompressed.
 200       Few browsers have the ability to gzip request bodies. However,
 201       some special applications actually do support request
 202       compression, for instance some <a
 203       href="http://www.webdav.org">WebDAV</a> clients.</p>
 204
 205       <note type="warning"><title>Note on Content-Length</title>
 206         <p>If you evaluate the request body yourself, <em>don't trust
 207         the <code>Content-Length</code> header!</em>
 208         The Content-Length header reflects the length of the
 209         incoming data from the client and <em>not</em> the byte count of
 210         the decompressed data stream.</p>
 211       </note>
 212     </section>
 213 </section>
 214
 215 <section id="proxies"><title>Dealing with proxy servers</title>
 216
 217     <p>The <module>mod_deflate</module> module sends a <code>Vary:
 218     Accept-Encoding</code> HTTP response header to alert proxies that
 219     a cached response should be sent only to clients that send the
 220     appropriate <code>Accept-Encoding</code> request header.  This
 221     prevents compressed content from being sent to a client that will
 222     not understand it.</p>
 223
 224     <p>If you use some special exclusions dependent
 225     on, for example, the <code>User-Agent</code> header, you must
 226     manually configure an addition to the <code>Vary</code> header
 227     to alert proxies of the additional restrictions.  For example,
 228     in a typical configuration where the addition of the <code>DEFLATE</code>
 229     filter depends on the <code>User-Agent</code>, you should add:</p>
 230
 231     <example>
 232       Header append Vary User-Agent
 233     </example>
 234
 235     <p>If your decision about compression depends on other information
 236     than request headers (<em>e.g.</em> HTTP version), you have to set the
 237     <code>Vary</code> header to the value <code>*</code>. This prevents
 238     compliant proxies from caching entirely.</p>
 239
 240     <example><title>Example</title>
 241       Header set Vary *
 242     </example>
 243 </section>
 244
 245 <directivesynopsis>
 246 <name>DeflateFilterNote</name>
 247 <description>Places the compression ratio in a note for logging</description>
 248 <syntax>DeflateFilterNote [<var>type</var>] <var>notename</var></syntax>
 249 <contextlist><context>server config</context><context>virtual host</context>
 250 </contextlist>
 251 <compatibility><var>type</var> is available since Apache 2.0.45</compatibility>
 252
 253 <usage>
 254     <p>The <directive>DeflateFilterNote</directive> directive
 255     specifies that a note about compression ratios should be attached
 256     to the request. The name of the note is the value specified for
 257     the directive. You can use that note for statistical purposes by
 258     adding the value to your <a href="../logs.html#accesslog"
 259     >access log</a>.</p>
 260
 261     <example><title>Example</title>
 262       DeflateFilterNote ratio<br />
 263       <br />
 264       LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate<br />
 265       CustomLog logs/deflate_log deflate
 266     </example>
 267
 268     <p>If you want to extract more accurate values from your logs, you
 269     can use the <var>type</var> argument to specify the type of data
 270     left as note for logging. <var>type</var> can be one of:</p>
 271
 272     <dl>
 273       <dt><code>Input</code></dt>
 274       <dd>Store the byte count of the filter's input stream in the note.</dd>
 275
 276       <dt><code>Output</code></dt>
 277       <dd>Store the byte count of the filter's output stream in the note.</dd>
 278
 279       <dt><code>Ratio</code></dt>
 280       <dd>Store the compression ratio (<code>output/input * 100</code>)
 281       in the note. This is the default, if the <var>type</var> argument
 282       is omitted.</dd>
 283     </dl>
 284
 285     <p>Thus you may log it this way:</p>
 286
 287     <example><title>Accurate Logging</title>
 288       DeflateFilterNote Input instream<br />
 289       DeflateFilterNote Output outstream<br />
 290       DeflateFilterNote Ratio ratio<br />
 291       <br />
 292       LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate<br />
 293       CustomLog logs/deflate_log deflate
 294     </example>
 295 </usage>
 296 <seealso><module>mod_log_config</module></seealso>
 297 </directivesynopsis>
 298
 299 <directivesynopsis>
 300 <name>DeflateBufferSize</name>
 301 <description>Fragment size to be compressed at one time by zlib</description>
 302 <syntax>DeflateBufferSize <var>value</var></syntax>
 303 <default>DeflateBufferSize 8096</default>
 304 <contextlist><context>server config</context><context>virtual host</context>
 305 </contextlist>
 306
 307 <usage>
 308     <p>The <directive>DeflateBufferSize</directive> directive specifies
 309     the size in bytes of the fragments that zlib should compress at one
 310     time.</p>
 311 </usage>
 312 </directivesynopsis>
 313
 314 <directivesynopsis>
 315 <name>DeflateWindowSize</name>
 316 <description>Zlib compression window size</description>
 317 <syntax>DeflateWindowSize <var>value</var></syntax>
 318 <default>DeflateWindowSize 15</default>
 319 <contextlist><context>server config</context><context>virtual host</context>
 320 </contextlist>
 321
 322 <usage>
 323     <p>The <directive>DeflateWindowSize</directive> directive specifies the
 324     zlib compression window size (a value between 1 and 15). Generally, the
 325     higher the window size, the higher can the compression ratio be expected.</p>
 326 </usage>
 327 </directivesynopsis>
 328
 329 <directivesynopsis>
 330
 331 <name>DeflateMemLevel</name>
 332 <description>How much memory should be used by zlib for compression</description>
 333 <syntax>DeflateMemLevel <var>value</var></syntax>
 334 <default>DeflateMemLevel 9</default>
 335 <contextlist><context>server config</context><context>virtual host</context>
 336 </contextlist>
 337
 338 <usage>
 339     <p>The <directive>DeflateMemLevel</directive> directive specifies
 340     how much memory should be used by zlib for compression
 341     (a value between 1 and 9).</p>
 342 </usage>
 343 </directivesynopsis>
 344
 345 <directivesynopsis>
 346 <name>DeflateCompressionLevel</name>
 347 <description>How much compression do we apply to the output</description>
 348 <syntax>DeflateCompressionLevel <var>value</var></syntax>
 349 <default>Zlib's default</default>
 350 <contextlist><context>server config</context><context>virtual host</context>
 351 </contextlist>
 352 <compatibility>This directive is available since Apache 2.0.45</compatibility>
 353
 354 <usage>
 355     <p>The <directive>DeflateCompressionLevel</directive> directive specifies
 356         what level of compression should be used, the higher the value,
 357         the better the compression, but the more CPU time is required to
 358         achieve this.</p>
 359     <p>The value must between 1 (less compression) and 9 (more compression).</p>
 360 </usage>
 361 </directivesynopsis>
 362
 363
 364 </modulesynopsis>
 365