httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ic...@apache.org
Subject svn commit: r1729655 - /httpd/httpd/trunk/docs/manual/mod/mod_http2.xml
Date Wed, 10 Feb 2016 16:57:29 GMT
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">
-&lt;Location /index.html&gt;
-    Header add Link "&lt;/css/site.css&gt;;rel=preload"
-    Header add Link "&lt;/images/logo.jpg&gt;;rel=preload"
-&lt;/Location&gt;
+                    &lt;Location /index.html&gt;
+                    Header add Link "&lt;/css/site.css&gt;;rel=preload"
+                    Header add Link "&lt;/images/logo.jpg&gt;;rel=preload"
+                    &lt;/Location&gt;
                 </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>



Mime
View raw message