mirror of
https://github.com/apache/httpd.git
synced 2025-12-09 11:41:15 +03:00
4f1b45df4e
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1734819 13f79535-47bb-0310-9956-ffa450edef68
253 lines
17 KiB
XML
253 lines
17 KiB
XML
<?xml version="1.0" encoding="ISO-8859-1"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
|
||
<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
|
||
<!--
|
||
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
||
This file is generated from xml source: DO NOT EDIT
|
||
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
||
-->
|
||
<title>HTTP/2 guide - Apache HTTP Server Version 2.5</title>
|
||
<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
|
||
<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
|
||
<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
|
||
<script src="../style/scripts/prettify.min.js" type="text/javascript">
|
||
</script>
|
||
|
||
<link href="../images/favicon.ico" rel="shortcut icon" /></head>
|
||
<body id="manual-page"><div id="page-header">
|
||
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
|
||
<p class="apache">Apache HTTP Server Version 2.5</p>
|
||
<img alt="" src="../images/feather.png" /></div>
|
||
<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
|
||
<div id="path">
|
||
<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.5</a> > <a href="./">How-To / Tutorials</a></div><div id="page-content"><div id="preamble"><h1>HTTP/2 guide</h1>
|
||
<div class="toplang">
|
||
<p><span>Available Languages: </span><a href="../en/howto/public_html.html" title="English"> en </a> |
|
||
<a href="../fr/howto/public_html.html" hreflang="fr" rel="alternate" title="Fran<61>ais"> fr </a> |
|
||
<a href="../ja/howto/public_html.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
|
||
<a href="../ko/howto/public_html.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
|
||
<a href="../tr/howto/public_html.html" hreflang="tr" rel="alternate" title="T<>rk<72>e"> tr </a></p>
|
||
</div>
|
||
|
||
<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="#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>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><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="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>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="clients" id="clients">Clients</a></h2>
|
||
|
||
<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><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> |
|
||
<a href="../fr/howto/public_html.html" hreflang="fr" rel="alternate" title="Fran<61>ais"> fr </a> |
|
||
<a href="../ja/howto/public_html.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
|
||
<a href="../ko/howto/public_html.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
|
||
<a href="../tr/howto/public_html.html" hreflang="tr" rel="alternate" title="T<>rk<72>e"> tr </a></p>
|
||
</div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
|
||
<script type="text/javascript"><!--//--><![CDATA[//><!--
|
||
var comments_shortname = 'httpd';
|
||
var comments_identifier = 'http://httpd.apache.org/docs/trunk/howto/public_html.html';
|
||
(function(w, d) {
|
||
if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
|
||
d.write('<div id="comments_thread"><\/div>');
|
||
var s = d.createElement('script');
|
||
s.type = 'text/javascript';
|
||
s.async = true;
|
||
s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
|
||
(d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
|
||
}
|
||
else {
|
||
d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
|
||
}
|
||
})(window, document);
|
||
//--><!]]></script></div><div id="footer">
|
||
<p class="apache">Copyright 2016 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
|
||
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
|
||
if (typeof(prettyPrint) !== 'undefined') {
|
||
prettyPrint();
|
||
}
|
||
//--><!]]></script>
|
||
</body></html> |