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