You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by ic...@apache.org on 2016/03/10 13:57:39 UTC
svn commit: r1734405 - /httpd/httpd/trunk/docs/manual/howto/http2.xml
Author: icing
Date: Thu Mar 10 12:57:38 2016
New Revision: 1734405
URL: http://svn.apache.org/viewvc?rev=1734405&view=rev
Log:
fleshing out the http2 howto a bit
Modified:
httpd/httpd/trunk/docs/manual/howto/http2.xml
Modified: httpd/httpd/trunk/docs/manual/howto/http2.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/howto/http2.xml?rev=1734405&r1=1734404&r2=1734405&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/howto/http2.xml (original)
+++ httpd/httpd/trunk/docs/manual/howto/http2.xml Thu Mar 10 12:57:38 2016
@@ -25,33 +25,198 @@
<title>HTTP/2 guide</title>
<summary>
- <p>This howto is still a work in progress! Please do not trust completely the following information until the work is finished.</p>
+ <p>This is the howto guide for the HTTP/2 implementation in Apache httpd. This
+ feature is <em>experimental</em> and you may expect interfaces and directives to
+ change between releases.
+ </p>
</summary>
<seealso><a href="../mod/mod_http2.html">mod_http2</a></seealso>
<section id="protocol">
<title>The HTTP/2 protocol</title>
- <p>This section should contain an overview of the protocol and links to official docs.</p>
+ <p>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.</p>
+ <p>There has been a lot written about HTTP/2 and how it works. The most normative is, of course,
+ its <a href="https://tools.ietf.org/html/rfc7540">RFC 7540</a>
+ (<a href="http://httpwg.org/specs/rfc7540.html">also available in more readable formatting, YMMV</a>).
+ So, there you'll find the nuts and bolts.</p>
+ <p>But, as RFC do, it's not really a good thing to read first. It's better to first understand
+ <em>what</em> a thing wants to do and then read the RFC about <em>how</em> it is done. A much
+ better document to start with is <a href="https://daniel.haxx.se/http2/">http2 explained</a>
+ by Daniel Stenberg, the author of <a href="https://curl.haxx.se">curl</a>. It is available in
+ an ever growing list of languages, too!</p>
</section>
+ <section id="implementation">
+ <title>HTTP/2 in Apache httpd</title>
+ <p>The HTTP/2 protocol is implemented by its own httpd module, aptly named
+ <a href="../mod/mod_http2.html">mod_http2</a>. 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 '<code>h2c</code>',
+ the secure one '<code>h2</code>'. For <code>h2c</code> it allows the <em>direct</em>
+ mode and the <code>Upgrade:</code> via an initial HTTP/1 request.</p>
+ <p>One feature of HTTP/2 that offers new capabilities for web developers is
+ <a href="#push">Server Push</a>. See that section on how your web application
+ can make use of it.</p>
+ </section>
+
<section id="building">
<title>Build httpd with HTTP/2 support</title>
- <p>This section should contain info about how to build HTTP/2 support into httpd plus other requirements.</p>
+ <p><a href="../mod/mod_http2.html">mod_http2</a> uses the library of <a href="https://nghttp2.org">nghttp2</a>
+ as its implementation base. In order to build <code>mod_http2</code> you need at least version 1.2.1 of
+ <code>libnghttp2</code> installed on your system.</p>
+ <p>When you <code>./configure</code> you Apache httpd source tree, you need to give it
+ '<code>--enable-http2</code>' as additional argument to trigger the build of the module.
+ Should your <code>libnghttp2</code> reside in an unusual place (whatever that is on your
+ operating system), you may announce its location with '<code>--with-nghttp2=<path></code>'
+ to <code>configure</code>.</p>
+ <p>While that should do the trick for most, they are people who might prefer a statically
+ linked <code>nghttp2</code> in this module. For those, the option <code>--enable-nghttp2-staticlib-deps</code>
+ exists. It works quite similar to how one statically links openssl to mod_ssl.</p>
+ <p>Speaking of SSL, you need to be aware that most browsers will speak HTTP/2 only on <code>https:</code>
+ URLs, so you need a server with SSL support. But not only that, you will need a SSL library
+ that supports the <code>ALPN</code> extension. If OpenSSL is the library you use, you need
+ at least version 1.0.2.</p>
</section>
- <section id="configurations">
- <title>Configurations</title>
- <p>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).</p>
+ <section id="basic-config">
+ <title>Basic Configuration</title>
+
+ <p>When you have a <code>httpd</code> built with <code>mod_http2</code> you need some
+ basic configuration for it becoming active. The first thing, as with every Apache module,
+ is that you need to load it:</p>
+ <highlight language="config">
+LoadModule http2_module modules/mod_http2.so
+ </highlight>
+
+ <p>The second directive you need to add to your server configuration is</p>
+ <highlight language="config">
+Protocols h2 http/1.1
+</highlight>
+ <p>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:</p>
+ <highlight language="config">
+Protocols h2 h2c http/1.1
+</highlight>
+ <p>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:</p>
+ <highlight language="config">
+Protocols http/1.1
+<VirtualHost ...>
+ ServerName test.example.org
+ Protocols h2 http/1.1
+</VirtualHost>
+</highlight>
+
+ <p>This allows only HTTP/1 on connections, except SSL connections to <code>test.example.org</code>
+ which offer HTTP/2.</p>
+ <p>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</p>
+ <highlight language="config">
+Protocols http/1.1 h2
+</highlight>
+ <p>the most preferred protocol is HTTP/1 and it will always be selected unless a
+ client <em>only</em> supports h2. Since we want to talk HTTP/2 to clients that
+ support it, the better order is</p>
+ <highlight language="config">
+Protocols h2 h2c http/1.1
+</highlight>
+
+ <p>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:</p>
+ <highlight language="config">
+ProtocolsHonorOrder Off
+ </highlight>
+ <p>makes the order <em>you</em> wrote the Protocols irrelevant and only the client's
+ ordering will decide.</p>
+ <p>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 <code>Protocols</code> with any <code>IfModule</code> checks.</p>
+ <p>For more advanced tips on configuration, see the <a href="../mod/mod_http2.html#dimensioning">
+ modules section about dimensioning</a> and <a href="../mod/mod_http2.html#misdirected">
+ how to manage multiple hosts with the same certificate</a>.</p>
</section>
- <section id="browsers">
- <title>Browsers</title>
- <p>Browser support.</p>
+ <section id="clients">
+ <title>Clients</title>
+ <p>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) (<a href="http://caniuse.com/#search=http2">source</a>).</p>
+ <p>Other clients, as well as servers, are listed
+ <a href="https://github.com/http2/http2-spec/wiki/Implementations">on the Implementations wiki</a>,
+ among them implementations for c, c++, common lisp, dart, erlang, haskell, java, nodejs, php,
+ python, perl, ruby, rust, scala and swift.</p>
+ <p>Several of the non-browser client implementations support HTTP/2 over cleartext, h2c. The
+ most versatile being <a href="https://curl.haxx.se">curl</a>.</p>
</section>
<section id="tools">
<title>Useful tools to debug HTTP/2</title>
- <p>This section should contain examples of tools to test/debug HTTP/2 connections.</p>
+ <p><a href="https://curl.haxx.se">curl</a>.</p>
+ <p>And for really deep inspection <a href="https://www.wireshark.org">wireshark</a>.</p>
+ <p>The <a href="https://nghttp2.org">nghttp2</a> package also includes clients, such as
+ <code>nghttp</code> and <code>h2load</code>, the latter one being very useful in putting
+ some stress on your server.</p>
+ <p>Chrome offers also detailed HTTP/2 logs on its connections via the
+ <a href="chrome://net-internals/#http2">special net-internals page</a>.</p>
</section>
+ <section id="push">
+ <title>Server Push</title>
+ <p>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..."</p>
+ <p>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.</p>
+ <p>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.</p>
+ <p>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.</p>
+ <p>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?</p>
+ <p><code>mod_http2</code> inspect response header for <code>Link</code> headers
+ in a certain format:</p>
+ <highlight language="config">
+Link </xxx.css>;rel=preload, </xxx.js>; rel=preload
+ </highlight>
+ <p>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</p>
+ <highlight language="config">
+<Location /xxx.html>
+ Header add Link "</xxx.css>;rel=preload"
+ Header add Link "</xxx.js>;rel=preload"
+</Location>
+ </highlight>
+ <p>If you want to use <code>preload</code> links without triggering a PUSH, you
+ can use the <code>nopush</code> parameter, as in</p>
+ <highlight language="config">
+Link </xxx.css>;rel=preload;nopush
+ </highlight>
+ <p>or you may disable PUSHes for your server entirely with the directive</p>
+ <highlight language="config">
+H2Push Off
+ </highlight>
+ <p>And there is more:</p>
+ <p>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.</p>
+ <p>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.</p>
+ <p>Another experimental draft that has been implemented in <code>mod_http2</code>
+ is the <a href="https://tools.ietf.org/html/draft-ruellan-http-accept-push-policy-00">
+ Accept-Push-Policy Header Field</a> where a client can, for each request, define
+ what kind of PUSHes it accepts.</p>
+ </section>
+
</manualpage>
Re: svn commit: r1734405 - /httpd/httpd/trunk/docs/manual/howto/http2.xml
Posted by Eric Covener <co...@gmail.com>.
On Thu, Mar 10, 2016 at 7:57 AM, <ic...@apache.org> wrote:
> + <p>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.</p>
Is there really a second restriction there?