<a href="../tr/howto/public_html.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p>
</div>
- <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>
</div>
<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#protocol">The HTTP/2 protocol</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#implementation">HTTP/2 in Apache httpd</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#building">Build httpd with HTTP/2 support</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#configurations">Configurations</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#browsers">Browsers</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#basic-config">Basic Configuration</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#clients">Clients</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#tools">Useful tools to debug HTTP/2</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#push">Server Push</a></li>
</ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_http2.html">mod_http2</a></li></ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="protocol" id="protocol">The HTTP/2 protocol</a></h2>
- <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>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="implementation" id="implementation">HTTP/2 in Apache httpd</a></h2>
+
+ <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>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="building" id="building">Build httpd with HTTP/2 support</a></h2>
- <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>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
-<h2><a name="configurations" id="configurations">Configurations</a></h2>
+<h2><a name="basic-config" id="basic-config">Basic Configuration</a></h2>
+
+
+ <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>
+ <pre class="prettyprint lang-config">LoadModule http2_module modules/mod_http2.so</pre>
+
- <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>
+ <p>The second directive you need to add to your server configuration is</p>
+ <pre class="prettyprint lang-config">Protocols h2 http/1.1</pre>
+
+ <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>
+ <pre class="prettyprint lang-config">Protocols h2 h2c http/1.1</pre>
+
+ <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>
+ <pre class="prettyprint lang-config">Protocols http/1.1
+<VirtualHost ...>
+ ServerName test.example.org
+ Protocols h2 http/1.1
+</VirtualHost></pre>
+
+
+ <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>
+ <pre class="prettyprint lang-config">Protocols http/1.1 h2</pre>
+
+ <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>
+ <pre class="prettyprint lang-config">Protocols h2 h2c http/1.1</pre>
+
+
+ <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>
+ <pre class="prettyprint lang-config">ProtocolsHonorOrder Off</pre>
+
+ <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>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
-<h2><a name="browsers" id="browsers">Browsers</a></h2>
+<h2><a name="clients" id="clients">Clients</a></h2>
- <p>Browser support.</p>
+ <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>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="tools" id="tools">Useful tools to debug HTTP/2</a></h2>
- <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>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="push" id="push">Server Push</a></h2>
+
+ <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>
+ <pre class="prettyprint lang-config">Link </xxx.css>;rel=preload, </xxx.js>; rel=preload</pre>
+
+ <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>
+ <pre class="prettyprint lang-config"><Location /xxx.html>
+ Header add Link "</xxx.css>;rel=preload"
+ Header add Link "</xxx.js>;rel=preload"
+</Location></pre>
+
+ <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>
+ <pre class="prettyprint lang-config">Link </xxx.css>;rel=preload;nopush</pre>
+
+ <p>or you may disable PUSHes for your server entirely with the directive</p>
+ <pre class="prettyprint lang-config">H2Push Off</pre>
+
+ <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>
</div></div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/howto/public_html.html" title="English"> en </a> |
<div class="directive-section"><h2><a name="SSLCARevocationCheck" id="SSLCARevocationCheck">SSLCARevocationCheck</a> <a name="sslcarevocationcheck" id="sslcarevocationcheck">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable CRL-based revocation checking</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCARevocationCheck chain|leaf|none</code></td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCARevocationCheck chain|leaf|none <em>flag</em>s</code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLCARevocationCheck none</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Optional <em>flag</em>s available in httpd 2.5-dev or
+later</td></tr>
</table>
<p>
Enables certificate revocation list (CRL) checking. At least one of
CRL checks are applied to all certificates in the chain, while setting it to
<code>leaf</code> limits the checks to the end-entity cert.
</p>
-<div class="note">
-<h3>When set to <code>chain</code> or <code>leaf</code>,
-CRLs <em>must</em> be available for successful validation</h3>
-<p>
-Prior to version 2.3.15, CRL checking in mod_ssl also succeeded when
-no CRL(s) were found in any of the locations configured with
-<code class="directive"><a href="#sslcarevocationfile">SSLCARevocationFile</a></code>
-or <code class="directive"><a href="#sslcarevocationpath">SSLCARevocationPath</a></code>.
-With the introduction of this directive, the behavior has been changed:
-when checking is enabled, CRLs <em>must</em> be present for the validation
-to succeed - otherwise it will fail with an
-<code>"unable to get certificate CRL"</code> error.
-</p>
-</div>
+<p>The available <em>flag</em>s are:</p>
+<ul>
+<li><code>no_crl_for_cert_ok</code>
+ <p>
+ Prior to version 2.3.15, CRL checking in mod_ssl also succeeded when
+ no CRL(s) for the checked certificate(s) were found in any of the locations
+ configured with <code class="directive"><a href="#sslcarevocationfile">SSLCARevocationFile</a></code>
+ or <code class="directive"><a href="#sslcarevocationpath">SSLCARevocationPath</a></code>.
+ </p>
+ <p>
+ With the introduction of <code class="directive">SSLCARevocationFile</code>,
+ the behavior has been changed: by default with <code>chain</code> or
+ <code>leaf</code>, CRLs <strong>must</strong> be present for the
+ validation to succeed - otherwise it will fail with an
+ <code>"unable to get certificate CRL"</code> error.
+ </p>
+ <p>
+ The <em>flag</em> <code>no_crl_for_cert_ok</code> allows to restore
+ previous behaviour.
+ </p>
+</li>
+</ul>
<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCARevocationCheck chain</pre>
</div>
+<div class="example"><h3>Compatibility with versions 2.2</h3><pre class="prettyprint lang-config">SSLCARevocationCheck chain no_crl_for_cert_ok</pre>
+</div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
projects / apache / commitdiff