granicus.if.org Git - apache/blob - docs/manual/mod/mod_proxy_express.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_proxy_express.xml.meta">
  24
  25 <name>mod_proxy_express</name>
  26 <description>Dynamic mass reverse proxy extension for
  27 <module>mod_proxy</module></description>
  28 <status>Extension</status>
  29 <sourcefile>mod_proxy_express.c</sourcefile>
  30 <identifier>proxy_express_module</identifier>
  31
  32 <summary>
  33     <p>This module creates dynamically configured mass reverse
  34     proxies, by mapping the Host: header of the HTTP request to
  35     a server name and backend URL stored in a DBM file.
  36     This allows for easy use of a huge number of reverse proxies
  37     with no configuration changes. It is much less feature-full
  38     than <module>mod_proxy_balancer</module>, which also provides
  39     dynamic growth, but is intended to handle much, much
  40     larger numbers of backends. It is ideally suited as a
  41     front-end HTTP switch and for micro-services architectures.</p>
  42
  43     <p>This module <em>requires</em> the service of <module
  44     >mod_proxy</module>.</p>
  45
  46     <note type="warning"><title>Warning</title>
  47       <p>Do not enable proxying until you have <a
  48       href="mod_proxy.html#access">secured your server</a>. Open proxy
  49       servers are dangerous both to your network and to the Internet at
  50       large.</p>
  51     </note>
  52
  53 <note><title>Limitations</title>
  54   <ul>
  55     <li>This module is not intended to replace the dynamic capability of
  56       <module>mod_proxy_balancer</module>. Instead, it is intended to be mostly
  57       a lightweight and fast alternative to using <module>mod_rewrite</module>
  58       with <directive>RewriteMap</directive> and the <code>[P]</code> flag
  59       for mapped reverse proxying.
  60     </li>
  61     <li>It does not support regex or pattern matching at all.
  62     </li>
  63     <li>It emulates:
  64       <highlight language="config">
  65 &lt;VirtualHost *:80&gt;
  66    ServerName front.end.server
  67    ProxyPass        "/" "back.end.server:port"
  68    ProxyPassReverse "/" "back.end.server:port"
  69 &lt;/VirtualHost&gt;
  70       </highlight>
  71       That is, the entire URL is appended to the mapped backend
  72       URL. This is in keeping with the intent of being a simple
  73       but fast reverse proxy switch.
  74     </li>
  75   </ul>
  76 </note>
  77
  78 </summary>
  79 <seealso><module>mod_proxy</module></seealso>
  80
  81 <directivesynopsis>
  82 <name>ProxyExpressEnable</name>
  83 <description>Enable the module functionality.</description>
  84 <syntax>ProxyExpressEnable [on|off]</syntax>
  85 <default>off</default>
  86 <contextlist><context>server config</context><context>virtual host</context>
  87   </contextlist>
  88 <override>FileInfo</override>
  89 <compatibility>Available in Apache 2.3.13 and later</compatibility>
  90
  91 <usage>
  92   <p>The <directive>ProxyExpressEnable</directive> directive
  93     controls whether the module will be active.</p>
  94 </usage>
  95 </directivesynopsis>
  96
  97 <directivesynopsis>
  98 <name>ProxyExpressDBMFile</name>
  99 <description>Pathname to DBM file.</description>
 100 <syntax>ProxyExpressDBMFile &lt;pathname&gt;</syntax>
 101 <default>None</default>
 102 <contextlist><context>server config</context><context>virtual host</context>
 103   </contextlist>
 104 <override>FileInfo</override>
 105 <compatibility>Available in Apache 2.3.13 and later</compatibility>
 106
 107 <usage>
 108   <p>The <directive>ProxyExpressDBMFile</directive> directive
 109     points to the location of the Express map DBM file. This
 110     file serves to map the incoming server name, obtained from
 111     the Host: header, to a backend URL.</p>
 112
 113     <note><title>Note</title>
 114       <p>The file is constructed from a plain text file format using
 115         the <code><a href="../programs/httxt2dbm.html">httxt2dbm</a></code>
 116         utility.</p>
 117
 118       <example><title>ProxyExpress map file</title>
 119         ##<br />
 120         ##express-map.txt:<br />
 121         ##<br />
 122         <br />
 123         www1.example.com    http://192.168.211.2:8080<br />
 124         www2.example.com   http://192.168.211.12:8088<br />
 125         www3.example.com   http://192.168.212.10<br />
 126       </example>
 127
 128       <example><title>Create DBM file</title>
 129         httxt2dbm -i express-map.txt -o emap<br />
 130         </example>
 131
 132       <example><title>Configuration</title>
 133         ProxyExpressEnable on<br />
 134         ProxyExpressDBMFile emap<br />
 135         </example>
 136     </note>
 137 </usage>
 138 </directivesynopsis>
 139
 140 <directivesynopsis>
 141 <name>ProxyExpressDBMType</name>
 142 <description>DBM type of file.</description>
 143 <syntax>ProxyExpressDBMFile &lt;type&gt;</syntax>
 144 <default>"default"</default>
 145 <contextlist><context>server config</context><context>virtual host</context>
 146   </contextlist>
 147 <override>FileInfo</override>
 148 <compatibility>Available in Apache 2.3.13 and later</compatibility>
 149
 150 <usage>
 151   <p>The <directive>ProxyExpressDBMType</directive> directive
 152     controls the DBM type expected by the module. The default
 153     is the default DBM type created with <code>
 154     <a href="../programs/httxt2dbm.html">httxt2dbm</a></code>.</p>
 155     <p>Possible values are (not all may be available at run time):</p>
 156 <table border="1" style="zebra">
 157     <columnspec><column width=".3"/><column width=".7"/></columnspec>
 158
 159     <tr><th>Value</th><th>Description</th></tr>
 160     <tr><td><code>db</code></td><td> Berkeley DB files</td></tr>
 161     <tr><td><code>gdbm</code></td><td> GDBM files</td></tr>
 162     <tr><td><code>ndbm</code></td><td> NDBM files</td></tr>
 163     <tr><td><code>sdbm</code></td><td> SDBM files (always available)</td></tr>
 164     <tr><td><code>default</code></td><td> default DBM type</td></tr>
 165     </table>
 166
 167 </usage>
 168 </directivesynopsis>
 169
 170 </modulesynopsis>