From df86c04b256a71efa01c386544f3fb13c9e61b06 Mon Sep 17 00:00:00 2001 From: Luca Toscano Date: Mon, 11 Apr 2016 21:06:26 +0000 Subject: [PATCH] Backporting from trunk the latest version of the mod_http2 doc git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1738645 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/mod_http2.xml | 270 ++++++++++++++++++---------------- 1 file changed, 143 insertions(+), 127 deletions(-) diff --git a/docs/manual/mod/mod_http2.xml b/docs/manual/mod/mod_http2.xml index 737a88b0dc..d83f2f6e66 100644 --- a/docs/manual/mod/mod_http2.xml +++ b/docs/manual/mod/mod_http2.xml @@ -30,32 +30,142 @@ Available in version 2.4.17 and later -

This module provides HTTP/2 (RFC 7540) support for the Apache - HTTP Server.

+

This module provides HTTP/2 (RFC 7540) + support for the Apache HTTP Server.

This module relies on libnghttp2 to provide the core http/2 engine.

Warning -

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.

+

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.

 + +

You must enable HTTP/2 via Protocols in order to use the + functionality described in this document. The HTTP/2 protocol does not require the use of encryption so two schemes are available: h2 (HTTP/2 over TLS) and h2c (HTTP/2 over TCP).

-

You must enable HTTP/2 via Protocols in order to use the - functionality described in this document:

+

Two useful configuration schemes are:

+ + HTTP/2 in a VirtualHost context (TLS only) + +Protocols h2 http/1.1 + +

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

+ + HTTP/2 in a Server context (TLS and cleartext) - Protocols h2 http/1.1 +Protocols h2 h2c http/1.1 +

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

+ +

Refer to the official HTTP/2 FAQ for any doubt about the protocol.

+ +
How it works + +
HTTP/2 Dimensioning +

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

+

+ 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 Worker + threads for processing, collects the results and streams them out + to the client. +

+

+ 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 H2MinWorkers and + H2MaxWorkers. +

+

+ 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: + H2MaxSessionStreams, + H2WindowSize and + H2StreamMaxMemSize. +

+

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

+

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

+

+ And last, but not least, H2StreamMaxMemSize + 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. +

+

+ If you serve a lot of static files, H2SessionExtraFiles + 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. +

+
+ +
Multiple Hosts and Misdirected Requests +

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

+

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

+

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

+

+ If you mix things, Apache httpd will detect it and return a special + response code, 421 Misdirected Request, to the client. +

+
+
Environment Variables - -

This module can be configured to provide HTTP/2 related information +

+ 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 %{VAR_NAME}e).

@@ -76,7 +186,8 @@ H2_STREAM_IDnumberHTTP/2 stream number of this request. H2_STREAM_TAGstringHTTP/2 process unique stream identifier, consisting of connection id and stream id separated by -. - +
+
@@ -128,7 +239,7 @@ - + H2Push H2 Server Push Switch @@ -198,7 +309,7 @@

- + H2PushDiarySize H2 Server Push Diary Size @@ -220,7 +331,7 @@

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. @@ -235,7 +346,7 @@

- + H2PushPriority H2 Server Push Priority @@ -246,7 +357,7 @@ virtual host Available in version 2.4.18 and later. For having an - effect, a nghttp2 library version 1.5.0 or newer is necessary. + effect, a nghttp2 library version 1.5.0 or newer is necessary.

@@ -269,12 +380,12 @@ When a stream has more than one dependant, say X1 and X2 both depend on Y, the weight 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.

Ultimately, every stream depends on the root 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 @@ -352,7 +463,7 @@

  1. '*' is the only special content-type that matches all others. - 'image/*' will not work.
    2. + 'image/*' will not work.
  2. The default dependency is 'After'.
  3. There are also default weights: for 'After' it is 16, 'interleaved' is 256.
    4. @@ -366,7 +477,7 @@ H2PushPriority text/css interleaved # weight 256 default - + H2Upgrade H2 Upgrade Protocol Switch @@ -462,7 +573,7 @@ H2PushPriority text/css interleaved # weight 256 default - + H2WindowSize Size of Stream Window for upstream data. @@ -490,7 +601,7 @@ H2PushPriority text/css interleaved # weight 256 default - + H2MinWorkers Minimal number of worker threads to use per child process. @@ -512,7 +623,7 @@ H2PushPriority text/css interleaved # weight 256 default - + H2MaxWorkers Maximum number of worker threads to use per child process. @@ -534,7 +645,7 @@ H2PushPriority text/css interleaved # weight 256 default - + H2MaxWorkerIdleSeconds Maximum number of seconds h2 workers remain idle until shut down. @@ -556,7 +667,7 @@ H2PushPriority text/css interleaved # weight 256 default - + H2SessionExtraFiles Number of Extra File Handles @@ -597,7 +708,7 @@ H2PushPriority text/css interleaved # weight 256 default

    - + H2SerializeHeaders Serialize Request/Response Processing Switch @@ -625,7 +736,7 @@ H2PushPriority text/css interleaved # weight 256 default - + H2ModernTLSOnly Require HTTP/2 connections to be "modern TLS" only @@ -636,7 +747,7 @@ H2PushPriority text/css interleaved # weight 256 default virtual host Available in version 2.4.18 and later. - +

    This directive toggles the security checks on HTTP/2 connections @@ -673,7 +784,7 @@ H2PushPriority text/css interleaved # weight 256 default - + H2TLSWarmUpSize @@ -695,7 +806,7 @@ H2PushPriority text/css interleaved # weight 256 default

    Measurements by google performance - labs show that best performance on TLS connections is reached, + labs 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.

    @@ -772,99 +883,4 @@ H2PushPriority text/css interleaved # weight 256 default     - - H2Timeout - Timeout (in seconds) for HTTP/2 connections - H2Timeout seconds - H2Timeout 5 - - server config - virtual host - - Available in version 2.4.19 and later. - - -

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

    -

    - This directive is similar to the - Timeout, but - applies only to HTTP/2 connections. -

    -

    - A value of 0 enforces no timeout. -

    -     -     - - - H2KeepAliveTimeout - Timeout (in seconds) for idle HTTP/2 connections - H2KeepAliveTimeout seconds - - server config - virtual host - - Available in version 2.4.19 and later. - - -

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

    -

    - This directive is similar to the - KeepAliveTimeout, 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. -

    -

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

    -     -     - - - H2StreamTimeout - Timeout (in seconds) for idle HTTP/2 connections - H2StreamTimeout seconds - H2StreamTimeout 0 - - server config - virtual host - - Available in version 2.4.19 and later. - - -

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

    -

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

    -

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

    -

    - 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 before - the requested one, the initial stream will not write until the - pushed resource is fully sent. -

    -     -     - -- 2.40.0