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  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
  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     <note type="warning"><title>Compression and TLS</title>
  42         <p>Some web applications are vulnerable to an information disclosure
  43         attack when a TLS connection carries deflate compressed data. For more
  44         information, review the details of the "BREACH" family of attacks.</p>
  45     </note>
  46     <p>This is a simple configuration that compresses common text-based content types.</p>
  47
  48     <example><title>Compress only a few types</title>
  49     <highlight language="config">
  50       AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript
  51       </highlight>
  52     </example>
  53
  54 </section>
  55
  56 <section id="enable"><title>Enabling Compression</title>
  57     <note type="warning"><title>Compression and TLS</title>
  58         <p>Some web applications are vulnerable to an information disclosure
  59         attack when a TLS connection carries deflate compressed data. For more
  60         information, review the details of the "BREACH" family of attacks.</p>
  61     </note>
  62
  63     <section id="output"><title>Output Compression</title>
  64       <p>Compression is implemented by the <code>DEFLATE</code>
  65       <a href="../filter.html">filter</a>. The following directive
  66       will enable compression for documents in the container where it
  67       is placed:</p>
  68
  69       <highlight language="config">
  70 SetOutputFilter DEFLATE
  71 SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ no-gzip
  72       </highlight>
  73
  74       <p>If you want to restrict the compression to particular MIME types
  75       in general, you may use the <directive module="mod_filter"
  76       >AddOutputFilterByType</directive> directive. Here is an example of
  77       enabling compression only for the html files of the Apache
  78       documentation:</p>
  79
  80       <highlight language="config">
  81 &lt;Directory "/your-server-root/manual"&gt;
  82     AddOutputFilterByType DEFLATE text/html
  83 &lt;/Directory&gt;
  84       </highlight>
  85
  86       <note><title>Note</title>
  87         The <code>DEFLATE</code> filter is always inserted after RESOURCE
  88         filters like PHP or SSI. It never touches internal subrequests.
  89       </note>
  90       <note><title>Note</title>
  91         There is an environment variable <code>force-gzip</code>,
  92         set via <directive module="mod_env">SetEnv</directive>, which
  93         will ignore the accept-encoding setting of your browser and will
  94         send compressed output.
  95       </note>
  96
  97     </section>
  98     <section id="inflate"><title>Output Decompression</title>
  99       <p>The <module>mod_deflate</module> module also provides a filter for
 100       inflating/uncompressing a gzip compressed response body. In order to activate
 101       this feature you have to insert the <code>INFLATE</code> filter into
 102       the output filter chain using <directive module="core"
 103       >SetOutputFilter</directive> or <directive module="mod_mime"
 104       >AddOutputFilter</directive>, for example:</p>
 105
 106       <highlight language="config">
 107 &lt;Location /dav-area&gt;
 108     ProxyPass http://example.com/
 109     SetOutputFilter INFLATE
 110 &lt;/Location&gt;
 111       </highlight>
 112
 113       <p>This Example will uncompress gzip'ed output from example.com, so other
 114       filters can do further processing with it.
 115       </p>
 116
 117     </section>
 118     <section id="input"><title>Input Decompression</title>
 119       <p>The <module>mod_deflate</module> module also provides a filter for
 120       decompressing a gzip compressed request body . In order to activate
 121       this feature you have to insert the <code>DEFLATE</code> filter into
 122       the input filter chain using <directive module="core"
 123       >SetInputFilter</directive> or <directive module="mod_mime"
 124       >AddInputFilter</directive>, for example:</p>
 125
 126       <highlight language="config">
 127 &lt;Location /dav-area&gt;
 128     SetInputFilter DEFLATE
 129 &lt;/Location&gt;
 130       </highlight>
 131
 132       <p>Now if a request contains a <code>Content-Encoding:
 133       gzip</code> header, the body will be automatically decompressed.
 134       Few browsers have the ability to gzip request bodies. However,
 135       some special applications actually do support request
 136       compression, for instance some <a
 137       href="http://www.webdav.org">WebDAV</a> clients.</p>
 138
 139       <note type="warning"><title>Note on Content-Length</title>
 140         <p>If you evaluate the request body yourself, <em>don't trust
 141         the <code>Content-Length</code> header!</em>
 142         The Content-Length header reflects the length of the
 143         incoming data from the client and <em>not</em> the byte count of
 144         the decompressed data stream.</p>
 145       </note>
 146     </section>
 147 </section>
 148
 149 <section id="proxies"><title>Dealing with proxy servers</title>
 150
 151     <p>The <module>mod_deflate</module> module sends a <code>Vary:
 152     Accept-Encoding</code> HTTP response header to alert proxies that
 153     a cached response should be sent only to clients that send the
 154     appropriate <code>Accept-Encoding</code> request header.  This
 155     prevents compressed content from being sent to a client that will
 156     not understand it.</p>
 157
 158     <p>If you use some special exclusions dependent
 159     on, for example, the <code>User-Agent</code> header, you must
 160     manually configure an addition to the <code>Vary</code> header
 161     to alert proxies of the additional restrictions.  For example,
 162     in a typical configuration where the addition of the <code>DEFLATE</code>
 163     filter depends on the <code>User-Agent</code>, you should add:</p>
 164
 165     <highlight language="config">
 166       Header append Vary User-Agent
 167     </highlight>
 168
 169     <p>If your decision about compression depends on other information
 170     than request headers (<em>e.g.</em> HTTP version), you have to set the
 171     <code>Vary</code> header to the value <code>*</code>. This prevents
 172     compliant proxies from caching entirely.</p>
 173
 174     <example><title>Example</title>
 175     <highlight language="config">
 176       Header set Vary *
 177       </highlight>
 178     </example>
 179 </section>
 180
 181 <directivesynopsis>
 182 <name>DeflateFilterNote</name>
 183 <description>Places the compression ratio in a note for logging</description>
 184 <syntax>DeflateFilterNote [<var>type</var>] <var>notename</var></syntax>
 185 <contextlist><context>server config</context><context>virtual host</context>
 186 </contextlist>
 187
 188 <usage>
 189     <p>The <directive>DeflateFilterNote</directive> directive
 190     specifies that a note about compression ratios should be attached
 191     to the request. The name of the note is the value specified for
 192     the directive. You can use that note for statistical purposes by
 193     adding the value to your <a href="../logs.html#accesslog"
 194     >access log</a>.</p>
 195
 196     <example><title>Example</title>
 197     <highlight language="config">
 198       DeflateFilterNote ratio
 199
 200       LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate
 201       CustomLog logs/deflate_log deflate
 202       </highlight>
 203     </example>
 204
 205     <p>If you want to extract more accurate values from your logs, you
 206     can use the <var>type</var> argument to specify the type of data
 207     left as a note for logging. <var>type</var> can be one of:</p>
 208
 209     <dl>
 210       <dt><code>Input</code></dt>
 211       <dd>Store the byte count of the filter's input stream in the note.</dd>
 212
 213       <dt><code>Output</code></dt>
 214       <dd>Store the byte count of the filter's output stream in the note.</dd>
 215
 216       <dt><code>Ratio</code></dt>
 217       <dd>Store the compression ratio (<code>output/input * 100</code>)
 218       in the note. This is the default, if the <var>type</var> argument
 219       is omitted.</dd>
 220     </dl>
 221
 222     <p>Thus you may log it this way:</p>
 223
 224     <example><title>Accurate Logging</title>
 225     <highlight language="config">
 226 DeflateFilterNote Input instream
 227 DeflateFilterNote Output outstream
 228 DeflateFilterNote Ratio ratio
 229
 230 LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate
 231 CustomLog logs/deflate_log deflate
 232 </highlight>
 233     </example>
 234 </usage>
 235 <seealso><module>mod_log_config</module></seealso>
 236 </directivesynopsis>
 237
 238 <directivesynopsis>
 239 <name>DeflateBufferSize</name>
 240 <description>Fragment size to be compressed at one time by zlib</description>
 241 <syntax>DeflateBufferSize <var>value</var></syntax>
 242 <default>DeflateBufferSize 8096</default>
 243 <contextlist><context>server config</context><context>virtual host</context>
 244 </contextlist>
 245
 246 <usage>
 247     <p>The <directive>DeflateBufferSize</directive> directive specifies
 248     the size in bytes of the fragments that zlib should compress at one
 249     time.</p>
 250 </usage>
 251 </directivesynopsis>
 252
 253 <directivesynopsis>
 254 <name>DeflateWindowSize</name>
 255 <description>Zlib compression window size</description>
 256 <syntax>DeflateWindowSize <var>value</var></syntax>
 257 <default>DeflateWindowSize 15</default>
 258 <contextlist><context>server config</context><context>virtual host</context>
 259 </contextlist>
 260
 261 <usage>
 262     <p>The <directive>DeflateWindowSize</directive> directive specifies the
 263     zlib compression window size (a value between 1 and 15). Generally, the
 264     higher the window size, the higher can the compression ratio be expected.</p>
 265 </usage>
 266 </directivesynopsis>
 267
 268 <directivesynopsis>
 269
 270 <name>DeflateMemLevel</name>
 271 <description>How much memory should be used by zlib for compression</description>
 272 <syntax>DeflateMemLevel <var>value</var></syntax>
 273 <default>DeflateMemLevel 9</default>
 274 <contextlist><context>server config</context><context>virtual host</context>
 275 </contextlist>
 276
 277 <usage>
 278     <p>The <directive>DeflateMemLevel</directive> directive specifies
 279     how much memory should be used by zlib for compression
 280     (a value between 1 and 9).</p>
 281 </usage>
 282 </directivesynopsis>
 283
 284 <directivesynopsis>
 285 <name>DeflateCompressionLevel</name>
 286 <description>How much compression do we apply to the output</description>
 287 <syntax>DeflateCompressionLevel <var>value</var></syntax>
 288 <default>Zlib's default</default>
 289 <contextlist><context>server config</context><context>virtual host</context>
 290 </contextlist>
 291
 292 <usage>
 293     <p>The <directive>DeflateCompressionLevel</directive> directive specifies
 294         what level of compression should be used, the higher the value,
 295         the better the compression, but the more CPU time is required to
 296         achieve this.</p>
 297     <p>The value must between 1 (less compression) and 9 (more compression).</p>
 298 </usage>
 299 </directivesynopsis>
 300
 301 <directivesynopsis>
 302 <name>DeflateAlterETag</name>
 303 <description>How the outgoing ETag header should be modified during compression</description>
 304 <syntax>DeflateAlterETag AddSuffix|NoChange|Remove</syntax>
 305 <default>DeflateAlterETag AddSuffix</default>
 306 <contextlist><context>server config</context><context>virtual host</context>
 307 </contextlist>
 308
 309 <usage>
 310     <p>The <directive>DeflateAlterETag</directive> directive specifies
 311     how the ETag hader should be altered when a response is compressed.</p>
 312     <dl>
 313     <dt>AddSuffix</dt>
 314     <dd><p>Append the compression method onto the end of the ETag, causing
 315         compressed and uncompressed representations to have unique ETags.
 316         This has been the default since 2.4.0, but prevents serving
 317         "HTTP Not Modified" (304) responses to conditional requests for
 318         compressed content.</p></dd>
 319     <dt>NoChange</dt>
 320     <dd><p>Don't change the ETag on a compressed response. This was the default
 321         prior to 2.4.0, but does not satisfy the HTTP/1.1 property that all
 322         representations of the same resource have unique ETags. </p></dd>
 323     <dt>Remove</dt>
 324     <dd><p>Remove the ETag header from compressed responses. This prevents
 325         some conditional requests from being possible, but avoids the
 326         shortcomings of the preceding options.  </p></dd>
 327     </dl>
 328 </usage>
 329 </directivesynopsis>
 330
 331 <directivesynopsis>
 332 <name>DeflateInflateLimitRequestBody</name>
 333 <description>Maximum size of inflated request bodies</description>
 334 <syntax>DeflateInflateLimitRequestBody<var>value</var></syntax>
 335 <default>None, but LimitRequestBody applies after deflation</default>
 336 <contextlist><context>server config</context><context>virtual host</context>
 337 <context>directory</context><context>.htaccess</context></contextlist>
 338 <compatibility>2.4.10 and later</compatibility>
 339
 340 <usage>
 341     <p>The <directive>DeflateInflateLimitRequestBody</directive> directive
 342         specifies the maximum size of an inflated request body. If it is unset,
 343         <directive module="core">LimitRequestBody</directive> is applied to the
 344         inflated body.</p>
 345 </usage>
 346 </directivesynopsis>
 347
 348 <directivesynopsis>
 349 <name>DeflateInflateRatioLimit</name>
 350 <description>Maximum inflation ratio for request bodies</description>
 351 <syntax>DeflateInflateRatioLimit <var>value</var></syntax>
 352 <default>200</default>
 353 <contextlist><context>server config</context><context>virtual host</context>
 354 <context>directory</context><context>.htaccess</context></contextlist>
 355 <compatibility>2.4.10 and later</compatibility>
 356
 357 <usage>
 358     <p>The <directive>DeflateInflateRatioLimit</directive> directive
 359         specifies the maximum ratio of deflated to inflated size of an
 360         inflated request body. This ratio is checked as the body is
 361         streamed in, and if crossed more than
 362         <directive>DeflateInflateRatioBurst</directive> times, the request
 363         will be terminated.</p>
 364 </usage>
 365 </directivesynopsis>
 366
 367 <directivesynopsis>
 368 <name>DeflateInflateRatioBurst</name>
 369 <description>Maximum number of times the inflation ratio for request bodies
 370              can be crossed</description>
 371 <syntax>DeflateInflateRatioBurst <var>value</var></syntax>
 372 <default>3</default>
 373 <contextlist><context>server config</context><context>virtual host</context>
 374 <context>directory</context><context>.htaccess</context></contextlist>
 375 <compatibility>2.4.10 and later</compatibility>
 376
 377 <usage>
 378     <p>The <directive>DeflateInflateRatioBurst</directive> directive
 379        specifies the maximum number of times the
 380        <directive>DeflateInflateRatioLimit</directive> cab be crossed before
 381        terminating the request.</p>
 382 </usage>
 383 </directivesynopsis>
 384
 385 </modulesynopsis>
 386