From: Jim Jagielski Date: Mon, 16 Jan 2017 19:51:31 +0000 (+0000) Subject: 1st draft X-Git-Tag: 2.5.0-alpha~783 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2a27541f780a26300e8ef5abc465795c0306d072;p=thirdparty%2Fapache%2Fhttpd.git 1st draft git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1779091 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_brotli.xml b/docs/manual/mod/mod_brotli.xml new file mode 100644 index 00000000000..f82486cbb28 --- /dev/null +++ b/docs/manual/mod/mod_brotli.xml @@ -0,0 +1,340 @@ + + + + + + + + + +mod_brotli +Compress content via Brotli before it is delivered to the +client +Extension +mod_brotli.c +brotli_module + + +

The mod_brotli module provides + the BROTLI_COMPRESS output filter that allows output from + your server to be compressed using the brotli compression format before being sent to the client over + the network.

+ +Filters + + + +
Enabling Compression + Compression and TLS +

Some web applications are vulnerable to an information disclosure + attack when a TLS connection carries deflate compressed data. For more + information, review the details of the "BREACH" family of attacks.

+ + +
Output Compression +

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

+ + +SetOutputFilter BROTLI_COMPRESS +SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ no-brotli + + +

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 BROTLI_COMPRESS text/html +</Directory> + + + Note + The BROTLI_COMPRESS filter is always inserted after RESOURCE + filters like PHP or SSI. It never touches internal subrequests. + + Note + There is an environment variable no-brotli, + set via SetEnv, which + will ignore the accept-encoding setting of your browser and will + send compressed output. + + +
+ +
Input Decompression +

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

+ + +<Location "/dav-area"> + SetInputFilter BROTLI_COMPRESS +</Location> + + +

Now if a request contains a Content-Encoding: + brotli header, the body will be automatically decompressed. + Few browsers have the ability to brotli 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! + The Content-Length header reflects the length of the + incoming data from the client and not the byte count of + the decompressed data stream.

+ +
+
+ +
Dealing with proxy servers + +

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

+ +

If you use some special exclusions dependent + 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 + + +

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 + compliant proxies from caching entirely.

+ + Example + + Header set Vary * + + +
+ +
Serving pre-compressed +content + +

Since mod_brotli re-compresses content each + time a request is made, some performance benefit can be derived by + pre-compressing the content and telling mod_brotli to serve them + without re-compressing them. This may be accomplished using a + configuration like the following:

+ + +<IfModule mod_headers.c> + # Serve brotli compressed CSS files if they exist + # and the client accepts brotli. + RewriteCond "%{HTTP:Accept-encoding}" "brotli" + RewriteCond "%{REQUEST_FILENAME}\.br" "-s" + RewriteRule "^(.*)\.css" "$1\.css\.br" [QSA] + + # Serve brotli compressed JS files if they exist + # and the client accepts brotli. + RewriteCond "%{HTTP:Accept-encoding}" "brotli" + RewriteCond "%{REQUEST_FILENAME}\.br" "-s" + RewriteRule "^(.*)\.js" "$1\.js\.br" [QSA] + + + # Serve correct content types, and prevent mod_brotli double brotli. + RewriteRule "\.css\.gz$" "-" [T=text/css,E=no-brotli:1] + RewriteRule "\.js\.gz$" "-" [T=text/javascript,E=no-brotli:1] + + + <FilesMatch "(\.js\.gz|\.css\.gz)$"> + # Serve correct encoding type. + Header append Content-Encoding brotli + + # Force proxies to cache brotli & + # non-brotli css/js files separately. + Header append Vary Accept-Encoding + </FilesMatch> +</IfModule> + + +
+ + +BrotliFilterNote +Places the compression ratio in a note for logging +BrotliFilterNote [type] notename +server configvirtual host + + + +

The BrotliFilterNote 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. You can use that note for statistical purposes by + adding the value to your access log.

+ + Example + + BrotliFilterNote ratio + + LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' brotli + CustomLog "logs/brotli_log" brotli + + + +

If you want to extract more accurate values from your logs, you + can use the type argument to specify the type of data + left as a note for logging. type can be one of:

+ +
+
Input
+
Store the byte count of the filter's input stream in the note.
+ +
Output
+
Store the byte count of the filter's output stream in the note.
+ +
Ratio
+
Store the compression ratio (output/input * 100) + in the note. This is the default, if the type argument + is omitted.
+
+ +

Thus you may log it this way:

+ + Accurate Logging + +BrotliFilterNote Input instream +BrotliFilterNote Output outstream +BrotliFilterNote Ratio ratio + +LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' brotli +CustomLog "logs/brotli_log" brotli + + + +mod_log_config + + + +BrotliCompressionQuality +Compression quality +BrotliCompressionQuality value +BrotliCompressionQuality 5 +server configvirtual host + + + +

The BrotliCompressionQuality directive specifies + the compression quality performed (a value between 0 and 11). Higher + quality values result in better compression but also slower compression + as well. +

+ + + + +BrotliCompressionWindow +Brotli sliding compression window size +BrotliCompressionWindow value +BrotliCompressionWindow 18 +server configvirtual host + + + +

The BrotliCompressionWindow directive specifies the + brotli sliding compression window size (a value between 10 and 24). Generally, the + higher the window size, the higher can the compression ratio be expected + but requires more memory.

+ + + + + +BrotliCompressionMaxInputBlock +Maximum input block size +BrotliCompressionMaxInputBlock value +BrotliCompressionMaxInputBlock 0 +server configvirtual host + + + +

The BrotliCompressionMaxInputBlock directive specifies + the maximum input block size between 16 and 24, with the caveat that + larger block sizes require more memory.

+ + + + +BrotliAlterETag +How the outgoing ETag header should be modified during compression +BrotliAlterETag AddSuffix|NoChange|Remove +BrotliAlterETag AddSuffix +server configvirtual host + + + +

The BrotliAlterETag directive specifies + how the ETag hader should be altered when a response is compressed.

+
+
AddSuffix
+

Append the compression method onto the end of the ETag, causing + compressed and uncompressed representations to have unique ETags. + This has been the default since 2.4.0, but prevents serving + "HTTP Not Modified" (304) responses to conditional requests for + compressed content.

+
NoChange
+

Don't change the ETag on a compressed response. This was the default + prior to 2.4.0, but does not satisfy the HTTP/1.1 property that all + representations of the same resource have unique ETags.

+
Remove
+

Remove the ETag header from compressed responses. This prevents + some conditional requests from being possible, but avoids the + shortcomings of the preceding options.

+
+ + + +