From: Rich Bowen Date: Thu, 18 Jun 2026 12:13:12 +0000 (+0000) Subject: docs: Editorial pass on howto/http2.xml X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=cf221bb4acf26bea3379f59f1e6d2ef57c03b62b;p=thirdparty%2Fapache%2Fhttpd.git docs: Editorial pass on howto/http2.xml - Grammar and spelling fixes throughout (fixes bz#70115) - Wrap overlong lines to match document style - Replace dead browser extension links with current equivalents - Update caniuse link to https - Simplify browser support list (all modern browsers support HTTP/2) - Note Server Push deprecation per RFC 9113; point to Early Hints - Note Accept-Push-Policy draft expired and was never adopted git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1935469 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/howto/http2.xml b/docs/manual/howto/http2.xml index bc389ff21b..bef9443f97 100644 --- a/docs/manual/howto/http2.xml +++ b/docs/manual/howto/http2.xml @@ -37,24 +37,38 @@ The HTTP/2 protocol

HTTP/2 is the evolution of the world's most successful application layer protocol, HTTP. It focuses on making more efficient use of network resources. It does not change the fundamentals - of HTTP, the semantics. There are still request and responses and headers and all that. So, if + of HTTP, the semantics. There are still requests 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 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 + better document to start with is http2 explained by Daniel Stenberg, the author of curl. It is available in an ever growing list of languages, too!

-

Too Long, Didn't read: there are some new terms and gotchas that need to be kept in mind while reading this document:

+

TL;DR: there are some new terms and gotchas that need to be kept in + mind while reading this document:

@@ -66,9 +80,9 @@ 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.

-

One feature of HTTP/2 that offers new capabilities for web developers is - Server Push. See that section on how your web application - can make use of it.

+

One feature of HTTP/2 that formerly offered new capabilities for web developers is + Server Push, though it is now deprecated. See the + Early Hints section for the recommended alternative.

@@ -83,9 +97,9 @@ to configure.

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.

+ exists. It works quite similarly 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: - URLs, so you need a server with SSL support. But not only that, you will need a SSL library + URLs, so you need a server with SSL support. But not only that, you will need an SSL library that supports the ALPN extension. If OpenSSL is the library you use, you need at least version 1.0.2.

@@ -94,7 +108,7 @@ Basic Configuration

When you have a httpd built with mod_http2 you need some - basic configuration for it becoming active. The first thing, as with every Apache module, + basic configuration for it becoming active. The first thing, as with every httpd module, is that you need to load it:

LoadModule http2_module modules/mod_http2.so @@ -124,9 +138,9 @@ Protocols http/1.1 Choose a strong SSLCipherSuite

The SSLCipherSuite needs to be configured with a strong TLS cipher suite. The current version of mod_http2 does not enforce any cipher but most - clients do so. Pointing a browser to a h2 enabled server with a inappropriate + clients do so. Pointing a browser to a h2 enabled server with an inappropriate 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 + made 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 (9113).

 @@ -181,9 +195,9 @@ ProtocolsHonorOrder Off
Clients -

Almost all modern browsers support HTTP/2, but only over SSL connections: Firefox (v43), - Chrome (v45), Safari (since v9), iOS Safari (v9), Opera (v35), Chrome for Android (v49) - and Internet Explorer (v11 on Windows10) (source).

+

All modern browsers support HTTP/2 over TLS connections + (source). Support has been universal across + major browsers since approximately 2015.

Other clients, as well as servers, are listed on the Implementations wiki, among them implementations for c, c++, common lisp, dart, erlang, haskell, java, nodejs, php, @@ -215,9 +229,9 @@ ProtocolsHonorOrder Off

Chrome offers detailed HTTP/2 logs on its connections via the special net-internals page. There is also an - interesting extension for Chrome - and Firefox - to visualize when your browser is using HTTP/2.

+ interesting extension for Chrome + and Firefox + to indicate when your browser is using HTTP/2.

@@ -244,7 +258,7 @@ ProtocolsHonorOrder Off

To summarize: there is no one good strategy on how to make best use of this feature of HTTP/2 and everyone is still experimenting. So, how do you experiment with it in Apache httpd?

-

mod_http2 inspect response header for Link headers +

mod_http2 inspects response headers for Link headers in a certain format:

Link </xxx.css>;rel=preload, </xxx.js>; rel=preload @@ -272,12 +286,12 @@ H2Push Off (hashes of URLs, basically) and will not PUSH the same resource twice. When the connection closes, this information is discarded.

There are people thinking about how a client can tell a server what it - already has, so PUSHes for those things can be avoided, but this is all - highly experimental right now.

-

Another experimental draft that has been implemented in mod_http2 + already has, so PUSHes for those things can be avoided, but no standard + emerged before push was deprecated.

+

An experimental draft that was implemented in mod_http2 is the Accept-Push-Policy Header Field where a client can, for each request, define - what kind of PUSHes it accepts.

+ what kind of PUSHes it accepts. This draft expired and was never adopted.

PUSH might not always trigger the request/response/performance that one expects or hopes for. There are various studies on this topic to be found on the web that explain @@ -293,8 +307,8 @@ H2Push Off accept-encoding, accept-language, cache-control.

All other headers are ignored. Cookies will also not be copied over. PUSHing resources that require a cookie to be present will not work. This can be a matter of debate. But - unless this is more clearly discussed with browser, let's err on the side of caution and - not expose cookie where they might ordinarily not be visible.

+ unless this is more clearly discussed with browsers, let's err on the side of caution and + not expose cookies where they might ordinarily not be visible.

@@ -316,11 +330,11 @@ H2EarlyHints on </Location>

This will send out a "103 Early Hints" response to a client as soon - as the server starts processing the request. This may be much early than + as the server starts processing the request. This may be much earlier than the time the first response headers have been determined, depending on your web application.

If H2Push is enabled, this will also start the PUSH right after the - 103 response. If H2Push is disabled however, the 103 response will be send + 103 response. If H2Push is disabled however, the 103 response will be sent nevertheless to the client.