From 736ff9c9e37dac28145030b495995f92a4448ee8 Mon Sep 17 00:00:00 2001
From: Rich Bowen <rbowen@apache.org>
Date: Wed, 9 Nov 2011 00:00:20 +0000
Subject: [PATCH] Applies patch provided by Luke Meyer in
 https://issues.apache.org/bugzilla/show_bug.cgi?id=51131 - Adds usage example
 to mod_proxy_ajp docs.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1199554 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/mod/mod_proxy_ajp.html.en | 41 +++++++++++++++++++++++++++
 docs/manual/mod/mod_proxy_ajp.xml     | 40 ++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)

diff --git a/docs/manual/mod/mod_proxy_ajp.html.en b/docs/manual/mod/mod_proxy_ajp.html.en
index 9f37034070..49791d315f 100644
--- a/docs/manual/mod/mod_proxy_ajp.html.en
+++ b/docs/manual/mod/mod_proxy_ajp.html.en
@@ -51,6 +51,7 @@
             directives.</p>
 <h3>Topics</h3>
 <ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#usage">Usage</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#env">Environment Variables</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#overviewprotocol">Overview of the protocol</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#basppacketstruct">Basic Packet Structure</a></li>
@@ -63,6 +64,46 @@
 </ul></div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
+<h2><a name="usage" id="usage">Usage</a></h2>
+    <p>This module is used to reverse proxy to a backend application server
+    (e.g. Apache Tomcat) using the AJP13 protocol. The usage is similar to
+    an HTTP reverse proxy, but uses the <code>ajp://</code> prefix:
+
+    <div class="example"><h3>Simple Reverse Proxy</h3><p><code>
+    ProxyPass /app ajp://backend.example.com:8009/app
+    </code></p></div>
+
+    Balancers may also be used:
+    <div class="example"><h3>Balancer Reverse Proxy</h3><p><code>
+      &lt;Proxy balancer://cluster&gt;<br />
+      <span class="indent">
+        BalancerMember ajp://app1.example.com:8009 loadfactor=1<br />
+        BalancerMember ajp://app2.example.com:8009 loadfactor=2<br />
+        ProxySet lbmethod=bytraffic<br />
+      </span>
+      &lt;/Proxy&gt;<br />
+      ProxyPass /app balancer://cluster/app
+    </code></p></div>
+    </p><p>
+    Note that usually no
+    <code class="directive"><a href="../mod/mod_proxy.html#proxypassreverse">ProxyPassReverse</a></code>
+    directive is necessary. The AJP request includes the original host
+    header given to the proxy, and the application server can be expected
+    to generate self-referential headers relative to this host, so no
+    rewriting is necessary.
+    </p><p>
+    The main exception is when the URL path on the proxy differs from that on the
+    backend. In this case, a redirect header can be rewritten relative to the
+    original host URL (not the backend <code>ajp://</code> URL), for example:
+    <div class="example"><h3>Rewriting Proxied Path</h3><p><code>
+      ProxyPass /apps/foo ajp://backend.example.com:8009/foo<br />
+      ProxyPassReverse /apps/foo http://www.example.com/foo
+    </code></p></div>
+    However, it is usually better to deploy the application on the backend
+    server at the same path as the proxy rather than to take this approach.
+    </p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
 <h2><a name="env" id="env">Environment Variables</a></h2>
     <p>Environment variables whose names have the prefix <code>AJP_</code>
     are forwarded to the origin server as AJP request attributes
diff --git a/docs/manual/mod/mod_proxy_ajp.xml b/docs/manual/mod/mod_proxy_ajp.xml
index 8a9db925bc..c501ad2b5f 100644
--- a/docs/manual/mod/mod_proxy_ajp.xml
+++ b/docs/manual/mod/mod_proxy_ajp.xml
@@ -51,6 +51,46 @@
 <seealso><module>mod_proxy</module></seealso>
 <seealso><a href="../env.html">Environment Variable documentation</a></seealso>
 
+<section id="usage"><title>Usage</title>
+    <p>This module is used to reverse proxy to a backend application server
+    (e.g. Apache Tomcat) using the AJP13 protocol. The usage is similar to
+    an HTTP reverse proxy, but uses the <code>ajp://</code> prefix:
+
+    <example><title>Simple Reverse Proxy</title>
+    ProxyPass /app ajp://backend.example.com:8009/app
+    </example>
+
+    Balancers may also be used:
+    <example><title>Balancer Reverse Proxy</title>
+      &lt;Proxy balancer://cluster&gt;<br />
+      <indent>
+        BalancerMember ajp://app1.example.com:8009 loadfactor=1<br />
+        BalancerMember ajp://app2.example.com:8009 loadfactor=2<br />
+        ProxySet lbmethod=bytraffic<br />
+      </indent>
+      &lt;/Proxy&gt;<br />
+      ProxyPass /app balancer://cluster/app
+    </example>
+    </p><p>
+    Note that usually no
+    <directive module="mod_proxy">ProxyPassReverse</directive>
+    directive is necessary. The AJP request includes the original host
+    header given to the proxy, and the application server can be expected
+    to generate self-referential headers relative to this host, so no
+    rewriting is necessary.
+    </p><p>
+    The main exception is when the URL path on the proxy differs from that on the
+    backend. In this case, a redirect header can be rewritten relative to the
+    original host URL (not the backend <code>ajp://</code> URL), for example:
+    <example><title>Rewriting Proxied Path</title>
+      ProxyPass /apps/foo ajp://backend.example.com:8009/foo<br />
+      ProxyPassReverse /apps/foo http://www.example.com/foo
+    </example>
+    However, it is usually better to deploy the application on the backend
+    server at the same path as the proxy rather than to take this approach.
+    </p>
+</section>
+
 <section id="env"><title>Environment Variables</title>
     <p>Environment variables whose names have the prefix <code>AJP_</code>
     are forwarded to the origin server as AJP request attributes
-- 
2.40.0