]> granicus.if.org Git - apache/blob - docs/manual/mod/mod_brotli.html.en
Xforms et.al.
[apache] / docs / manual / mod / mod_brotli.html.en
1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
4 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
5 <!--
6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
7               This file is generated from xml source: DO NOT EDIT
8         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
9       -->
10 <title>mod_brotli - Apache HTTP Server Version 2.5</title>
11 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
12 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
13 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
14 <script src="../style/scripts/prettify.min.js" type="text/javascript">
15 </script>
16
17 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
18 <body>
19 <div id="page-header">
20 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
21 <p class="apache">Apache HTTP Server Version 2.5</p>
22 <img alt="" src="../images/feather.png" /></div>
23 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
24 <div id="path">
25 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Modules</a></div>
26 <div id="page-content">
27 <div id="preamble"><h1>Apache Module mod_brotli</h1>
28 <div class="toplang">
29 <p><span>Available Languages: </span><a href="../en/mod/mod_brotli.html" title="English">&nbsp;en&nbsp;</a></p>
30 </div>
31 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Compress content via Brotli before it is delivered to the
32 client</td></tr>
33 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
34 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>brotli_module</td></tr>
35 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_brotli.c</td></tr></table>
36 <h3>Summary</h3>
37
38     <p>The <code class="module"><a href="../mod/mod_brotli.html">mod_brotli</a></code> module provides
39     the <code>BROTLI_COMPRESS</code> output filter that allows output from
40     your server to be compressed using the brotli compression format before being sent to the client over
41     the network.</p>
42 </div>
43 <div id="quickview"><h3>Topics</h3>
44 <ul id="topics">
45 <li><img alt="" src="../images/down.gif" /> <a href="#recommended">Sample Configurations</a></li>
46 <li><img alt="" src="../images/down.gif" /> <a href="#enable">Enabling Compression</a></li>
47 <li><img alt="" src="../images/down.gif" /> <a href="#proxies">Dealing with proxy servers</a></li>
48 <li><img alt="" src="../images/down.gif" /> <a href="#precompressed">Serving pre-compressed
49 content</a></li>
50 </ul><h3 class="directives">Directives</h3>
51 <ul id="toc">
52 <li><img alt="" src="../images/down.gif" /> <a href="#brotlialteretag">BrotliAlterETag</a></li>
53 <li><img alt="" src="../images/down.gif" /> <a href="#brotlicompressionmaxinputblock">BrotliCompressionMaxInputBlock</a></li>
54 <li><img alt="" src="../images/down.gif" /> <a href="#brotlicompressionquality">BrotliCompressionQuality</a></li>
55 <li><img alt="" src="../images/down.gif" /> <a href="#brotlicompressionwindow">BrotliCompressionWindow</a></li>
56 <li><img alt="" src="../images/down.gif" /> <a href="#brotlifilternote">BrotliFilterNote</a></li>
57 </ul>
58 <h3>Bugfix checklist</h3><ul class="seealso"><li><a href="https://www.apache.org/dist/httpd/CHANGES_2.4">httpd changelog</a></li><li><a href="https://bz.apache.org/bugzilla/buglist.cgi?bug_status=__open__&amp;list_id=144532&amp;product=Apache%20httpd-2&amp;query_format=specific&amp;order=changeddate%20DESC%2Cpriority%2Cbug_severity&amp;component=mod_brotli">Known issues</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&amp;component=mod_brotli">Report a bug</a></li></ul><h3>See also</h3>
59 <ul class="seealso">
60 <li><a href="../filter.html">Filters</a></li>
61 <li><a href="#comments_section">Comments</a></li></ul></div>
62 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
63 <div class="section">
64 <h2><a name="recommended" id="recommended">Sample Configurations</a></h2>
65     <div class="warning"><h3>Compression and TLS</h3>
66         <p>Some web applications are vulnerable to an information disclosure
67         attack when a TLS connection carries deflate compressed data. For more
68         information, review the details of the "BREACH" family of attacks.</p>
69     </div>
70     <p>This is a simple configuration that compresses common text-based content types.</p>
71
72     <div class="example"><h3>Compress only a few types</h3><pre class="prettyprint lang-config">AddOutputFilterByType BROTLI_COMPRESS text/html text/plain text/xml text/css text/javascript application/javascript</pre>
73 </div>
74
75 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
76 <div class="section">
77 <h2><a name="enable" id="enable">Enabling Compression</a></h2>
78     <div class="warning"><h3>Compression and TLS</h3>
79         <p>Some web applications are vulnerable to an information disclosure
80         attack when a TLS connection carries deflate compressed data. For more
81         information, review the details of the "BREACH" family of attacks.</p>
82     </div>
83
84     <h3><a name="output" id="output">Output Compression</a></h3>
85       <p>Compression is implemented by the <code>BROTLI_COMPRESS</code>
86       <a href="../filter.html">filter</a>. The following directive
87       will enable compression for documents in the container where it
88       is placed:</p>
89
90       <pre class="prettyprint lang-config">SetOutputFilter BROTLI_COMPRESS
91 SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ no-brotli</pre>
92
93
94       <p>If you want to restrict the compression to particular MIME types
95       in general, you may use the <code class="directive"><a href="../mod/mod_filter.html#addoutputfilterbytype">AddOutputFilterByType</a></code> directive. Here is an example of
96       enabling compression only for the html files of the Apache
97       documentation:</p>
98
99       <pre class="prettyprint lang-config">&lt;Directory "/your-server-root/manual"&gt;
100     AddOutputFilterByType BROTLI_COMPRESS text/html
101 &lt;/Directory&gt;</pre>
102
103
104       <div class="note"><h3>Note</h3>
105         The <code>BROTLI_COMPRESS</code> filter is always inserted after RESOURCE
106         filters like PHP or SSI. It never touches internal subrequests.
107       </div>
108       <div class="note"><h3>Note</h3>
109         There is an environment variable <code>no-brotli</code>,
110         set via <code class="directive"><a href="../mod/mod_env.html#setenv">SetEnv</a></code>, which
111         will ignore the accept-encoding setting of your browser and will
112         send compressed output.
113       </div>
114
115     
116
117     <h3><a name="input" id="input">Input Decompression</a></h3>
118       <p>The <code class="module"><a href="../mod/mod_brotli.html">mod_brotli</a></code> module also provides a filter for
119       decompressing a brotli compressed request body . In order to activate
120       this feature you have to insert the <code>BROTLI_COMPRESS</code> filter into
121       the input filter chain using <code class="directive"><a href="../mod/core.html#setinputfilter">SetInputFilter</a></code> or <code class="directive"><a href="../mod/mod_mime.html#addinputfilter">AddInputFilter</a></code>, for example:</p>
122
123       <pre class="prettyprint lang-config">&lt;Location "/dav-area"&gt;
124     SetInputFilter BROTLI_COMPRESS
125 &lt;/Location&gt;</pre>
126
127
128       <p>Now if a request contains a <code>Content-Encoding:
129       brotli</code> header, the body will be automatically decompressed.
130       Few browsers have the ability to brotli request bodies. However,
131       some special applications actually do support request
132       compression, for instance some <a href="http://www.webdav.org">WebDAV</a> clients.</p>
133
134       <div class="warning"><h3>Note on Content-Length</h3>
135         <p>If you evaluate the request body yourself, <em>don't trust
136         the <code>Content-Length</code> header!</em>
137         The Content-Length header reflects the length of the
138         incoming data from the client and <em>not</em> the byte count of
139         the decompressed data stream.</p>
140       </div>
141     
142 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
143 <div class="section">
144 <h2><a name="proxies" id="proxies">Dealing with proxy servers</a></h2>
145
146     <p>The <code class="module"><a href="../mod/mod_brotli.html">mod_brotli</a></code> module sends a <code>Vary:
147     Accept-Encoding</code> HTTP response header to alert proxies that
148     a cached response should be sent only to clients that send the
149     appropriate <code>Accept-Encoding</code> request header.  This
150     prevents compressed content from being sent to a client that will
151     not understand it.</p>
152
153     <p>If you use some special exclusions dependent
154     on, for example, the <code>User-Agent</code> header, you must
155     manually configure an addition to the <code>Vary</code> header
156     to alert proxies of the additional restrictions.  For example,
157     in a typical configuration where the addition of the <code>DEFLATE</code>
158     filter depends on the <code>User-Agent</code>, you should add:</p>
159
160     <pre class="prettyprint lang-config">Header append Vary User-Agent</pre>
161
162
163     <p>If your decision about compression depends on other information
164     than request headers (<em>e.g.</em> HTTP version), you have to set the
165     <code>Vary</code> header to the value <code>*</code>. This prevents
166     compliant proxies from caching entirely.</p>
167
168     <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">Header set Vary *</pre>
169 </div>
170 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
171 <div class="section">
172 <h2><a name="precompressed" id="precompressed">Serving pre-compressed
173 content</a></h2>
174
175     <p>Since <code class="module"><a href="../mod/mod_brotli.html">mod_brotli</a></code> re-compresses content each
176     time a request is made, some performance benefit can be derived by
177     pre-compressing the content and telling mod_brotli to serve them
178     without re-compressing them. This may be accomplished using a
179     configuration like the following:</p>
180
181     <pre class="prettyprint lang-config">&lt;IfModule mod_headers.c&gt;
182     # Serve brotli compressed CSS files if they exist
183     # and the client accepts brotli.
184     RewriteCond "%{HTTP:Accept-encoding}" "brotli"
185     RewriteCond "%{REQUEST_FILENAME}\.br" "-s"
186     RewriteRule "^(.*)\.css"              "$1\.css\.br" [QSA]
187
188     # Serve brotli compressed JS files if they exist
189     # and the client accepts brotli.
190     RewriteCond "%{HTTP:Accept-encoding}" "brotli"
191     RewriteCond "%{REQUEST_FILENAME}\.br" "-s"
192     RewriteRule "^(.*)\.js"               "$1\.js\.br" [QSA]
193
194
195     # Serve correct content types, and prevent mod_brotli double brotli.
196     RewriteRule "\.css\.gz$" "-" [T=text/css,E=no-brotli:1]
197     RewriteRule "\.js\.gz$"  "-" [T=text/javascript,E=no-brotli:1]
198
199
200     &lt;FilesMatch "(\.js\.gz|\.css\.gz)$"&gt;
201       # Serve correct encoding type.
202       Header append Content-Encoding brotli
203
204       # Force proxies to cache brotli &amp;
205       # non-brotli css/js files separately.
206       Header append Vary Accept-Encoding
207     &lt;/FilesMatch&gt;
208 &lt;/IfModule&gt;</pre>
209
210
211 </div>
212 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
213 <div class="directive-section"><h2><a name="BrotliAlterETag" id="BrotliAlterETag">BrotliAlterETag</a> <a name="brotlialteretag" id="brotlialteretag">Directive</a></h2>
214 <table class="directive">
215 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>How the outgoing ETag header should be modified during compression</td></tr>
216 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BrotliAlterETag AddSuffix|NoChange|Remove</code></td></tr>
217 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BrotliAlterETag AddSuffix</code></td></tr>
218 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
219 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
220 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_brotli</td></tr>
221 </table>
222     <p>The <code class="directive">BrotliAlterETag</code> directive specifies
223     how the ETag hader should be altered when a response is compressed.</p>
224     <dl>
225     <dt>AddSuffix</dt>
226     <dd><p>Append the compression method onto the end of the ETag, causing
227         compressed and uncompressed representations to have unique ETags.
228         This has been the default since 2.4.0, but prevents serving
229         "HTTP Not Modified" (304) responses to conditional requests for
230         compressed content.</p></dd>
231     <dt>NoChange</dt>
232     <dd><p>Don't change the ETag on a compressed response. This was the default
233         prior to 2.4.0, but does not satisfy the HTTP/1.1 property that all
234         representations of the same resource have unique ETags. </p></dd>
235     <dt>Remove</dt>
236     <dd><p>Remove the ETag header from compressed responses. This prevents
237         some conditional requests from being possible, but avoids the
238         shortcomings of the preceding options.  </p></dd>
239     </dl>
240
241 </div>
242 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
243 <div class="directive-section"><h2><a name="BrotliCompressionMaxInputBlock" id="BrotliCompressionMaxInputBlock">BrotliCompressionMaxInputBlock</a> <a name="brotlicompressionmaxinputblock" id="brotlicompressionmaxinputblock">Directive</a></h2>
244 <table class="directive">
245 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum input block size</td></tr>
246 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BrotliCompressionMaxInputBlock <var>value</var></code></td></tr>
247 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BrotliCompressionMaxInputBlock 0</code></td></tr>
248 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
249 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
250 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_brotli</td></tr>
251 </table>
252     <p>The <code class="directive">BrotliCompressionMaxInputBlock</code> directive specifies
253     the maximum input block size between 16 and 24, with the caveat that
254     larger block sizes require more memory.</p>
255
256 </div>
257 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
258 <div class="directive-section"><h2><a name="BrotliCompressionQuality" id="BrotliCompressionQuality">BrotliCompressionQuality</a> <a name="brotlicompressionquality" id="brotlicompressionquality">Directive</a></h2>
259 <table class="directive">
260 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Compression quality</td></tr>
261 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BrotliCompressionQuality <var>value</var></code></td></tr>
262 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BrotliCompressionQuality 5</code></td></tr>
263 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
264 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
265 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_brotli</td></tr>
266 </table>
267     <p>The <code class="directive">BrotliCompressionQuality</code> directive specifies
268     the compression quality performed (a value between 0 and 11). Higher
269     quality values result in better compression but also slower compression
270     as well.
271   </p>
272
273 </div>
274 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
275 <div class="directive-section"><h2><a name="BrotliCompressionWindow" id="BrotliCompressionWindow">BrotliCompressionWindow</a> <a name="brotlicompressionwindow" id="brotlicompressionwindow">Directive</a></h2>
276 <table class="directive">
277 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Brotli sliding compression window size</td></tr>
278 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BrotliCompressionWindow <var>value</var></code></td></tr>
279 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BrotliCompressionWindow 18</code></td></tr>
280 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
281 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
282 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_brotli</td></tr>
283 </table>
284     <p>The <code class="directive">BrotliCompressionWindow</code> directive specifies the
285     brotli sliding compression window size (a value between 10 and 24). Generally, the
286     higher the window size, the higher can the compression ratio be expected
287     but requires more memory.</p>
288
289 </div>
290 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
291 <div class="directive-section"><h2><a name="BrotliFilterNote" id="BrotliFilterNote">BrotliFilterNote</a> <a name="brotlifilternote" id="brotlifilternote">Directive</a></h2>
292 <table class="directive">
293 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Places the compression ratio in a note for logging</td></tr>
294 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BrotliFilterNote [<var>type</var>] <var>notename</var></code></td></tr>
295 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
296 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
297 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_brotli</td></tr>
298 </table>
299     <p>The <code class="directive">BrotliFilterNote</code> directive
300     specifies that a note about compression ratios should be attached
301     to the request. The name of the note is the value specified for
302     the directive. You can use that note for statistical purposes by
303     adding the value to your <a href="../logs.html#accesslog">access log</a>.</p>
304
305     <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">      BrotliFilterNote ratio
306
307       LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' brotli
308       CustomLog "logs/brotli_log" brotli</pre>
309 </div>
310
311     <p>If you want to extract more accurate values from your logs, you
312     can use the <var>type</var> argument to specify the type of data
313     left as a note for logging. <var>type</var> can be one of:</p>
314
315     <dl>
316       <dt><code>Input</code></dt>
317       <dd>Store the byte count of the filter's input stream in the note.</dd>
318
319       <dt><code>Output</code></dt>
320       <dd>Store the byte count of the filter's output stream in the note.</dd>
321
322       <dt><code>Ratio</code></dt>
323       <dd>Store the compression ratio (<code>output/input * 100</code>)
324       in the note. This is the default, if the <var>type</var> argument
325       is omitted.</dd>
326     </dl>
327
328     <p>Thus you may log it this way:</p>
329
330     <div class="example"><h3>Accurate Logging</h3><pre class="prettyprint lang-config">BrotliFilterNote Input instream
331 BrotliFilterNote Output outstream
332 BrotliFilterNote Ratio ratio
333
334 LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' brotli
335 CustomLog "logs/brotli_log" brotli</pre>
336 </div>
337
338 <h3>See also</h3>
339 <ul>
340 <li><code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code></li>
341 </ul>
342 </div>
343 </div>
344 <div class="bottomlang">
345 <p><span>Available Languages: </span><a href="../en/mod/mod_brotli.html" title="English">&nbsp;en&nbsp;</a></p>
346 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again 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 Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
347 <script type="text/javascript"><!--//--><![CDATA[//><!--
348 var comments_shortname = 'httpd';
349 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_brotli.html';
350 (function(w, d) {
351     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
352         d.write('<div id="comments_thread"><\/div>');
353         var s = d.createElement('script');
354         s.type = 'text/javascript';
355         s.async = true;
356         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
357         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
358     }
359     else {
360         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
361     }
362 })(window, document);
363 //--><!]]></script></div><div id="footer">
364 <p class="apache">Copyright 2017 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
365 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
366 if (typeof(prettyPrint) !== 'undefined') {
367     prettyPrint();
368 }
369 //--><!]]></script>
370 </body></html>