httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From elu...@apache.org
Subject svn commit: r1738647 [1/2] - in /httpd/httpd/branches/2.4.x/docs/manual/mod: directives.html.en mod_http2.html.en quickreference.html.en
Date Mon, 11 Apr 2016 21:12:02 GMT
Author: elukey
Date: Mon Apr 11 21:12:02 2016
New Revision: 1738647

URL: http://svn.apache.org/viewvc?rev=1738647&view=rev
Log:
Documentation rebuild

Modified:
    httpd/httpd/branches/2.4.x/docs/manual/mod/directives.html.en
    httpd/httpd/branches/2.4.x/docs/manual/mod/mod_http2.html.en
    httpd/httpd/branches/2.4.x/docs/manual/mod/quickreference.html.en

Modified: httpd/httpd/branches/2.4.x/docs/manual/mod/directives.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/mod/directives.html.en?rev=1738647&r1=1738646&r2=1738647&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/mod/directives.html.en (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/mod/directives.html.en Mon Apr 11 21:12:02 2016
@@ -285,7 +285,6 @@
 <li><a href="mpm_common.html#gracefulshutdowntimeout">GracefulShutdownTimeout</a></li>
 <li><a href="mod_unixd.html#group">Group</a></li>
 <li><a href="mod_http2.html#h2direct" id="H" name="H">H2Direct</a></li>
-<li><a href="mod_http2.html#h2keepalivetimeout">H2KeepAliveTimeout</a></li>
 <li><a href="mod_http2.html#h2maxsessionstreams">H2MaxSessionStreams</a></li>
 <li><a href="mod_http2.html#h2maxworkeridleseconds">H2MaxWorkerIdleSeconds</a></li>
 <li><a href="mod_http2.html#h2maxworkers">H2MaxWorkers</a></li>
@@ -297,8 +296,6 @@
 <li><a href="mod_http2.html#h2serializeheaders">H2SerializeHeaders</a></li>
 <li><a href="mod_http2.html#h2sessionextrafiles">H2SessionExtraFiles</a></li>
 <li><a href="mod_http2.html#h2streammaxmemsize">H2StreamMaxMemSize</a></li>
-<li><a href="mod_http2.html#h2streamtimeout">H2StreamTimeout</a></li>
-<li><a href="mod_http2.html#h2timeout">H2Timeout</a></li>
 <li><a href="mod_http2.html#h2tlscooldownsecs">H2TLSCoolDownSecs</a></li>
 <li><a href="mod_http2.html#h2tlswarmupsize">H2TLSWarmUpSize</a></li>
 <li><a href="mod_http2.html#h2upgrade">H2Upgrade</a></li>

Modified: httpd/httpd/branches/2.4.x/docs/manual/mod/mod_http2.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/mod/mod_http2.html.en?rev=1738647&r1=1738646&r2=1738647&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/mod/mod_http2.html.en (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/mod/mod_http2.html.en Mon Apr 11 21:12:02 2016
@@ -35,33 +35,45 @@
 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available
in version 2.4.17 and later</td></tr></table>
 <h3>Summary</h3>
 
-        <p>This module provides HTTP/2 (RFC 7540) support for the Apache
-            HTTP Server.</p>
+        <p>This module provides HTTP/2 (<a href="https://tools.ietf.org/html/rfc7540">RFC
7540</a>) 
+        support for the Apache HTTP Server.</p>
         
         <p>This module relies on <a href="http://nghttp2.org/">libnghttp2</a>
             to provide the core http/2 engine.</p>
         
         <div class="warning"><h3>Warning</h3>
-          <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>
         </div>
-
+        
         <p>You must enable HTTP/2 via <code class="directive"><a href="../mod/core.html#protocols">Protocols</a></code>
in order to use the
-        functionality described in this document:</p>
+        functionality described in this document. The 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: <code>h2</code>
(HTTP/2 over TLS) and <code>h2c</code> (HTTP/2 over TCP).</p>
 
+        <p>Two useful configuration schemes are:</p>
+        
+        <div class="note"><h3>HTTP/2 in a VirtualHost context (TLS only)</h3>
         <pre class="prettyprint lang-config">Protocols h2 http/1.1</pre>
 
+        <p>Allows HTTP/2 negotiation (h2) via TLS ALPN in a secure <code class="directive">VirtualHost</code>.
HTTP/2 preamble checking (Direct mode, see <code class="directive">H2Direct</code>)
is disabled by default for <code>h2</code>.</p>
+        </div>
+
+        <div class="note"><h3>HTTP/2 in a Server context (TLS and cleartext)</h3>
+        <pre class="prettyprint lang-config">Protocols h2 h2c http/1.1</pre>
 
+        <p>Allows HTTP/2 negotiation (h2) via TLS ALPN for secure <code class="directive">VirtualHost</code>.
Allows HTTP/2 cleartext negotiation (h2c) upgrading from an initial HTTP/1.1 connection or
via HTTP/2 preamble checking (Direct mode, see <code class="directive">H2Direct</code>).</p>
+        </div>
+
+        <p>Refer to the official <a href="https://http2.github.io/faq">HTTP/2
FAQ</a> for any doubt about the protocol.</p>
+        
     </div>
 <div id="quickview"><h3>Topics</h3>
 <ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#envvars">Environment
Variables</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#how-it-works">How
it works</a></li>
 </ul><h3 class="directives">Directives</h3>
 <ul id="toc">
 <li><img alt="" src="../images/down.gif" /> <a href="#h2direct">H2Direct</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#h2keepalivetimeout">H2KeepAliveTimeout</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#h2maxsessionstreams">H2MaxSessionStreams</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#h2maxworkeridleseconds">H2MaxWorkerIdleSeconds</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#h2maxworkers">H2MaxWorkers</a></li>
@@ -73,8 +85,6 @@
 <li><img alt="" src="../images/down.gif" /> <a href="#h2serializeheaders">H2SerializeHeaders</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#h2sessionextrafiles">H2SessionExtraFiles</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#h2streammaxmemsize">H2StreamMaxMemSize</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#h2streamtimeout">H2StreamTimeout</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#h2timeout">H2Timeout</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#h2tlscooldownsecs">H2TLSCoolDownSecs</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#h2tlswarmupsize">H2TLSWarmUpSize</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#h2upgrade">H2Upgrade</a></li>
@@ -83,9 +93,106 @@
 <ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"
/></a></div>
 <div class="section">
-<h2><a name="envvars" id="envvars">Environment Variables</a></h2>
-        
-        <p>This module can be configured to provide HTTP/2 related information
+<h2><a name="how-it-works" id="how-it-works">How it works</a></h2>
+    
+    <h3><a name="dimensioning" id="dimensioning">HTTP/2 Dimensioning</a></h3>
+        <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 noticeable 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 <code class="directive">H2MinWorkers</code> and
+            <code class="directive">H2MaxWorkers</code>.
+        </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:
+            <code class="directive">H2MaxSessionStreams</code>,
+            <code class="directive">H2WindowSize</code> and
+            <code class="directive">H2StreamMaxMemSize</code>.
+        </p>
+        <p>
+            <code class="directive">H2MaxSessionStreams</code> 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>
+            <code class="directive">H2WindowSize</code> 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, <code class="directive">H2StreamMaxMemSize</code>
+            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, <code class="directive">H2SessionExtraFiles</code>
+            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>
+    
+    
+    <h3><a name="misdirected" id="misdirected">Multiple Hosts and Misdirected
Requests</a></h3>
+        <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 Misdirected Request, to the client.
+        </p>
+    
+
+    <h3><a name="envvars" id="envvars">Environment Variables</a></h3>
+        <p>
+            This module can be configured to provide HTTP/2 related information
             as additional environment variables to the SSI and CGI namespace, as well
             as in custom log configurations (see <code>%{VAR_NAME}e</code>).
         </p>
@@ -105,7 +212,8 @@
             <tr><td><code>H2_STREAM_ID</code></td><td>number</td><td>HTTP/2
stream number of this request.</td></tr>
             <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>
         </table>
-        
+    
+    
     </div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"
/></a></div>
 <div class="directive-section"><h2><a name="H2Direct" id="H2Direct">H2Direct</a>
<a name="h2direct" id="h2direct">Directive</a></h2>
@@ -153,34 +261,6 @@
         
 </div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"
/></a></div>
-<div class="directive-section"><h2><a name="H2KeepAliveTimeout" id="H2KeepAliveTimeout">H2KeepAliveTimeout</a>
<a name="h2keepalivetimeout" id="h2keepalivetimeout">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Timeout
(in seconds) for idle HTTP/2 connections</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2KeepAliveTimeout
seconds</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server
config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available
in version 2.4.19 and later.</td></tr>
-</table>
-            <p>
-                This directive sets the timeout for read/write operations on
-                idle connections where HTTP/2 is negotiated. This can be used server wide
or for specific
-                <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</a></code>s.

-            </p>
-            <p>
-                This directive is similar to the 
-                <code class="directive"><a href="../mod/core.html#keepalivetimeout">&lt;KeepAliveTimeout&gt;</a></code>,
but
-                applies only to HTTP/2 connections. A HTTP/2 connection is considered
-                idle when no streams are open, e.g. no requests are ongoing.
-            </p>
-            <p>
-                By default, for non-async MPMs (prefork, worker) the keepalive timeout
-                will be the same as H2Timeout. For async MPMs, the keepalive handling for
-                HTTP/1 connections applies as no special action is taken.
-            </p>
-        
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"
/></a></div>
 <div class="directive-section"><h2><a name="H2MaxSessionStreams" id="H2MaxSessionStreams">H2MaxSessionStreams</a>
<a name="h2maxsessionstreams" id="h2maxsessionstreams">Directive</a></h2>
 <table class="directive">
 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum
number of active streams per HTTP/2 session.</td></tr>
@@ -381,7 +461,7 @@
             <p>
                 The push diary records a digest (currently using a 64 bit number) of pushed
                 resources (their URL) to avoid duplicate pushes on the same connection.
-                These value are not persisted, so clients openeing a new connection
+                These value are not persisted, so clients opening a new connection
                 will experience known pushes again. There is ongoing work to enable
                 a client to disclose a digest of the resources it already has, so
                 the diary maybe initialized by the client on each connection setup.
@@ -406,7 +486,7 @@
 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available
in version 2.4.18 and later. For having an
-        effect, a nghttp2 library version 1.5.0 or newer is necessary.</td></tr>
+            effect, a nghttp2 library version 1.5.0 or newer is necessary.</td></tr>
 </table>
             <p>
                 This directive defines the priority handling of pushed responses
@@ -428,12 +508,12 @@
                 When a stream has more than one dependant, say X1 and X2 both
                 depend on Y, the <em>weight</em> determines the bandwidth
                 allocation. If X1 and X2 have the same weight, they both get
-                half of the available bandwdith. If the weight of X1 is twice
+                half of the available bandwidth. If the weight of X1 is twice
                 as large as that for X2, X1 gets twice the bandwidth of X2.
             </p>
             <p> 
                 Ultimately, every stream depends on the <em>root</em> stream
which
-                gets all the bandwidht available, but never sends anything. So all
+                gets all the bandwidth available, but never sends anything. So all
                 its bandwidth is distributed by weight among its children. Which
                 either have data to send or distribute the bandwidth to their
                 own children. And so on. If none of the children have data
@@ -502,7 +582,7 @@
             </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>
@@ -594,67 +674,6 @@ H2PushPriority text/css   interleaved
         
 </div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"
/></a></div>
-<div class="directive-section"><h2><a name="H2StreamTimeout" id="H2StreamTimeout">H2StreamTimeout</a>
<a name="h2streamtimeout" id="h2streamtimeout">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Timeout
(in seconds) for idle HTTP/2 connections</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2StreamTimeout
seconds</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>H2StreamTimeout
0</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server
config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available
in version 2.4.19 and later.</td></tr>
-</table>
-            <p>
-                This directive sets the timeout for read/write operations on
-                HTTP/2 streams, e.g. individual requests. This can be used server wide or
for specific
-                <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</a></code>s.

-            </p>
-            <p>
-                Due to the nature of HTTP/2, which sends multiple requests over a single
-                connection and has priority scheduling, individual streams might not
-                see input for much longer times than HTTP/1.1 requests would. 
-            </p>
-            <p>
-                A value of 0 enforces no timeout, so could wait on chances to receive
-                input or write data indefinitely. This expose a server to
-                risks of thread exhaustion. 
-            </p>
-            <p>
-                Depending on your handling of pushed streams,
-                priorities and general responsiveness, a site might need to increase
-                this value. For example, if you PUSH a large resource <em>before</em>
-                the requested one, the initial stream will not write until the
-                pushed resource is fully sent.
-            </p>
-        
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"
/></a></div>
-<div class="directive-section"><h2><a name="H2Timeout" id="H2Timeout">H2Timeout</a>
<a name="h2timeout" id="h2timeout">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Timeout
(in seconds) for HTTP/2 connections</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>H2Timeout
seconds</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>H2Timeout
5</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server
config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_http2</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available
in version 2.4.19 and later.</td></tr>
-</table>
-            <p>
-                This directive sets the timeout for read/write operations on
-                connections where HTTP/2 is negotiated. This can be used server wide or for
specific
-                <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</a></code>s.

-            </p>
-            <p>
-                This directive is similar to the 
-                <code class="directive"><a href="../mod/core.html#timeout">&lt;Timeout&gt;</a></code>,
but
-                applies only to HTTP/2 connections.
-            </p>
-            <p>
-                A value of 0 enforces no timeout.
-            </p>
-        
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"
/></a></div>
 <div class="directive-section"><h2><a name="H2TLSCoolDownSecs" id="H2TLSCoolDownSecs">H2TLSCoolDownSecs</a>
<a name="h2tlscooldownsecs" id="h2tlscooldownsecs">Directive</a></h2>
 <table class="directive">
 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td
/></tr>
@@ -713,7 +732,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