You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by ic...@apache.org on 2016/02/10 17:57:29 UTC
svn commit: r1729655 - /httpd/httpd/trunk/docs/manual/mod/mod_http2.xml
Author: icing
Date: Wed Feb 10 16:57:29 2016
New Revision: 1729655
URL: http://svn.apache.org/viewvc?rev=1729655&view=rev
Log:
added dimensioning and mutlti domain sections
Modified:
httpd/httpd/trunk/docs/manual/mod/mod_http2.xml
Modified: httpd/httpd/trunk/docs/manual/mod/mod_http2.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_http2.xml?rev=1729655&r1=1729654&r2=1729655&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/mod_http2.xml (original)
+++ httpd/httpd/trunk/docs/manual/mod/mod_http2.xml Wed Feb 10 16:57:29 2016
@@ -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
</example>
</usage>
</directivesynopsis>
-
+
<directivesynopsis>
<name>H2WindowSize</name>
<description>Size of Stream Window for upstream data.</description>
@@ -484,7 +578,7 @@ H2PushPriority text/css interleaved
</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
</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
</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
</example>
</usage>
</directivesynopsis>
-
+
<directivesynopsis>
<name>H2SessionExtraFiles</name>
<description>Number of Extra File Handles</description>
@@ -591,7 +685,7 @@ H2PushPriority text/css interleaved
</p>
</usage>
</directivesynopsis>
-
+
<directivesynopsis>
<name>H2SerializeHeaders</name>
<description>Serialize Request/Response Processing Switch</description>
@@ -619,7 +713,7 @@ H2PushPriority text/css interleaved
</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
<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
</example>
</usage>
</directivesynopsis>
-
+
<directivesynopsis>
<name>H2TLSWarmUpSize</name>
<description></description>
@@ -689,7 +783,7 @@ H2PushPriority text/css interleaved
</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>