HTTP/2 guide

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 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 RFC 7540 (also available in more readable formatting, YMMV). 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 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 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:

• 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 section.
• 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 section.
• 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).

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

Build httpd with HTTP/2 support

mod_http2 uses the library of nghttp2 as its implementation base. In order to build mod_http2 you need at least version 1.2.1 of libnghttp2 installed on your system.

When you ./configure your Apache httpd source tree, you need to give it '--enable-http2' as additional argument to trigger the build of the module. 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 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: URLs, so you need a server with SSL support. But not only that, you will need a SSL library that supports the ALPN extension. If OpenSSL is the library you use, you need at least version 1.0.2.

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, is that you need to load it:

LoadModule http2_module modules/mod_http2.so

The second directive you need to add to your server configuration is

Protocols h2 http/1.1

This allows h2, the secure variant, to be the preferred protocol on your server connections. When you want to enable all HTTP/2 variants, you simply write:

Protocols h2 h2c http/1.1

Depending on where you put this directive, it affects all connections or just the ones to a certain virtual host. You can nest it, as in:

Protocols http/1.1
<VirtualHost ...>
    ServerName test.example.org
    Protocols h2 http/1.1
</VirtualHost>

This allows only HTTP/1 on connections, except SSL connections to test.example.org which offer HTTP/2.

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 left is selected. In

Protocols http/1.1 h2

the most preferred protocol is HTTP/1 and it will always be selected unless a client only supports h2. Since we want to talk HTTP/2 to clients that support it, the better order is

Protocols h2 h2c http/1.1

There is one more thing to ordering: the client has its own preferences, too. If you want, you can configure your server to select the protocol most preferred by the client:

ProtocolsHonorOrder Off

makes the order you wrote the Protocols irrelevant and only the client's ordering will decide.

A last thing: the protocols you configure are not checked for correctness or spelling. You can mention protocols that do not exist, so there is no need to guard Protocols with any <IfModule> checks.

For more advanced tips on configuration, see the modules section about dimensioning and how to manage multiple hosts with the same certificate.

MPM Configuration

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

mod_http2 will not work around this limit by default. The reason is that