Merge in APR[-util] macros from branches/trunk-buildconf-noapr

[apache] / docs / manual / mod / mod_proxy_http2.html.en

diff --git a/docs/manual/mod/mod_proxy_http2.html.en b/docs/manual/mod/mod_proxy_http2.html.en
index 6682a4d8de3cea41adca9c22fe720bb87df32cc7..9238b7f7ca56cbc1afd0ca37c67f29f47d4358fa 100644 (file)
--- a/docs/manual/mod/mod_proxy_http2.html.en
+++ b/docs/manual/mod/mod_proxy_http2.html.en
@@ -35,19 +35,27 @@
 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_proxy_http2.c</td></tr></table>
 <h3>Summary</h3>
 
-    <p>This module <em>requires</em> the service of <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>. It provides the features used for
-    proxying HTTP/2 requests. <code class="module"><a href="../mod/mod_proxy_http2.html">mod_proxy_http2</a></code>
-    supports HTTP/2 only. It does <em>not</em>
-    provide any downgrades to HTTP/1.1.</p>
+    <p><code class="module"><a href="../mod/mod_proxy_http2.html">mod_proxy_http2</a></code>
+    supports HTTP/2 only, it does <em>not</em>
+    provide any downgrades to HTTP/1.1. This means that the backend
+    needs to support HTTP/2 because HTTP/1.1 will not be used instead.</p>
 
-    <p>Thus, in order to get the ability of handling HTTP/2 proxy requests,
+    <p>This module <em>requires</em> the service of <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, so in order to get the ability of
+    handling HTTP/2 proxy requests,
     <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> and <code class="module"><a href="../mod/mod_proxy_http2.html">mod_proxy_http2</a></code>
-    have to be present in the server.</p>
+    need to be both loaded by the server.</p>
 
-    <p><code class="module"><a href="../mod/mod_proxy_http2.html">mod_proxy_http2</a></code> works with incoming requests
-    over HTTP/1.1 and HTTP/2 requests. If <code class="module"><a href="../mod/mod_proxy_http2.html">mod_proxy_http2</a></code>
-    handles the frontend connection, requests against the same HTTP/2
-    backend are sent over a single connection, whenever possible.</p>
+    <p><code class="module"><a href="../mod/mod_proxy_http2.html">mod_proxy_http2</a></code> works with incoming fronted requests
+    using HTTP/1.1 or HTTP/2. In both cases, requests proxied
+    to the same backend are sent over a single TCP connection
+    whenever possible (namely when the connection can be re-used).</p>
+
+    <p>Caveat: there will be no attemp to consolidate multiple HTTP/1.1 
+    frontend requests (configured to be proxied to the same backend)
+    into HTTP/2 streams belonging to the same HTTP/2 request.
+    Each HTTP/1.1 frontend request will be proxied to the backend using
+    a separate HTTP/2 request (trying to re-use the same TCP connection
+    if possible).</p>
 
     <p>This module relies on <a href="http://nghttp2.org/">libnghttp2</a>
     to provide the core http/2 engine.</p>
@@ -67,6 +75,7 @@
 </div>
 <div id="quickview"><h3>Topics</h3>
 <ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#examples">Basic Examples</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#notes">Request notes</a></li>
 </ul><h3 class="directives">Directives</h3>
 <p>This module provides no
@@ -76,9 +85,31 @@
 <li><code class="module"><a href="../mod/mod_http2.html">mod_http2</a></code></li>
 <li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li>
 <li><code class="module"><a href="../mod/mod_proxy_connect.html">mod_proxy_connect</a></code></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<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="examples" id="examples">Basic Examples</a></h2>
+
+    <p>The examples below demonstrate how to configure HTTP/2 for
+    backend connections for a reverse proxy. </p>
+
+    <div class="example"><h3>HTTP/2 (TLS)</h3><pre class="prettyprint lang-config">ProxyPass "/app" "h2://app.example.com"
+ProxyPassReverse "/app" "https://app.example.com"</pre>
+</div>
+
+    <div class="example"><h3>HTTP/2 (cleartext)</h3><pre class="prettyprint lang-config">ProxyPass "/app" "h2c://app.example.com"
+ProxyPassReverse "/app" "http://app.example.com"</pre>
+</div>
+
+    <div class="note">
+      <p>The schemes to configure above in
+      <code class="directive">ProxyPassReverse</code> for reverse proxying
+      <code>h2</code> (or <code>h2c</code>) protocols are the usual
+      <code>https</code> (resp. <code>http</code>) as expected/used by
+      the user agent.</p>
+    </div>
+    </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
 <h2><a name="notes" id="notes">Request notes</a></h2>
     <p><code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code> creates the following request notes for
         logging using the <code>%{VARNAME}n</code> format in
@@ -113,7 +144,7 @@ var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_proxy_http
     }
 })(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="apache">Copyright 2017 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();