From 66e5a07de6270f424ee2d9112d376b7be8f6b18a Mon Sep 17 00:00:00 2001 From: =?utf8?q?Andr=C3=A9=20Malo?= Date: Mon, 11 Nov 2002 03:13:54 +0000 Subject: [PATCH] - add a forgotten CSS rule; examples in warnings also get a border around (and no bgcolor) - extend mod_deflate documentation (better example, notes on proxies) it still needs some fine tuning. Reviewed by: Luiz Rocha , Joshua Slive git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@97479 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/mod_deflate.xml | 273 ++++++++++++++++++++++++++----- docs/manual/style/css/manual.css | 3 +- 2 files changed, 235 insertions(+), 41 deletions(-) diff --git a/docs/manual/mod/mod_deflate.xml b/docs/manual/mod/mod_deflate.xml index 69d0d3ecf3..d9f923f721 100644 --- a/docs/manual/mod/mod_deflate.xml +++ b/docs/manual/mod/mod_deflate.xml @@ -4,8 +4,8 @@ mod_deflate -Compress content before - it is delivered to the client +Compress content before it is delivered to the +client Extension mod_deflate.c deflate_module @@ -16,44 +16,226 @@ your server to be compressed before being sent to the client over the network.

-AddOutputFilter -SetOutputFilter - -
Enabling Compression - -

Compression is implemented by the DEFLATE - filter. The following directive - will enable compression for documents in the container where it - is placed:

-

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).

-

If you set this to anything but '1' it will be ignored, so you can do - negative matches.

- -SetEnv gzip-only-text/html 1
-SetOutputFilter DEFLATE - - -

Here is an example of enabling compression for the Apache - documentation:

- - -<Directory "/your-server-root/manual">
- SetEnv gzip-only-text/html 1
- SetOutputFilter DEFLATE
-</Directory> - - -

For browsers that have problems even with compression of html files, - use the BrowserMatch directive to set the 'no-gzip' note - for that particular browser so that no compression will be performed.

+The filter documentation + + + +
Enabling Compression + +
Output Compression +

Compression is implemented by the DEFLATE + filter. The following directive + will enable compression for documents in the container where it + is placed:

+ + + SetOutputFilter DEFLATE + + +

Some popular browsers cannot 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). If you set this to anything but 1 it + will be ignored.

+ +

If you want to restrict the compression to particular MIME types + in general, you may use the AddOutputFilterByType directive. Here is an example of + enabling compression only for the html files of the Apache + documentation:

+ + + <Directory "/your-server-root/manual">
+ + AddOutputFilterByType DEFLATE text/html
+ + </Directory> + + +

For browsers that have problems even with compression of all file + types, use the BrowserMatch directive to set the no-gzip + note for that particular browser so that no compression will be + performed. You may combine no-gzip with gzip-only-text/html to get the best results. In that case + the former overrides the latter. Take a look at the following + excerpt from the configuration example + defined in the section above:

+ + + BrowserMatch ^Mozilla/4 gzip-only-text/html
+ BrowserMatch ^Mozilla/4\.0[678] no-gzip
+ BrowserMatch \bMSIE !no-gzip !gzip-only-text/html + + +

At first we probe for a User-Agent string that + indicates a Netscape Navigator version of 4.x. These versions + have some big problems to decompress content types different + from text/html. The versions 4.06, 4.07 and 4.08 have + also sometimes problems to decompress html files. Thus, we + completely turn off the deflate filter for them.

+ +

The third BrowserMatch + directive fixes the guessed identity of the user agent, because + the Microsoft Internet Explorer identifies itself also as "Mozilla/4" + but is actually able to handle requested compression. Therefore we + match against the additional string "MSIE" (\b means + "word boundary") in the User-Agent Header and turn off + the restrictions defined before.

+ + Note + The DEFLATE filter is always inserted after RESOURCE + filters like PHP or SSI. It never touches internal subrequests. + +
+ +
Input Decompression +

