granicus.if.org Git - apache/blob - docs/manual/mod/mod_http2.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_http2 - 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_http2</h1>
  28 <div class="toplang">
  29 <p><span>Available Languages: </span><a href="../en/mod/mod_http2.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>Support for the HTTP/2 transport layer</td></tr>
  32 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  33 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>http2_module</td></tr>
  34 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_http2.c</td></tr>
  35 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.4.17 and later</td></tr></table>
  36 <h3>Summary</h3>
  37
  38         <p>This module provides HTTP/2 (<a href="https://tools.ietf.org/html/rfc7540">RFC 7540</a>)
  39         support for the Apache HTTP Server.</p>
  40
  41         <p>This module relies on <a href="http://nghttp2.org/">libnghttp2</a>
  42         to provide the core http/2 engine.</p>
  43
  44         <div class="warning"><h3>Warning</h3>
  45             <p>This module is experimental. Its behaviors, directives, and
  46                 defaults are subject to more change from release to
  47                 release relative to other standard modules. Users are encouraged to
  48                 consult the "CHANGES" file for potential updates.</p>
  49         </div>
  50
  51         <p>You must enable HTTP/2 via <code class="directive"><a href="../mod/core.html#protocols">Protocols</a></code>
  52         in order to use the functionality described in this document. The
  53         HTTP/2 protocol <a href="https://http2.github.io/faq/#does-http2-require-encryption">does not require</a> the use of encryption so two schemes are available:
  54         <code>h2</code> (HTTP/2 over TLS) and <code>h2c</code> (HTTP/2 over TCP).</p>
  55
  56         <p>Two useful configuration schemes are:</p>
  57
  58         <div class="note"><h3>HTTP/2 in a VirtualHost context (TLS only)</h3>
  59         <pre class="prettyprint lang-config">Protocols h2 http/1.1</pre>
  60
  61         <p>Allows HTTP/2 negotiation (h2) via TLS ALPN in a secure
  62         <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</a></code>.
  63         HTTP/2 preamble checking (Direct mode, see <code class="directive"><a href="#h2direct">H2Direct</a></code>) is disabled by default for <code>h2</code>.</p>
  64         </div>
  65
  66         <div class="note"><h3>HTTP/2 in a Server context (TLS and cleartext)</h3>
  67         <pre class="prettyprint lang-config">Protocols h2 h2c http/1.1</pre>
  68
  69         <p>Allows HTTP/2 negotiation (h2) via TLS ALPN for secure
  70         <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</a></code>. Allows
  71         HTTP/2 cleartext negotiation (h2c) upgrading from an initial HTTP/1.1
  72         connection or via HTTP/2 preamble checking (Direct mode, see
  73         <code class="directive"><a href="#h2direct">H2Direct</a></code>).</p>
  74         </div>
  75
  76         <p>Refer to the official <a href="https://http2.github.io/faq">HTTP/2 FAQ</a>
  77         for any doubt about the protocol.</p>
  78
  79     </div>
  80 <div id="quickview"><h3>Topics</h3>
  81 <ul id="topics">
  82 <li><img alt="" src="../images/down.gif" /> <a href="#how-it-works">How it works</a></li>
  83 </ul><h3 class="directives">Directives</h3>
  84 <ul id="toc">
  85 <li><img alt="" src="../images/down.gif" /> <a href="#h2direct">H2Direct</a></li>
  86 <li><img alt="" src="../images/down.gif" /> <a href="#h2maxsessionstreams">H2MaxSessionStreams</a></li>
  87 <li><img alt="" src="../images/down.gif" /> <a href="#h2maxworkeridleseconds">H2MaxWorkerIdleSeconds</a></li>
  88 <li><img alt="" src="../images/down.gif" /> <a href="#h2maxworkers">H2MaxWorkers</a></li>
  89 <li><img alt="" src="../images/down.gif" /> <a href="#h2minworkers">H2MinWorkers</a></li>
  90 <li><img alt="" src="../images/down.gif" /> <a href="#h2moderntlsonly">H2ModernTLSOnly</a></li>
  91 <li><img alt="" src="../images/down.gif" /> <a href="#h2push">H2Push</a></li>
  92 <li><img alt="" src="../images/down.gif" /> <a href="#h2pushdiarysize">H2PushDiarySize</a></li>
  93 <li><img alt="" src="../images/down.gif" /> <a href="#h2pushpriority">H2PushPriority</a></li>
  94 <li><img alt="" src="../images/down.gif" /> <a href="#h2serializeheaders">H2SerializeHeaders</a></li>
  95 <li><img alt="" src="../images/down.gif" /> <a href="#h2sessionextrafiles">H2SessionExtraFiles</a></li>
  96 <li><img alt="" src="../images/down.gif" /> <a href="#h2streammaxmemsize">H2StreamMaxMemSize</a></li>
  97 <li><img alt="" src="../images/down.gif" /> <a href="#h2tlscooldownsecs">H2TLSCoolDownSecs</a></li>
  98 <li><img alt="" src="../images/down.gif" /> <a href="#h2tlswarmupsize">H2TLSWarmUpSize</a></li>
  99 <li><img alt="" src="../images/down.gif" /> <a href="#h2upgrade">H2Upgrade</a></li>
 100 <li><img alt="" src="../images/down.gif" /> <a href="#h2windowsize">H2WindowSize</a></li>
 101 </ul>
 102 <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_http2">Known issues</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&amp;component=mod_http2">Report a bug</a></li></ul><h3>See also</h3>
 103 <ul class="seealso">
 104 <li><a href="#comments_section">Comments</a></li></ul></div>
 105 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 106 <div class="section">
 107 <h2><a name="how-it-works" id="how-it-works">How it works</a></h2>
 108
 109     <h3><a name="dimensioning" id="dimensioning">HTTP/2 Dimensioning</a></h3>
 110         <p>
 111             Enabling HTTP/2 on your Apache Server has impact on the resource
 112             consumption and if you have a busy site, you may need to consider
 113             carefully the implications.
 114         </p>
 115         <p>
 116             The first noticeable thing after enabling HTTP/2 is that your server
 117             processes will start additional threads. The reason for this is that
 118             HTTP/2 gives all requests that it receives to its own <em>Worker</em>
 119             threads for processing, collects the results and streams them out
 120             to the client.
 121         </p>
 122         <p>
 123             In the current implementation, these workers use a separate thread
 124             pool from the MPM workers that you might be familiar with. This is
 125             just how things are right now and not intended to be like this forever.
 126             (It might be forever for the 2.4.x release line, though.) So, HTTP/2
 127             workers, or shorter H2Workers, will not show up in <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>. They
 128             are also not counted against directives such as <code class="directive"><a href="../mod/mpm_common.html#threadsperchild">ThreadsPerChild</a></code>. However
 129             they take <code class="directive"><a href="../mod/mpm_common.html#threadsperchild">ThreadsPerChild</a></code>
 130             as default if you have not configured something
 131             else via <code class="directive"><a href="#h2minworkers">H2MinWorkers</a></code> and
 132             <code class="directive"><a href="#h2maxworkers">H2MaxWorkers</a></code>.
 133         </p>
 134         <p>
 135             Another thing to watch out for is is memory consumption. Since HTTP/2
 136             keeps more state on the server to manage all the open request, priorities
 137             for and dependencies between them, it will always need more memory
 138             than HTTP/1.1 processing. There are three directives which steer the
 139             memory footprint of a HTTP/2 connection:
 140             <code class="directive"><a href="#h2maxsessionstreams">H2MaxSessionStreams</a></code>,
 141             <code class="directive"><a href="#h2windowsize">H2WindowSize</a></code> and
 142             <code class="directive"><a href="#h2streammaxmemsize">H2StreamMaxMemSize</a></code>.
 143         </p>
 144         <p>
 145             <code class="directive"><a href="#h2maxsessionstreams">H2MaxSessionStreams</a></code> limits the
 146             number of parallel requests that a client can make on a HTTP/2 connection.
 147             It depends on your site how many you should allow. The default is 100 which
 148             is plenty and unless you run into memory problems, I would keep it this
 149             way. Most requests that browsers send are GETs without a body, so they
 150             use up only a little bit of memory until the actual processing starts.
 151         </p>
 152         <p>
 153             <code class="directive"><a href="#h2windowsize">H2WindowSize</a></code> controls how much
 154             the client is allowed to send as body of a request, before it waits
 155             for the server to encourage more. Or, the other way around, it is the
 156             amount of request body data the server needs to be able to buffer. This
 157             is per request.
 158         </p>
 159         <p>
 160             And last, but not least, <code class="directive"><a href="#h2streammaxmemsize">H2StreamMaxMemSize</a></code>
 161             controls how much response data shall be buffered. The request sits in
 162             a H2Worker thread and is producing data, the HTTP/2 connection tries
 163             to send this to the client. If the client does not read fast enough,
 164             the connection will buffer this amount of data and then suspend the
 165             H2Worker.
 166         </p>
 167         <p>
 168             If you serve a lot of static files, <code class="directive"><a href="#h2sessionextrafiles">H2SessionExtraFiles</a></code>
 169             is of interest. This tells the server how many file handles per
 170             HTTP/2 connection it is allowed to waste for better performance. Because
 171             when a request produces a static file as the response, the file handle
 172             gets passed around and is buffered and not the file contents. That allows
 173             to serve many large files without wasting memory or copying data
 174             unnecessarily. However file handles are a limited resource for a process,
 175             and if too many are used this way, requests may fail under load as
 176             the amount of open handles has been exceeded.
 177         </p>
 178
 179
 180     <h3><a name="misdirected" id="misdirected">Multiple Hosts and Misdirected Requests</a></h3>
 181         <p>
 182             Many sites use the same TLS certificate for multiple virtual hosts. The
 183             certificate either has a wildcard name, such as '*.example.org' or carries
 184             several alternate names. Browsers using HTTP/2 will recognize that and reuse
 185             an already opened connection for such hosts.
 186         </p>
 187         <p>
 188             While this is great for performance, it comes at a price: such vhosts
 189             need more care in their configuration. The problem is that you will have
 190             multiple requests for multiple hosts on the same TLS connection. And that
 191             makes renegotiation impossible, in face the HTTP/2 standard forbids it.
 192         </p>
 193         <p>
 194             So, if you have several virtual hosts using the same certificate and
 195             want to use HTTP/2 for them, you need to make sure that all vhosts have
 196             exactly the same SSL configuration. You need the same protocol,
 197             ciphers and settings for client verification.
 198         </p>
 199         <p>
 200             If you mix things, Apache httpd will detect it and return a special
 201             response code, 421 Misdirected Request, to the client.
 202         </p>
 203
 204
 205     <h3><a name="envvars" id="envvars">Environment Variables</a></h3>
 206         <p>
 207             This module can be configured to provide HTTP/2 related information
 208             as additional environment variables to the SSI and CGI namespace, as well
 209             as in custom log configurations (see <code>%{VAR_NAME}e</code>).
 210         </p>
 211
 212         <table class="bordered">
 213
 214             <tr>
 215                 <th><a name="table3">Variable Name:</a></th>
 216                 <th>Value Type:</th>
 217                 <th>Description:</th>
 218             </tr>
 219             <tr><td><code>HTTP2</code></td><td>flag</td><td>HTTP/2 is being used.</td></tr>
 220             <tr><td><code>H2PUSH</code></td><td>flag</td><td>HTTP/2 Server Push is enabled for this connection and also supported by the client.</td></tr>
 221             <tr><td><code>H2_PUSH</code></td><td>flag</td><td>alternate name for <code>H2PUSH</code></td></tr>
 222             <tr><td><code>H2_PUSHED</code></td><td>string</td><td>empty or <code>PUSHED</code> for a request being pushed by the server.</td></tr>
 223             <tr><td><code>H2_PUSHED_ON</code></td><td>number</td><td>HTTP/2 stream number that triggered the push of this request.</td></tr>
 224             <tr><td><code>H2_STREAM_ID</code></td><td>number</td><td>HTTP/2 stream number of this request.</td></tr>
 225             <tr><td><code>H2_STREAM_TAG</code></td><td>string</td><td>HTTP/2 process unique stream identifier, consisting of connection id and stream id separated by <code>-</code>.</td></tr>
 226         </table>
 227
 228
 229     </div>
 230 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 231 <div class="directive-section"><h2><a name="H2Direct" id="H2Direct">H2Direct</a> <a name="h2direct" id="h2direct">Directive</a></h2>
 232 <table class="directive">
 233 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>H2 Direct Protocol Switch</td></tr>
 234 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2Direct on|off</code></td></tr>
 235 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>H2Direct on for h2c, off for h2 protocol</code></td></tr>
 236 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 237 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 238 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
 239 </table>
 240             <p>
 241                 This directive toggles the usage of the HTTP/2 Direct Mode. This
 242                 should be used inside a
 243                 <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</a></code>
 244                 section to enable direct HTTP/2 communication for that virtual host.
 245             </p>
 246             <p>
 247                 Direct communication means that if the first bytes received by the
 248                 server on a connection match the HTTP/2 preamble, the HTTP/2
 249                 protocol is switched to immediately without further negotiation.
 250                 This mode is defined in RFC 7540 for the cleartext (h2c) case. Its
 251                 use on TLS connections not mandated by the standard.
 252             </p>
 253             <p>
 254                 When a server/vhost does not have h2 or h2c enabled via
 255                 <code class="directive"><a href="../mod/core.html#protocols">Protocols</a></code>,
 256                 the connection is never inspected for a HTTP/2 preamble.
 257                 <code class="directive">H2Direct</code>
 258                 does not matter then. This is important for connections that
 259                 use protocols where an initial read might hang indefinitely, such
 260                 as NNTP.
 261             </p>
 262             <p>
 263                 For clients that have out-of-band knowledge about a server
 264                 supporting h2c, direct HTTP/2 saves the client from having to
 265                 perform an HTTP/1.1 upgrade, resulting in better performance
 266                 and avoiding the Upgrade restrictions on request bodies.
 267             </p>
 268             <p>
 269                 This makes direct h2c attractive for server to server communication
 270                 as well, when the connection can be trusted or is secured by other means.
 271             </p>
 272             <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">H2Direct on</pre>
 273 </div>
 274
 275 </div>
 276 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 277 <div class="directive-section"><h2><a name="H2MaxSessionStreams" id="H2MaxSessionStreams">H2MaxSessionStreams</a> <a name="h2maxsessionstreams" id="h2maxsessionstreams">Directive</a></h2>
 278 <table class="directive">
 279 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum number of active streams per HTTP/2 session.</td></tr>
 280 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2MaxSessionStreams <em>n</em></code></td></tr>
 281 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>H2MaxSessionStreams 100</code></td></tr>
 282 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 283 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 284 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
 285 </table>
 286             <p>
 287                 This directive sets the maximum number of active streams per HTTP/2 session (e.g. connection)
 288                 that the server allows. A stream is active if it is not <code>idle</code> or
 289                 <code>closed</code> according to RFC 7540.
 290             </p>
 291             <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">H2MaxSessionStreams 20</pre>
 292 </div>
 293
 294 </div>
 295 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 296 <div class="directive-section"><h2><a name="H2MaxWorkerIdleSeconds" id="H2MaxWorkerIdleSeconds">H2MaxWorkerIdleSeconds</a> <a name="h2maxworkeridleseconds" id="h2maxworkeridleseconds">Directive</a></h2>
 297 <table class="directive">
 298 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum number of seconds h2 workers remain idle until shut down.</td></tr>
 299 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2MaxWorkerIdleSeconds <em>n</em></code></td></tr>
 300 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>H2MaxWorkerIdleSeconds 600</code></td></tr>
 301 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
 302 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 303 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
 304 </table>
 305             <p>
 306                 This directive sets the maximum number of seconds a h2 worker may
 307                 idle until it shuts itself down. This only happens while the number of
 308                 h2 workers exceeds <code class="directive"><a href="#h2minworkers">H2MinWorkers</a></code>.
 309             </p>
 310             <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">H2MaxWorkerIdleSeconds 20</pre>
 311 </div>
 312
 313 </div>
 314 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 315 <div class="directive-section"><h2><a name="H2MaxWorkers" id="H2MaxWorkers">H2MaxWorkers</a> <a name="h2maxworkers" id="h2maxworkers">Directive</a></h2>
 316 <table class="directive">
 317 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum number of worker threads to use per child process.</td></tr>
 318 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2MaxWorkers <em>n</em></code></td></tr>
 319 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
 320 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 321 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
 322 </table>
 323             <p>
 324                 This directive sets the maximum number of worker threads to spawn
 325                 per child process for HTTP/2 processing. If this directive is not used,
 326                 <code class="module"><a href="../mod/mod_http2.html">mod_http2</a></code> will chose a value suitable for the <code>mpm</code>
 327                 module loaded.
 328             </p>
 329             <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">H2MaxWorkers 20</pre>
 330 </div>
 331
 332 </div>
 333 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 334 <div class="directive-section"><h2><a name="H2MinWorkers" id="H2MinWorkers">H2MinWorkers</a> <a name="h2minworkers" id="h2minworkers">Directive</a></h2>
 335 <table class="directive">
 336 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Minimal number of worker threads to use per child process.</td></tr>
 337 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2MinWorkers <em>n</em></code></td></tr>
 338 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
 339 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 340 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
 341 </table>
 342             <p>
 343                 This directive sets the minimum number of worker threads to spawn
 344                 per child process for HTTP/2 processing. If this directive is not used,
 345                 <code class="module"><a href="../mod/mod_http2.html">mod_http2</a></code> will chose a value suitable for the <code>mpm</code>
 346                 module loaded.
 347             </p>
 348             <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">H2MinWorkers 10</pre>
 349 </div>
 350
 351 </div>
 352 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 353 <div class="directive-section"><h2><a name="H2ModernTLSOnly" id="H2ModernTLSOnly">H2ModernTLSOnly</a> <a name="h2moderntlsonly" id="h2moderntlsonly">Directive</a></h2>
 354 <table class="directive">
 355 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Require HTTP/2 connections to be "modern TLS" only</td></tr>
 356 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2ModernTLSOnly on|off</code></td></tr>
 357 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>H2ModernTLSOnly on</code></td></tr>
 358 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 359 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 360 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
 361 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.4.18 and later.</td></tr>
 362 </table>
 363             <p>
 364                 This directive toggles the security checks on HTTP/2 connections
 365                 in TLS mode (https:). This can be used server wide or for specific
 366                 <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</a></code>s.
 367             </p>
 368             <p>
 369                 The security checks require that the TSL protocol is at least
 370                 TLSv1.2 and that none of the ciphers listed in RFC 7540, Appendix A
 371                 is used. These checks will be extended once new security requirements
 372                 come into place.
 373             </p>
 374             <p>
 375                 The name stems from the
 376                 <a href="https://wiki.mozilla.org/Security/Server_Side_TLS">Security/Server Side TLS</a>
 377                 definitions at mozilla where "modern compatibility" is defined. Mozilla Firefox and
 378                 other browsers require modern compatibility for HTTP/2 connections. As everything
 379                 in OpSec, this is a moving target and can be expected to evolve in the future.
 380             </p>
 381             <p>
 382                 One purpose of having these checks in <code class="module"><a href="../mod/mod_http2.html">mod_http2</a></code> is to enforce this
 383                 security level for all connections, not only those from browsers. The other
 384                 purpose is to prevent the negotiation of HTTP/2 as a protocol should
 385                 the requirements not be met.
 386             </p>
 387             <p>
 388                 Ultimately, the security of the TLS connection is determined by the
 389                 server configuration directives for <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code>.
 390             </p>
 391             <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">H2ModernTLSOnly off</pre>
 392 </div>
 393
 394 </div>
 395 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 396 <div class="directive-section"><h2><a name="H2Push" id="H2Push">H2Push</a> <a name="h2push" id="h2push">Directive</a></h2>
 397 <table class="directive">
 398 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>H2 Server Push Switch</td></tr>
 399 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2Push on|off</code></td></tr>
 400 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>H2Push on</code></td></tr>
 401 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 402 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 403 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
 404 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.4.18 and later.</td></tr>
 405 </table>
 406             <p>
 407                 This directive toggles the usage of the HTTP/2 server push
 408                 protocol feature. This should be used inside a
 409                 <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</a></code>
 410                 section to enable direct HTTP/2 communication for that virtual host.
 411             </p>
 412             <p>
 413                 The HTTP/2 protocol allows the server to push other resources to
 414                 a client when it asked for a particular one. This is helpful
 415                 if those resources are connected in some way and the client can
 416                 be expected to ask for it anyway. The pushing then saves the
 417                 time it takes the client to ask for the resources itself. On the
 418                 other hand, pushing resources the client never needs or already
 419                 has is a waste of bandwidth.
 420             </p>
 421             <p>
 422                 Server pushes are detected by inspecting the <code>Link</code> headers of
 423                 responses (see https://tools.ietf.org/html/rfc5988 for the
 424                 specification). When a link thus specified has the <code>rel=preload</code>
 425                 attribute, it is treated as a resource to be pushed.
 426             </p>
 427             <p>
 428                 Link headers in responses are either set by the application or
 429                 can be configured via <code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code> as:
 430             </p>
 431             <div class="example"><h3>mod_headers example</h3><pre class="prettyprint lang-config">&lt;Location /index.html&gt;
 432     Header add Link "&lt;/css/site.css&gt;;rel=preload"
 433     Header add Link "&lt;/images/logo.jpg&gt;;rel=preload"
 434 &lt;/Location&gt;</pre>
 435 </div>
 436             <p>
 437                 As the example shows, there can be several link headers added
 438                 to a response, resulting in several pushes being triggered. There
 439                 are no checks in the module to avoid pushing the same resource
 440                 twice or more to one client. Use with care.
 441             </p>
 442             <p>
 443                 HTTP/2 server pushes are enabled by default. This directive
 444                 allows it to be switch off on all resources of this server/virtual
 445                 host.
 446             </p>
 447             <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">H2Push off</pre>
 448 </div>
 449             <p>
 450                 Last but not least, pushes happen only when the client signals
 451                 its willingness to accept those. Most browsers do, some, like Safari 9,
 452                 do not. Also, pushes also only happen for resources from the same
 453                 <em>authority</em> as the original response is for.
 454             </p>
 455
 456 </div>
 457 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 458 <div class="directive-section"><h2><a name="H2PushDiarySize" id="H2PushDiarySize">H2PushDiarySize</a> <a name="h2pushdiarysize" id="h2pushdiarysize">Directive</a></h2>
 459 <table class="directive">
 460 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>H2 Server Push Diary Size</td></tr>
 461 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2PushDiarySize <em>n</em></code></td></tr>
 462 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>H2PushDiarySize 256</code></td></tr>
 463 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 464 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 465 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
 466 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.4.19 and later.</td></tr>
 467 </table>
 468             <p>
 469                 This directive toggles the maximum number of HTTP/2 server pushes
 470                 that are remembered per HTTP/2 connection. This can be used inside the
 471                 <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</a></code>
 472                 section to influence the number for all connections to that virtual host.
 473             </p>
 474             <p>
 475                 The push diary records a digest (currently using a 64 bit number) of pushed
 476                 resources (their URL) to avoid duplicate pushes on the same connection.
 477                 These value are not persisted, so clients opening a new connection
 478                 will experience known pushes again. There is ongoing work to enable
 479                 a client to disclose a digest of the resources it already has, so
 480                 the diary maybe initialized by the client on each connection setup.
 481             </p>
 482             <p>
 483                 If the maximum size is reached, newer entries replace the oldest
 484                 ones. A diary entry uses 8 bytes, letting a
 485                 default diary with 256 entries consume around 2 KB of memory.
 486             </p>
 487             <p>
 488                 A size of 0 will effectively disable the push diary.
 489             </p>
 490
 491 </div>
 492 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 493 <div class="directive-section"><h2><a name="H2PushPriority" id="H2PushPriority">H2PushPriority</a> <a name="h2pushpriority" id="h2pushpriority">Directive</a></h2>
 494 <table class="directive">
 495 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>H2 Server Push Priority</td></tr>
 496 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2PushPriority <em>mime-type</em> [after|before|interleaved] [weight]</code></td></tr>
 497 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>H2PushPriority * After 16</code></td></tr>
 498 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 499 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 500 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
 501 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.4.18 and later. For having an
 502             effect, a nghttp2 library version 1.5.0 or newer is necessary.</td></tr>
 503 </table>
 504             <p>
 505                 This directive defines the priority handling of pushed responses
 506                 based on the content-type of the response. This is usually defined
 507                 per server config, but may also appear in a virtual host.
 508             </p>
 509             <p>
 510                 HTTP/2 server pushes are always related to a client request. Each
 511                 such request/response pairs, or <em>streams</em> have a dependency
 512                 and a weight, together defining the <em>priority</em> of a stream.
 513             </p>
 514             <p>
 515                 When a stream <em>depends</em> on another, say X depends on Y,
 516                 then Y gets all bandwidth before X gets any. Note that this
 517                 does not mean that Y will block X. If Y has no data to send,
 518                 all bandwidth allocated to Y can be used by X.
 519             </p>
 520             <p>
 521                 When a stream has more than one dependant, say X1 and X2 both
 522                 depend on Y, the <em>weight</em> determines the bandwidth
 523                 allocation. If X1 and X2 have the same weight, they both get
 524                 half of the available bandwidth. If the weight of X1 is twice
 525                 as large as that for X2, X1 gets twice the bandwidth of X2.
 526             </p>
 527             <p>
 528                 Ultimately, every stream depends on the <em>root</em> stream which
 529                 gets all the bandwidth available, but never sends anything. So all
 530                 its bandwidth is distributed by weight among its children. Which
 531                 either have data to send or distribute the bandwidth to their
 532                 own children. And so on. If none of the children have data
 533                 to send, that bandwidth get distributed somewhere else according
 534                 to the same rules.
 535             </p>
 536             <p>
 537                 The purpose of this priority system is to always make use of
 538                 available bandwidth while allowing precedence and weight
 539                 to be given to specific streams. Since, normally, all streams
 540                 are initiated by the client, it is also the one that sets
 541                 these priorities.
 542             </p>
 543             <p>
 544                 Only when such a stream results in a PUSH, gets the server to
 545                 decide what the <em>initial</em> priority of such a pushed
 546                 stream is. In the examples below, X is the client stream. It
 547                 depends on Y and the server decides to PUSH streams P1 and P2
 548                 onto X.
 549             </p>
 550             <p>
 551                 The default priority rule is:
 552             </p>
 553             <div class="example"><h3>Default Priority Rule</h3><pre class="prettyprint lang-config">H2PushPriority * After 16</pre>
 554 </div>
 555             <p>
 556                 which reads as 'Send a pushed stream of any content-type
 557                 depending on the client stream with weight 16'. And so P1
 558                 and P2 will be send after X and, as they have equal weight,
 559                 share bandwidth equally among themselves.
 560             </p>
 561             <div class="example"><h3>Interleaved Priority Rule</h3><pre class="prettyprint lang-config">H2PushPriority text/css Interleaved 256</pre>
 562 </div>
 563             <p>
 564                 which reads as 'Send any CSS resource on the same dependency and
 565                 weight as the client stream'. If P1 has content-type 'text/css',
 566                 it will depend on Y (as does X) and its effective weight will be
 567                 calculated as <code>P1ew = Xw * (P1w / 256)</code>. With P1w being
 568                 256, this will make the effective weight the same as the weight
 569                 of X. If both X and P1 have data to send, bandwidth will be allocated
 570                 to both equally.
 571             </p>
 572             <p>
 573                 With Pw specified as 512, a pushed, interleaved stream would
 574                 get double the weight of X. With 128 only half as much. Note that
 575                 effective weights are always capped at 256.
 576             </p>
 577             <div class="example"><h3>Before Priority Rule</h3><pre class="prettyprint lang-config">H2PushPriority application/json Before</pre>
 578 </div>
 579             <p>
 580                 This says that any pushed stream of content type 'application/json'
 581                 should be send out <em>before</em> X. This makes P1 dependent
 582                 on Y and X dependent on P1. So, X will be stalled as long as
 583                 P1 has data to send. The effective weight is inherited from the
 584                 client stream. Specifying a weight is not allowed.
 585             </p>
 586             <p>
 587                 Be aware that the effect of priority specifications is limited
 588                 by the available server resources. If a server does not have
 589                 workers available for pushed streams, the data for the stream
 590                 may only ever arrive when other streams have been finished.
 591             </p>
 592             <p>
 593                 Last, but not least, there are some specifics of the syntax
 594                 to be used in this directive:
 595             </p>
 596             <ol>
 597                 <li>'*' is the only special content-type that matches all others.
 598                     'image/*' will not work.</li>
 599                 <li>The default dependency is 'After'. </li>
 600                 <li>There are also default weights: for 'After' it is 16, 'interleaved' is 256.
 601                 </li>
 602             </ol>
 603             <div class="example"><h3>Shorter Priority Rules</h3><pre class="prettyprint lang-config">H2PushPriority application/json 32         # an After rule
 604 H2PushPriority image/jpeg before           # weight inherited
 605 H2PushPriority text/css   interleaved      # weight 256 default</pre>
 606 </div>
 607
 608 </div>
 609 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 610 <div class="directive-section"><h2><a name="H2SerializeHeaders" id="H2SerializeHeaders">H2SerializeHeaders</a> <a name="h2serializeheaders" id="h2serializeheaders">Directive</a></h2>
 611 <table class="directive">
 612 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Serialize Request/Response Processing Switch</td></tr>
 613 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2SerializeHeaders on|off</code></td></tr>
 614 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>H2SerializeHeaders off</code></td></tr>
 615 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 616 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 617 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
 618 </table>
 619             <p>
 620                 This directive toggles if HTTP/2 requests shall be serialized in
 621                 HTTP/1.1 format for processing by <code>httpd</code> core or if
 622                 received binary data shall be passed into the <code>request_rec</code>s
 623                 directly.
 624             </p>
 625             <p>
 626                 Serialization will lower performance, but gives more backward
 627                 compatibility in case custom filters/hooks need it.
 628             </p>
 629             <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">H2SerializeHeaders on</pre>
 630 </div>
 631
 632 </div>
 633 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 634 <div class="directive-section"><h2><a name="H2SessionExtraFiles" id="H2SessionExtraFiles">H2SessionExtraFiles</a> <a name="h2sessionextrafiles" id="h2sessionextrafiles">Directive</a></h2>
 635 <table class="directive">
 636 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of Extra File Handles</td></tr>
 637 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2SessionExtraFiles <em>n</em></code></td></tr>
 638 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 639 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 640 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
 641 </table>
 642             <p>
 643                 This directive sets maximum number of <em>extra</em> file handles
 644                 a HTTP/2 session is allowed to use. A file handle is counted as
 645                 <em>extra</em> when it is transferred from a h2 worker thread to
 646                 the main HTTP/2 connection handling. This commonly happens when
 647                 serving static files.
 648             </p><p>
 649                 Depending on the processing model configured on the server, the
 650                 number of connections times number of active streams may exceed
 651                 the number of file handles for the process. On the other hand,
 652                 converting every file into memory bytes early results in too
 653                 many buffer writes. This option helps to mitigate that.
 654             </p><p>
 655                 The number of file handles used by a server process is then in
 656                 the order of:
 657             </p>
 658             <pre>(h2_connections * extra_files) + (h2_max_worker)</pre>
 659             <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">H2SessionExtraFiles 10</pre>
 660 </div>
 661             <p>
 662                 If nothing is configured, the module tries to make a conservative
 663                 guess how many files are safe to use. This depends largely on the
 664                 MPM chosen.
 665             </p>
 666
 667 </div>
 668 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 669 <div class="directive-section"><h2><a name="H2StreamMaxMemSize" id="H2StreamMaxMemSize">H2StreamMaxMemSize</a> <a name="h2streammaxmemsize" id="h2streammaxmemsize">Directive</a></h2>
 670 <table class="directive">
 671 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum amount of output data buffered per stream.</td></tr>
 672 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2StreamMaxMemSize <em>bytes</em></code></td></tr>
 673 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>H2StreamMaxMemSize 65536</code></td></tr>
 674 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 675 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 676 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
 677 </table>
 678             <p>
 679                 This directive sets the maximum number of outgoing data bytes buffered in memory
 680                 for an active streams. This memory is not allocated per stream as such. Allocations
 681                 are counted against this limit when they are about to be done. Stream processing
 682                 freezes when the limit has been reached and will only continue when buffered data
 683                 has been sent out to the client.
 684             </p>
 685             <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">H2StreamMaxMemSize 128000</pre>
 686 </div>
 687
 688 </div>
 689 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 690 <div class="directive-section"><h2><a name="H2TLSCoolDownSecs" id="H2TLSCoolDownSecs">H2TLSCoolDownSecs</a> <a name="h2tlscooldownsecs" id="h2tlscooldownsecs">Directive</a></h2>
 691 <table class="directive">
 692 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td /></tr>
 693 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2TLSCoolDownSecs <em>seconds</em></code></td></tr>
 694 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>H2TLSCoolDownSecs 1</code></td></tr>
 695 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 696 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 697 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
 698 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.4.18 and later.</td></tr>
 699 </table>
 700             <p>
 701                 This directive sets the number of seconds of idle time on a TLS
 702                 connection before the TLS write size falls back to small (~1300 bytes)
 703                 length.
 704                 This can be used server wide or for specific
 705                 <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</a></code>s.
 706             </p>
 707             <p>
 708                 See <code class="directive"><a href="#h2tlswarmupsize">H2TLSWarmUpSize</a></code> for a
 709                 description of TLS warmup. <code class="directive">H2TLSCoolDownSecs</code> reflects the fact
 710                 that connections may deteriorate over time (and TCP flow adjusts)
 711                 for idle connections as well. It is beneficial to overall performance
 712                 to fall back to the pre-warmup phase after a number of seconds that
 713                 no data has been sent.
 714             </p>
 715             <p>
 716                 In deployments where connections can be considered reliable, this
 717                 timer can be disabled by setting it to 0.
 718             </p>
 719             <p>
 720                 The following example sets the seconds to zero, effectively disabling
 721                 any cool down. Warmed up TLS connections stay on maximum record
 722                 size.
 723             </p>
 724             <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">H2TLSCoolDownSecs 0</pre>
 725 </div>
 726
 727 </div>
 728 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 729 <div class="directive-section"><h2><a name="H2TLSWarmUpSize" id="H2TLSWarmUpSize">H2TLSWarmUpSize</a> <a name="h2tlswarmupsize" id="h2tlswarmupsize">Directive</a></h2>
 730 <table class="directive">
 731 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td /></tr>
 732 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2TLSWarmUpSize <em>amount</em></code></td></tr>
 733 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>H2TLSWarmUpSize 1048576</code></td></tr>
 734 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 735 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 736 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
 737 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.4.18 and later.</td></tr>
 738 </table>
 739             <p>
 740                 This directive sets the number of bytes to be sent in small
 741                 TLS records (~1300 bytes) until doing maximum sized writes (16k)
 742                 on https: HTTP/2 connections.
 743                 This can be used server wide or for specific
 744                 <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</a></code>s.
 745             </p>
 746             <p>
 747                 Measurements by <a href="https://www.igvita.com">google performance
 748                     labs</a> show that best performance on TLS connections is reached,
 749                 if initial record sizes stay below the MTU level, to allow a
 750                 complete record to fit into an IP packet.
 751             </p>
 752             <p>
 753                 While TCP adjust its flow-control and window sizes, longer TLS
 754                 records can get stuck in queues or get lost and need retransmission.
 755                 This is of course true for all packets. TLS however needs the
 756                 whole record in order to decrypt it. Any missing bytes at the end
 757                 will stall usage of the received ones.
 758             </p>
 759             <p>
 760                 After a sufficient number of bytes have been send successfully,
 761                 the TCP state of the connection is stable and maximum TLS record
 762                 sizes (16 KB) can be used for optimal performance.
 763             </p>
 764             <p>
 765                 In deployments where servers are reached locally or over reliable
 766                 connections only, the value might be decreased with 0 disabling
 767                 any warmup phase altogether.
 768             </p>
 769             <p>
 770                 The following example sets the size to zero, effectively disabling
 771                 any warmup phase.
 772             </p>
 773             <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">H2TLSWarmUpSize 0</pre>
 774 </div>
 775
 776 </div>
 777 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 778 <div class="directive-section"><h2><a name="H2Upgrade" id="H2Upgrade">H2Upgrade</a> <a name="h2upgrade" id="h2upgrade">Directive</a></h2>
 779 <table class="directive">
 780 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>H2 Upgrade Protocol Switch</td></tr>
 781 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2Upgrade on|off</code></td></tr>
 782 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>H2Upgrade on for h2c, off for h2 protocol</code></td></tr>
 783 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 784 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 785 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
 786 </table>
 787             <p>
 788                 This directive toggles the usage of the HTTP/1.1 Upgrade method
 789                 for switching to HTTP/2. This
 790                 should be used inside a
 791                 <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</a></code>
 792                 section to enable Upgrades to HTTP/2 for that virtual host.
 793             </p>
 794             <p>
 795                 This method of switching protocols is defined in HTTP/1.1 and
 796                 uses the "Upgrade" header (thus the name) to announce willingness
 797                 to use another protocol. This may happen on any request of a
 798                 HTTP/1.1 connection.
 799             </p>
 800             <p>
 801                 This method of protocol switching is enabled by default on cleartext
 802                 (potential h2c) connections and disabled on TLS (potential h2),
 803                 as mandated by RFC 7540.
 804             </p>
 805             <p>
 806                 Please be aware that Upgrades are only accepted for requests
 807                 that carry no body. POSTs and PUTs with content will never
 808                 trigger an upgrade to HTTP/2.
 809                 See <code class="directive"><a href="#h2direct">H2Direct</a></code> for an
 810                 alternative to Upgrade.
 811             </p>
 812             <p>
 813                 This mode only has an effect when h2 or h2c is enabled via
 814                 the <code class="directive"><a href="../mod/core.html#protocols">Protocols</a></code>.
 815             </p>
 816             <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">H2Upgrade on</pre>
 817 </div>
 818
 819 </div>
 820 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 821 <div class="directive-section"><h2><a name="H2WindowSize" id="H2WindowSize">H2WindowSize</a> <a name="h2windowsize" id="h2windowsize">Directive</a></h2>
 822 <table class="directive">
 823 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Size of Stream Window for upstream data.</td></tr>
 824 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2WindowSize <em>bytes</em></code></td></tr>
 825 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>H2WindowSize 65535</code></td></tr>
 826 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 827 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 828 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
 829 </table>
 830             <p>
 831                 This directive sets the size of the window that is used for flow control
 832                 from client to server and limits the amount of data the server has to buffer.
 833                 The client will stop sending on a stream once the limit has been reached until
 834                 the server announces more available space (as it has processed some of the data).
 835             </p><p>
 836                 This limit affects only request bodies, not its meta data such as headers. Also,
 837                 it has no effect on response bodies as the window size for those are managed
 838                 by the clients.
 839             </p>
 840             <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">H2WindowSize 128000</pre>
 841 </div>
 842
 843 </div>
 844 </div>
 845 <div class="bottomlang">
 846 <p><span>Available Languages: </span><a href="../en/mod/mod_http2.html" title="English">&nbsp;en&nbsp;</a></p>
 847 </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>
 848 <script type="text/javascript"><!--//--><![CDATA[//><!--
 849 var comments_shortname = 'httpd';
 850 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_http2.html';
 851 (function(w, d) {
 852     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 853         d.write('<div id="comments_thread"><\/div>');
 854         var s = d.createElement('script');
 855         s.type = 'text/javascript';
 856         s.async = true;
 857         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 858         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 859     }
 860     else {
 861         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 862     }
 863 })(window, document);
 864 //--><!]]></script></div><div id="footer">
 865 <p class="apache">Copyright 2016 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>
 866 <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[//><!--
 867 if (typeof(prettyPrint) !== 'undefined') {
 868     prettyPrint();
 869 }
 870 //--><!]]></script>
 871 </body></html>