granicus.if.org Git - apache/blob - 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>
  36 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.4.26 and later.</td></tr></table>
  37 <h3>Summary</h3>
  38
  39     <p>The <code class="module"><a href="../mod/mod_brotli.html">mod_brotli</a></code> module provides
  40     the <code>BROTLI_COMPRESS</code> output filter that allows output from
  41     your server to be compressed using the brotli compression format before being sent to the client over
  42     the network. This module uses the Brotli library found at
  43     <a href="https://github.com/google/brotli">https://github.com/google/brotli</a>.</p>
  44 </div>
  45 <div id="quickview"><h3>Topics</h3>
  46 <ul id="topics">
  47 <li><img alt="" src="../images/down.gif" /> <a href="#recommended">Sample Configurations</a></li>
  48 <li><img alt="" src="../images/down.gif" /> <a href="#enable">Enabling Compression</a></li>
  49 <li><img alt="" src="../images/down.gif" /> <a href="#proxies">Dealing with proxy servers</a></li>
  50 <li><img alt="" src="../images/down.gif" /> <a href="#precompressed">Serving pre-compressed
  51 content</a></li>
  52 </ul><h3 class="directives">Directives</h3>
  53 <ul id="toc">
  54 <li><img alt="" src="../images/down.gif" /> <a href="#brotlialteretag">BrotliAlterETag</a></li>
  55 <li><img alt="" src="../images/down.gif" /> <a href="#brotlicompressionmaxinputblock">BrotliCompressionMaxInputBlock</a></li>
  56 <li><img alt="" src="../images/down.gif" /> <a href="#brotlicompressionquality">BrotliCompressionQuality</a></li>
  57 <li><img alt="" src="../images/down.gif" /> <a href="#brotlicompressionwindow">BrotliCompressionWindow</a></li>
  58 <li><img alt="" src="../images/down.gif" /> <a href="#brotlifilternote">BrotliFilterNote</a></li>
  59 </ul>
  60 <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>
  61 <ul class="seealso">
  62 <li><a href="../filter.html">Filters</a></li>
  63 <li><a href="#comments_section">Comments</a></li></ul></div>
  64 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  65 <div class="section">
  66 <h2><a name="recommended" id="recommended">Sample Configurations</a></h2>
  67     <div class="warning"><h3>Compression and TLS</h3>
  68         <p>Some web applications are vulnerable to an information disclosure
  69         attack when a TLS connection carries compressed data. For more
  70         information, review the details of the "BREACH" family of attacks.</p>
  71     </div>
  72     <p>This is a simple configuration that compresses common text-based content types.</p>
  73
  74     <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>
  75 </div>
  76
  77 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  78 <div class="section">
  79 <h2><a name="enable" id="enable">Enabling Compression</a></h2>
  80     <div class="warning"><h3>Compression and TLS</h3>
  81         <p>Some web applications are vulnerable to an information disclosure
  82         attack when a TLS connection carries compressed data. For more
  83         information, review the details of the "BREACH" family of attacks.</p>
  84     </div>
  85
  86     <h3><a name="output" id="output">Output Compression</a></h3>
  87       <p>Compression is implemented by the <code>BROTLI_COMPRESS</code>
  88       <a href="../filter.html">filter</a>. The following directive
  89       will enable compression for documents in the container where it
  90       is placed:</p>
  91
  92       <pre class="prettyprint lang-config">SetOutputFilter BROTLI_COMPRESS
  93 SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ no-brotli</pre>
  94
  95
  96       <p>If you want to restrict the compression to particular MIME types
  97       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
  98       enabling compression only for the html files of the Apache
  99       documentation:</p>
 100
 101       <pre class="prettyprint lang-config">&lt;Directory "/your-server-root/manual"&gt;
 102     AddOutputFilterByType BROTLI_COMPRESS text/html
 103 &lt;/Directory&gt;</pre>
 104
 105
 106       <div class="note"><h3>Note</h3>
 107         The <code>BROTLI_COMPRESS</code> filter is always inserted after RESOURCE
 108         filters like PHP or SSI. It never touches internal subrequests.
 109       </div>
 110       <div class="note"><h3>Note</h3>
 111         There is an environment variable <code>no-brotli</code>,
 112         set via <code class="directive"><a href="../mod/mod_env.html#setenv">SetEnv</a></code>, which
 113         will disable brotli compression for a particular request, even if
 114         it is supported by the client.
 115       </div>
 116
 117
 118
 119 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 120 <div class="section">
 121 <h2><a name="proxies" id="proxies">Dealing with proxy servers</a></h2>
 122
 123     <p>The <code class="module"><a href="../mod/mod_brotli.html">mod_brotli</a></code> module sends a <code>Vary:
 124     Accept-Encoding</code> HTTP response header to alert proxies that
 125     a cached response should be sent only to clients that send the
 126     appropriate <code>Accept-Encoding</code> request header.  This
 127     prevents compressed content from being sent to a client that will
 128     not understand it.</p>
 129
 130     <p>If you use some special exclusions dependent
 131     on, for example, the <code>User-Agent</code> header, you must
 132     manually configure an addition to the <code>Vary</code> header
 133     to alert proxies of the additional restrictions.  For example,
 134     in a typical configuration where the addition of the <code>BROTLI_COMPRESS</code>
 135     filter depends on the <code>User-Agent</code>, you should add:</p>
 136
 137     <pre class="prettyprint lang-config">Header append Vary User-Agent</pre>
 138
 139
 140     <p>If your decision about compression depends on other information
 141     than request headers (<em>e.g.</em> HTTP version), you have to set the
 142     <code>Vary</code> header to the value <code>*</code>. This prevents
 143     compliant proxies from caching entirely.</p>
 144
 145     <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">Header set Vary *</pre>
 146 </div>
 147 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 148 <div class="section">
 149 <h2><a name="precompressed" id="precompressed">Serving pre-compressed
 150 content</a></h2>
 151
 152     <p>Since <code class="module"><a href="../mod/mod_brotli.html">mod_brotli</a></code> re-compresses content each
 153     time a request is made, some performance benefit can be derived by
 154     pre-compressing the content and telling mod_brotli to serve them
 155     without re-compressing them. This may be accomplished using a
 156     configuration like the following:</p>
 157
 158     <pre class="prettyprint lang-config">&lt;IfModule mod_headers.c&gt;
 159     # Serve brotli compressed CSS files if they exist
 160     # and the client accepts brotli.
 161     RewriteCond "%{HTTP:Accept-encoding}" "br"
 162     RewriteCond "%{REQUEST_FILENAME}\.br" "-s"
 163     RewriteRule "^(.*)\.css"              "$1\.css\.br" [QSA]
 164
 165     # Serve brotli compressed JS files if they exist
 166     # and the client accepts brotli.
 167     RewriteCond "%{HTTP:Accept-encoding}" "br"
 168     RewriteCond "%{REQUEST_FILENAME}\.br" "-s"
 169     RewriteRule "^(.*)\.js"               "$1\.js\.br" [QSA]
 170
 171
 172     # Serve correct content types, and prevent double compression.
 173     RewriteRule "\.css\.br$" "-" [T=text/css,E=no-brotli:1]
 174     RewriteRule "\.js\.br$"  "-" [T=text/javascript,E=no-brotli:1]
 175
 176
 177     &lt;FilesMatch "(\.js\.br|\.css\.br)$"&gt;
 178       # Serve correct encoding type.
 179       Header append Content-Encoding br
 180
 181       # Force proxies to cache brotli &amp;
 182       # non-brotli css/js files separately.
 183       Header append Vary Accept-Encoding
 184     &lt;/FilesMatch&gt;
 185 &lt;/IfModule&gt;</pre>
 186
 187
 188 </div>
 189 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 190 <div class="directive-section"><h2><a name="BrotliAlterETag" id="BrotliAlterETag">BrotliAlterETag</a> <a name="brotlialteretag" id="brotlialteretag">Directive</a></h2>
 191 <table class="directive">
 192 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>How the outgoing ETag header should be modified during compression</td></tr>
 193 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BrotliAlterETag AddSuffix|NoChange|Remove</code></td></tr>
 194 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BrotliAlterETag AddSuffix</code></td></tr>
 195 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 196 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 197 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_brotli</td></tr>
 198 </table>
 199     <p>The <code class="directive">BrotliAlterETag</code> directive specifies
 200     how the ETag hader should be altered when a response is compressed.</p>
 201     <dl>
 202     <dt>AddSuffix</dt>
 203     <dd><p>Append the compression method onto the end of the ETag, causing
 204         compressed and uncompressed representations to have unique ETags.
 205         In another dynamic compression module, mod_deflate, this has been
 206         the default since 2.4.0. This setting prevents serving "HTTP Not
 207         Modified" (304) responses to conditional requests for compressed
 208         content.</p></dd>
 209     <dt>NoChange</dt>
 210     <dd><p>Don't change the ETag on a compressed response. In another dynamic
 211         compression module, mod_deflate, this has been the default prior to
 212         2.4.0. This setting does not satisfy the HTTP/1.1 property that all
 213         representations of the same resource have unique ETags. </p></dd>
 214     <dt>Remove</dt>
 215     <dd><p>Remove the ETag header from compressed responses. This prevents
 216         some conditional requests from being possible, but avoids the
 217         shortcomings of the preceding options.  </p></dd>
 218     </dl>
 219
 220 </div>
 221 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 222 <div class="directive-section"><h2><a name="BrotliCompressionMaxInputBlock" id="BrotliCompressionMaxInputBlock">BrotliCompressionMaxInputBlock</a> <a name="brotlicompressionmaxinputblock" id="brotlicompressionmaxinputblock">Directive</a></h2>
 223 <table class="directive">
 224 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum input block size</td></tr>
 225 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BrotliCompressionMaxInputBlock <var>value</var></code></td></tr>
 226 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>(automatic)</code></td></tr>
 227 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 228 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 229 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_brotli</td></tr>
 230 </table>
 231     <p>The <code class="directive">BrotliCompressionMaxInputBlock</code> directive specifies
 232     the maximum input block size between 16 and 24, with the caveat that
 233     larger block sizes require more memory.</p>
 234
 235 </div>
 236 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 237 <div class="directive-section"><h2><a name="BrotliCompressionQuality" id="BrotliCompressionQuality">BrotliCompressionQuality</a> <a name="brotlicompressionquality" id="brotlicompressionquality">Directive</a></h2>
 238 <table class="directive">
 239 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Compression quality</td></tr>
 240 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BrotliCompressionQuality <var>value</var></code></td></tr>
 241 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BrotliCompressionQuality 5</code></td></tr>
 242 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 243 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 244 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_brotli</td></tr>
 245 </table>
 246     <p>The <code class="directive">BrotliCompressionQuality</code> directive specifies
 247     the compression quality (a value between 0 and 11). Higher quality values
 248     result in better, but also slower compression.
 249   </p>
 250
 251 </div>
 252 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 253 <div class="directive-section"><h2><a name="BrotliCompressionWindow" id="BrotliCompressionWindow">BrotliCompressionWindow</a> <a name="brotlicompressionwindow" id="brotlicompressionwindow">Directive</a></h2>
 254 <table class="directive">
 255 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Brotli sliding compression window size</td></tr>
 256 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BrotliCompressionWindow <var>value</var></code></td></tr>
 257 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BrotliCompressionWindow 18</code></td></tr>
 258 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 259 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 260 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_brotli</td></tr>
 261 </table>
 262     <p>The <code class="directive">BrotliCompressionWindow</code> directive specifies the
 263     brotli sliding compression window size (a value between 10 and 24). Larger
 264     window sizes can improve compression quality, but require more memory.</p>
 265
 266 </div>
 267 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 268 <div class="directive-section"><h2><a name="BrotliFilterNote" id="BrotliFilterNote">BrotliFilterNote</a> <a name="brotlifilternote" id="brotlifilternote">Directive</a></h2>
 269 <table class="directive">
 270 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Places the compression ratio in a note for logging</td></tr>
 271 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BrotliFilterNote [<var>type</var>] <var>notename</var></code></td></tr>
 272 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 273 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 274 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_brotli</td></tr>
 275 </table>
 276     <p>The <code class="directive">BrotliFilterNote</code> directive
 277     specifies that a note about compression ratios should be attached
 278     to the request. The name of the note is the value specified for
 279     the directive. You can use that note for statistical purposes by
 280     adding the value to your <a href="../logs.html#accesslog">access log</a>.</p>
 281
 282     <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">BrotliFilterNote ratio
 283
 284 LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' brotli
 285 CustomLog "logs/brotli_log" brotli</pre>
 286 </div>
 287
 288     <p>If you want to extract more accurate values from your logs, you
 289     can use the <var>type</var> argument to specify the type of data
 290     left as a note for logging. <var>type</var> can be one of:</p>
 291
 292     <dl>
 293       <dt><code>Input</code></dt>
 294       <dd>Store the byte count of the filter's input stream in the note.</dd>
 295
 296       <dt><code>Output</code></dt>
 297       <dd>Store the byte count of the filter's output stream in the note.</dd>
 298
 299       <dt><code>Ratio</code></dt>
 300       <dd>Store the compression ratio (<code>output/input * 100</code>)
 301       in the note. This is the default, if the <var>type</var> argument
 302       is omitted.</dd>
 303     </dl>
 304
 305     <p>Thus you may log it this way:</p>
 306
 307     <div class="example"><h3>Accurate Logging</h3><pre class="prettyprint lang-config">BrotliFilterNote Input instream
 308 BrotliFilterNote Output outstream
 309 BrotliFilterNote Ratio ratio
 310
 311 LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' brotli
 312 CustomLog "logs/brotli_log" brotli</pre>
 313 </div>
 314
 315 <h3>See also</h3>
 316 <ul>
 317 <li><code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code></li>
 318 </ul>
 319 </div>
 320 </div>
 321 <div class="bottomlang">
 322 <p><span>Available Languages: </span><a href="../en/mod/mod_brotli.html" title="English">&nbsp;en&nbsp;</a></p>
 323 </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>
 324 <script type="text/javascript"><!--//--><![CDATA[//><!--
 325 var comments_shortname = 'httpd';
 326 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_brotli.html';
 327 (function(w, d) {
 328     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 329         d.write('<div id="comments_thread"><\/div>');
 330         var s = d.createElement('script');
 331         s.type = 'text/javascript';
 332         s.async = true;
 333         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 334         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 335     }
 336     else {
 337         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 338     }
 339 })(window, document);
 340 //--><!]]></script></div><div id="footer">
 341 <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>
 342 <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[//><!--
 343 if (typeof(prettyPrint) !== 'undefined') {
 344     prettyPrint();
 345 }
 346 //--><!]]></script>
 347 </body></html>