From 6beeb1b708550be0d4a53b272283e17e5e35fe17 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:01:30 +0200 Subject: Adding upstream version 2.4.57. Signed-off-by: Daniel Baumann --- docs/manual/mod/mod_brotli.html.en | 349 +++++++++++++++++++++++++++++++++++++ 1 file changed, 349 insertions(+) create mode 100644 docs/manual/mod/mod_brotli.html.en (limited to 'docs/manual/mod/mod_brotli.html.en') diff --git a/docs/manual/mod/mod_brotli.html.en b/docs/manual/mod/mod_brotli.html.en new file mode 100644 index 0000000..97afac1 --- /dev/null +++ b/docs/manual/mod/mod_brotli.html.en @@ -0,0 +1,349 @@ + + + + + +mod_brotli - Apache HTTP Server Version 2.4 + + + + + + + +
+

Modules | Directives | FAQ | Glossary | Sitemap

+

Apache HTTP Server Version 2.4

+
+
<-
+ +
+

Apache Module mod_brotli

+
+

Available Languages:  en  | + fr 

+
+ + + + +
Description:Compress content via Brotli before it is delivered to the +client
Status:Extension
Module Identifier:brotli_module
Source File:mod_brotli.c
Compatibility:Available in version 2.4.26 and later.
+

Summary

+ +

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. This module uses the Brotli library found at + https://github.com/google/brotli.

+
+ +
top
+
+

Sample Configurations

+

Compression and TLS

+

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

+
+

This is a simple configuration that compresses common text-based content types.

+ +

Compress only a few types

AddOutputFilterByType BROTLI_COMPRESS text/html text/plain text/xml text/css text/javascript application/javascript
+
+ +
top
+
+

Enabling Compression

+

Compression and TLS

+

Some web applications are vulnerable to an information disclosure + attack when a TLS connection carries 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 disable brotli compression for a particular request, even if + it is supported by the client. +
+ + + +
top
+
+

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 BROTLI_COMPRESS + 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 *
+
+
top
+
+

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}" "br"
+    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}" "br"
+    RewriteCond "%{REQUEST_FILENAME}\.br" "-s"
+    RewriteRule "^(.*)\.js"               "$1\.js\.br" [QSA]
+
+
+    # Serve correct content types, and prevent double compression.
+    RewriteRule "\.css\.br$" "-" [T=text/css,E=no-brotli:1]
+    RewriteRule "\.js\.br$"  "-" [T=text/javascript,E=no-brotli:1]
+
+
+    <FilesMatch "(\.js\.br|\.css\.br)$">
+      # Serve correct encoding type.
+      Header append Content-Encoding br
+
+      # Force proxies to cache brotli &
+      # non-brotli css/js files separately.
+      Header append Vary Accept-Encoding
+    </FilesMatch>
+</IfModule>
+ + +
+
top
+

BrotliAlterETag Directive

+ + + + + + + +
Description:How the outgoing ETag header should be modified during compression
Syntax:BrotliAlterETag AddSuffix|NoChange|Remove
Default:BrotliAlterETag AddSuffix
Context:server config, virtual host
Status:Extension
Module:mod_brotli
+

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. + In another dynamic compression module, mod_deflate, this has been + the default since 2.4.0. This setting prevents serving "HTTP Not + Modified" (304) responses to conditional requests for compressed + content.

+
NoChange
+

Don't change the ETag on a compressed response. In another dynamic + compression module, mod_deflate, this has been the default prior to + 2.4.0. This setting 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.

+
+ +
+
top
+

BrotliCompressionMaxInputBlock Directive

+ + + + + + + +
Description:Maximum input block size
Syntax:BrotliCompressionMaxInputBlock value
Default:(automatic)
Context:server config, virtual host
Status:Extension
Module:mod_brotli
+

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

+ +
+
top
+

BrotliCompressionQuality Directive

+ + + + + + + +
Description:Compression quality
Syntax:BrotliCompressionQuality value
Default:BrotliCompressionQuality 5
Context:server config, virtual host
Status:Extension
Module:mod_brotli
+

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

+ +
+
top
+

BrotliCompressionWindow Directive

+ + + + + + + +
Description:Brotli sliding compression window size
Syntax:BrotliCompressionWindow value
Default:BrotliCompressionWindow 18
Context:server config, virtual host
Status:Extension
Module:mod_brotli
+

The BrotliCompressionWindow directive specifies the + brotli sliding compression window size (a value between 10 and 24). Larger + window sizes can improve compression quality, but require more memory.

+ +
+
top
+

BrotliFilterNote Directive

+ + + + + + +
Description:Places the compression ratio in a note for logging
Syntax:BrotliFilterNote [type] notename
Context:server config, virtual host
Status:Extension
Module:mod_brotli
+

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

See also

+ +
+
+
+

Available Languages:  en  | + fr 

+
top

Comments

Notice:
This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Libera.chat, or sent to our mailing lists.
+
+ \ No newline at end of file -- cgit v1.2.3