From 11c135bf6feefb788dbf302a44d1c780f0e82d4d Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 10 Mar 2016 12:57:38 +0000 Subject: [PATCH] fleshing out the http2 howto a bit git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1734405 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/howto/http2.xml | 185 ++++++++++++++++++++++++++++++++++-- 1 file changed, 175 insertions(+), 10 deletions(-) diff --git a/docs/manual/howto/http2.xml b/docs/manual/howto/http2.xml index 67e54e6f82..00eb8bb602 100644 --- a/docs/manual/howto/http2.xml +++ b/docs/manual/howto/http2.xml @@ -25,33 +25,198 @@ HTTP/2 guide -

This howto is still a work in progress! Please do not trust completely the following information until the work is finished.

+

This is the howto guide for the HTTP/2 implementation in Apache httpd. This + feature is experimental and you may expect interfaces and directives to + change between releases. +

mod_http2
The HTTP/2 protocol -

This section should contain an overview of the protocol and links to official docs.

+

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!

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

This section should contain info about how to build HTTP/2 support into httpd plus other requirements.

+

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

-
- Configurations -

This section should contain various configuration examples for HTTP/2 (h2, h2c, etc..) plus common pitfalls (for example not setting a strong TLS cipher suite with h2).

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

-
- Browsers -

Browser support.

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

+

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, + python, perl, ruby, rust, scala and swift.

+

Several of the non-browser client implementations support HTTP/2 over cleartext, h2c. The + most versatile being curl.

Useful tools to debug HTTP/2 -

This section should contain examples of tools to test/debug HTTP/2 connections.

+

curl.

+

And for really deep inspection wireshark.

+

The nghttp2 package also includes clients, such as + nghttp and h2load, the latter one being very useful in putting + some stress on your server.

+

Chrome offers also detailed HTTP/2 logs on its connections via the + special net-internals page.

+
+ Server Push +

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

+

But there are restrictions: the client can disable this feature and the + server may only ever PUSH on a request that came from the client.

+

The intention is to allow the server to send resources to the clien that + it will most likely need: a css or javascript resource that belongs to a html + page the client requested. A set of images that is referenced by a css, etc.

+

The advantage for the client is that it saves the time to send the request which + may range from a few milli seconds to half a second, depending on where on the + globe both are located. The disadvantage is that the client may get sent + things it already has in its cache. Sure, HTTP/2 allows for the early cancellation + of such requests, but still there are resources wasted.

+

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 + in a certain format:

+ +Link </xxx.css>;rel=preload, </xxx.js>; rel=preload + +

If the connection supports PUSH, these two resources will be sent to the + client. As a web developer, you may set these headers either directly in + your application response or you configure the server via

+ +<Location /xxx.html> + Header add Link "</xxx.css>;rel=preload" + Header add Link "</xxx.js>;rel=preload" +</Location> + +

If you want to use preload links without triggering a PUSH, you + can use the nopush parameter, as in

+ +Link </xxx.css>;rel=preload;nopush + +

or you may disable PUSHes for your server entirely with the directive

+ +H2Push Off + +

And there is more:

+

The module will keep a diary of what has been PUSHed for each connection + (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 + is the + Accept-Push-Policy Header Field where a client can, for each request, define + what kind of PUSHes it accepts.

+
+ -- 2.50.1