From: Rich Bowen Date: Wed, 17 Jun 2026 20:56:52 +0000 (+0000) Subject: docs: Modernize howto/http2.xml X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=d1d2130daf842bbfc96e5f6b99692fc068bbac63;p=thirdparty%2Fapache%2Fhttpd.git docs: Modernize howto/http2.xml - Update all RFC references from 7540 to 9113 (which obsoletes it) - Remove duplicated RFC link in protocol overview - Add Server Push deprecation note (deprecated in RFC 9113 §8.4, removed by Chrome 106+/Edge 106+; recommend 103 Early Hints) - Update Homebrew note: remove obsolete --with-openssl/--with-nghttp2 flags (Homebrew removed formula options in 2019; curl includes HTTP/2 support by default now) - Fix typos: "consistent releases" → "consistent across releases", "as RFC do" → "as RFCs do", "they are" → "there are", "at at time" → "at a time", "avoiding to re-instantiate" → "avoiding the need to re-instantiate", "head of blocking" → "head-of-line blocking" git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1935464 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/howto/http2.xml b/docs/manual/howto/http2.xml index 90a76afe79..bc389ff21b 100644 --- a/docs/manual/howto/http2.xml +++ b/docs/manual/howto/http2.xml @@ -28,7 +28,7 @@

This is the howto guide for the HTTP/2 implementation in Apache httpd. This feature is production-ready and you may expect interfaces and directives to - remain consistent releases. + remain consistent across releases.

mod_http2 @@ -40,10 +40,9 @@ of HTTP, the semantics. There are still request and responses and headers and all that. So, if you already know HTTP/1, you know 95% about HTTP/2 as well.

There has been a lot written about HTTP/2 and how it works. The most normative is, of course, - its 7540 - (also available in more readable formatting, YMMV (7540)). - So, there you'll find the nuts and bolts.

-

But, as RFC do, it's not really a good thing to read first. It's better to first understand + its 9113 (which obsoletes the original 7540). + There you'll find the nuts and bolts.

+

But, as RFCs do, it's not really a good thing to read first. It's better to first understand what a thing wants to do and then read the RFC about how it is done. A much better document to start with is http2 explained by Daniel Stenberg, the author of curl. It is available in @@ -53,9 +52,9 @@

  • HTTP/2 is a binary protocol, as opposed to HTTP 1.1 that is plain text. The latter is meant to be human readable (for example sniffing network traffic) meanwhile the former is not. More info in the official FAQ question.
  • h2 is HTTP/2 over TLS (protocol negotiation via ALPN).
  • h2c is HTTP/2 over TCP.
    • -
  • A frame is the smallest unit of communication within an HTTP/2 connection, consisting of a header and a variable-length sequence of octets structured according to the frame type. More info in the official documentation 7540.
    • -
  • A stream is a bidirectional flow of frames within the HTTP/2 connection. The correspondent concept in HTTP 1.1 is a request/response message exchange. More info in the official documentation 7540.
    • -
  • HTTP/2 is able to run multiple streams of data over the same TCP connection, avoiding the classic HTTP 1.1 head of blocking slow request and avoiding to re-instantiate TCP connections for each request/response (KeepAlive patched the problem in HTTP 1.1 but did not fully solve it).
    • +
  • A frame is the smallest unit of communication within an HTTP/2 connection, consisting of a header and a variable-length sequence of octets structured according to the frame type. More info in the official documentation 9113.
    • +
  • A stream is a bidirectional flow of frames within the HTTP/2 connection. The correspondent concept in HTTP 1.1 is a request/response message exchange. More info in the official documentation 9113.
    • +
  • HTTP/2 is able to run multiple streams of data over the same TCP connection, avoiding the classic HTTP 1.1 head-of-line blocking of slow requests and avoiding the need to re-instantiate TCP connections for each request/response (KeepAlive patched the problem in HTTP 1.1 but did not fully solve it).
    • @@ -63,7 +62,7 @@ HTTP/2 in Apache httpd

    The HTTP/2 protocol is implemented by its own httpd module, aptly named mod_http2. It implements the complete set - of features described by RFC 7540 and supports HTTP/2 over cleartext (http:), as + of features described by RFC 9113 and supports HTTP/2 over cleartext (http:), as well as secure (https:) connections. The cleartext variant is named 'h2c', the secure one 'h2'. For h2c it allows the direct mode and the Upgrade: via an initial HTTP/1 request.

    @@ -82,7 +81,7 @@ Should your libnghttp2 reside in an unusual place (whatever that is on your operating system), you may announce its location with '--with-nghttp2=<path>' to configure.

    -

    While that should do the trick for most, they are people who might prefer a statically +

    While that should do the trick for most, there are people who might prefer a statically linked nghttp2 in this module. For those, the option --enable-nghttp2-staticlib-deps exists. It works quite similar to how one statically links openssl to mod_ssl.

    Speaking of SSL, you need to be aware that most browsers will speak HTTP/2 only on https: @@ -129,7 +128,7 @@ Protocols http/1.1 cipher suite will force it to simply refuse and fall back to HTTP 1.1. This is a common mistake that is done while configuring httpd for HTTP/2 the first time, so please keep it in mind to avoid long debugging sessions! If you want to be sure about the cipher suite to choose please avoid - the ones listed in the HTTP/2 TLS reject list (7540).

    + the ones listed in the HTTP/2 TLS reject list (9113).

    The order of protocols mentioned is also relevant. By default, the first one is the most preferred protocol. When a client offers multiple choices, the one most to the @@ -166,7 +165,7 @@ ProtocolsHonorOrder Off

    HTTP/2 is supported in all multi-processing modules that come with httpd. However, if you use the prefork mpm, there will be severe restrictions.

    -

    In prefork, mod_http2 will only process one request at at time +

    In prefork, mod_http2 will only process one request at a time per connection. But clients, such as browsers, will send many requests at the same time. If one of these takes long to process (or is a long polling one), the other requests will stall.

    @@ -203,8 +202,10 @@ ProtocolsHonorOrder Off Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 [...] Features: IPv6 Largefile NTLM NTLM_WB SSL libz TLS-SRP HTTP2 - Mac OS homebrew notes - brew install curl --with-openssl --with-nghttp2 + macOS Homebrew notes +

    Homebrew's curl includes HTTP/2 support by default. Install with + brew install curl and follow the displayed caveats to put it ahead + of the system curl in your PATH.

    And for really deep inspection wireshark.

    The nghttp2 package also includes clients, such as:

    @@ -221,6 +222,12 @@ ProtocolsHonorOrder Off
    Server Push + Deprecation Notice +

    Server Push is deprecated in 9113. Major browsers + (Chrome 106+, Edge 106+) have removed support for it. While mod_http2 + still implements push, new deployments should use 103 Early Hints + instead as a more reliable way to inform clients about needed resources.

    +

    The HTTP/2 protocol allows the server to PUSH responses to a client it never asked for. The tone of the conversation is: "here is a request that you never sent and the response to it will arrive soon..."