From 9b6d0f2106be4f0ef3aabf23a414dcc3b8e7068e Mon Sep 17 00:00:00 2001
From: Stefan Eissing
You must enable HTTP/2 via
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
+
+ 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.
+ This directive toggles the usage of the HTTP/2 server push
+ protocol feature. This should be used inside a
+
+ 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
+ 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. +
++ 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. +
+
+ This directive toggles the usage of the HTTP/1.1 Upgrade method
+ for switching to HTTP/2. This
+ should be used inside a
+
+ 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
+ This mode only has an effect when h2 or h2c is enabled via
+ the
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.
@@ -282,4 +426,147 @@
+ This directive toggles the security checks on HTTP/2 connections
+ in TLS mode (https:). This can be used server wide or for specific
+
+ 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. +
+
+ 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
+
+ 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. +
+
+ 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
+
+ See
+ 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. +
+