* Joshua Slive wrote:
> Some suggestions:
[...]
Thanks (Luiz also) for your feedback. The only thing I didn't (re-)built in
is the SetEnv example. I currently can't imagine a configuration that makes
much sense, since AddoutputFilterByType exists and is much more flexible.
I also added a section about mod_deflate and proxy servers. Another review
would be appreciated...
I put the whole revision online again at
<http://cvs.apache.org/~nd/manual/mod/mod_deflate.html>
attached you'll find the whole patch against the current xml and a patch
against the first version (choose whatever you want to read ;-)
nd
--
Treat your password like your toothbrush. Don't let anybody else
use it, and get a new one every six months. -- Clifford Stoll
(found in ssl_engine_pphrase.c)
Index: mod_deflate.xml
===================================================================
RCS file: /home/cvs/httpd-2.0/docs/manual/mod/mod_deflate.xml,v
retrieving revision 1.9
diff -u -r1.9 mod_deflate.xml
--- mod_deflate.xml 4 Oct 2002 16:13:23 -0000 1.9
+++ mod_deflate.xml 9 Nov 2002 22:42:04 -0000
@@ -4,8 +4,8 @@
<modulesynopsis>
<name>mod_deflate</name>
-<description>Compress content before
- it is delivered to the client</description>
+<description>Compress content before it is delivered to the
+client</description>
<status>Extension</status>
<sourcefile>mod_deflate.c</sourcefile>
<identifier>deflate_module</identifier>
@@ -16,44 +16,180 @@
your server to be compressed before being sent to the client over
the network.</p>
</summary>
-<seealso><directive module="mod_mime">AddOutputFilter</directive></seealso>
-<seealso><directive module="core">SetOutputFilter</directive></seealso>
+<seealso><a href="../filter.html">The filter documentation</a></seealso>
-<section><title>Enabling Compression</title>
+<section id="enable"><title>Enabling Compression</title>
- <p>Compression is implemented by the <code>DEFLATE</code>
- <a href="../filter.html">filter</a>. The following directive
- will enable compression for documents in the container where it
- is placed:</p>
- <p><strong>Most popular browsers can not handle compression of all content
- so you may want to set the 'gzip-only-text/html' note to 1 to only
- allow html files to be compressed (see below).</strong></p>
- <p><strong>If you set this to anything but '1' it will be ignored, so you
can do
- negative matches.</strong></p>
-
-<example>SetEnv gzip-only-text/html 1<br />
-SetOutputFilter DEFLATE
-</example>
-
- <p>Here is an example of enabling compression for the Apache
- documentation:</p>
-
-<example>
-<Directory "/your-server-root/manual"><br />
- SetEnv gzip-only-text/html 1<br />
- SetOutputFilter DEFLATE<br />
-</Directory>
-</example>
-
- <p>For browsers that have problems even with compression of html files,
- use the <directive>BrowserMatch</directive> directive to set the 'no-gzip'
note
- for that particular browser so that no compression will be performed.</p>
+ <section id="output"><title>Output Compression</title>
+ <p>Compression is implemented by the <code>DEFLATE</code>
+ <a href="../filter.html">filter</a>. The following directive
+ will enable compression for documents in the container where it
+ is placed:</p>
+
+ <example>
+ SetOutputFilter DEFLATE
+ </example>
+
+ <p>Some popular browsers cannot handle compression of all content
+ so you may want to set the <code>gzip-only-text/html</code> note to
+ <code>1</code> to only allow html files to be compressed (see
+ below). If you set this to <em>anything but <code>1</code></em> it
+ will be ignored.</p>
+
+ <p>If you want to restrict the compression to particular MIME types
+ in general, you may use the <directive module="core"
+ >AddOutputFilterByType</directive> directive. Here is an example of
+ enabling compression only for the html files of the Apache
+ documentation:</p>
+
+ <example>
+ <Directory "/your-server-root/manual"><br />
+ <indent>
+ AddOutputFilterByType DEFLATE text/html<br />
+ </indent>
+ </Directory>
+ </example>
+
+ <p>For browsers that have problems even with compression of all file
+ types, use the <directive module="mod_setenvif"
+ >BrowserMatch</directive> directive to set the <code>no-gzip</code>
+ note for that particular browser so that no compression will be
+ performed. You may combine <code>no-gzip</code> with <code
+ >gzip-only-text/html</code> to get the best results. In that case
+ the former overrides the latter.</p>
+
+ <example><title>Recommended restrictions</title>
+ # Netscape 4.x has some problems...<br />
+ BrowserMatch ^Mozilla/4 gzip-only-text/html<br />
+ <br />
+ # Netscape 4.06-4.08 have some more problems<br />
+ BrowserMatch ^Mozilla/4\.0[678] no-gzip<br />
+ <br />
+ # fix identity<br />
+ BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
+ </example>
+
+ <p>Note, that the Microsoft Internet Explorer identifies itself
+ as "Mozilla/4" but is able to handle requested compression. Therefore
+ in the example above we match against the additional string "MSIE"
+ (<code>\b</code> means "word boundary") in the <code>User-Agent</code>
+ Header and turn off the restrictions.</p>
+
+ <note><title>Note</title>
+ The <code>DEFLATE</code> filter is always inserted after RESOURCE
+ filters like PHP or SSI. It never touches internal subrequests.
+ </note>
+ </section>
+
+ <section id="input"><title>Input Decompression</title>
+ <p>The <module>mod_deflate</module> module also provides a filter for
+ decompressing a gzip compressed request body. In order to activate
+ this feature you have to insert the <code>DEFLATE</code> filter into
+ the input filter chain using <directive module="core"
+ >SetInputFilter</directive> or <directive module="mod_mime"
+ >AddInputFilter</directive>, for example:</p>
+
+ <example>
+ <Location /dav-area>
+ <indent>
+ SetInputFilter DEFLATE
+ </indent>
+ </Location>
+ </example>
+
+ <p>Now if a request contains a <code>Content-Encoding: gzip</code>
+ header, the body will be automatically decompressed. Ordinary
+ browsers usually don't have the ability to gzip e.g. <code>POST</code>
+ request bodies. However, some special applications actually do
+ support request compression, for instance <a
+ href="http://www.webdav.org";>WebDAV</a> clients.</p>
+
+ <note type="warning"><title>Note on Content-Length</title>
+ <p>If you evaluate the request body yourself, <em>don't trust
+ the Content-length!</em> For example, a wide-spread code to read
+ the request body in perl is:</p>
+
+ <example>
+ # WRONG!<br />
+ if (($len = $ENV{'CONTENT_LENGTH'}) > 0) {<br />
+ <indent>
+ read(STDIN, $body, $len);<br />
+ </indent>
+ }
+ </example>
+
+ <p>Since the Content-Length header reflects the length of the
+ incoming data from the client and <em>not</em> the byte count of
+ the decompressed data, you would read too less and cut off the
+ stream.</p>
+
+ <p>Thus, if you want to slurp the whole request body, use for
+ example:</p>
+
+ <example>
+ {<br />
+ <indent>
+ local $/; # undef input record separator<br />
+ $body = <STDIN>;<br />
+ </indent>
+ }
+ </example>
+ </note>
+ </section>
+</section>
+
+<section id="proxies"><title>Dealing with proxy servers</title>
+ <p>Since the <code>DEFLATE</code> filter actually performs a kind
+ of <a href="../content-negotiation.html">content negotiation</a>,
+ you should take care of caching proxy servers. In order to prevent a
+ proxy cache from delivering the wrong data (<em>e.g.</em> gzip
+ compressed data to a client which doesn't send an appropriate
+ <code>Accept-Encoding</code> header), the origin server
+ (<em>i.e.</em> you) has to indicate the negotiation parameters in the
+ <code>Vary</code> response header.</p>
+
+ <p>If <module>mod_deflate</module> actually compresses the data, the
+ following header will be set:</p>
+
+ <example>
+ Vary: Accept-Encoding
+ </example>
+
+ <p>A HTTP compiliant proxy now delivers the cached data to any client,
+ which sends the <em>same</em> <code>Accept-Encoding</code> header as
+ the client, which did the initially request that was cached.</p>
+
+ <p>Fine. But what happens, if you use some special exclusions dependant
+ on, say the <code>User-Agent</code> header? The proxy server doesn't
+ know anything about your server configuration, thus you have to tell
+ him, what you're doing. You have to use the <module>mod_headers</module>
+ module to add appropriate values to the <code>Vary</code> header, for
+ example:</p>
+
+ <example>
+ Header append Vary User-Agent
+ </example>
+
+ <p>That would result in the following response header:</p>
+
+ <example>
+ Vary: Accept-Encoding,User-Agent
+ </example>
+
+ <p>If your decision about compression depends on other information
+ than request headers (<em>e.g.</em> HTTP version), you have to set the
+ <code>Vary</code> header to the value <code>*</code>. This prevents
+ documents from caching by HTTP compiliant proxies at all.</p>
+
+ <example><title>Example</title>
+ Header set Vary *
+ </example>
</section>
<directivesynopsis>
<name>DeflateFilterNote</name>
<description>Places the compression ratio in a note for logging</description>
-<syntax>DeflateFilterNote <em>notename</em></syntax>
+<syntax>DeflateFilterNote <var>notename</var></syntax>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
@@ -61,14 +197,24 @@
<p>The <directive>DeflateFilterNote</directive> directive
specifies that a note about compression ratios should be attached
to the request. The name of the note is the value specified for
- the directive.</p>
+ the directive. You can use that note for statistical purposes by
+ adding the value to your <a href="../logs.html#accesslog"
+ >access log</a>.</p>
+
+ <example><title>Example</title>
+ DeflateFilterNote ratio<br />
+ <br />
+ LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate<br />
+ CustomLog logs/deflate_log deflate
+ </example>
</usage>
+<seealso><module>mod_log_config</module></seealso>
</directivesynopsis>
<directivesynopsis>
<name>DeflateBufferSize</name>
<description>Fragment size to be compressed at one time by zlib</description>
-<syntax>DeflateBufferSize <em>value</em></syntax>
+<syntax>DeflateBufferSize <var>value</var></syntax>
<default>DeflateBufferSize 8096</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
@@ -83,21 +229,22 @@
<directivesynopsis>
<name>DeflateWindowSize</name>
<description>Zlib compression window size</description>
-<syntax>DeflateWindowSize <em>value</em></syntax>
+<syntax>DeflateWindowSize <var>value</var></syntax>
<default>DeflateWindowSize 15</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
<usage>
<p>The <directive>DeflateWindowSize</directive> directive specifies the
- zlib compression window size (a value between 1 and 15).</p>
+ zlib compression window size (a value between 1 and 15). Generally, the
+ higher the window size, the higher can the compression ratio be
expected.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>DeflateMemLevel</name>
<description>How much memory should be used by zlib for
compression</description>
-<syntax>DeflateMemLevel <em>value</em></syntax>
+<syntax>DeflateMemLevel <var>value</var></syntax>
<default>DeflateMemLevel 9</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
--- mod_deflate.xml Sat Nov 09 23:44:02 2002
+++ d:\p\mod_deflate.xml Sat Nov 09 23:38:39 2002
@@ -16,12 +16,6 @@
your server to be compressed before being sent to the client over
the network.</p>
</summary>
-<seealso><directive module="core">AddOutputFilterByType</directive>
-</seealso>
-<seealso><directive module="mod_mime">AddOutputFilter</directive></seealso>
-<seealso><directive module="core">SetOutputFilter</directive></seealso>
-<seealso><directive module="mod_mime">AddInputFilter</directive></seealso>
-<seealso><directive module="core">SetInputFilter</directive></seealso>
<seealso><a href="../filter.html">The filter documentation</a></seealso>
<section id="enable"><title>Enabling Compression</title>
@@ -40,7 +34,7 @@
so you may want to set the <code>gzip-only-text/html</code> note to
<code>1</code> to only allow html files to be compressed (see
below). If you set this to <em>anything but <code>1</code></em> it
- will be ignored, so you can do negative matches.</p>
+ will be ignored.</p>
<p>If you want to restrict the compression to particular MIME types
in general, you may use the <directive module="core"
@@ -64,22 +58,22 @@
>gzip-only-text/html</code> to get the best results. In that case
the former overrides the latter.</p>
- <example><title>Example</title>
+ <example><title>Recommended restrictions</title>
# Netscape 4.x has some problems...<br />
BrowserMatch ^Mozilla/4 gzip-only-text/html<br />
<br />
# Netscape 4.06-4.08 have some more problems<br />
BrowserMatch ^Mozilla/4\.0[678] no-gzip<br />
<br />
- # other browsers have other problems ;-)<br />
+ # fix identity<br />
BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
</example>
- <p>Note, that the Microsoft Internet Explorer identifies himself
+ <p>Note, that the Microsoft Internet Explorer identifies itself
as "Mozilla/4" but is able to handle requested compression. Therefore
in the example above we match against the additional string "MSIE"
- (<code>\b</code> means "word boundary") in the User-Agent Header and
- turn off the restrictions.</p>
+ (<code>\b</code> means "word boundary") in the <code>User-Agent</code>
+ Header and turn off the restrictions.</p>
<note><title>Note</title>
The <code>DEFLATE</code> filter is always inserted after RESOURCE
@@ -103,7 +97,7 @@
</Location>
</example>
- <p>If now a request contains a <code>Content-Encoding: gzip</code>
+ <p>Now if a request contains a <code>Content-Encoding: gzip</code>
header, the body will be automatically decompressed. Ordinary
browsers usually don't have the ability to gzip e.g. <code>POST</code>
request bodies. However, some special applications actually do
@@ -142,6 +136,54 @@
</example>
</note>
</section>
+</section>
+
+<section id="proxies"><title>Dealing with proxy servers</title>
+ <p>Since the <code>DEFLATE</code> filter actually performs a kind
+ of <a href="../content-negotiation.html">content negotiation</a>,
+ you should take care of caching proxy servers. In order to prevent a
+ proxy cache from delivering the wrong data (<em>e.g.</em> gzip
+ compressed data to a client which doesn't send an appropriate
+ <code>Accept-Encoding</code> header), the origin server
+ (<em>i.e.</em> you) has to indicate the negotiation parameters in the
+ <code>Vary</code> response header.</p>
+
+ <p>If <module>mod_deflate</module> actually compresses the data, the
+ following header will be set:</p>
+
+ <example>
+ Vary: Accept-Encoding
+ </example>
+
+ <p>A HTTP compiliant proxy now delivers the cached data to any client,
+ which sends the <em>same</em> <code>Accept-Encoding</code> header as
+ the client, which did the initially request that was cached.</p>
+
+ <p>Fine. But what happens, if you use some special exclusions dependant
+ on, say the <code>User-Agent</code> header? The proxy server doesn't
+ know anything about your server configuration, thus you have to tell
+ him, what you're doing. You have to use the <module>mod_headers</module>
+ module to add appropriate values to the <code>Vary</code> header, for
+ example:</p>
+
+ <example>
+ Header append Vary User-Agent
+ </example>
+
+ <p>That would result in the following response header:</p>
+
+ <example>
+ Vary: Accept-Encoding,User-Agent
+ </example>
+
+ <p>If your decision about compression depends on other information
+ than request headers (<em>e.g.</em> HTTP version), you have to set the
+ <code>Vary</code> header to the value <code>*</code>. This prevents
+ documents from caching by HTTP compiliant proxies at all.</p>
+
+ <example><title>Example</title>
+ Header set Vary *
+ </example>
</section>
<directivesynopsis>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
