diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/manual/mod/mod_http2.xml | 168 |
1 files changed, 131 insertions, 37 deletions
diff --git a/docs/manual/mod/mod_http2.xml b/docs/manual/mod/mod_http2.xml index ad1a887733..6eeb1b013a 100644 --- a/docs/manual/mod/mod_http2.xml +++ b/docs/manual/mod/mod_http2.xml @@ -37,25 +37,25 @@ to provide the core http/2 engine.</p> <note type="warning"><title>Warning</title> - <p>This module is experimental. Its behaviors, directives, and - defaults are subject to more change from release to - release relative to other standard modules. Users are encouraged to - consult the "CHANGES" file for potential updates.</p> + <p>This module is experimental. Its behaviors, directives, and + defaults are subject to more change from release to + release relative to other standard modules. Users are encouraged to + consult the "CHANGES" file for potential updates.</p> </note> - + <p>You must enable HTTP/2 via <directive - module="core">Protocols</directive> in order to use the + module="core">Protocols</directive> in order to use the functionality described in this document:</p> - + <highlight language="config"> Protocols h2 http/1.1 </highlight> - + </summary> <section id="envvars"><title>Environment Variables</title> - - <p>This module can be configured to provide HTTP/2 related information + <p> + This module can be configured to provide HTTP/2 related information as additional environment variables to the SSI and CGI namespace. </p> @@ -67,12 +67,106 @@ <th>Value Type:</th> <th>Description:</th> </tr> - <tr><td><code>HTTPe</code></td> <td>flag</td> <td>HTTP/2 is being used.</td></tr> - <tr><td><code>H2PUSH</code></td> <td>flag</td> <td>HTTP/2 Server Push is enabled for this request and also supported by the client.</td></tr> + <tr><td><code>HTTP2</code></td><td>flag</td><td>HTTP/2 is being used.</td></tr> + <tr><td><code>H2PUSH</code></td><td>flag</td><td>HTTP/2 Server Push is enabled for this request and also supported by the client.</td></tr> </table> - </section> - + + <section id="dimensioning"><title>HTTP/2 Dimensioning</title> + <p> + Enabling HTTP/2 on your Apache Server has impact on the resource + consumption and if you have a busy site, you may need to consider + carefully the implications. + </p> + <p> + The first noticable thing after enabling HTTP/2 is that your server + processes will start additional threads. The reason for this is that + HTTP/2 gives all requests that it receives to its own <em>Worker</em> + threads for processing, collects the results and streams them out + to the client. + </p> + <p> + In the current implementation, these workers use a separate thread + pool from the MPM workers that you might be familiar with. This is + just how things are right now and not intended to be like this forever. + (It might be forever for the 2.4.x release line, though.) So, HTTP/2 + workers, or shorter H2Workers, will not show up in mod_status. They + are also not counted against directives such as ThreadsPerChild. However + they take ThreadsPerChild as default if you have not configured something + else via <directive type="section">H2MinWorkers</directive> and + <directive type="section">H2MaxWorkers</directive>. + </p> + <p> + Another thing to watch out for is is memory consumption. Since HTTP/2 + keeps more state on the server to manage all the open request, priorities + for and dependencies between them, it will always need more memory + than HTTP/1.1 processing. There are three directives which steer the + memory footprint of a HTTP/2 connection: + <directive type="section">H2MaxSessionStreams</directive>, + <directive type="section">H2WindowSize</directive> and + <directive type="section">H2StreamMaxMemSize</directive>. + </p> + <p> + <directive type="section">H2MaxSessionStreams</directive> limits the + number of parallel requests that a client can make on a HTTP/2 connection. + It depends on your site how many you should allow. The default is 100 which + is plenty and unless you run into memory problems, I would keep it this + way. Most requests that browsers send are GETs without a body, so they + use up only a little bit of memory until the actual processing starts. + </p> + <p> + <directive type="section">H2WindowSize</directive> controls how much + the client is allowed to send as body of a request, before it waits + for the server to encourage more. Or, the other way around, it is the + amount of request body data the server needs to be able to buffer. This + is per request. + </p> + <p> + And last, but not least, <directive type="section">H2StreamMaxMemSize</directive> + controls how much response data shall be buffered. The request sits in + a H2Worker thread and is producing data, the HTTP/2 connection tries + to send this to the client. If the client does not read fast enough, + the connection will buffer this amount of data and then suspend the + H2Worker. + </p> + <p> + If you serve a lot of static files, <directive type="section">H2SessionExtraFiles</directive> + is of interest. This tells the server how many file handles per + HTTP/2 connection it is allowed to waste for better performance. Because + when a request produces a static file as the response, the file handle + gets passed around and is buffered and not the file contents. That allows + to serve many large files without wasting memory or copying data + unnecessarily. However file handles are a limited resource for a process, + and if too many are used this way, requests may fail under load as + the amount of open handles has been exceeded. + </p> + </section> + + <section id="misdirected"><title>Multiple Hosts and Misdirected Requests</title> + <p> + Many sites use the same TLS certificate for multiple virtual hosts. The + certificate either has a wildcard name, such as '*.example.org' or carries + several alternate names. Browsers using HTTP/2 will recognize that and reuse + an already opened connection for such hosts. + </p> + <p> + While this is great for performance, it comes at a price: such vhosts + need more care in their configuration. The problem is that you will have + multiple requests for multiple hosts on the same TLS connection. And that + makes renegotiation impossible, in face the HTTP/2 standard forbids it. + </p> + <p> + So, if you have several virtual hosts using the same certificate and + want to use HTTP/2 for them, you need to make sure that all vhosts have + exactly the same SSL configuration. You need the same protocol, + ciphers and settings for client verification. + </p> + <p> + If you mix things, Apache httpd will detect it and return a special + response code, 421 Misidrected Request, to the client. + </p> + </section> + <directivesynopsis> <name>H2Direct</name> <description>H2 Direct Protocol Switch</description> @@ -122,7 +216,7 @@ </example> </usage> </directivesynopsis> - + <directivesynopsis> <name>H2Push</name> <description>H2 Server Push Switch</description> @@ -162,10 +256,10 @@ </p> <example><title>mod_headers example</title> <highlight language="config"> -<Location /index.html> - Header add Link "</css/site.css>;rel=preload" - Header add Link "</images/logo.jpg>;rel=preload" -</Location> + <Location /index.html> + Header add Link "</css/site.css>;rel=preload" + Header add Link "</images/logo.jpg>;rel=preload" + </Location> </highlight> </example> <p> @@ -192,7 +286,7 @@ </p> </usage> </directivesynopsis> - + <directivesynopsis> <name>H2PushDiarySize</name> <description>H2 Server Push Diary Size</description> @@ -229,7 +323,7 @@ </p> </usage> </directivesynopsis> - + <directivesynopsis> <name>H2PushPriority</name> <description>H2 Server Push Priority</description> @@ -240,7 +334,7 @@ <context>virtual host</context> </contextlist> <compatibility>Available in version 2.4.18 and later. For having an - effect, a nghttp2 library version 1.5.0 or newer is necessary.</compatibility> + effect, a nghttp2 library version 1.5.0 or newer is necessary.</compatibility> <usage> <p> @@ -346,21 +440,21 @@ </p> <ol> <li>'*' is the only special content-type that matches all others. - 'image/*' will not work.</li> + 'image/*' will not work.</li> <li>The default dependency is 'After'. </li> <li>There are also default weights: for 'After' it is 16, 'interleaved' is 256. </li> </ol> <example><title>Shorter Priority Rules</title> <highlight language="config"> -H2PushPriority application/json 32 # an After rule -H2PushPriority image/jpeg before # weight inherited -H2PushPriority text/css interleaved # weight 256 default + H2PushPriority application/json 32 # an After rule + H2PushPriority image/jpeg before # weight inherited + H2PushPriority text/css interleaved # weight 256 default </highlight> </example> </usage> </directivesynopsis> - + <directivesynopsis> <name>H2Upgrade</name> <description>H2 Upgrade Protocol Switch</description> @@ -456,7 +550,7 @@ H2PushPriority text/css interleaved # weight 256 default </example> </usage> </directivesynopsis> - + <directivesynopsis> <name>H2WindowSize</name> <description>Size of Stream Window for upstream data.</description> @@ -484,7 +578,7 @@ H2PushPriority text/css interleaved # weight 256 default </example> </usage> </directivesynopsis> - + <directivesynopsis> <name>H2MinWorkers</name> <description>Minimal number of worker threads to use per child process.</description> @@ -506,7 +600,7 @@ H2PushPriority text/css interleaved # weight 256 default </example> </usage> </directivesynopsis> - + <directivesynopsis> <name>H2MaxWorkers</name> <description>Maximum number of worker threads to use per child process.</description> @@ -528,7 +622,7 @@ H2PushPriority text/css interleaved # weight 256 default </example> </usage> </directivesynopsis> - + <directivesynopsis> <name>H2MaxWorkerIdleSeconds</name> <description>Maximum number of seconds h2 workers remain idle until shut down.</description> @@ -550,7 +644,7 @@ H2PushPriority text/css interleaved # weight 256 default </example> </usage> </directivesynopsis> - + <directivesynopsis> <name>H2SessionExtraFiles</name> <description>Number of Extra File Handles</description> @@ -591,7 +685,7 @@ H2PushPriority text/css interleaved # weight 256 default </p> </usage> </directivesynopsis> - + <directivesynopsis> <name>H2SerializeHeaders</name> <description>Serialize Request/Response Processing Switch</description> @@ -619,7 +713,7 @@ H2PushPriority text/css interleaved # weight 256 default </example> </usage> </directivesynopsis> - + <directivesynopsis> <name>H2ModernTLSOnly</name> <description>Require HTTP/2 connections to be "modern TLS" only</description> @@ -630,7 +724,7 @@ H2PushPriority text/css interleaved # weight 256 default <context>virtual host</context> </contextlist> <compatibility>Available in version 2.4.18 and later.</compatibility> - + <usage> <p> This directive toggles the security checks on HTTP/2 connections @@ -667,7 +761,7 @@ H2PushPriority text/css interleaved # weight 256 default </example> </usage> </directivesynopsis> - + <directivesynopsis> <name>H2TLSWarmUpSize</name> <description></description> @@ -689,7 +783,7 @@ H2PushPriority text/css interleaved # weight 256 default </p> <p> Measurements by <a href="https://www.igvita.com">google performance - labs</a> show that best performance on TLS connections is reached, + labs</a> show that best performance on TLS connections is reached, if initial record sizes stay below the MTU level, to allow a complete record to fit into an IP packet. </p> |