From: Joshua Slive Date: Mon, 11 Nov 2002 18:24:42 +0000 (+0000) Subject: Tighten up the writing a little and add an even simpler X-Git-Tag: 2.0.44~86 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=9b11acd3bbd3d81f405d6518fd4d45a9160bb371;p=apache Tighten up the writing a little and add an even simpler configuration example. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@97483 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_deflate.html.en b/docs/manual/mod/mod_deflate.html.en index 09dd4abd14..1a9f65b6e4 100644 --- a/docs/manual/mod/mod_deflate.html.en +++ b/docs/manual/mod/mod_deflate.html.en @@ -22,10 +22,14 @@ clientStatus:

This is a sample configuration for the impatient. But please take the time and read the sections below for a detailed description!

-

+

Compress only a few types

+ AddOutputFilterByType DEFLATE text/html text/plain text/xml +

+ +

Compress everything except images

<Location />
- # insert filter
+ # Insert filter
SetOutputFilter DEFLATE

# Netscape 4.x has some problems...
@@ -34,25 +38,21 @@ clientStatus: # Netscape 4.06-4.08 have some more problems
BrowserMatch ^Mozilla/4\.0[678] no-gzip

- # fix identity
+ # MSIE masquerades as Netscape, but it is fine
BrowserMatch \bMSIE !no-gzip !gzip-only-text/html

- # don't bother:
+ # Don't compress images
SetEnvIfNoCase Request_URI \
\.(?:gif|jpe?g|png)$ no-gzip dont-vary
- # be verbose about configuration
+ # Make sure proxies don't deliver the wrong content
Header append Vary User-Agent env=!dont-vary
</Location>

-

Note, that gzip compression of binary files (e.g. images) - usually has only little effect. Therefore in the example above we use - an exclusion list of some file types. Alternatively you may use a - positive list using AddOutputFilter or AddOutputFilterByType instead of the SetOutputFilter directive.

top

Enabling Compression

Output Compression

@@ -100,10 +100,10 @@ clientStatus:

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.

+ cannot handle compression of types other than + text/html. The versions 4.06, 4.07 and 4.08 also + have problems with decompressing 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 @@ -133,86 +133,44 @@ clientStatus: </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.

+

Now if a request contains a Content-Encoding: + gzip header, the body will be automatically decompressed. + Few browsers have the ability to gzip request bodies. However, + some special applications actually do support request + compression, for instance some 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 + the Content-Length header! + 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>;
- - } -

+ the decompressed data stream.

top

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:

+

The mod_deflate module sends a Vary: + Accept-Encoding HTTP response header to alert proxies that + a cached response should be sent only to clients that send the + appropriate Accept-Encoding request header. This + prevents compressed content from being sent to a client that will + not understand it.

-

- 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:

+

If you use some special exclusions dependant + on, for example, the User-Agent header, you must + manually configure an addition to the Vary header + to alert proxies of the additional restrictions. For example, + in a typical configuration where the addition of the DEFLATE + filter depends on the User-Agent, you should add:

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.

+ compliant proxies from caching entirely.

Example

Header set Vary * diff --git a/docs/manual/mod/mod_deflate.xml b/docs/manual/mod/mod_deflate.xml index d9f923f721..4c11af3cc2 100644 --- a/docs/manual/mod/mod_deflate.xml +++ b/docs/manual/mod/mod_deflate.xml @@ -22,10 +22,14 @@ client

This is a sample configuration for the impatient. But please take the time and read the sections below for a detailed description!

- + Compress only a few types + AddOutputFilterByType DEFLATE text/html text/plain text/xml + + + Compress everything except images <Location />
- # insert filter
+ # Insert filter
SetOutputFilter DEFLATE

# Netscape 4.x has some problems...
@@ -34,28 +38,21 @@ client # Netscape 4.06-4.08 have some more problems
BrowserMatch ^Mozilla/4\.0[678] no-gzip

- # fix identity
+ # MSIE masquerades as Netscape, but it is fine
BrowserMatch \bMSIE !no-gzip !gzip-only-text/html

- # don't bother:
+ # Don't compress images
SetEnvIfNoCase Request_URI \
\.(?:gif|jpe?g|png)$ no-gzip dont-vary
- # be verbose about configuration
+ # Make sure proxies don't deliver the wrong content
Header append Vary User-Agent env=!dont-vary
 </Location> -

Note, that gzip compression of binary files (e.g. images) - usually has only little effect. Therefore in the example above we use - an exclusion list of some file types. Alternatively you may use a - positive list using AddOutputFilter or AddOutputFilterByType instead of the SetOutputFilter directive.

Enabling Compression @@ -108,10 +105,10 @@ client

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.

+ cannot handle compression of types other than + text/html. The versions 4.06, 4.07 and 4.08 also + have problems with decompressing 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 @@ -143,89 +140,47 @@ client </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 Now if a request contains a Content-Encoding: + gzip header, the body will be automatically decompressed. + Few browsers have the ability to gzip request bodies. However, + some special applications actually do support request + compression, for instance some 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 + the Content-Length header! + 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>;
- - } - + the decompressed data stream.
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.

+

The mod_deflate module sends a Vary: + Accept-Encoding HTTP response header to alert proxies that + a cached response should be sent only to clients that send the + appropriate Accept-Encoding request header. This + prevents compressed content from being sent to a client that will + not understand it.

-

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:

+

If you use some special exclusions dependant + on, for example, the User-Agent header, you must + manually configure an addition to the Vary header + to alert proxies of the additional restrictions. For example, + in a typical configuration where the addition of the DEFLATE + filter depends on the User-Agent, you should add:

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.

+ compliant proxies from caching entirely.

Example Header set Vary *