From 71ec87d3a61264c42228812ddd61434909c0cdb2 Mon Sep 17 00:00:00 2001 From: Luca Toscano Date: Tue, 15 Mar 2016 15:51:37 +0000 Subject: [PATCH] Added some sections to the HTTP/2 howto. Still WIP. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1735114 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/howto/http2.xml | 173 ++++++++++++++++++------------------ 1 file changed, 85 insertions(+), 88 deletions(-) diff --git a/docs/manual/howto/http2.xml b/docs/manual/howto/http2.xml index 00eb8bb602..89a0a0e6ed 100644 --- a/docs/manual/howto/http2.xml +++ b/docs/manual/howto/http2.xml @@ -34,19 +34,26 @@
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!

+

The HTTP/2 protocol offers an excellent documentation and we strongly suggest to check the following links before proceeding:

+
+
RFC 7540
+
The Hypertext Transfer Protocol version 2 - very dense of information but also really nice for newcomers.
+
HTTP/2 FAQ
+
A lot of answers to common questions about the HTTP/2 protocol.
+
RFC 7541
+
HPACK, the header compression specification for HTTP/2
+
+

There are some new terms and gotchas that need to be kept in mind while reading this document:

+
@@ -64,94 +71,84 @@
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 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.

+

Building a httpd release is described in this document and it involves adding parameters to a configure script. The ones specific for HTTP/2 are:

+
+
--enable-http2
+
This enables the module 'http2' which does implement the HTTP/2 protocol.
+
--with-nghttp2=dir
+
This specifies a non-standard location for the library libnghttp2 which is necessary for the http2 module. If nghttp2 is in a standard place, the configure process will pick it up automatically.
+
--enable-nghttp2-staticlib-deps
+
Ultra-rarely needed option used to statically link the nghttp2 library to the server. On most platforms, this only has an effect when there is no shared nghttp2 library to be found.
+
+

The instructions to build libnghttp2 from the sources (if needed) are described in the related page.

+

An up to date TLS library that implements ALPN is needed to negotiate the h2 protocol (secure variant of HTTP/2, please check above for more info). OpenSSL fully supports ALPN from 1.0.2 onwards.

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

+
+ Protocol Configuration +

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

+ +

The first thing to do is to load the mod_http2 module and to enable some basic logging:

+# Load the http2 module LoadModule http2_module modules/mod_http2.so + +# Enable basic logging for the http2 module +<IfModule http2_module> + LogLevel http2:info +</IfModule> - -

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:

+

Before reading the next sections please think about the following questions:

+
    +
  • Is HTTP/2 support needed at server level or only in a specific VirtualHost?
    • +
  • Is HTTP/2 support needed for secure (h2) and insecure (h2c) connections or only the former?
    • +
+
Server wide +

In order to simply add HTTP/2 support at server level for secure/insecure connections the following config is sufficient:

+# Enable HTTP/2 and HTTP 1.1 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> - + +

Detailed list of things that will be enabled by this configuration:

+
    +
  • HTTP/2 negotiation (h2) via TLS ALPN for secure VirtualHost.
    • +
  • HTTP/2 cleartext negotiation (h2c) upgrading from an initial HTTP/1.1 connection or via HTTP/2 preamble checking (Direct mode, see H2Direct).
    • +
+

Something to notice is the difference in the protocol negotiation between h2 and h2c: the former uses the TLS ALPN extensions meanwhile the latter requires to establish a HTTP 1.1 connection first and then Upgrade it to HTTP/2 (this step is handled transparently by the httpd server - websockets use the same procedure too).

+
-

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

+
Secure VirtualHost only +

A very common scenario is enabling HTTP/2 only for a secure VirtualHost, leaving HTTP 1.1 for insecure connections:

-Protocols h2 h2c http/1.1 - +# Enable HTTP/2 and HTTP 1.1 +Protocols h2 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 +<VirtualHost *:443> + # [...] refers to content truncated + SSLCipherSuite ECDHE-RSA-AES128-GCM-SHA256:[...] + SSLHonorCipherOrder on + SSLCertificateFile <path> + SSLCertificateKeyFile <path> + [...] +</VirtualHost> -

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.

+

Detailed list of things that will be enabled by this configuration:

+
    +
  • HTTP/2 negotiation (h2) via TLS ALPN only for the secure VirtualHost.
    • +
  • HTTP 1.1 for both secure and insecure connections (HTTP/2 cleartext negotiation - h2c - is not allowed in this config).
    • +
+

Please note: 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 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 blacklist.

+
+
+ +
+ Module Configuration +

This section should contain examples of mod_http2 configurations.

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

+
+ Browsers +

Browser support.

-- 2.40.0