Backporting from trunk the latest version of the mod_http2 doc

    <compatibility>Available in version 2.4.17 and later</compatibility>

    <summary>

        <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>

                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

        functionality described in this document:</p>

        <p>You must enable HTTP/2 via <directive module="core">Protocols</directive> in order to use the

        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>

        <note><title>HTTP/2 in a VirtualHost context (TLS only)</title>

        <highlight language="config">

Protocols h2 http/1.1

        </highlight>

        <p>Allows HTTP/2 negotiation (h2) via TLS ALPN in a secure <directive>VirtualHost</directive>. HTTP/2 preamble checking (Direct mode, see <directive>H2Direct</directive>) is disabled by default for <code>h2</code>.</p>

        </note>

        <note><title>HTTP/2 in a Server context (TLS and cleartext)</title>

        <highlight language="config">

Protocols h2 h2c http/1.1

        </highlight>

        <p>Allows HTTP/2 negotiation (h2) via TLS ALPN for secure <directive>VirtualHost</directive>. Allows HTTP/2 cleartext negotiation (h2c) upgrading from an initial HTTP/1.1 connection or via HTTP/2 preamble checking (Direct mode, see <directive>H2Direct</directive>).</p>

        </note>

        <p>Refer to the official <a href="https://http2.github.io/faq">HTTP/2 FAQ</a> for any doubt about the protocol.</p>

    </summary>

    <section id="envvars"><title>Environment Variables</title>

    <section id="how-it-works"><title>How it works</title>

    <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 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 <directive>H2MinWorkers</directive> and

            <directive>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>H2MaxSessionStreams</directive>,

            <directive>H2WindowSize</directive> and

            <directive>H2StreamMaxMemSize</directive>.

        </p>

        <p>

            <directive>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>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>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>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 Misdirected Request, to the client.

        </p>

    </section>

        <p>This module can be configured to provide HTTP/2 related information

    <section id="envvars"><title>Environment Variables</title>

        <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>

            <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>

    </section>

    </section>

            <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.

                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

        </usage>

    </directivesynopsis>

    <directivesynopsis>

        <name>H2Timeout</name>

        <description>Timeout (in seconds) for HTTP/2 connections</description>

        <syntax>H2Timeout seconds</syntax>

        <default>H2Timeout 5</default>

        <contextlist>

            <context>server config</context>

            <context>virtual host</context>

        </contextlist>

        <compatibility>Available in version 2.4.19 and later.</compatibility>

        <usage>

            <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

                <directive module="core" type="section">VirtualHost</directive>s. 

            </p>

            <p>

                This directive is similar to the 

                <directive module="core" type="section">Timeout</directive>, but

                applies only to HTTP/2 connections.

            </p>

            <p>

                A value of 0 enforces no timeout.

            </p>

        </usage>

    </directivesynopsis>

    <directivesynopsis>

        <name>H2KeepAliveTimeout</name>

        <description>Timeout (in seconds) for idle HTTP/2 connections</description>

        <syntax>H2KeepAliveTimeout seconds</syntax>

        <contextlist>

            <context>server config</context>

            <context>virtual host</context>

        </contextlist>

        <compatibility>Available in version 2.4.19 and later.</compatibility>

        <usage>

            <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

                <directive module="core" type="section">VirtualHost</directive>s. 

            </p>

            <p>

                This directive is similar to the 

                <directive module="core" type="section">KeepAliveTimeout</directive>, 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>

        </usage>

    </directivesynopsis>

    <directivesynopsis>

        <name>H2StreamTimeout</name>

        <description>Timeout (in seconds) for idle HTTP/2 connections</description>

        <syntax>H2StreamTimeout seconds</syntax>

        <default>H2StreamTimeout 0</default>

        <contextlist>

            <context>server config</context>

            <context>virtual host</context>

        </contextlist>

        <compatibility>Available in version 2.4.19 and later.</compatibility>

        <usage>

            <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

                <directive module="core" type="section">VirtualHost</directive>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>

        </usage>

    </directivesynopsis>

</modulesynopsis>