Commit 10819698 authored by Jim Jagielski's avatar Jim Jagielski
Browse files

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
parent 1b36b67f

CHANGES

+3 −0
Changes for CHANGES: 3 added lines, 0 removed lines.
Original line number Diff line number Diff line
@@ -2,6 +2,9 @@ 


Changes with Apache 2.3.13



  *) mod_proxy_express: New mass reverse-proxy switch extension for

     mod_proxy. [Jim Jagielski]



  *) configure: Fix script error when configuring module set "reallyall".

     [Rainer Jung]

docs/manual/mod/mod_proxy_express.html

0 → 100644
+5 −0
Changes for docs/manual/mod/mod_proxy_express.html: 5 added lines, 0 removed lines.
Original line number Diff line number Diff line 
# GENERATED FROM XML -- DO NOT EDIT



URI: mod_proxy_express.html.en

Content-Language: en

Content-type: text/html; charset=ISO-8859-1

docs/manual/mod/mod_proxy_express.html.en

0 → 100644
+164 −0
Changes for docs/manual/mod/mod_proxy_express.html.en: 164 added lines, 0 removed lines.
Original line number Diff line number Diff line 
<?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><!--

        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

              This file is generated from xml source: DO NOT EDIT

        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

      -->

<title>mod_proxy_express - Apache HTTP Server</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 href="../images/favicon.ico" rel="shortcut icon" /></head>

<body>

<div id="page-header">

<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>

<p class="apache">Apache HTTP Server Version 2.3</p>

<img alt="" src="../images/feather.gif" /></div>

<div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>

<div id="path">

<a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.3</a> &gt; <a href="./">Modules</a></div>

<div id="page-content">

<div id="preamble"><h1>Apache Module mod_proxy_express</h1>

<div class="toplang">

<p><span>Available Languages: </span><a href="../en/mod/mod_proxy_express.html" title="English">&nbsp;en&nbsp;</a></p>

</div>

<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Dynamic mass reverse proxy extension for

<code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></td></tr>

<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>

<tr><th><a href="module-dict.html#ModuleIdentifier">ModuleIdentifier:</a></th><td>proxy_express_module</td></tr>

<tr><th><a href="module-dict.html#SourceFile">SourceFile:</a></th><td>mod_proxy_express.c</td></tr></table>

<h3>Summary</h3>



    <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 <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code>, 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 <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>.</p>



    <div class="warning"><h3>Warning</h3>

      <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>

    </div>



<div class="note"><h3>Limitations</h3>

  <ul>

    <li>This module is not intended to replace the dynamic capability of

      <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code>. Instead, it is intended to be mostly

      a lightweight and fast alternative to using <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>

      with <code class="directive">RewriteMap</code> 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:

      <div class="example"><p><code>

        ProxyPass / backend.server:port<br />

        ProxyPassReverse / backend.server:port<br />

      </code></p></div>

      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>

</div>



</div>

<div id="quickview"><h3 class="directives">Directives</h3>

<ul id="toc">

<li><img alt="" src="../images/down.gif" /> <a href="#proxyexpressdbmfile">ProxyExpressDBMFile</a></li>

<li><img alt="" src="../images/down.gif" /> <a href="#proxyexpressdbmtype">ProxyExpressDBMType</a></li>

<li><img alt="" src="../images/down.gif" /> <a href="#proxyexpressenable">ProxyExpressEnable</a></li>

</ul>

<h3>See also</h3>

<ul class="seealso">

<li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li>

</ul></div>



<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>

<div class="directive-section"><h2><a name="ProxyExpressDBMFile" id="ProxyExpressDBMFile">ProxyExpressDBMFile</a> <a name="proxyexpressdbmfile" id="proxyexpressdbmfile">Directive</a></h2>

<table class="directive">

<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Pathname to DBM file.</td></tr>

<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyExpressDBMFile &lt;pathname&gt;</code></td></tr>

<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>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_proxy_express</td></tr>

<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.13 and later</td></tr>

</table>

  <p>The <code class="directive">ProxyExpressDBMFile</code> 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>



    <div class="note"><h3>Note</h3>

      <p>The file is constructed from a plain text file format using

        the <code><a href="../programs/httxt2dbm.html">httxt2dbm</a></code> 

        utility.</p>



      <div class="example"><h3>ProxyExpress map file</h3><p><code>

        ##<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 />

      </code></p></div>



      <div class="example"><h3>Create DBM file</h3><p><code>

        httxt2dbm -i express-map.txt -o emap<br />

        </code></p></div>



      <div class="example"><h3>Configuration</h3><p><code>

        ProxyExpressDBMFile emap<br />

        </code></p></div>

    </div>



</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>

<div class="directive-section"><h2><a name="ProxyExpressDBMType" id="ProxyExpressDBMType">ProxyExpressDBMType</a> <a name="proxyexpressdbmtype" id="proxyexpressdbmtype">Directive</a></h2>

<table class="directive">

<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>DBM type of file.</td></tr>

<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyExpressDBMFile &lt;type&gt;</code></td></tr>

<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>"default"</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_proxy_express</td></tr>

<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.13 and later</td></tr>

</table>

  <p>The <code class="directive">ProxyExpressDBMType</code> 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>



</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>

<div class="directive-section"><h2><a name="ProxyExpressEnable" id="ProxyExpressEnable">ProxyExpressEnable</a> <a name="proxyexpressenable" id="proxyexpressenable">Directive</a></h2>

<table class="directive">

<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable the module functionality.</td></tr>

<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyExpressEnable [on|off]</code></td></tr>

<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>off</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_proxy_express</td></tr>

<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.13 and later</td></tr>

</table>

  <p>The <code class="directive">ProxyExpressEnable</code> directive

    controls whether the module will be active.</p>



</div>

</div>

<div class="bottomlang">

<p><span>Available Languages: </span><a href="../en/mod/mod_proxy_express.html" title="English">&nbsp;en&nbsp;</a></p>

</div><div id="footer">

<p class="apache">Copyright 2011 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/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>

</body></html>
 
 No newline at end of file

docs/manual/mod/mod_proxy_express.xml

0 → 100644
+151 −0
Changes for docs/manual/mod/mod_proxy_express.xml: 151 added lines, 0 removed lines.
Original line number Diff line number Diff line 
<?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>

docs/manual/mod/mod_proxy_express.xml.meta

0 → 100644
+12 −0
Changes for docs/manual/mod/mod_proxy_express.xml.meta: 12 added lines, 0 removed lines.
Original line number Diff line number Diff line 
<?xml version="1.0" encoding="UTF-8" ?>

<!-- GENERATED FROM XML: DO NOT EDIT -->



<metafile reference="mod_proxy_express.xml">

  <basename>mod_proxy_express</basename>

  <path>/mod/</path>

  <relpath>..</relpath>



  <variants>

    <variant>en</variant>

  </variants>

</metafile>