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">&nbsp;en&nbsp;</a> | <a href="../ja/mod/mod_deflate.html">&nbsp;ja&nbsp;</a> | <a href="../ko/mod/mod_deflate.html">&nbsp;ko&nbsp;</a></p>
  25 </div>
  26 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Compress content before it is delivered to the
  27 client</td></tr>
  28 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  29 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>deflate_module</td></tr>
  30 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_deflate.c</td></tr></table>
  31 <h3>Summary</h3>
  32
  33     <p>The <code class="module"><a href="../mod/mod_deflate.html">mod_deflate</a></code> 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 </div>
  38 <div id="quickview"><h3 class="directives">Directives</h3>
  39 <ul id="toc">
  40 <li><img alt="" src="../images/down.gif" /> <a href="#deflatebuffersize">DeflateBufferSize</a></li>
  41 <li><img alt="" src="../images/down.gif" /> <a href="#deflatecompressionlevel">DeflateCompressionLevel</a></li>
  42 <li><img alt="" src="../images/down.gif" /> <a href="#deflatefilternote">DeflateFilterNote</a></li>
  43 <li><img alt="" src="../images/down.gif" /> <a href="#deflatememlevel">DeflateMemLevel</a></li>
  44 <li><img alt="" src="../images/down.gif" /> <a href="#deflatewindowsize">DeflateWindowSize</a></li>
  45 </ul>
  46 <h3>Topics</h3>
  47 <ul id="topics">
  48 <li><img alt="" src="../images/down.gif" /> <a href="#recommended">Recommended Configuration</a></li>
  49 <li><img alt="" src="../images/down.gif" /> <a href="#enable">Enabling Compression</a></li>
  50 <li><img alt="" src="../images/down.gif" /> <a href="#proxies">Dealing with proxy servers</a></li>
  51 </ul><h3>See also</h3>
  52 <ul class="seealso">
  53 <li><a href="../filter.html">Filters</a></li>
  54 </ul></div>
  55 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  56 <div class="section">
  57 <h2><a name="recommended" id="recommended">Recommended Configuration</a></h2>
  58     <p>This is a sample configuration for the impatient. But please take
  59     the time and read the sections below for a detailed description!</p>
  60
  61     <div class="example"><h3>Compress only a few types</h3><p><code>
  62       AddOutputFilterByType DEFLATE text/html text/plain text/xml
  63     </code></p></div>
  64
  65     <div class="example"><h3>Compress everything except images</h3><p><code>
  66       &lt;Location /&gt;<br />
  67       <span class="indent">
  68         # Insert filter<br />
  69         SetOutputFilter DEFLATE<br />
  70         <br />
  71         # Netscape 4.x has some problems...<br />
  72         BrowserMatch ^Mozilla/4         gzip-only-text/html<br />
  73         <br />
  74         # Netscape 4.06-4.08 have some more problems<br />
  75         BrowserMatch ^Mozilla/4\.0[678] no-gzip<br />
  76         <br />
  77         # MSIE masquerades as Netscape, but it is fine<br />
  78         BrowserMatch \bMSIE             !no-gzip !gzip-only-text/html<br />
  79         <br />
  80         # Don't compress images<br />
  81         SetEnvIfNoCase Request_URI \<br />
  82         <span class="indent">
  83           \.(?:gif|jpe?g|png)$ no-gzip dont-vary<br />
  84         </span>
  85         <br />
  86         # Make sure proxies don't deliver the wrong content<br />
  87         Header append Vary User-Agent env=!dont-vary<br />
  88       </span>
  89       &lt;/Location&gt;
  90     </code></p></div>
  91
  92 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  93 <div class="section">
  94 <h2><a name="enable" id="enable">Enabling Compression</a></h2>
  95
  96     <h3><a name="output" id="output">Output Compression</a></h3>
  97       <p>Compression is implemented by the <code>DEFLATE</code>
  98       <a href="../filter.html">filter</a>. The following directive
  99       will enable compression for documents in the container where it
 100       is placed:</p>
 101
 102       <div class="example"><p><code>
 103         SetOutputFilter DEFLATE
 104       </code></p></div>
 105
 106       <p>Some popular browsers cannot handle compression of all content
 107       so you may want to set the <code>gzip-only-text/html</code> note to
 108       <code>1</code> to only allow html files to be compressed (see
 109       below). If you set this to <em>anything but <code>1</code></em> it
 110       will be ignored.</p>
 111
 112       <p>If you want to restrict the compression to particular MIME types
 113       in general, you may use the <code class="directive"><a href="../mod/core.html#addoutputfilterbytype">AddOutputFilterByType</a></code> directive. Here is an example of
 114       enabling compression only for the html files of the Apache
 115       documentation:</p>
 116
 117       <div class="example"><p><code>
 118         &lt;Directory "/your-server-root/manual"&gt;<br />
 119         <span class="indent">
 120           AddOutputFilterByType DEFLATE text/html<br />
 121         </span>
 122         &lt;/Directory&gt;
 123       </code></p></div>
 124
 125       <p>For browsers that have problems even with compression of all file
 126       types, use the <code class="directive"><a href="../mod/mod_setenvif.html#browsermatch">BrowserMatch</a></code> directive to set the <code>no-gzip</code>
 127       note for that particular browser so that no compression will be
 128       performed. You may combine <code>no-gzip</code> with <code>gzip-only-text/html</code> to get the best results. In that case
 129       the former overrides the latter. Take a look at the following
 130       excerpt from the <a href="#recommended">configuration example</a>
 131       defined in the section above:</p>
 132
 133       <div class="example"><p><code>
 134         BrowserMatch ^Mozilla/4         gzip-only-text/html<br />
 135         BrowserMatch ^Mozilla/4\.0[678] no-gzip<br />
 136         BrowserMatch \bMSIE             !no-gzip !gzip-only-text/html
 137       </code></p></div>
 138
 139       <p>At first we probe for a <code>User-Agent</code> string that
 140       indicates a Netscape Navigator version of 4.x. These versions
 141       cannot handle compression of types other than
 142       <code>text/html</code>. The versions 4.06, 4.07 and 4.08 also
 143       have problems with decompressing html files. Thus, we completely
 144       turn off the deflate filter for them.</p>
 145
 146       <p>The third <code class="directive"><a href="../mod/mod_setenvif.html#browsermatch">BrowserMatch</a></code>
 147       directive fixes the guessed identity of the user agent, because
 148       the Microsoft Internet Explorer identifies itself also as "Mozilla/4"
 149       but is actually able to handle requested compression. Therefore we
 150       match against the additional string "MSIE" (<code>\b</code> means
 151       "word boundary") in the <code>User-Agent</code> Header and turn off
 152       the restrictions defined before.</p>
 153
 154       <div class="note"><h3>Note</h3>
 155         The <code>DEFLATE</code> filter is always inserted after RESOURCE
 156         filters like PHP or SSI. It never touches internal subrequests.
 157       </div>
 158
 159
 160     <h3><a name="input" id="input">Input Decompression</a></h3>
 161       <p>The <code class="module"><a href="../mod/mod_deflate.html">mod_deflate</a></code> module also provides a filter for
 162       decompressing a gzip compressed request body . In order to activate
 163       this feature you have to insert the <code>DEFLATE</code> filter into
 164       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>
 165
 166       <div class="example"><p><code>
 167         &lt;Location /dav-area&gt;<br />
 168         <span class="indent">
 169           SetInputFilter DEFLATE<br />
 170         </span>
 171         &lt;/Location&gt;
 172       </code></p></div>
 173
 174       <p>Now if a request contains a <code>Content-Encoding:
 175       gzip</code> header, the body will be automatically decompressed.
 176       Few browsers have the ability to gzip request bodies. However,
 177       some special applications actually do support request
 178       compression, for instance some <a href="http://www.webdav.org">WebDAV</a> clients.</p>
 179
 180       <div class="warning"><h3>Note on Content-Length</h3>
 181         <p>If you evaluate the request body yourself, <em>don't trust
 182         the <code>Content-Length</code> header!</em>
 183         The Content-Length header reflects the length of the
 184         incoming data from the client and <em>not</em> the byte count of
 185         the decompressed data stream.</p>
 186       </div>
 187
 188 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 189 <div class="section">
 190 <h2><a name="proxies" id="proxies">Dealing with proxy servers</a></h2>
 191
 192     <p>The <code class="module"><a href="../mod/mod_deflate.html">mod_deflate</a></code> module sends a <code>Vary:
 193     Accept-Encoding</code> HTTP response header to alert proxies that
 194     a cached response should be sent only to clients that send the
 195     appropriate <code>Accept-Encoding</code> request header.  This
 196     prevents compressed content from being sent to a client that will
 197     not understand it.</p>
 198
 199     <p>If you use some special exclusions dependent
 200     on, for example, the <code>User-Agent</code> header, you must
 201     manually configure an addition to the <code>Vary</code> header
 202     to alert proxies of the additional restrictions.  For example,
 203     in a typical configuration where the addition of the <code>DEFLATE</code>
 204     filter depends on the <code>User-Agent</code>, you should add:</p>
 205
 206     <div class="example"><p><code>
 207       Header append Vary User-Agent
 208     </code></p></div>
 209
 210     <p>If your decision about compression depends on other information
 211     than request headers (<em>e.g.</em> HTTP version), you have to set the
 212     <code>Vary</code> header to the value <code>*</code>. This prevents
 213     compliant proxies from caching entirely.</p>
 214
 215     <div class="example"><h3>Example</h3><p><code>
 216       Header set Vary *
 217     </code></p></div>
 218 </div>
 219 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 220 <div class="directive-section"><h2><a name="DeflateBufferSize" id="DeflateBufferSize">DeflateBufferSize</a> <a name="deflatebuffersize" id="deflatebuffersize">Directive</a></h2>
 221 <table class="directive">
 222 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fragment size to be compressed at one time by zlib</td></tr>
 223 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DeflateBufferSize <var>value</var></code></td></tr>
 224 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DeflateBufferSize 8096</code></td></tr>
 225 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 226 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 227 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_deflate</td></tr>
 228 </table>
 229     <p>The <code class="directive">DeflateBufferSize</code> directive specifies
 230     the size in bytes of the fragments that zlib should compress at one
 231     time.</p>
 232
 233 </div>
 234 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 235 <div class="directive-section"><h2><a name="DeflateCompressionLevel" id="DeflateCompressionLevel">DeflateCompressionLevel</a> <a name="deflatecompressionlevel" id="deflatecompressionlevel">Directive</a></h2>
 236 <table class="directive">
 237 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>How much compression do we apply to the output</td></tr>
 238 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DeflateCompressionLevel <var>value</var></code></td></tr>
 239 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Zlib's default</code></td></tr>
 240 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 241 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 242 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_deflate</td></tr>
 243 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>This directive is available since Apache 2.0.45</td></tr>
 244 </table>
 245     <p>The <code class="directive">DeflateCompressionLevel</code> directive specifies
 246         what level of compression should be used, the higher the value,
 247         the better the compression, but the more CPU time is required to
 248         achieve this.</p>
 249     <p>The value must between 1 (less compression) and 9 (more compression).</p>
 250
 251 </div>
 252 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 253 <div class="directive-section"><h2><a name="DeflateFilterNote" id="DeflateFilterNote">DeflateFilterNote</a> <a name="deflatefilternote" id="deflatefilternote">Directive</a></h2>
 254 <table class="directive">
 255 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Places the compression ratio in a note for logging</td></tr>
 256 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DeflateFilterNote [<var>type</var>] <var>notename</var></code></td></tr>
 257 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 258 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 259 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_deflate</td></tr>
 260 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td><var>type</var> is available since Apache 2.0.45</td></tr>
 261 </table>
 262     <p>The <code class="directive">DeflateFilterNote</code> directive
 263     specifies that a note about compression ratios should be attached
 264     to the request. The name of the note is the value specified for
 265     the directive. You can use that note for statistical purposes by
 266     adding the value to your <a href="../logs.html#accesslog">access log</a>.</p>
 267
 268     <div class="example"><h3>Example</h3><p><code>
 269       DeflateFilterNote ratio<br />
 270       <br />
 271       LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate<br />
 272       CustomLog logs/deflate_log deflate
 273     </code></p></div>
 274
 275     <p>If you want to extract more accurate values from your logs, you
 276     can use the <var>type</var> argument to specify the type of data
 277     left as note for logging. <var>type</var> can be one of:</p>
 278
 279     <dl>
 280       <dt><code>Input</code></dt>
 281       <dd>Store the byte count of the filter's input stream in the note.</dd>
 282
 283       <dt><code>Output</code></dt>
 284       <dd>Store the byte count of the filter's output stream in the note.</dd>
 285
 286       <dt><code>Ratio</code></dt>
 287       <dd>Store the compression ratio (<code>output/input * 100</code>)
 288       in the note. This is the default, if the <var>type</var> argument
 289       is omitted.</dd>
 290     </dl>
 291
 292     <p>Thus you may log it this way:</p>
 293
 294     <div class="example"><h3>Accurate Logging</h3><p><code>
 295       DeflateFilterNote Input instream<br />
 296       DeflateFilterNote Output outstream<br />
 297       DeflateFilterNote Ratio ratio<br />
 298       <br />
 299       LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate<br />
 300       CustomLog logs/deflate_log deflate
 301     </code></p></div>
 302
 303 <h3>See also</h3>
 304 <ul>
 305 <li><code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code></li>
 306 </ul>
 307 </div>
 308 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 309 <div class="directive-section"><h2><a name="DeflateMemLevel" id="DeflateMemLevel">DeflateMemLevel</a> <a name="deflatememlevel" id="deflatememlevel">Directive</a></h2>
 310 <table class="directive">
 311 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>How much memory should be used by zlib for compression</td></tr>
 312 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DeflateMemLevel <var>value</var></code></td></tr>
 313 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DeflateMemLevel 9</code></td></tr>
 314 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 315 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 316 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_deflate</td></tr>
 317 </table>
 318     <p>The <code class="directive">DeflateMemLevel</code> directive specifies
 319     how much memory should be used by zlib for compression
 320     (a value between 1 and 9).</p>
 321
 322 </div>
 323 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 324 <div class="directive-section"><h2><a name="DeflateWindowSize" id="DeflateWindowSize">DeflateWindowSize</a> <a name="deflatewindowsize" id="deflatewindowsize">Directive</a></h2>
 325 <table class="directive">
 326 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Zlib compression window size</td></tr>
 327 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DeflateWindowSize <var>value</var></code></td></tr>
 328 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DeflateWindowSize 15</code></td></tr>
 329 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 330 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 331 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_deflate</td></tr>
 332 </table>
 333     <p>The <code class="directive">DeflateWindowSize</code> directive specifies the
 334     zlib compression window size (a value between 1 and 15). Generally, the
 335     higher the window size, the higher can the compression ratio be expected.</p>
 336
 337 </div>
 338 </div>
 339 <div class="bottomlang">
 340 <p><span>Available Languages: </span><a href="../en/mod/mod_deflate.html">&nbsp;en&nbsp;</a> | <a href="../ja/mod/mod_deflate.html">&nbsp;ja&nbsp;</a> | <a href="../ko/mod/mod_deflate.html">&nbsp;ko&nbsp;</a></p>
 341 </div><div id="footer">
 342 <p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p>
 343 <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>
 344 </body></html>