From: Mike Rumph Date: Thu, 3 Dec 2015 16:31:00 +0000 (+0000) Subject: Generated doc changes X-Git-Tag: 2.4.18~34 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=40edf69ce910a0fc606db57506b01f7c686e177d;p=apache Generated doc changes git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1717798 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/directives.html.en b/docs/manual/mod/directives.html.en index eda7e37055..ebe6fa21c0 100644 --- a/docs/manual/mod/directives.html.en +++ b/docs/manual/mod/directives.html.en @@ -288,9 +288,15 @@
  • H2MaxWorkerIdleSeconds
  • H2MaxWorkers
  • H2MinWorkers
    • +
  • H2ModernTLSOnly
    • +
  • H2Push
    • +
  • H2PushPriority
  • H2SerializeHeaders
  • H2SessionExtraFiles
  • H2StreamMaxMemSize
    • +
  • H2TLSCoolDownSecs
    • +
  • H2TLSWarmUpSize
    • +
  • H2Upgrade
  • H2WindowSize
  • Header
  • HeaderName
    • diff --git a/docs/manual/mod/mod_http2.html.en b/docs/manual/mod/mod_http2.html.en index 1b8cdd0aea..855725ee01 100644 --- a/docs/manual/mod/mod_http2.html.en +++ b/docs/manual/mod/mod_http2.html.en @@ -47,6 +47,13 @@ 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:

    + + 
    Protocols h2 http/1.1
    + +

    Directives

    @@ -67,7 +80,7 @@ - + @@ -77,12 +90,31 @@ should be used inside a <VirtualHost> section to enable direct HTTP/2 communication for that virtual host. +

    +

    Direct communication means that if the first bytes received by the server on a connection match the HTTP/2 preamble, the HTTP/2 protocol is switched to immediately without further negotiation. - This mode falls outside the RFC 7540 but has become widely implemented - as it is very convenient for development and testing. - By default the direct HTTP/2 mode is enabled. + This mode is defined in RFC 7540 for the cleartext (h2c) case. Its + use on TLS connections not mandated by the standard. +

    +

    + When a server/vhost does not have h2 or h2c enabled via + <Protocols>, + the connection is never inspected for a HTTP/2 preamble. H2Direct + does not matter then. This is important for connections that + use protocols where an initial read might hang indefinitely, such + as NNTP. +

    +

    + For clients that have out-of-band knowledge about a server + supporting h2c, direct HTTP/2 saves the client from having to + perform an HTTP/1.1 upgrade, resulting in better performance + and avoiding the Upgrade restrictions on request bodies. +

    +

    + This makes direct h2c attractive for server to server communication + as well, when the connection can be trusted or is secured by other means.

    Example

    H2Direct on
    @@ -163,6 +195,228 @@

    Example

    H2MinWorkers 10
    + +
    top
    +

    H2ModernTLSOnly Directive

    +
    Description:H2 Direct Protocol Switch
    Syntax:H2Direct on|off
    Default:H2Direct on (for non TLS)
    Default:H2Direct on for h2c, off for h2 protocol
    Context:server config, virtual host
    Status:Extension
    Module:mod_http2
    + + + + + + + +
    Description:Require HTTP/2 connections to be "modern TLS" only
    Syntax:H2ModernTLSOnly on|off
    Default:H2ModernTLSOnly on
    Context:server config, virtual host
    Status:Extension
    Module:mod_http2
    Compatibility:Available in version 2.4.18 and later.
    +

    + This directive toggles the security checks on HTTP/2 connections + in TLS mode (https:). This can be used server wide or for specific + <VirtualHost>s. +

    +

    + The security checks require that the TSL protocol is at least + TLSv1.2 and that none of the ciphers listed in RFC 7540, Appendix A + is used. These checks will be extended once new security requirements + come into place. +

    +

    + The name stems from the + Security/Server Side TLS + definitions at mozilla where "modern compatibility" is defined. Mozilla Firefox and + other browsers require modern compatibility for HTTP/2 connections. As everything + in OpSec, this is a moving target and can be expected to evolve in the future. +

    +

    + One purpose of having these checks in mod_http2 is to enforce this + security level for all connections, not only those from browsers. The other + purpose is to prevent the negotiation of HTTP/2 as a protocol should + the requirements not be met. +

    +

    + Ultimately, the security of the TLS connection is determined by the + server configuration directives for mod_ssl. +

    +

    Example

    H2ModernTLSOnly off
    +
    + + +
    top
    +

    H2Push Directive

    + + + + + + + + +
    Description:H2 Server Push Switch
    Syntax:H2Push on|off
    Default:H2Push on
    Context:server config, virtual host
    Status:Extension
    Module:mod_http2
    Compatibility:Available in version 2.4.18 and later.
    +

    + This directive toggles the usage of the HTTP/2 server push + protocol feature. This should be used inside a + <VirtualHost> + section to enable direct HTTP/2 communication for that virtual host. +

    +

    + The HTTP/2 protocol allows the server to push other resources to + a client when it asked for a particular one. This is helpful + if those resources are connected in some way and the client can + be expected to ask for it anyway. The pushing then saves the + time it takes the client to ask for the resources itself. On the + other hand, pushing resources the client never needs or already + has is a waste of bandwidth. +

    +

    + Server pushes are detected by inspecting the Link headers of + responses (see https://tools.ietf.org/html/rfc5988 for the + specification). When a link thus specified has the rel=preload + attribute, it is treated as a resource to be pushed. +

    +

    + Link headers in responses are either set by the application or + can be configured via mod_headers as: +

    +

    mod_headers example

    <Location /index.html>
+    Header add Link "</css/site.css>;rel=preload"
+    Header add Link "</images/logo.jpg>;rel=preload"
+</Location>
    +
    +

    + As the example shows, there can be several link headers added + to a response, resulting in several pushes being triggered. There + are no checks in the module to avoid pushing the same resource + twice or more to one client. Use with care. +

    +

    + HTTP/2 server pushes are enabled by default. This directive + allows it to be switch off on all resources of this server/virtual + host. +

    +

    Example

    H2Push off
    +
    +

    + Last but not least, pushes happen only when the client signals + its willingness to accept those. Most browsers do, some, like Safari 9, + do not. Also, pushes also only happen for resources from the same + authority as the original response is for. +

    + +
    +
    top
    +

    H2PushPriority Directive

    + + + + + + + + +
    Description:H2 Server Push Priority
    Syntax:H2PushPriority mime-type [after|before|interleaved] [weight]
    Default:H2PushPriority * After 16
    Context:server config, virtual host
    Status:Extension
    Module:mod_http2
    Compatibility:Available in version 2.4.18 and later. For having an + effect, a nghttp2 library version 1.5.0 or newer is necessary.
    +

    + This directive defines the priority handling of pushed responses + based on the content-type of the response. This is usually defined + per server config, but may also appear in a virtual host. +

    +

    + HTTP/2 server pushes are always related to a client request. Each + such request/response pairs, or streams have a dependency + and a weight, together defining the priority of a stream. +

    +

    + When a stream depends on another, say X depends on Y, + then Y gets all bandwidth before X gets any. Note that this + does not men that Y will block X. If Y has no data to send, + all bandwidth allocated to Y can be used by X. +

    +

    + 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 + 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 + 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 + to send, that bandwidth get distributed somewhere else according + to the same rules. +

    +

    + The purpose of this priority system is to always make use of + available bandwidth while allowing precedence and weight + to be given to specific streams. Since, normally, all streams + are initiated by the client, it is also the one that sets + these priorities. +

    +

    + Only when such a stream results in a PUSH, gets the server to + decide what the initial priority of such a pushed + stream is. In the examples below, X is the client stream. It + depends on Y and the server decides to PUSH streams P1 and P2 + onto X. +

    +

    + The default priority rule is: +

    +

    Default Priority Rule

    H2PushPriority * After 16
    +
    +

    + which reads as 'Send a pushed stream of any content-type + depending on the client stream with weight 16'. And so P1 + and P2 will be send after X and, as they have equal weight, + share bandwidth equally among themselves. +

    +

    Interleaved Priority Rule

    H2PushPriority text/css Interleaved 256
    +
    +

    + which reads as 'Send any CSS resource on the same dependency and + weight as the client stream'. If P1 has content-type 'text/css', + it will depend on Y (as does X) and its effective weight will be + calculated as P1ew = Xw * (P1w / 256). With P1w being + 256, this will make the effective weight the same as the weight + of X. If both X and P1 have data to send, bandwidth will be allocated + to both equally. +

    +

    + With Pw specified as 512, a pushed, interleaved stream would + get double the weight of X. With 128 only half as much. Note that + effective weights are always capped at 256. +

    +

    Before Priority Rule

    H2PushPriority application/json Before 256
    +
    +

    + This says that any pushed stream of content type 'application/json' + should be send out before X. This makes P1 dependant + on Y and X dependant on P1. So, X will be stalled as long as + P1 has data to send. The effective weight is calculated as + in the interleaved case. +

    +

    + Be aware that the effect of priority specifications is limited + by the available server resources. If a server does not have + workers available for pushed streams, the data for the stream + may only ever arrive when other streams have been finished. +

    +

    + Last, but not least, there are some specifics of the syntax + to be used in this directive. +

      +
    1. '*' is the only special content-type that matches all oither. + 'image/*' will not work.
      2. +
    2. The default dependency is 'After'.
      3. +
    3. There are also default weights: for 'After' it is 16, otherwise 256. +
      4. +
    +

    +

    Shorter Priority Rules

    H2PushPriority application/json 32         # an After rule
+H2PushPriority image/jpeg before           # weight 256 default
+H2PushPriority text/css   interleaved      # weight 256 default
    +
    +
    top

    H2SerializeHeaders Directive

    @@ -201,7 +455,7 @@

    This directive sets maximum number of extra file handles a HTTP/2 session is allowed to use. A file handle is counted as - extra when it is transfered from a h2 worker thread to + extra when it is transferred from a h2 worker thread to the main HTTP/2 connection handling. This commonly happens when serving static files.

    @@ -239,6 +493,137 @@

    Example

    H2StreamMaxMemSize 128000
    +
    +
    top
    +

    H2TLSCoolDownSecs Directive

    + + + + + + + + +
    Description:
    Syntax:H2TLSCoolDownSecs seconds
    Default:H2TLSCoolDownSecs 1
    Context:server config, virtual host
    Status:Extension
    Module:mod_http2
    Compatibility:Available in version 2.4.18 and later.
    +

    + This directive sets the number of seconds of idle time on a TLS + connection before the TLS write size falls back to small (~1300 bytes) + length. + This can be used server wide or for specific + <VirtualHost>s. +

    +

    + See <H2TLSWarmUpSize> for a + description of TLS warmup. H2TLSCoolDownSecs reflects the fact + that connections may deteriorate over time (and TCP flow adjusts) + for idle connections as well. It is beneficial to overall performance + to fall back to the pre-warmup phase after a number of seconds that + no data has been sent. +

    +

    + In deployments where connections can be considered reliable, this + timer can be disabled by setting it to 0. +

    +

    + The following example sets the seconds to zero, effectively disabling + any cool down. Warmed up TLS connections stay on maximum record + size. +

    +

    Example

    H2TLSCoolDownSecs 0
    +
    + +
    +
    top
    +

    H2TLSWarmUpSize Directive

    + + + + + + + + +
    Description:
    Syntax:H2TLSWarmUpSize amount
    Default:H2TLSWarmUpSize 1048576
    Context:server config, virtual host
    Status:Extension
    Module:mod_http2
    Compatibility:Available in version 2.4.18 and later.
    +

    + This directive sets the number of bytes to be sent in small + TLS records (~1300 bytes) until doing maximum sized writes (16k) + on https: HTTP/2 connections. + This can be used server wide or for specific + <VirtualHost>s. +

    +

    + Measurements by google performance + 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. +

    +

    + While TCP adjust its flow-control and window sizes, longer TLS + records can get stuck in queues or get lost and need retransmission. + This is of course true for all packets. TLS however needs the + whole record in order to decrypt it. Any missing bytes at the end + will stall usage of the received ones. +

    +

    + After a sufficient number of bytes have been send successfully, + the TCP state of the connection is stable and maximum TLS record + sizes (16 KB) can be used for optimal performance. +

    +

    + In deployments where servers are reached locally or over reliable + connections only, the value might be decreased with 0 disabling + any warmup phase altogether. +

    +

    + The following example sets the size to zero, effectively disabling + any warmup phase. +

    +

    Example

    H2TLSWarmUpSize 0
    +
    + +
    +
    top
    +

    H2Upgrade Directive

    + + + + + + + +
    Description:H2 Upgrade Protocol Switch
    Syntax:H2Upgrade on|off
    Default:H2Upgrade on for h2c, off for h2 protocol
    Context:server config, virtual host
    Status:Extension
    Module:mod_http2
    +

    + This directive toggles the usage of the HTTP/1.1 Upgrade method + for switching to HTTP/2. This + should be used inside a + <VirtualHost> + section to enable Upgrades to HTTP/2 for that virtual host. +

    +

    + This method of switching protocols is defined in HTTP/1.1 and + uses the "Upgrade" header (thus the name) to announce willingness + to use another protocol. This may happen on any request of a + HTTP/1.1 connection. +

    +

    + This method of protocol switching is enabled by default on cleartext + (potential h2c) connections and disabled on TLS (potential h2), + as mandated by RFC 7540. +

    +

    + Please be aware that Upgrades are only accepted for requests + that carry no body. POSTs and PUTs with content will never + trigger an upgrade to HTTP/2. + See <H2Direct> for an + alternative to Upgrade. +

    +

    + This mode only has an effect when h2 or h2c is enabled via + the <Protocols>. +

    +

    Example

    H2Upgrade on
    +
    +
    top

    H2WindowSize Directive

    diff --git a/docs/manual/mod/mod_ssl.html.en b/docs/manual/mod/mod_ssl.html.en index df6b18e8af..3e7f45a6e6 100644 --- a/docs/manual/mod/mod_ssl.html.en +++ b/docs/manual/mod/mod_ssl.html.en @@ -2426,9 +2426,11 @@ if SSLUseStapling i Compatibility:Available if using OpenSSL 0.9.8h or later

    When enabled, mod_ssl will pass responses from unsuccessful -stapling related OCSP queries (such as status errors, expired responses etc.) -on to the client. If set to off, no stapled responses -for failed queries will be included in the TLS handshake.

    +stapling related OCSP queries (such as responses with an overall status +other than "successful", responses with a certificate status other than +"good", expired responses etc.) on to the client. +If set to off, only responses indicating a certificate status +of "good" will be included in the TLS handshake.

    top
    diff --git a/docs/manual/mod/quickreference.html.en b/docs/manual/mod/quickreference.html.en index 05b51b7f96..7f2b46fd97 100644 --- a/docs/manual/mod/quickreference.html.en +++ b/docs/manual/mod/quickreference.html.en @@ -467,14 +467,20 @@ media type in the HTTP Content-Type header field will exit. Group unix-group #-1 sBGroup under which the server will answer requests -H2Direct on|off on (for non TLS) svEH2 Direct Protocol Switch +H2Direct on|off on for h2c, off for +svEH2 Direct Protocol Switch H2MaxSessionStreams n 100 svEMaximum number of active streams per HTTP/2 session. H2MaxWorkerIdleSeconds n 600 sEMaximum number of seconds h2 workers remain idle until shut down. H2MaxWorkers nsEMaximum number of worker threads to use per child process. H2MinWorkers nsEMinimal number of worker threads to use per child process. -H2SerializeHeaders on|off off svESerialize Request/Response Processing Switch -H2SessionExtraFiles n 5 svENumber of Extra File Handles -H2StreamMaxMemSize bytes 65536 svEMaximum amount of output data buffered per stream. +H2ModernTLSOnly on|off on svERequire HTTP/2 connections to be "modern TLS" only +H2Push on|off on svEH2 Server Push Switch +H2PushPriority mime-type [after|before|interleaved] [weight] * After 16 svEH2 Server Push Priority +H2SerializeHeaders on|off off svESerialize Request/Response Processing Switch +H2SessionExtraFiles n 5 svENumber of Extra File Handles +H2StreamMaxMemSize bytes 65536 svEMaximum amount of output data buffered per stream. +H2TLSCoolDownSecs seconds 1 svE- +H2TLSWarmUpSize amount 1048576 svE- +H2Upgrade on|off on for h2c, off for +svEH2 Upgrade Protocol Switch H2WindowSize bytes 65536 svESize of Stream Window for upstream data. Header [condition] add|append|echo|edit|edit*|merge|set|setifempty|unset|note header [[expr=]value [replacement]