The mod_deflate module also provides a filter for + decompressing a gzip compressed request body . In order to activate + this feature you have to insert the DEFLATE filter into + the input filter chain using SetInputFilter or AddInputFilter, for example:

+ + + <Location /dav-area> + + SetInputFilter DEFLATE + + </Location> + + +

Now if a request contains a Content-Encoding: gzip + header, the body will be automatically decompressed. Ordinary + browsers usually don't have the ability to gzip e.g. POST + request bodies. However, some special applications actually do + support request compression, for instance WebDAV clients.

+ + Note on Content-Length +

If you evaluate the request body yourself, don't trust + the Content-Length header! For example, a + wide-spread code to read the request body in perl is:

+ + + # WRONG!
+ if (($len = $ENV{'CONTENT_LENGTH'}) > 0) {
+ + read(STDIN, $body, $len);
+ + } + + +

Since the Content-Length header reflects the length of the + incoming data from the client and not the byte count of + the decompressed data, you would read too less and cut off the + stream.

+ +

Thus, if you want to slurp the whole request body, use for + example:

+ + + {
+ + local $/; # undef input record separator
+ $body = <STDIN>;
+ + } + + +
+
+ +
Dealing with proxy servers +

Since the DEFLATE output filter actually performs a + kind of content negotiation, + you should take care of caching proxy servers. In order to prevent a + proxy cache from delivering the wrong data (e.g. gzip + compressed data to a client which doesn't send an appropriate + Accept-Encoding header), the origin server + (i.e. you) has to indicate the negotiation parameters in the + Vary response header.

+ +

If the DEFLATE filter is involved in the request, the + following header will be set:

+ + + Vary: Accept-Encoding + + +

A HTTP compiliant proxy now delivers the cached data to any client, + which sends the same Accept-Encoding header as + the client, which did the initial request that was cached.

+ +

Fine. But what happens, if you use some special exclusions dependant + on, say the User-Agent 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 mod_headers + module to add appropriate values to the Vary header, for + example:

+ + + Header append Vary User-Agent + + +

would result in the following response header:

+ + + Vary: Accept-Encoding,User-Agent + + +

If your decision about compression depends on other information + than request headers (e.g. HTTP version), you have to set the + Vary header to the value *. This prevents + documents from caching by HTTP compiliant proxies at all.

+ + Example + Header set Vary * +
DeflateFilterNote Places the compression ratio in a note for logging -DeflateFilterNote notename +DeflateFilterNote notename server configvirtual host @@ -61,14 +243,24 @@ SetOutputFilter DEFLATE

The DeflateFilterNote 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.

+ the directive. You can use that note for statistical purposes by + adding the value to your access log.

+ + Example + DeflateFilterNote ratio
+
+ LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate
+ CustomLog logs/deflate_log deflate + +mod_log_config DeflateBufferSize Fragment size to be compressed at one time by zlib -DeflateBufferSize value +DeflateBufferSize value DeflateBufferSize 8096 server configvirtual host @@ -83,21 +275,22 @@ SetOutputFilter DEFLATE DeflateWindowSize Zlib compression window size -DeflateWindowSize value +DeflateWindowSize value DeflateWindowSize 15 server configvirtual host

The DeflateWindowSize directive specifies the - zlib compression window size (a value between 1 and 15).

+ zlib compression window size (a value between 1 and 15). Generally, the + higher the window size, the higher can the compression ratio be expected.

 DeflateMemLevel How much memory should be used by zlib for compression -DeflateMemLevel value +DeflateMemLevel value DeflateMemLevel 9 server configvirtual host diff --git a/docs/manual/style/css/manual.css b/docs/manual/style/css/manual.css index 366518f1bc..75d9ea0260 100644 --- a/docs/manual/style/css/manual.css +++ b/docs/manual/style/css/manual.css @@ -717,7 +717,8 @@ div.example { * so simply draw a border around * and keep it gray */ -div.note div.example { +div.note div.example, +div.warning div.example { border: 1px solid #aaa; background-color: transparent; color: inherit; -- 2.40.0