Add in new mod_proxy "extension" module: mod_proxy_express.

This is a module developed by myself to support the
RedHat OpenShift Express project, to allow for dynamic
and fast reverse-proxy switching.

The idea is to easily map Host: header entries to
backend servers, with the mapping done in a DBM file
(think of mod_vhost_alias, kinda, for mod_proxy).
Yeah, mod_rewrite and RewriteMap could kinda do
it but (1) that is slow and (2) no support for
ProxyPassReverse capability.

Donated to the ASF.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1102733 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 151 insertions, 0 deletions

diff --git a/docs/manual/mod/mod_proxy_express.xml b/docs/manual/mod/mod_proxy_express.xml
new file mode 100644
index 0000000000..1ca43e184f
--- /dev/null
+++ b/docs/manual/mod/mod_proxy_express.xml
@@ -0,0 +1,151 @@
+<?xml version="1.0"?>
+<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision$ -->
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<modulesynopsis metafile="mod_proxy_express.xml.meta">
+
+<name>mod_proxy_express</name>
+<description>Dynamic mass reverse proxy extension for
+<module>mod_proxy</module></description>
+<status>Extension</status>
+<sourcefile>mod_proxy_express.c</sourcefile>
+<identifier>proxy_express_module</identifier>
+
+<summary>
+    <p>This module creates dynamically configured mass reverse
+    proxies, by mapping the Host: header of the HTTP request to
+    a server name and backend URL stored in a DBM file.
+    This allows for easy use of a huge number of reverse proxies
+    with no configuration changes. It is much less feature-full
+    than <module>mod_proxy_balancer</module>, which also provides
+    dynamic growth, but is intended to handle much, much
+    larger numbers of backends. It is ideally suited as a
+    front-end HTTP switch.</p>
+    
+    <p>This module <em>requires</em> the service of <module
+    >mod_proxy</module>.</p>
+
+    <note type="warning"><title>Warning</title>
+      <p>Do not enable proxying until you have <a
+      href="mod_proxy.html#access">secured your server</a>. Open proxy
+      servers are dangerous both to your network and to the Internet at
+      large.</p>
+    </note>
+
+<note><title>Limitations</title>
+  <ul>
+    <li>This module is not intended to replace the dynamic capability of
+      <module>mod_proxy_balancer</module>. Instead, it is intended to be mostly
+      a lightweight and fast alternative to using <module>mod_rewrite</module>
+      with <directive>RewriteMap</directive> and the <code>[P]</code> flag
+      for mapped reverse proxying.
+    </li>
+    <li>It does not support regex or pattern matching at all.
+    </li>
+    <li>It emulates:
+      <example>
+        ProxyPass / backend.server:port<br />
+        ProxyPassReverse / backend.server:port<br />
+      </example>
+      That is, the entire URL is appended to the mapped backend
+      URL. This is in keeping with the intent of being a simple
+      but fast reverse proxy switch.
+    </li>
+  </ul>
+</note>
+
+</summary>
+<seealso><module>mod_proxy</module></seealso>
+       
+<directivesynopsis>
+<name>ProxyExpressEnable</name>
+<description>Enable the module functionality.</description>
+<syntax>ProxyExpressEnable [on|off]</syntax>
+<default>off</default>
+<contextlist><context>server config</context><context>virtual host</context>
+  </contextlist>
+<compatibility>Available in Apache 2.3.13 and later</compatibility>
+
+<usage>
+  <p>The <directive>ProxyExpressEnable</directive> directive
+    controls whether the module will be active.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>ProxyExpressDBMFile</name>
+<description>Pathname to DBM file.</description>
+<syntax>ProxyExpressDBMFile &lt;pathname&gt;</syntax>
+<default>None</default>
+<contextlist><context>server config</context><context>virtual host</context>
+  </contextlist>
+<compatibility>Available in Apache 2.3.13 and later</compatibility>
+
+<usage>
+  <p>The <directive>ProxyExpressDBMFile</directive> directive
+    points to the location of the Express map DBM file. This
+    file serves to map the incoming server name, obtained from
+    the Host: header, to a backend URL.</p>
+
+    <note><title>Note</title>
+      <p>The file is constructed from a plain text file format using
+        the <code><a href="../programs/httxt2dbm.html">httxt2dbm</a></code> 
+        utility.</p>
+
+      <example><title>ProxyExpress map file</title>
+        ##<br />
+        ##express-map.txt:<br />
+        ##<br />
+        <br />
+        www1.example.com    http://192.168.211.2:8080<br />
+        www2.example.com   http://192.168.211.12:8088<br />
+        www3.example.com   http://192.168.212.10<br />
+      </example>
+
+      <example><title>Create DBM file</title>
+        httxt2dbm -i express-map.txt -o emap<br />
+        </example>
+
+      <example><title>Configuration</title>
+        ProxyExpressDBMFile emap<br />
+        </example>
+    </note>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>ProxyExpressDBMType</name>
+<description>DBM type of file.</description>
+<syntax>ProxyExpressDBMFile &lt;type&gt;</syntax>
+<default>"default"</default>
+<contextlist><context>server config</context><context>virtual host</context>
+  </contextlist>
+<compatibility>Available in Apache 2.3.13 and later</compatibility>
+
+<usage>
+  <p>The <directive>ProxyExpressDBMType</directive> directive
+    controls the DBM type expected by the module. The default
+    is the default DBM type created with <code>
+    <a href="../programs/httxt2dbm.html">httxt2dbm</a></code></p>
+</usage>
+</directivesynopsis>
+
+</modulesynopsis>