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

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