842ae4bd224140319ae7feec1872b93dfd491143fielding<?xml version="1.0"?>

842ae4bd224140319ae7feec1872b93dfd491143fielding<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

842ae4bd224140319ae7feec1872b93dfd491143fielding<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

842ae4bd224140319ae7feec1872b93dfd491143fielding

3568de757bac0b47256647504c186d17ca272f85rbb

3568de757bac0b47256647504c186d17ca272f85rbb<modulesynopsis metafile="mod_proxy.xml.meta">

3568de757bac0b47256647504c186d17ca272f85rbb

3568de757bac0b47256647504c186d17ca272f85rbb<name>mod_proxy</name>

3568de757bac0b47256647504c186d17ca272f85rbb<description>Multi-protocol proxy/gateway server</description>

3568de757bac0b47256647504c186d17ca272f85rbb<status>Extension</status>

3568de757bac0b47256647504c186d17ca272f85rbb<sourcefile>mod_proxy.c</sourcefile>

3568de757bac0b47256647504c186d17ca272f85rbb<identifier>proxy_module</identifier>

3568de757bac0b47256647504c186d17ca272f85rbb

3568de757bac0b47256647504c186d17ca272f85rbb<summary>

3568de757bac0b47256647504c186d17ca272f85rbb <note type="warning"><title>Warning</title>

3568de757bac0b47256647504c186d17ca272f85rbb <p>Do not enable proxying with <directive module="mod_proxy"

3568de757bac0b47256647504c186d17ca272f85rbb >ProxyRequests</directive> until you have <a href="#access"

3568de757bac0b47256647504c186d17ca272f85rbb >secured your server</a>. Open proxy servers are dangerous both to your

3568de757bac0b47256647504c186d17ca272f85rbb network and to the Internet at large.</p>

3568de757bac0b47256647504c186d17ca272f85rbb </note>

3568de757bac0b47256647504c186d17ca272f85rbb

3568de757bac0b47256647504c186d17ca272f85rbb <p><module>mod_proxy</module> and related modules implement a

3568de757bac0b47256647504c186d17ca272f85rbb proxy/gateway for Apache HTTP Server, supporting a number of popular

3568de757bac0b47256647504c186d17ca272f85rbb protocols as well as several different load balancing algorithms.

3568de757bac0b47256647504c186d17ca272f85rbb Third-party modules can add support for additional protocols and

3568de757bac0b47256647504c186d17ca272f85rbb load balancing algorithms.</p>

3568de757bac0b47256647504c186d17ca272f85rbb

3568de757bac0b47256647504c186d17ca272f85rbb <p>A set of modules must be loaded into the server to provide the

3568de757bac0b47256647504c186d17ca272f85rbb necessary features. These modules can be included statically at

3568de757bac0b47256647504c186d17ca272f85rbb build time or dynamically via the

3568de757bac0b47256647504c186d17ca272f85rbb <directive module="mod_so">LoadModule</directive> directive).

3568de757bac0b47256647504c186d17ca272f85rbb The set must include:</p>

3568de757bac0b47256647504c186d17ca272f85rbb

3568de757bac0b47256647504c186d17ca272f85rbb <ul>

3568de757bac0b47256647504c186d17ca272f85rbb <li><module>mod_proxy</module>, which provides basic proxy

3568de757bac0b47256647504c186d17ca272f85rbb capabilities</li>

3568de757bac0b47256647504c186d17ca272f85rbb

3568de757bac0b47256647504c186d17ca272f85rbb <li><module>mod_proxy_balancer</module> and one or more

3568de757bac0b47256647504c186d17ca272f85rbb balancer modules, if load balancing is required. (See

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <module>mod_proxy_balancer</module> for more information.)</li>

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <li>one or more proxy scheme, or protocol, modules:

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding

3568de757bac0b47256647504c186d17ca272f85rbb <table border="1">

cd8f8c995d415473f3bfb0b329b2450f2a722c3atrawick <tr><th>Protocol</th><th>Module</th></tr>

3568de757bac0b47256647504c186d17ca272f85rbb <tr><td>AJP13 (Apache JServe Protocol version

3568de757bac0b47256647504c186d17ca272f85rbb 1.3)</td><td><module>mod_proxy_ajp</module></td></tr>

3568de757bac0b47256647504c186d17ca272f85rbb <tr><td>CONNECT (for

3568de757bac0b47256647504c186d17ca272f85rbb SSL)</td><td><module>mod_proxy_connect</module></td></tr>

98fb535f829e2a95aabd82420931f476661fa8e3jorton <tr><td>FastCGI</td><td><module>mod_proxy_fcgi</module></td></tr>

db12cd62083041bf90945eeb90cc40fbd2340797trawick <tr><td>ftp</td><td><module>mod_proxy_ftp</module></td></tr>

db12cd62083041bf90945eeb90cc40fbd2340797trawick <tr><td>HTTP/0.9, HTTP/1.0, and

db12cd62083041bf90945eeb90cc40fbd2340797trawick HTTP/1.1</td><td><module>mod_proxy_http</module></td></tr>

333eac96e4fb7d6901cb75e6ca7bb22b2ccb84cetrawick <tr><td>SCGI</td><td><module>mod_proxy_scgi</module></td></tr>

333eac96e4fb7d6901cb75e6ca7bb22b2ccb84cetrawick </table>

9f979f5c8061f6f6f560d1824e0e378ff5b91931rpluem </li>

3568de757bac0b47256647504c186d17ca272f85rbb </ul>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz

3568de757bac0b47256647504c186d17ca272f85rbb <p>In addition, extended features are provided by other modules.

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz Caching is provided by <module>mod_cache</module> and related

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz modules. The ability to contact remote servers using the SSL/TLS

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz protocol is provided by the <code>SSLProxy*</code> directives of

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <module>mod_ssl</module>. These additional modules will need

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz to be loaded and configured to take advantage of these features.</p>

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding</summary>

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<seealso><module>mod_cache</module></seealso>

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<seealso><module>mod_proxy_ajp</module></seealso>

8f3ec4772d2aeb347cf40e87c77627bb784dd018rbb<seealso><module>mod_proxy_connect</module></seealso>

8f3ec4772d2aeb347cf40e87c77627bb784dd018rbb<seealso><module>mod_proxy_fcgi</module></seealso>

3d96ee83babeec32482c9082c9426340cee8c44dwrowe<seealso><module>mod_proxy_ftp</module></seealso>

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<seealso><module>mod_proxy_http</module></seealso>

397df70abe0bdd78a84fb6c38c02641bcfeadceasf<seealso><module>mod_proxy_scgi</module></seealso>

cd8f8c995d415473f3bfb0b329b2450f2a722c3atrawick<seealso><module>mod_proxy_balancer</module></seealso>

98fb535f829e2a95aabd82420931f476661fa8e3jorton<seealso><module>mod_ssl</module></seealso>

f0e395a55abfcad3d2bd7c63470003b08a93d567nd

f0e395a55abfcad3d2bd7c63470003b08a93d567nd <section id="forwardreverse"><title>Forward Proxies and Reverse

f0e395a55abfcad3d2bd7c63470003b08a93d567nd Proxies/Gateways</title>

f0e395a55abfcad3d2bd7c63470003b08a93d567nd <p>Apache HTTP Server can be configured in both a <dfn>forward</dfn> and

98fb535f829e2a95aabd82420931f476661fa8e3jorton <dfn>reverse</dfn> proxy (also known as <dfn>gateway</dfn>) mode.</p>

7cd5419264796cfeaf8215383cf0f89130a81fectrawick

7cd5419264796cfeaf8215383cf0f89130a81fectrawick <p>An ordinary <dfn>forward proxy</dfn> is an intermediate

7cd5419264796cfeaf8215383cf0f89130a81fectrawick server that sits between the client and the <em>origin

7cd5419264796cfeaf8215383cf0f89130a81fectrawick server</em>. In order to get content from the origin server,

7cd5419264796cfeaf8215383cf0f89130a81fectrawick the client sends a request to the proxy naming the origin server

7cd5419264796cfeaf8215383cf0f89130a81fectrawick as the target and the proxy then requests the content from the

7cd5419264796cfeaf8215383cf0f89130a81fectrawick origin server and returns it to the client. The client must be

7cd5419264796cfeaf8215383cf0f89130a81fectrawick specially configured to use the forward proxy to access other

3568de757bac0b47256647504c186d17ca272f85rbb sites.</p>

41634f717c623556a16b27b25d7d909a66fe20f8wrowe

3568de757bac0b47256647504c186d17ca272f85rbb <p>A typical usage of a forward proxy is to provide Internet

3568de757bac0b47256647504c186d17ca272f85rbb access to internal clients that are otherwise restricted by a

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz firewall. The forward proxy can also use caching (as provided

3568de757bac0b47256647504c186d17ca272f85rbb by <module>mod_cache</module>) to reduce network usage.</p>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz

3568de757bac0b47256647504c186d17ca272f85rbb <p>The forward proxy is activated using the <directive

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz module="mod_proxy">ProxyRequests</directive> directive. Because

3568de757bac0b47256647504c186d17ca272f85rbb forward proxies allow clients to access arbitrary sites through

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz your server and to hide their true origin, it is essential that

3568de757bac0b47256647504c186d17ca272f85rbb you <a href="#access">secure your server</a> so that only

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding authorized clients can access the proxy before activating a

41634f717c623556a16b27b25d7d909a66fe20f8wrowe forward proxy.</p>

3568de757bac0b47256647504c186d17ca272f85rbb

3568de757bac0b47256647504c186d17ca272f85rbb <p>A <dfn>reverse proxy</dfn> (or <dfn>gateway</dfn>), by

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz contrast, appears to the client just like an ordinary web

3568de757bac0b47256647504c186d17ca272f85rbb server. No special configuration on the client is necessary.

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz The client makes ordinary requests for content in the name-space

3568de757bac0b47256647504c186d17ca272f85rbb of the reverse proxy. The reverse proxy then decides where to

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz send those requests, and returns the content as if it was itself

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding the origin.</p>

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz <p>A typical usage of a reverse proxy is to provide Internet

3568de757bac0b47256647504c186d17ca272f85rbb users access to a server that is behind a firewall. Reverse

fc1efab92032301e317f07e1b3a00082d9d71f3frbb proxies can also be used to balance load among several back-end

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz servers, or to provide caching for a slower back-end server.

24b534291150023e6b68eca89ddd33e475ccddc0wrowe In addition, reverse proxies can be used simply to bring

3568de757bac0b47256647504c186d17ca272f85rbb several servers into the same URL space.</p>

24b534291150023e6b68eca89ddd33e475ccddc0wrowe

3568de757bac0b47256647504c186d17ca272f85rbb <p>A reverse proxy is activated using the <directive

24b534291150023e6b68eca89ddd33e475ccddc0wrowe module="mod_proxy">ProxyPass</directive> directive or the

24b534291150023e6b68eca89ddd33e475ccddc0wrowe <code>[P]</code> flag to the <directive

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz module="mod_rewrite">RewriteRule</directive> directive. It is

3568de757bac0b47256647504c186d17ca272f85rbb <strong>not</strong> necessary to turn <directive

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz module="mod_proxy">ProxyRequests</directive> on in order to

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz configure a reverse proxy.</p>

3568de757bac0b47256647504c186d17ca272f85rbb </section> <!-- /forwardreverse -->

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz <section id="examples"><title>Basic Examples</title>

3568de757bac0b47256647504c186d17ca272f85rbb

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz <p>The examples below are only a very basic idea to help you

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz get started. Please read the documentation on the individual

3568de757bac0b47256647504c186d17ca272f85rbb directives.</p>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz

3568de757bac0b47256647504c186d17ca272f85rbb <p>In addition, if you wish to have caching enabled, consult

3568de757bac0b47256647504c186d17ca272f85rbb the documentation from <module>mod_cache</module>.</p>

3568de757bac0b47256647504c186d17ca272f85rbb

3568de757bac0b47256647504c186d17ca272f85rbb <example><title>Reverse Proxy</title>

3568de757bac0b47256647504c186d17ca272f85rbb <highlight language="config">

3568de757bac0b47256647504c186d17ca272f85rbbProxyPass /foo http://foo.example.com/bar

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantzProxyPassReverse /foo http://foo.example.com/bar

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz </highlight>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz </example>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz

3568de757bac0b47256647504c186d17ca272f85rbb <example><title>Forward Proxy</title>

3568de757bac0b47256647504c186d17ca272f85rbb <highlight language="config">

3568de757bac0b47256647504c186d17ca272f85rbbProxyRequests On

3568de757bac0b47256647504c186d17ca272f85rbbProxyVia On

3568de757bac0b47256647504c186d17ca272f85rbb

3568de757bac0b47256647504c186d17ca272f85rbb&lt;Proxy *&gt;

3568de757bac0b47256647504c186d17ca272f85rbb Require host internal.example.com

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz&lt;/Proxy&gt;

3568de757bac0b47256647504c186d17ca272f85rbb </highlight>

3568de757bac0b47256647504c186d17ca272f85rbb </example>

3568de757bac0b47256647504c186d17ca272f85rbb </section> <!-- /examples -->

3568de757bac0b47256647504c186d17ca272f85rbb

3568de757bac0b47256647504c186d17ca272f85rbb

3568de757bac0b47256647504c186d17ca272f85rbb <section id="workers"><title>Workers</title>

3568de757bac0b47256647504c186d17ca272f85rbb <p>The proxy manages the configuration of origin servers and their

397df70abe0bdd78a84fb6c38c02641bcfeadceasf communication parameters in objects called <dfn>workers</dfn>.

397df70abe0bdd78a84fb6c38c02641bcfeadceasf There are two built-in workers, the default forward proxy worker and the

397df70abe0bdd78a84fb6c38c02641bcfeadceasf default reverse proxy worker. Additional workers can be configured

397df70abe0bdd78a84fb6c38c02641bcfeadceasf explicitly.</p>

397df70abe0bdd78a84fb6c38c02641bcfeadceasf

3568de757bac0b47256647504c186d17ca272f85rbb <p>The two default workers have a fixed configuration

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding and will be used if no other worker matches the request.

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding They do not use HTTP Keep-Alive or connection pooling.

3568de757bac0b47256647504c186d17ca272f85rbb The TCP connections to the origin server will instead be

239f998fbee5ac5b114b965bb76e217cce0003edstoddard opened and closed for each request.</p>

78ae889ffe0fdfab72f56c6993b0f302cb48da55rbb

3568de757bac0b47256647504c186d17ca272f85rbb <p>Explicitly configured workers are identified by their URL.

6653a33e820463abd4f81915b7a1eba0f602e200brianp They are usually created and configured using

6653a33e820463abd4f81915b7a1eba0f602e200brianp <directive module="mod_proxy">ProxyPass</directive> or

6653a33e820463abd4f81915b7a1eba0f602e200brianp <directive module="mod_proxy">ProxyPassMatch</directive> when used

41634f717c623556a16b27b25d7d909a66fe20f8wrowe for a reverse proxy:</p>

41634f717c623556a16b27b25d7d909a66fe20f8wrowe

6653a33e820463abd4f81915b7a1eba0f602e200brianp <highlight language="config">

3568de757bac0b47256647504c186d17ca272f85rbb ProxyPass /example http://backend.example.com connectiontimeout=5 timeout=30

6653a33e820463abd4f81915b7a1eba0f602e200brianp </highlight>

6653a33e820463abd4f81915b7a1eba0f602e200brianp

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm <p>This will create a worker associated with the origin server URL

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm <code>http://backend.example.com</code> and using the given timeout

cd8f8c995d415473f3bfb0b329b2450f2a722c3atrawick values. When used in a forward proxy, workers are usually defined

36c8049de63c446926139936c3d195330a0539cetrawick via the <directive module="mod_proxy">ProxySet</directive> directive:</p>

3568de757bac0b47256647504c186d17ca272f85rbb

dd028aa8111afb6534fece555e8c2d408894671etrawick <highlight language="config">

d90b36a9e6f6ea9a583694f4db5e5edd54a750b3minfrin ProxySet http://backend.example.com connectiontimeout=5 timeout=30

d90b36a9e6f6ea9a583694f4db5e5edd54a750b3minfrin </highlight>

d90b36a9e6f6ea9a583694f4db5e5edd54a750b3minfrin

d90b36a9e6f6ea9a583694f4db5e5edd54a750b3minfrin <p>or alternatively using <directive module="mod_proxy">Proxy</directive>

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding and <directive module="mod_proxy">ProxySet</directive>:</p>

d90b36a9e6f6ea9a583694f4db5e5edd54a750b3minfrin

d90b36a9e6f6ea9a583694f4db5e5edd54a750b3minfrin <highlight language="config">

ca53a74f4012a45cbad48e940eddf27d866981f9dougm&lt;Proxy http://backend.example.com&gt;

ca53a74f4012a45cbad48e940eddf27d866981f9dougm ProxySet connectiontimeout=5 timeout=30

ca53a74f4012a45cbad48e940eddf27d866981f9dougm&lt;/Proxy&gt;

d90b36a9e6f6ea9a583694f4db5e5edd54a750b3minfrin </highlight>

d90b36a9e6f6ea9a583694f4db5e5edd54a750b3minfrin

d90b36a9e6f6ea9a583694f4db5e5edd54a750b3minfrin <p>Using explicitly configured workers in the forward mode is

d90b36a9e6f6ea9a583694f4db5e5edd54a750b3minfrin not very common, because forward proxies usually communicate with many

dd028aa8111afb6534fece555e8c2d408894671etrawick different origin servers. Creating explicit workers for some of the

dd028aa8111afb6534fece555e8c2d408894671etrawick origin servers can still be useful, if they are used very often.

6653a33e820463abd4f81915b7a1eba0f602e200brianp Explicitly configured workers have no concept of forward or reverse

6653a33e820463abd4f81915b7a1eba0f602e200brianp proxying by themselves. They encapsulate a common concept of

6653a33e820463abd4f81915b7a1eba0f602e200brianp communication with origin servers. A worker created by

6653a33e820463abd4f81915b7a1eba0f602e200brianp <directive module="mod_proxy">ProxyPass</directive> for use in a

6653a33e820463abd4f81915b7a1eba0f602e200brianp reverse proxy will be also used for forward proxy requests whenever

6653a33e820463abd4f81915b7a1eba0f602e200brianp the URL to the origin server matches the worker URL and vice versa.</p>

6653a33e820463abd4f81915b7a1eba0f602e200brianp

6653a33e820463abd4f81915b7a1eba0f602e200brianp <p>The URL identifying a direct worker is the URL of its

6653a33e820463abd4f81915b7a1eba0f602e200brianp origin server including any path components given:</p>

6653a33e820463abd4f81915b7a1eba0f602e200brianp

6653a33e820463abd4f81915b7a1eba0f602e200brianp <highlight language="config">

6653a33e820463abd4f81915b7a1eba0f602e200brianpProxyPass /examples http://backend.example.com/examples

6653a33e820463abd4f81915b7a1eba0f602e200brianpProxyPass /docs http://backend.example.com/docs

6653a33e820463abd4f81915b7a1eba0f602e200brianp </highlight>

6653a33e820463abd4f81915b7a1eba0f602e200brianp

6653a33e820463abd4f81915b7a1eba0f602e200brianp <p>This example defines two different workers, each using a separate

cd8f8c995d415473f3bfb0b329b2450f2a722c3atrawick connection pool and configuration.</p>

cd8f8c995d415473f3bfb0b329b2450f2a722c3atrawick

cd8f8c995d415473f3bfb0b329b2450f2a722c3atrawick <note type="warning"><title>Worker Sharing</title>

239f998fbee5ac5b114b965bb76e217cce0003edstoddard <p>Worker sharing happens if the worker URLs overlap, which occurs when

3568de757bac0b47256647504c186d17ca272f85rbb the URL of some worker is a leading substring of the URL of another

3568de757bac0b47256647504c186d17ca272f85rbb worker defined later in the configuration file. In the following example</p>

3568de757bac0b47256647504c186d17ca272f85rbb

12901074f5d6b36d08be84d8637b6f2c21e0da26trawick <highlight language="config">

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddardProxyPass /apps http://backend.example.com/ timeout=60

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddardProxyPass /examples http://backend.example.com/examples timeout=10

3568de757bac0b47256647504c186d17ca272f85rbb </highlight>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz

48d2edbfb84e5559b5da0f8d614ccab805cc67a8rbb <p>the second worker isn't actually created. Instead the first

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding worker is used. The benefit is, that there is only one connection pool,

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard so connections are more often reused. Note that all configuration attributes

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding given explicitly for the later worker will be ignored. This will be logged

f2e009134c7e279f99dfca5bd421f721bf1f7840jorton as a warning. In the above example the resulting timeout value

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding for the URL <code>/examples</code> will be <code>60</code> instead

3568de757bac0b47256647504c186d17ca272f85rbb of <code>10</code>!</p>

3568de757bac0b47256647504c186d17ca272f85rbb

3568de757bac0b47256647504c186d17ca272f85rbb <p>If you want to avoid worker sharing, sort your worker definitions

3568de757bac0b47256647504c186d17ca272f85rbb by URL length, starting with the longest worker URLs. If you want to maximize

3568de757bac0b47256647504c186d17ca272f85rbb worker sharing use the reverse sort order. See also the related warning about

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard ordering <directive module="mod_proxy">ProxyPass</directive> directives.</p>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz </note> <!-- /worker_sharing -->

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <p>Explicitly configured workers come in two flavors:

9f979f5c8061f6f6f560d1824e0e378ff5b91931rpluem <dfn>direct workers</dfn> and <dfn>(load) balancer workers</dfn>.

9f979f5c8061f6f6f560d1824e0e378ff5b91931rpluem They support many important configuration attributes which are

9f979f5c8061f6f6f560d1824e0e378ff5b91931rpluem described below in the <directive module="mod_proxy">ProxyPass</directive>

9f979f5c8061f6f6f560d1824e0e378ff5b91931rpluem directive. The same attributes can also be set using

9f979f5c8061f6f6f560d1824e0e378ff5b91931rpluem <directive module="mod_proxy">ProxySet</directive>.</p>

9f979f5c8061f6f6f560d1824e0e378ff5b91931rpluem

9f979f5c8061f6f6f560d1824e0e378ff5b91931rpluem <p>The set of options available for a direct worker

9f979f5c8061f6f6f560d1824e0e378ff5b91931rpluem depends on the protocol, which is specified in the origin server URL.

9f979f5c8061f6f6f560d1824e0e378ff5b91931rpluem Available protocols include <code>ajp</code>, <code>fcgi</code>,

83a5021aef5ebb67395b93f75df4fd0f0b4fc8c8fuankg <code>ftp</code>, <code>http</code> and <code>scgi</code>.</p>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard

9f979f5c8061f6f6f560d1824e0e378ff5b91931rpluem <p>Balancer workers are virtual workers that use direct workers known

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard as their members to actually handle the requests. Each balancer can

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard have multiple members. When it handles a request, it chooses a member

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard based on the configured load balancing algorithm.</p>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard

f2e009134c7e279f99dfca5bd421f721bf1f7840jorton <p>A balancer worker is created if its worker URL uses

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <code>balancer</code> as the protocol scheme.

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard The balancer URL uniquely identifies the balancer worker.

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard Members are added to a balancer using

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <directive module="mod_proxy">BalancerMember</directive>.</p>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard </section> <!-- /workers -->

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard

3568de757bac0b47256647504c186d17ca272f85rbb <section id="access"><title>Controlling access to your proxy</title>

3568de757bac0b47256647504c186d17ca272f85rbb <p>You can control who can access your proxy via the <directive

cd8f8c995d415473f3bfb0b329b2450f2a722c3atrawick module="mod_proxy" type="section">Proxy</directive> control block as in

7cd5419264796cfeaf8215383cf0f89130a81fectrawick the following example:</p>

7cd5419264796cfeaf8215383cf0f89130a81fectrawick

7cd5419264796cfeaf8215383cf0f89130a81fectrawick <highlight language="config">

7cd5419264796cfeaf8215383cf0f89130a81fectrawick&lt;Proxy *&gt;

e8f95a682820a599fe41b22977010636be5c2717jim Require ip 192.168.0

98cd3186185bb28ae6c95a3f159899fcf56a663ftrawick&lt;/Proxy&gt;

cd8f8c995d415473f3bfb0b329b2450f2a722c3atrawick </highlight>

cd8f8c995d415473f3bfb0b329b2450f2a722c3atrawick

3568de757bac0b47256647504c186d17ca272f85rbb <p>For more information on access control directives, see

a72ba68ecbbc61e4b513e50d6000245c33f753dcwrowe <module>mod_authz_host</module>.</p>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm

397df70abe0bdd78a84fb6c38c02641bcfeadceasf <p>Strictly limiting access is essential if you are using a

397df70abe0bdd78a84fb6c38c02641bcfeadceasf forward proxy (using the <directive

397df70abe0bdd78a84fb6c38c02641bcfeadceasf module="mod_proxy">ProxyRequests</directive> directive).

397df70abe0bdd78a84fb6c38c02641bcfeadceasf Otherwise, your server can be used by any client to access

397df70abe0bdd78a84fb6c38c02641bcfeadceasf arbitrary hosts while hiding his or her true identity. This is

397df70abe0bdd78a84fb6c38c02641bcfeadceasf dangerous both for your network and for the Internet at large.

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz When using a reverse proxy (using the <directive

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm module="mod_proxy">ProxyPass</directive> directive with

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm <code>ProxyRequests Off</code>), access control is less

3cbd177a6c885562f9ad0cf11695f044489c881dgregames critical because clients can only contact the hosts that you

dd028aa8111afb6534fece555e8c2d408894671etrawick have specifically configured.</p>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard

3cbd177a6c885562f9ad0cf11695f044489c881dgregames <p><strong>See Also</strong> the <a href="mod_proxy_http.html#env"

3cbd177a6c885562f9ad0cf11695f044489c881dgregames >Proxy-Chain-Auth</a> environment variable.</p>

3cbd177a6c885562f9ad0cf11695f044489c881dgregames

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard </section> <!-- /access -->

5a0f707b48da7703cbe6bc087f13a6735b1c742dgregames

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz <section id="startup"><title>Slow Startup</title>

5a0f707b48da7703cbe6bc087f13a6735b1c742dgregames <p>If you're using the <directive module="mod_proxy"

5a0f707b48da7703cbe6bc087f13a6735b1c742dgregames >ProxyBlock</directive> directive, hostnames' IP addresses are looked up

5a0f707b48da7703cbe6bc087f13a6735b1c742dgregames and cached during startup for later match test. This may take a few

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard seconds (or more) depending on the speed with which the hostname lookups

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm occur.</p>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm </section> <!-- /startup -->

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <section id="intranet"><title>Intranet Proxy</title>

ad83978f20c7d1a4323059d9af122e56fcd353bdstoddard <p>An Apache httpd proxy server situated in an intranet needs to forward

7cd5419264796cfeaf8215383cf0f89130a81fectrawick external requests through the company's firewall (for this, configure

7cd5419264796cfeaf8215383cf0f89130a81fectrawick the <directive module="mod_proxy">ProxyRemote</directive> directive

7cd5419264796cfeaf8215383cf0f89130a81fectrawick to forward the respective <var>scheme</var> to the firewall proxy).

7cd5419264796cfeaf8215383cf0f89130a81fectrawick However, when it has to

7cd5419264796cfeaf8215383cf0f89130a81fectrawick access resources within the intranet, it can bypass the firewall when

7cd5419264796cfeaf8215383cf0f89130a81fectrawick accessing hosts. The <directive module="mod_proxy">NoProxy</directive>

7cd5419264796cfeaf8215383cf0f89130a81fectrawick directive is useful for specifying which hosts belong to the intranet and

7cd5419264796cfeaf8215383cf0f89130a81fectrawick should be accessed directly.</p>

7cd5419264796cfeaf8215383cf0f89130a81fectrawick

7cd5419264796cfeaf8215383cf0f89130a81fectrawick <p>Users within an intranet tend to omit the local domain name from their

7cd5419264796cfeaf8215383cf0f89130a81fectrawick WWW requests, thus requesting "http://somehost/" instead of

7cd5419264796cfeaf8215383cf0f89130a81fectrawick <code>http://somehost.example.com/</code>. Some commercial proxy servers

7cd5419264796cfeaf8215383cf0f89130a81fectrawick let them get away with this and simply serve the request, implying a

7cd5419264796cfeaf8215383cf0f89130a81fectrawick configured local domain. When the <directive module="mod_proxy"

7cd5419264796cfeaf8215383cf0f89130a81fectrawick >ProxyDomain</directive> directive is used and the server is <a

7cd5419264796cfeaf8215383cf0f89130a81fectrawick href="#proxyrequests">configured for proxy service</a>, Apache httpd can return

7cd5419264796cfeaf8215383cf0f89130a81fectrawick a redirect response and send the client to the correct, fully qualified,

7cd5419264796cfeaf8215383cf0f89130a81fectrawick server address. This is the preferred method since the user's bookmark

7cd5419264796cfeaf8215383cf0f89130a81fectrawick files will then contain fully qualified hosts.</p>

7cd5419264796cfeaf8215383cf0f89130a81fectrawick </section> <!-- /intranet -->

7cd5419264796cfeaf8215383cf0f89130a81fectrawick

7cd5419264796cfeaf8215383cf0f89130a81fectrawick <section id="envsettings"><title>Protocol Adjustments</title>

ad83978f20c7d1a4323059d9af122e56fcd353bdstoddard <p>For circumstances where <module>mod_proxy</module> is sending

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz requests to an origin server that doesn't properly implement

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard keepalives or HTTP/1.1, there are two <a

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard href="/env.html">environment variables</a> that can force the

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz request to use HTTP/1.0 with no keepalive. These are set via the

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <directive module="mod_env">SetEnv</directive> directive.</p>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <p>These are the <code>force-proxy-request-1.0</code> and

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <code>proxy-nokeepalive</code> notes.</p>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <highlight language="config">

3568de757bac0b47256647504c186d17ca272f85rbb&lt;Location /buggyappserver/&gt;

7cd5419264796cfeaf8215383cf0f89130a81fectrawick ProxyPass http://buggyappserver:7001/foo/

7cd5419264796cfeaf8215383cf0f89130a81fectrawick SetEnv force-proxy-request-1.0 1

7cd5419264796cfeaf8215383cf0f89130a81fectrawick SetEnv proxy-nokeepalive 1

7cd5419264796cfeaf8215383cf0f89130a81fectrawick&lt;/Location&gt;

7cd5419264796cfeaf8215383cf0f89130a81fectrawick </highlight>

7cd5419264796cfeaf8215383cf0f89130a81fectrawick

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm </section> <!-- /envsettings -->

3568de757bac0b47256647504c186d17ca272f85rbb

3568de757bac0b47256647504c186d17ca272f85rbb <section id="request-bodies"><title>Request Bodies</title>

74fd6d9aeadb9022086259c5c1ae00bc0dda9c9astoddard

72b6f1cf3e616473e1c26464b3193b13c2c09e87brianp <p>Some request methods such as POST include a request body.

72b6f1cf3e616473e1c26464b3193b13c2c09e87brianp The HTTP protocol requires that requests which include a body

3568de757bac0b47256647504c186d17ca272f85rbb either use chunked transfer encoding or send a

3568de757bac0b47256647504c186d17ca272f85rbb <code>Content-Length</code> request header. When passing these

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard requests on to the origin server, <module>mod_proxy_http</module>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard will always attempt to send the <code>Content-Length</code>. But

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard if the body is large and the original request used chunked

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard encoding, then chunked encoding may also be used in the upstream

b5ffe4f30780fb159db08bd9f628980d2a092711sf request. You can control this selection using <a

b5ffe4f30780fb159db08bd9f628980d2a092711sf href="/env.html">environment variables</a>. Setting

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <code>proxy-sendcl</code> ensures maximum compatibility with

1ce78cf71b5baaf2c1ab48e818cb1f2397df5010trawick upstream servers by always sending the

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <code>Content-Length</code>, while setting

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <code>proxy-sendchunked</code> minimizes resource usage by using

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard chunked encoding.</p>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz <p>Under some circumstances, the server must spool request bodies

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard to disk to satisfy the requested handling of request bodies. For

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz example, this spooling will occur if the original body was sent with

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz chunked encoding (and is large), but the administrator has

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz asked for backend requests to be sent with Content-Length or as HTTP/1.0.

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard This spooling can also occur if the request body already has a

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz Content-Length header, but the server is configured to filter incoming

dd028aa8111afb6534fece555e8c2d408894671etrawick request bodies.</p>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <p><directive module="core">LimitRequestBody</directive> only applies to

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard request bodies that the server will spool to disk</p>

3568de757bac0b47256647504c186d17ca272f85rbb

3568de757bac0b47256647504c186d17ca272f85rbb </section> <!-- /request-bodies -->

3568de757bac0b47256647504c186d17ca272f85rbb

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <section id="x-headers"><title>Reverse Proxy Request Headers</title>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz

f714f1a7002928d785e53e70349700a7f595fee3trawick <p>When acting in a reverse-proxy mode (using the <directive

f714f1a7002928d785e53e70349700a7f595fee3trawick module="mod_proxy">ProxyPass</directive> directive, for example),

3568de757bac0b47256647504c186d17ca272f85rbb <module>mod_proxy_http</module> adds several request headers in

ad83978f20c7d1a4323059d9af122e56fcd353bdstoddard order to pass information to the origin server. These headers

4a13940dc2990df0a798718d3a3f9cf1566c2217bjh are:</p>

4a13940dc2990df0a798718d3a3f9cf1566c2217bjh

4a13940dc2990df0a798718d3a3f9cf1566c2217bjh <dl>

4a13940dc2990df0a798718d3a3f9cf1566c2217bjh <dt><code>X-Forwarded-For</code></dt>

3568de757bac0b47256647504c186d17ca272f85rbb <dd>The IP address of the client.</dd>

3568de757bac0b47256647504c186d17ca272f85rbb <dt><code>X-Forwarded-Host</code></dt>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <dd>The original host requested by the client in the <code>Host</code>

663237d6bcc59ac0997d71d48a1baa55fa29a3d8jim HTTP request header.</dd>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <dt><code>X-Forwarded-Server</code></dt>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <dd>The hostname of the proxy server.</dd>

3568de757bac0b47256647504c186d17ca272f85rbb </dl>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <p>Be careful when using these headers on the origin server, since

663237d6bcc59ac0997d71d48a1baa55fa29a3d8jim they will contain more than one (comma-separated) value if the

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard original request already contained one of these headers. For

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard example, you can use <code>%{X-Forwarded-For}i</code> in the log

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard format string of the origin server to log the original clients IP

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard address, but you may get more than one address if the request

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz passes through several proxies.</p>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <p>See also the <directive

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard module="mod_proxy">ProxyPreserveHost</directive> and <directive

3568de757bac0b47256647504c186d17ca272f85rbb module="mod_proxy">ProxyVia</directive> directives, which control

ad83978f20c7d1a4323059d9af122e56fcd353bdstoddard other request headers.</p>

4a13940dc2990df0a798718d3a3f9cf1566c2217bjh

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard </section> <!--/x-headers -->

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard

3568de757bac0b47256647504c186d17ca272f85rbb

4a13940dc2990df0a798718d3a3f9cf1566c2217bjh<directivesynopsis type="section">

4a13940dc2990df0a798718d3a3f9cf1566c2217bjh<name>Proxy</name>

4a13940dc2990df0a798718d3a3f9cf1566c2217bjh<description>Container for directives applied to proxied resources</description>

3568de757bac0b47256647504c186d17ca272f85rbb<syntax>&lt;Proxy <var>wildcard-url</var>&gt; ...&lt;/Proxy&gt;</syntax>

3568de757bac0b47256647504c186d17ca272f85rbb<contextlist><context>server config</context><context>virtual host</context>

663237d6bcc59ac0997d71d48a1baa55fa29a3d8jim</contextlist>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard<usage>

3568de757bac0b47256647504c186d17ca272f85rbb <p>Directives placed in <directive type="section">Proxy</directive>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz sections apply only to matching proxied content. Shell-style wildcards are

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard allowed.</p>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <p>For example, the following will allow only hosts in

3568de757bac0b47256647504c186d17ca272f85rbb <code>yournetwork.example.com</code> to access content via your proxy

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard server:</p>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <highlight language="config">

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard&lt;Proxy *&gt;

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard Require host yournetwork.example.com

3568de757bac0b47256647504c186d17ca272f85rbb&lt;/Proxy&gt;

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard </highlight>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz <p>The following example will process all files in the <code>foo</code>

3568de757bac0b47256647504c186d17ca272f85rbb directory of <code>example.com</code> through the <code>INCLUDES</code>

3568de757bac0b47256647504c186d17ca272f85rbb filter when they are sent through the proxy server:</p>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz <highlight language="config">

3568de757bac0b47256647504c186d17ca272f85rbb&lt;Proxy http://example.com/foo/*&gt;

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard SetOutputFilter INCLUDES

3568de757bac0b47256647504c186d17ca272f85rbb&lt;/Proxy&gt;

3568de757bac0b47256647504c186d17ca272f85rbb </highlight>

3568de757bac0b47256647504c186d17ca272f85rbb

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard</usage>

3568de757bac0b47256647504c186d17ca272f85rbb<seealso><directive type="section" module="mod_proxy">ProxyMatch</directive></seealso>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard</directivesynopsis>

3568de757bac0b47256647504c186d17ca272f85rbb

cd8f8c995d415473f3bfb0b329b2450f2a722c3atrawick<directivesynopsis>

cd8f8c995d415473f3bfb0b329b2450f2a722c3atrawick<name>ProxyBadHeader</name>

cd8f8c995d415473f3bfb0b329b2450f2a722c3atrawick<description>Determines how to handle bad header lines in a

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddardresponse</description>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz<syntax>ProxyBadHeader IsError|Ignore|StartBody</syntax>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz<default>ProxyBadHeader IsError</default>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard<contextlist><context>server config</context><context>virtual host</context>

beb70d51e435dc36c56a72b6cd83556c04db9283wrowe</contextlist>

fe6baec9bbcd36f932b71a355120cd7b5a685d6cfielding

3568de757bac0b47256647504c186d17ca272f85rbb<usage>

3568de757bac0b47256647504c186d17ca272f85rbb <p>The <directive>ProxyBadHeader</directive> directive determines the

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard behaviour of <module>mod_proxy</module> if it receives syntactically invalid

3568de757bac0b47256647504c186d17ca272f85rbb response header lines (<em>i.e.</em> containing no colon) from the origin

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard server. The following arguments are possible:</p>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <dl>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <dt><code>IsError</code></dt>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <dd>Abort the request and end up with a 502 (Bad Gateway) response. This is

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard the default behaviour.</dd>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <dt><code>Ignore</code></dt>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <dd>Treat bad header lines as if they weren't sent.</dd>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard <dt><code>StartBody</code></dt>

1ec8bd0373f11c07688ec9afbbf778cf78a0bc52wrowe <dd>When receiving the first bad header line, finish reading the headers and

397df70abe0bdd78a84fb6c38c02641bcfeadceasf treat the remainder as body. This helps to work around buggy backend servers

397df70abe0bdd78a84fb6c38c02641bcfeadceasf which forget to insert an empty line between the headers and the body.</dd>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard </dl>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard</usage>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard</directivesynopsis>

8e9734d1a4af74c141e2a0f880bb51bb061fa03atrawick

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard<directivesynopsis type="section">

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard<name>ProxyMatch</name>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard<description>Container for directives applied to regular-expression-matched

cd8f8c995d415473f3bfb0b329b2450f2a722c3atrawickproxied resources</description>

cd8f8c995d415473f3bfb0b329b2450f2a722c3atrawick<syntax>&lt;ProxyMatch <var>regex</var>&gt; ...&lt;/ProxyMatch&gt;</syntax>

3568de757bac0b47256647504c186d17ca272f85rbb<contextlist><context>server config</context><context>virtual host</context>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard</contextlist>

cb97ae2ff6969c2789b8e03f1bc4187fa73b6bafwrowe

0f113d7123e8bd3e3e2e9b6373461a1a773bfccatrawick<usage>

0f113d7123e8bd3e3e2e9b6373461a1a773bfccatrawick <p>The <directive type="section">ProxyMatch</directive> directive is

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz identical to the <directive module="mod_proxy"

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard type="section">Proxy</directive> directive, except it matches URLs

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard using <glossary ref="regex">regular expressions</glossary>.</p>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard</usage>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard<seealso><directive type="section" module="mod_proxy">Proxy</directive></seealso>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard</directivesynopsis>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard

3568de757bac0b47256647504c186d17ca272f85rbb<directivesynopsis>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard<name>ProxyPreserveHost</name>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz<description>Use incoming Host HTTP request header for proxy

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddardrequest</description>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard<syntax>ProxyPreserveHost On|Off</syntax>

c0659e61002e9d6ff77b2dca72540e0af1b2ca64stoddard<default>ProxyPreserveHost Off</default>

3568de757bac0b47256647504c186d17ca272f85rbb<contextlist><context>server config</context><context>virtual host</context>

3568de757bac0b47256647504c186d17ca272f85rbb<context>directory</context>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick</contextlist>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<compatibility>Usable in directory

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawickcontext in 2.3.3 and later.</compatibility>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<usage>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <p>When enabled, this option will pass the Host: line from the incoming

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick request to the proxied host, instead of the hostname specified in the

f886987cd0bd4220c14043c4d9be77ec22902e73trawick <directive>ProxyPass</directive> line.</p>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick

f886987cd0bd4220c14043c4d9be77ec22902e73trawick <p>This option should normally be turned <code>Off</code>. It is mostly

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick useful in special configurations like proxied mass name-based virtual

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick hosting, where the original Host header needs to be evaluated by the

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick backend server.</p>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick</usage>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz</directivesynopsis>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz<directivesynopsis>

a72ba68ecbbc61e4b513e50d6000245c33f753dcwrowe<name>ProxyRequests</name>

2e7f1d7da527c09e717251e186deffe55e6fbd0ftrawick<description>Enables forward (standard) proxy requests</description>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm<syntax>ProxyRequests On|Off</syntax>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm<default>ProxyRequests Off</default>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm<contextlist><context>server config</context><context>virtual host</context>

2e7f1d7da527c09e717251e186deffe55e6fbd0ftrawick</contextlist>

2e7f1d7da527c09e717251e186deffe55e6fbd0ftrawick

2e7f1d7da527c09e717251e186deffe55e6fbd0ftrawick<usage>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm <p>This allows or prevents Apache httpd from functioning as a forward proxy

3568de757bac0b47256647504c186d17ca272f85rbb server. (Setting ProxyRequests to <code>Off</code> does not disable use of

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm the <directive module="mod_proxy">ProxyPass</directive> directive.)</p>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz <p>In a typical reverse proxy or gateway configuration, this

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz option should be set to

e8f95a682820a599fe41b22977010636be5c2717jim <code>Off</code>.</p>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz <p>In order to get the functionality of proxying HTTP or FTP sites, you

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz need also <module>mod_proxy_http</module> or <module>mod_proxy_ftp</module>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz (or both) present in the server.</p>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm <p>In order to get the functionality of (forward) proxying HTTPS sites, you

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm need <module>mod_proxy_connect</module> enabled in the server.</p>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm <note type="warning"><title>Warning</title>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm <p>Do not enable proxying with <directive

36c8049de63c446926139936c3d195330a0539cetrawick module="mod_proxy">ProxyRequests</directive> until you have <a

36c8049de63c446926139936c3d195330a0539cetrawick href="#access">secured your server</a>. Open proxy servers are dangerous

36c8049de63c446926139936c3d195330a0539cetrawick both to your network and to the Internet at large.</p>

36c8049de63c446926139936c3d195330a0539cetrawick </note>

36c8049de63c446926139936c3d195330a0539cetrawick</usage>

36c8049de63c446926139936c3d195330a0539cetrawick<seealso><a href="#forwardreverse">Forward and Reverse Proxies/Gateways</a></seealso>

36c8049de63c446926139936c3d195330a0539cetrawick</directivesynopsis>

36c8049de63c446926139936c3d195330a0539cetrawick

e8f95a682820a599fe41b22977010636be5c2717jim<directivesynopsis>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<name>ProxyRemote</name>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm<description>Remote proxy used to handle certain requests</description>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<syntax>ProxyRemote <var>match</var> <var>remote-server</var></syntax>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<contextlist><context>server config</context><context>virtual host</context>

36c8049de63c446926139936c3d195330a0539cetrawick</contextlist>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<usage>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <p>This defines remote proxies to this proxy. <var>match</var> is either the

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick name of a URL-scheme that the remote server supports, or a partial URL

cb97ae2ff6969c2789b8e03f1bc4187fa73b6bafwrowe for which the remote server should be used, or <code>*</code> to indicate

36c8049de63c446926139936c3d195330a0539cetrawick the server should be contacted for all requests. <var>remote-server</var> is

36c8049de63c446926139936c3d195330a0539cetrawick a partial URL for the remote server. Syntax:</p>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick

e8f95a682820a599fe41b22977010636be5c2717jim <example>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm <dfn>remote-server</dfn> =

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <var>scheme</var>://<var>hostname</var>[:<var>port</var>]

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick </example>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <p><var>scheme</var> is effectively the protocol that should be used to

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick communicate with the remote server; only <code>http</code> and <code>https</code>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick are supported by this module. When using <code>https</code>, the requests

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick are forwarded through the remote proxy using the HTTP CONNECT method.</p>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <example><title>Example</title>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <highlight language="config">

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawickProxyRemote http://goodguys.example.com/ http://mirrorguys.example.com:8000

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawickProxyRemote * http://cleverproxy.localdomain

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawickProxyRemote ftp http://ftpproxy.mydomain:8080

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick </highlight>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick </example>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <p>In the last example, the proxy will forward FTP requests, encapsulated

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick as yet another HTTP proxy request, to another proxy which can handle

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick them.</p>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <p>This option also supports reverse proxy configuration - a backend

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick webserver can be embedded within a virtualhost URL space even if that

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick server is hidden by another forward proxy.</p>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick</usage>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick</directivesynopsis>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<directivesynopsis>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<name>ProxyRemoteMatch</name>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<description>Remote proxy used to handle requests matched by regular

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawickexpressions</description>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<syntax>ProxyRemoteMatch <var>regex</var> <var>remote-server</var></syntax>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<contextlist><context>server config</context><context>virtual host</context>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick</contextlist>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<usage>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <p>The <directive>ProxyRemoteMatch</directive> is identical to the

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <directive module="mod_proxy">ProxyRemote</directive> directive, except the

e8f95a682820a599fe41b22977010636be5c2717jim first argument is a <glossary ref="regex">regular expression</glossary>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick match against the requested URL.</p>

f886987cd0bd4220c14043c4d9be77ec22902e73trawick</usage>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick</directivesynopsis>

f886987cd0bd4220c14043c4d9be77ec22902e73trawick

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<directivesynopsis>

f886987cd0bd4220c14043c4d9be77ec22902e73trawick<name>BalancerGrowth</name>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm<description>Number of additional Balancers that can be added Post-configuration</description>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm <syntax>BalancerGrowth <var>#</var></syntax>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm <default>BalancerGrowth 5</default>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm <contextlist><context>server config</context><context>virtual host</context></contextlist>

3568de757bac0b47256647504c186d17ca272f85rbb<compatibility>BalancerGrowth is only available in Apache HTTP Server 2.3.13

72b6f1cf3e616473e1c26464b3193b13c2c09e87brianp and later.</compatibility>

72b6f1cf3e616473e1c26464b3193b13c2c09e87brianp<usage>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <p>This directive allows for growth potential in the number of

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick Balancers available for a virtualhost in addition to the

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick number pre-configured. It only takes effect if there is at

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick least 1 pre-configured Balancer.</p>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick</usage>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick</directivesynopsis>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<directivesynopsis>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <name>BalancerPersist</name>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <description>Attempt to persist changes made by the Balancer Manager across restarts.</description>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <syntax>BalancerPersist On|Off</syntax>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm <default>BalancerPersist Off</default>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <contextlist><context>server config</context><context>virtual host</context></contextlist>

f2e009134c7e279f99dfca5bd421f721bf1f7840jorton <compatibility>BalancerPersist is only available in Apache HTTP Server 2.5.0

f2e009134c7e279f99dfca5bd421f721bf1f7840jorton and later.</compatibility>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <usage>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm <p>This directive will cause the shared memory storage associated

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick with the balancers and balancer members to be persisted across

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick restarts. This allows these local changes to not be lost during the

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm normal restart/graceful state transitions.</p>

2e7f1d7da527c09e717251e186deffe55e6fbd0ftrawick </usage>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick</directivesynopsis>

36c8049de63c446926139936c3d195330a0539cetrawick

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<directivesynopsis>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <name>ProxyPassInherit</name>

f886987cd0bd4220c14043c4d9be77ec22902e73trawick <description>Inherit ProxyPass directives defined from the main server</description>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <syntax>ProxyPassInherit On|Off</syntax>

cb97ae2ff6969c2789b8e03f1bc4187fa73b6bafwrowe <default>ProxyPassInherit On</default>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <contextlist><context>server config</context><context>virtual host</context></contextlist>

36c8049de63c446926139936c3d195330a0539cetrawick <compatibility>ProxyPassInherit is only available in Apache HTTP Server 2.5.0 and later.

36c8049de63c446926139936c3d195330a0539cetrawick and later.</compatibility>

36c8049de63c446926139936c3d195330a0539cetrawick <usage>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <p>This directive will cause the current server/vhost to "inherit"

e8f95a682820a599fe41b22977010636be5c2717jim <directive module="mod_proxy">ProxyPass</directive>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm directives defined in the main server. This can cause issues and

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick inconsistent behavior if using the Balancer Manager for dynamic changes

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick and so should be disabled if using that feature.</p>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <p>The setting in the global server defines the default for all vhosts.</p>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <p>Disabling ProxyPassInherit also disables <directive module="mod_proxy">BalancerInherit</directive>.</p>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick </usage>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick</directivesynopsis>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<directivesynopsis>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <name>BalancerInherit</name>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <description>Inherit proxy Balancers/Workers defined from the main server</description>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <syntax>BalancerInherit On|Off</syntax>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <default>BalancerInherit On</default>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <contextlist><context>server config</context><context>virtual host</context></contextlist>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <compatibility>BalancerInherit is only available in Apache HTTP Server 2.4.4 and later.

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick and later.</compatibility>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <usage>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <p>This directive will cause the current server/vhost to "inherit"

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick Balancers and Workers defined in the main server. This can cause issues and

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick inconsistent behavior if using the Balancer Manager for dynamic changes

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick and so should be disabled if using that feature.</p>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <p>The setting in the global server defines the default for all vhosts.</p>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <p>Disabling <directive module="mod_proxy">ProxyPassInherit</directive> also disables BalancerInherit.</p>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick </usage>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick</directivesynopsis>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<directivesynopsis>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <name>BalancerMember</name>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <description>Add a member to a load balancing group</description>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <syntax>BalancerMember [<var>balancerurl</var>] <var>url</var> [<var

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick >key=value [key=value ...]]</var></syntax>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <contextlist><context>directory</context>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick </contextlist>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <usage>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <p>This directive adds a member to a load balancing group. It could be used

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick within a <code>&lt;Proxy <var>balancer://</var>...&gt;</code> container

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick directive, and can take any of the key value pair parameters available to

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <directive module="mod_proxy">ProxyPass</directive> directives.</p>

e8f95a682820a599fe41b22977010636be5c2717jim <p>One additional parameter is available only to <directive

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick module="mod_proxy">BalancerMember</directive> directives:

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <var>loadfactor</var>. This is the member load factor - a number between 1

f886987cd0bd4220c14043c4d9be77ec22902e73trawick (default) and 100, which defines the weighted load to be applied to the

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick member in question.</p>

f886987cd0bd4220c14043c4d9be77ec22902e73trawick <p>The balancerurl is only needed when not in <code>&lt;Proxy <var>balancer://</var>...&gt;</code>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick container directive. It corresponds to the url of a balancer defined in

f886987cd0bd4220c14043c4d9be77ec22902e73trawick <directive module="mod_proxy">ProxyPass</directive> directive.</p>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm <p>The path component of the balancer URL in any

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm <code>&lt;Proxy <var>balancer://</var>...&gt;</code> container directive

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm is ignored.</p>

64c351fd973428b5bb4c28e983fa86875ea4e60fdougm <p>Trailing slashes should typically be removed from the URL of a

3568de757bac0b47256647504c186d17ca272f85rbb <code>BalancerMember</code>.</p>

72b6f1cf3e616473e1c26464b3193b13c2c09e87brianp </usage>

72b6f1cf3e616473e1c26464b3193b13c2c09e87brianp</directivesynopsis>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick

e8f95a682820a599fe41b22977010636be5c2717jim<directivesynopsis>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<name>ProxySet</name>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<description>Set various Proxy balancer or member parameters</description>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick<syntax>ProxySet <var>url</var> <var>key=value [key=value ...]</var></syntax>

e8f95a682820a599fe41b22977010636be5c2717jim<contextlist><context>directory</context>

44d2e75323651320b480d8bc2f098448a08de4fcwrowe</contextlist>

44d2e75323651320b480d8bc2f098448a08de4fcwrowe<usage>

44d2e75323651320b480d8bc2f098448a08de4fcwrowe <p>This directive is used as an alternate method of setting any of the

44d2e75323651320b480d8bc2f098448a08de4fcwrowe parameters available to Proxy balancers and workers normally done via the

44d2e75323651320b480d8bc2f098448a08de4fcwrowe <directive module="mod_proxy">ProxyPass</directive> directive. If used

44d2e75323651320b480d8bc2f098448a08de4fcwrowe within a <code>&lt;Proxy <var>balancer url|worker url</var>&gt;</code>

44d2e75323651320b480d8bc2f098448a08de4fcwrowe container directive, the <var>url</var> argument is not required. As a side

44d2e75323651320b480d8bc2f098448a08de4fcwrowe effect the respective balancer or worker gets created. This can be useful

44d2e75323651320b480d8bc2f098448a08de4fcwrowe when doing reverse proxying via a

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <directive module="mod_rewrite">RewriteRule</directive> instead of a

2e7f1d7da527c09e717251e186deffe55e6fbd0ftrawick <directive module="mod_proxy">ProxyPass</directive> directive.</p>

2e7f1d7da527c09e717251e186deffe55e6fbd0ftrawick

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz <example>

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick <highlight language="config">

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz&lt;Proxy balancer://hotcluster&gt;

1ec8bd0373f11c07688ec9afbbf778cf78a0bc52wrowe BalancerMember http://www2.example.com:8080 loadfactor=1

3568de757bac0b47256647504c186d17ca272f85rbb BalancerMember http://www3.example.com:8080 loadfactor=2

1ec8bd0373f11c07688ec9afbbf778cf78a0bc52wrowe ProxySet lbmethod=bytraffic

1ec8bd0373f11c07688ec9afbbf778cf78a0bc52wrowe&lt;/Proxy&gt;

1ec8bd0373f11c07688ec9afbbf778cf78a0bc52wrowe </highlight>

f886987cd0bd4220c14043c4d9be77ec22902e73trawick </example>

f886987cd0bd4220c14043c4d9be77ec22902e73trawick

f886987cd0bd4220c14043c4d9be77ec22902e73trawick <highlight language="config">

f886987cd0bd4220c14043c4d9be77ec22902e73trawick&lt;Proxy http://backend&gt;

f886987cd0bd4220c14043c4d9be77ec22902e73trawick ProxySet keepalive=On

f886987cd0bd4220c14043c4d9be77ec22902e73trawick&lt;/Proxy&gt;

f886987cd0bd4220c14043c4d9be77ec22902e73trawick </highlight>

1ec8bd0373f11c07688ec9afbbf778cf78a0bc52wrowe

1ec8bd0373f11c07688ec9afbbf778cf78a0bc52wrowe <highlight language="config">

1ec8bd0373f11c07688ec9afbbf778cf78a0bc52wrowe ProxySet balancer://foo lbmethod=bytraffic timeout=15

1ec8bd0373f11c07688ec9afbbf778cf78a0bc52wrowe </highlight>

3568de757bac0b47256647504c186d17ca272f85rbb

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz <highlight language="config">

8bfe865d8d61be4ba4a89e45427a3c4211ebabdctrawick ProxySet ajp://backend:7001 timeout=15

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz </highlight>

3568de757bac0b47256647504c186d17ca272f85rbb

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz <note type="warning"><title>Warning</title>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz <p>Keep in mind that the same parameter key can have a different meaning

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz depending whether it is applied to a balancer or a worker as shown by the two

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz examples above regarding timeout.</p>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz </note>

3568de757bac0b47256647504c186d17ca272f85rbb

3568de757bac0b47256647504c186d17ca272f85rbb</usage>

98fb535f829e2a95aabd82420931f476661fa8e3jorton</directivesynopsis>

98fb535f829e2a95aabd82420931f476661fa8e3jorton

e8f95a682820a599fe41b22977010636be5c2717jim<directivesynopsis>

e8f95a682820a599fe41b22977010636be5c2717jim<name>ProxyPass</name>

98fb535f829e2a95aabd82420931f476661fa8e3jorton<description>Maps remote servers into the local server URL-space</description>

98fb535f829e2a95aabd82420931f476661fa8e3jorton<syntax>ProxyPass [<var>path</var>] !|<var>url</var> [<var>key=value</var>

e8f95a682820a599fe41b22977010636be5c2717jim <var>[key=value</var> ...]] [nocanon] [interpolate] [noquery]</syntax>

98fb535f829e2a95aabd82420931f476661fa8e3jorton<contextlist><context>server config</context><context>virtual host</context>

98fb535f829e2a95aabd82420931f476661fa8e3jorton<context>directory</context>

98fb535f829e2a95aabd82420931f476661fa8e3jorton</contextlist>

3568de757bac0b47256647504c186d17ca272f85rbb

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz<usage>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz <p>This directive allows remote servers to be mapped into the

3568de757bac0b47256647504c186d17ca272f85rbb space of the local server; the local server does not act as a

3568de757bac0b47256647504c186d17ca272f85rbb proxy in the conventional sense, but appears to be a mirror of the

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding remote server. The local server is often called a <dfn>reverse

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding proxy</dfn> or <dfn>gateway</dfn>. The <var>path</var> is the name of

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding a local virtual path; <var>url</var> is a partial URL for the

85c5af648e9f414bd4f157490766d2fd5515a9f5rpluem remote server and cannot include a query string.</p>

0cb6873985efbf0cc9644114925df6baa4b32d5awrowe

0cb6873985efbf0cc9644114925df6baa4b32d5awrowe <note type="warning">The <directive

0cb6873985efbf0cc9644114925df6baa4b32d5awrowe module="mod_proxy">ProxyRequests</directive> directive should

0cb6873985efbf0cc9644114925df6baa4b32d5awrowe usually be set <strong>off</strong> when using

0cb6873985efbf0cc9644114925df6baa4b32d5awrowe <directive>ProxyPass</directive>.</note>

0cb6873985efbf0cc9644114925df6baa4b32d5awrowe

0cb6873985efbf0cc9644114925df6baa4b32d5awrowe <p>Suppose the local server has address <code>http://example.com/</code>;

85c5af648e9f414bd4f157490766d2fd5515a9f5rpluem then</p>

0cb6873985efbf0cc9644114925df6baa4b32d5awrowe

3568de757bac0b47256647504c186d17ca272f85rbb <highlight language="config">

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz&lt;Location /mirror/foo/&gt;

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz ProxyPass http://backend.example.com/

3568de757bac0b47256647504c186d17ca272f85rbb&lt;/Location&gt;

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz </highlight>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz

3568de757bac0b47256647504c186d17ca272f85rbb <p>will cause a local request for

3568de757bac0b47256647504c186d17ca272f85rbb <code>http://example.com/mirror/foo/bar</code> to be internally converted

3568de757bac0b47256647504c186d17ca272f85rbb into a proxy request to <code>http://backend.example.com/bar</code>.</p>

3568de757bac0b47256647504c186d17ca272f85rbb

3568de757bac0b47256647504c186d17ca272f85rbb <p>The following alternative syntax is possible, however it can carry a

3568de757bac0b47256647504c186d17ca272f85rbb performance penalty when present in very large numbers. The advantage of

ec020ca384efb30d501a5af796ddc3bb237d7b8fgregames the below syntax is that it allows for dynamic control via the

3568de757bac0b47256647504c186d17ca272f85rbb <a href="mod_proxy_balancer.html#balancer_manager">Balancer Manager</a> interface:</p>

ce03576b2434cec77f2921db9d5b6a0510581c23rederpj

397df70abe0bdd78a84fb6c38c02641bcfeadceasf <highlight language="config">

cd8f8c995d415473f3bfb0b329b2450f2a722c3atrawick ProxyPass /mirror/foo/ http://backend.example.com/

cd8f8c995d415473f3bfb0b329b2450f2a722c3atrawick </highlight>

397df70abe0bdd78a84fb6c38c02641bcfeadceasf

397df70abe0bdd78a84fb6c38c02641bcfeadceasf <note type="warning">

397df70abe0bdd78a84fb6c38c02641bcfeadceasf <p>If the first argument ends with a trailing <strong>/</strong>, the second

397df70abe0bdd78a84fb6c38c02641bcfeadceasf argument should also end with a trailing <strong>/</strong> and vice

397df70abe0bdd78a84fb6c38c02641bcfeadceasf versa. Otherwise the resulting requests to the backend may miss some

9d0665da83d1e22c0ea0e5f6f940f70f75bf5237ianh needed slashes and do not deliver the expected results.

3568de757bac0b47256647504c186d17ca272f85rbb </p>

3568de757bac0b47256647504c186d17ca272f85rbb </note>

7cd5419264796cfeaf8215383cf0f89130a81fectrawick

7cd5419264796cfeaf8215383cf0f89130a81fectrawick <p>The <code>!</code> directive is useful in situations where you don't want

7cd5419264796cfeaf8215383cf0f89130a81fectrawick to reverse-proxy a subdirectory, <em>e.g.</em></p>

7cd5419264796cfeaf8215383cf0f89130a81fectrawick

7cd5419264796cfeaf8215383cf0f89130a81fectrawick <highlight language="config">

7cd5419264796cfeaf8215383cf0f89130a81fectrawick&lt;Location /mirror/foo/&gt;

7cd5419264796cfeaf8215383cf0f89130a81fectrawick ProxyPass http://backend.example.com/

73e8b26287de5c06fa470d36162e103dbac9c7e5wrowe&lt;/Location&gt;

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding&lt;Location /mirror/foo/i&gt;

b980ad7fdc218b4855cde9f75a747527f50c554dwrowe ProxyPass !

0cb6873985efbf0cc9644114925df6baa4b32d5awrowe&lt;/Location&gt;

3568de757bac0b47256647504c186d17ca272f85rbb </highlight>

7cd5419264796cfeaf8215383cf0f89130a81fectrawick

7cd5419264796cfeaf8215383cf0f89130a81fectrawick <highlight language="config">

7cd5419264796cfeaf8215383cf0f89130a81fectrawickProxyPass /mirror/foo/i !

ca53a74f4012a45cbad48e940eddf27d866981f9dougmProxyPass /mirror/foo http://backend.example.com

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding </highlight>

36ef8f77bffe75d1aa327882be1b5bdbe2ff567asf

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>will proxy all requests to <code>/mirror/foo</code> to

302dc1f7b3feee23a91ad8f3cf3cb2edd95a557bmanoj <code>backend.example.com</code> <em>except</em> requests made to

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz <code>/mirror/foo/i</code>.</p>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz <note type="warning"><title>Ordering ProxyPass Directives</title>

28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz <p>The configured <directive module="mod_proxy">ProxyPass</directive>

0cb6873985efbf0cc9644114925df6baa4b32d5awrowe and <directive module="mod_proxy">ProxyPassMatch</directive>

3568de757bac0b47256647504c186d17ca272f85rbb rules are checked in the order of configuration. The first rule that

0f081398cf0eef8cc7c66a535d450110a92dc8aefielding matches wins. So usually you should sort conflicting

3568de757bac0b47256647504c186d17ca272f85rbb <directive module="mod_proxy">ProxyPass</directive> rules starting with the

longest URLs first. Otherwise later rules for longer URLS will be hidden

by any earlier rule which uses a leading substring of the URL. Note that

there is some relation with worker sharing. In contrast, only one

<directive module="mod_proxy">ProxyPass</directive> directive can be placed

in a <directive module="core">Location</directive> block, and the most

specific location will take precedence.</p>

<p>For the same reasons exclusions must come <em>before</em> the

general <directive>ProxyPass</directive> directives.</p>

</note> <!-- /ordering_proxypass -->

<p>In Apache HTTP Server 2.1 and later, mod_proxy supports pooled

connections to a backend server. Connections created on demand

can be retained in a pool for future use. Limits on the pool size

and other settings can be coded on

the <directive>ProxyPass</directive> directive

using <code>key=value</code> parameters, described in the table

below.</p>

<p>By default, mod_proxy will allow and retain the maximum number of

connections that could be used simultaneously by that web server child

process. Use the <code>max</code> parameter to reduce the number from

the default. Use the <code>ttl</code> parameter to set an optional

time to live; connections which have been unused for at least

<code>ttl</code> seconds will be closed. <code>ttl</code> can be used

to avoid using a connection which is subject to closing because of the

backend server's keep-alive timeout.</p>

<p>The pool of connections is maintained per web server child

process, and <code>max</code> and other settings are not coordinated

among all child processes, except when only one child process is allowed

by configuration or MPM design.</p>

<example><title>Example</title>

<highlight language="config">

ProxyPass /example http://backend.example.com max=20 ttl=120 retry=300

</highlight>

</example>

<table border="2"><tr><th>BalancerMember parameters</th></tr></table>

<table>

<tr><th>Parameter</th>

<th>Default</th>

<th>Description</th></tr>

<tr><td>min</td>

<td>0</td>

<td>Minimum number of connection pool entries, unrelated to the

actual number of connections. This only needs to be modified from the

default for special circumstances where heap memory associated with the

backend connections should be preallocated or retained.</td></tr>

<tr><td>max</td>

<td>1...n</td>

<td>Maximum number of connections that will be allowed to the

backend server. The default for this limit is the number of threads

per process in the active MPM. In the Prefork MPM, this is always 1,

while with other MPMs it is controlled by the

<directive>ThreadsPerChild</directive> directive.</td></tr>

<tr><td>smax</td>

<td>max</td>

<td>Retained connection pool entries above this limit are freed

during certain operations if they have been unused for longer than

the time to live, controlled by the <code>ttl</code> parameter. If

the connection pool entry has an associated connection, it will be

closed. This only needs to be modified from the default for special

circumstances where connection pool entries and any associated

connections which have exceeded the time to live need to be freed or

closed more aggressively.</td></tr>

<tr><td>acquire</td>

<td>-</td>

<td>If set this will be the maximum time to wait for a free

connection in the connection pool, in milliseconds. If there are no free

connections in the pool the Apache httpd will return <code>SERVER_BUSY</code>

status to the client.

</td></tr>

<tr><td>connectiontimeout</td>

<td>timeout</td>

<td>Connect timeout in seconds.

The number of seconds Apache httpd waits for the creation of a connection to

the backend to complete. By adding a postfix of ms the timeout can be

also set in milliseconds.

</td></tr>

<tr><td>disablereuse</td>

<td>Off</td>

<td>This parameter should be used when you want to force mod_proxy

to immediately close a connection to the backend after being used, and

thus, disable its persistent connection and pool for that backend.

This helps in various situations where a firewall between Apache

httpd and

the backend server (regardless of protocol) tends to silently

drop connections or when backends themselves may be under round-

robin DNS. To disable connection pooling reuse,

set this property value to <code>On</code>.

</td></tr>

<tr><td>flushpackets</td>

<td>off</td>

<td>Determines whether the proxy module will auto-flush the output

brigade after each "chunk" of data. 'off' means that it will flush

only when needed, 'on' means after each chunk is sent and

'auto' means poll/wait for a period of time and flush if

no input has been received for 'flushwait' milliseconds.

Currently this is in effect only for AJP.

</td></tr>

<tr><td>flushwait</td>

<td>10</td>

<td>The time to wait for additional input, in milliseconds, before

flushing the output brigade if 'flushpackets' is 'auto'.

</td></tr>

<tr><td>iobuffersize</td>

<td>8192</td>

<td>Adjusts the size of the internal scratchpad IO buffer. This allows you

to override the <directive>ProxyIOBufferSize</directive> for a specific worker.

This must be at least 512 or set to 0 for the system default of 8192.

</td></tr>

<tr><td>keepalive</td>

<td>Off</td>

<td><p>This parameter should be used when you have a firewall between your

Apache httpd and the backend server, who tend to drop inactive connections.

This flag will tell the Operating System to send <code>KEEP_ALIVE</code>

messages on inactive connections and thus prevent the firewall to drop the connection.

To enable keepalive set this property value to <code>On</code>. </p>

<p>The frequency of initial and subsequent TCP keepalive probes

depends on global OS settings, and may be as high as 2 hours. To be useful,

the frequency configured in the OS must be smaller than the threshold used

by the firewall.</p>

</td></tr>

<tr><td>lbset</td>

<td>0</td>

<td>Sets the load balancer cluster set that the worker is a member

of. The load balancer will try all members of a lower numbered

lbset before trying higher numbered ones.

</td></tr>

<tr><td>ping</td>

<td>0</td>

<td>Ping property tells the webserver to "test" the connection to

the backend before forwarding the request. For AJP, it causes

<module>mod_proxy_ajp</module>to send a <code>CPING</code>

request on the ajp13 connection (implemented on Tomcat 3.3.2+, 4.1.28+

and 5.0.13+). For HTTP, it causes <module>mod_proxy_http</module>

to send a <code>100-Continue</code> to the backend (only valid for

HTTP/1.1 - for non HTTP/1.1 backends, this property has no

effect). In both cases the parameter is the delay in seconds to wait

for the reply.

This feature has been added to avoid problems with hung and

busy backends.

This will increase the network traffic during the normal operation

which could be an issue, but it will lower the

traffic in case some of the cluster nodes are down or busy.

By adding a postfix of ms the delay can be also set in

milliseconds.

</td></tr>

<tr><td>receivebuffersize</td>

<td>0</td>

<td>Adjusts the size of the explicit (TCP/IP) network buffer size for

proxied connections. This allows you to override the

<directive>ProxyReceiveBufferSize</directive> for a specific worker.

This must be at least 512 or set to 0 for the system default.

</td></tr>

<tr><td>redirect</td>

<td>-</td>

<td>Redirection Route of the worker. This value is usually

set dynamically to enable safe removal of the node from

the cluster. If set all requests without session id will be

redirected to the BalancerMember that has route parameter

equal as this value.

</td></tr>

<tr><td>retry</td>

<td>60</td>

<td>Connection pool worker retry timeout in seconds.

If the connection pool worker to the backend server is in the error state,

Apache httpd will not forward any requests to that server until the timeout

expires. This enables to shut down the backend server for maintenance,

and bring it back online later. A value of 0 means always retry workers

in an error state with no timeout.

</td></tr>

<tr><td>route</td>

<td>-</td>

<td>Route of the worker when used inside load balancer.

The route is a value appended to session id.

</td></tr>

<tr><td>status</td>

<td>-</td>

<td>Single letter value defining the initial status of

this worker.

<table>

<tr><td>D: Worker is disabled and will not accept any requests.</td></tr>

<tr><td>S: Worker is administratively stopped.</td></tr>

<tr><td>I: Worker is in ignore-errors mode, and will always be considered available.</td></tr>

<tr><td>H: Worker is in hot-standby mode and will only be used if no other

viable workers are available.</td></tr>

<tr><td>E: Worker is in an error state.</td></tr>

<tr><td>N: Worker is in drain mode, and will only accept existing sticky sessions

destined for itself and ignore all other requests.</td></tr>

</table>Status

can be set (which is the default) by prepending with '+' or

cleared by prepending with '-'.

Thus, a setting of 'S-E' sets this worker to Stopped and

clears the in-error flag.

</td></tr>

<tr><td>timeout</td>

<td><directive module="mod_proxy">ProxyTimeout</directive></td>

<td>Connection timeout in seconds.

The number of seconds Apache httpd waits for data sent by / to the backend.

</td></tr>

<tr><td>ttl</td>

<td>-</td>

<td>Time to live for inactive connections and associated connection

pool entries, in seconds. Once reaching this limit, a

connection will not be used again; it will be closed at some

later time.

</td></tr>

</table>

<p>If the Proxy directive scheme starts with the

<code>balancer://</code> (eg: <code>balancer://cluster</code>,

any path information is ignored) then a virtual worker that does not really

communicate with the backend server will be created. Instead it is responsible

for the management of several "real" workers. In that case the special set of

parameters can be add to this virtual worker. See <module>mod_proxy_balancer</module>

for more information about how the balancer works.

</p>

<table border="2"><tr><th>Balancer parameters</th></tr></table>

<table>

<tr><th>Parameter</th>

<th>Default</th>

<th>Description</th></tr>

<tr><td>lbmethod</td>

<td>byrequests</td>

<td>Balancer load-balance method. Select the load-balancing scheduler

method to use. Either <code>byrequests</code>, to perform weighted

request counting, <code>bytraffic</code>, to perform weighted

traffic byte count balancing, or <code>bybusyness</code>, to perform

pending request balancing. Default is <code>byrequests</code>.

</td></tr>

<tr><td>maxattempts</td>

<td>One less than the number of workers, or 1 with a single worker.</td>

<td>Maximum number of failover attempts before giving up.

</td></tr>

<tr><td>nofailover</td>

<td>Off</td>

<td>If set to <code>On</code> the session will break if the worker is in

error state or disabled. Set this value to On if backend servers do not

support session replication.

</td></tr>

<tr><td>stickysession</td>

<td>-</td>

<td>Balancer sticky session name. The value is usually set to something

like <code>JSESSIONID</code> or <code>PHPSESSIONID</code>,

and it depends on the backend application server that support sessions.

If the backend application server uses different name for cookies

and url encoded id (like servlet containers) use | to to separate them.

The first part is for the cookie the second for the path.

</td></tr>

<tr><td>stickysessionsep</td>

<td>"."</td>

<td>Sets the separation symbol in the session cookie. Some backend application servers

do not use the '.' as the symbol. For example the Oracle Weblogic server uses

'!'. The correct symbol can be set using this option. The setting of 'Off'

signifies that no symbol is used.

</td></tr>

<tr><td>scolonpathdelim</td>

<td>Off</td>

<td>If set to <code>On</code> the semi-colon character ';' will be

used as an additional sticky session path deliminator/separator. This

is mainly used to emulate mod_jk's behavior when dealing with paths such

as <code>JSESSIONID=6736bcf34;foo=aabfa</code>

</td></tr>

<tr><td>timeout</td>

<td>0</td>

<td>Balancer timeout in seconds. If set this will be the maximum time

to wait for a free worker. Default is not to wait.

</td></tr>

<tr><td>failonstatus</td>

<td>-</td>

<td>A single or comma-separated list of HTTP status codes. If set this will

force the worker into error state when the backend returns any status code

in the list. Worker recovery behaves the same as other worker errors.

</td></tr>

<tr><td>failontimeout</td>

<td>Off</td>

<td>If set, an IO read timeout after a request is sent to the backend will

force the worker into error state. Worker recovery behaves the same as other

worker errors.

</td></tr>

<tr><td>nonce</td>

<td>&lt;auto&gt;</td>

<td>The protective nonce used in the <code>balancer-manager</code> application page.

The default is to use an automatically determined UUID-based

nonce, to provide for further protection for the page. If set,

then the nonce is set to that value. A setting of <code>None</code>

disables all nonce checking.

<note><title>Note</title>

<p>In addition to the nonce, the <code>balancer-manager</code> page

should be protected via an ACL.</p>

</note>

</td></tr>

<tr><td>growth</td>

<td>0</td>

<td>Number of additional BalancerMembers to allow to be added

to this balancer in addition to those defined at configuration.

</td></tr>

<tr><td>forcerecovery</td>

<td>On</td>

<td>Force the immediate recovery of all workers without considering the

retry parameter of the workers if all workers of a balancer are

in error state. There might be cases where an already overloaded backend

can get into deeper trouble if the recovery of all workers is enforced

without considering the retry parameter of each worker. In this case

set to <code>Off</code>.

</td></tr>

</table>

<p>A sample balancer setup</p>

<highlight language="config">

ProxyPass /special-area http://special.example.com smax=5 max=10

ProxyPass / balancer://mycluster/ stickysession=JSESSIONID|jsessionid nofailover=On

&lt;Proxy balancer://mycluster&gt;

BalancerMember ajp://1.2.3.4:8009

BalancerMember ajp://1.2.3.5:8009 loadfactor=20

# Less powerful server, don't send as many requests there,

BalancerMember ajp://1.2.3.6:8009 loadfactor=5

&lt;/Proxy&gt;

</highlight>

<p>Setting up a hot-standby, that will only be used if no other

members are available</p>

<highlight language="config">

ProxyPass / balancer://hotcluster/

&lt;Proxy balancer://hotcluster&gt;

BalancerMember ajp://1.2.3.4:8009 loadfactor=1

BalancerMember ajp://1.2.3.5:8009 loadfactor=2

# The server below is on hot standby

BalancerMember ajp://1.2.3.6:8009 status=+H

ProxySet lbmethod=bytraffic

&lt;/Proxy&gt;

</highlight>

<p>Normally, mod_proxy will canonicalise ProxyPassed URLs.

But this may be incompatible with some backends, particularly those

that make use of <var>PATH_INFO</var>. The optional <var>nocanon</var>

keyword suppresses this, and passes the URL path "raw" to the

backend. Note that may affect the security of your backend, as it

removes the normal limited protection against URL-based attacks

provided by the proxy.</p>

<p>The optional <var>interpolate</var> keyword (available in

httpd 2.2.9 and later), in combination with

<directive>ProxyPassInterpolateEnv</directive> causes the ProxyPass

to interpolate environment variables, using the syntax

<var>${VARNAME}</var>. Note that many of the standard CGI-derived

environment variables will not exist when this interpolation happens,

so you may still have to resort to <module>mod_rewrite</module>

for complex rules.</p>

<p>Normally, mod_proxy will include the query string when

generating the <var>SCRIPT_FILENAME</var> environment variable.

The optional <var>noquery</var> keyword (available in

httpd 2.4.1 and later) prevents this.</p>

<p>When used inside a <directive type="section" module="core"

>Location</directive> section, the first argument is omitted and the local

directory is obtained from the <directive type="section" module="core"

>Location</directive>. The same will occur inside a

<directive type="section" module="core">LocationMatch</directive> section,

however ProxyPass does not interpret the regexp as such, so it is necessary

to use <directive>ProxyPassMatch</directive> in this situation instead.</p>

<p>This directive is not supported in <directive type="section" module="core"

>Directory</directive> or <directive type="section" module="core"

>Files</directive> sections.</p>

<p>If you require a more flexible reverse-proxy configuration, see the

<directive module="mod_rewrite">RewriteRule</directive> directive with the

<code>[P]</code> flag.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>ProxyPassMatch</name>

<description>Maps remote servers into the local server URL-space using regular expressions</description>

<syntax>ProxyPassMatch [<var>regex</var>] !|<var>url</var> [<var>key=value</var>

<var>[key=value</var> ...]]</syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context>

</contextlist>

<usage>

<p>This directive is equivalent to <directive module="mod_proxy">ProxyPass</directive>,

but makes use of regular expressions, instead of simple prefix matching. The

supplied regular expression is matched against the <var>url</var>, and if it

matches, the server will substitute any parenthesized matches into the given

string and use it as a new <var>url</var>.</p>

<p>Suppose the local server has address <code>http://example.com/</code>;

then</p>

<highlight language="config">

ProxyPassMatch ^(/.*\.gif)$ http://backend.example.com$1

</highlight>

<p>will cause a local request for

<code>http://example.com/foo/bar.gif</code> to be internally converted

into a proxy request to <code>http://backend.example.com/foo/bar.gif</code>.</p>

<note><title>Note</title>

<p>The URL argument must be parsable as a URL <em>before</em> regexp

substitutions (as well as after). This limits the matches you can use.

For instance, if we had used</p>

<highlight language="config">

ProxyPassMatch ^(/.*\.gif)$ http://backend.example.com:8000$1

</highlight>

<p>in our previous example, it would fail with a syntax error

at server startup. This is a bug (PR 46665 in the ASF bugzilla),

and the workaround is to reformulate the match:</p>

<highlight language="config">

ProxyPassMatch ^/(.*\.gif)$ http://backend.example.com:8000/$1

</highlight>

</note>

<p>The <code>!</code> directive is useful in situations where you don't want

to reverse-proxy a subdirectory.</p>

<p>When used inside a <directive type="section" module="core"

>LocationMatch</directive> section, the first argument is omitted and the

regexp is obtained from the <directive type="section" module="core"

>LocationMatch</directive>.</p>

<p>If you require a more flexible reverse-proxy configuration, see the

<directive module="mod_rewrite">RewriteRule</directive> directive with the

<code>[P]</code> flag.</p>

<note type="warning">

<title>Security Warning</title>

<p>Take care when constructing the target URL of the rule, considering

the security impact from allowing the client influence over the set of

URLs to which your server will act as a proxy. Ensure that the scheme

and hostname part of the URL is either fixed, or does not allow the

client undue influence.</p>

</note>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>ProxyPassReverse</name>

<description>Adjusts the URL in HTTP response headers sent from a reverse

proxied server</description>

<syntax>ProxyPassReverse [<var>path</var>] <var>url</var>

[<var>interpolate</var>]</syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context>

</contextlist>

<usage>

<p>This directive lets Apache httpd adjust the URL in the <code>Location</code>,

<code>Content-Location</code> and <code>URI</code> headers on HTTP

redirect responses. This is essential when Apache httpd is used as a

reverse proxy (or gateway) to avoid by-passing the reverse proxy

because of HTTP redirects on the backend servers which stay behind

the reverse proxy.</p>

<p>Only the HTTP response headers specifically mentioned above

will be rewritten. Apache httpd will not rewrite other response

headers, nor will it by default rewrite URL references inside HTML pages.

This means that if the proxied content contains absolute URL

references, they will by-pass the proxy. To rewrite HTML content to

match the proxy, you must load and enable <module>mod_proxy_html</module>.

</p>

<p><var>path</var> is the name of a local virtual path. <var>url</var> is a

partial URL for the remote server - the same way they are used for the

<directive module="mod_proxy">ProxyPass</directive> directive.</p>

<p>For example, suppose the local server has address

<code>http://example.com/</code>; then</p>

<highlight language="config">

ProxyPass /mirror/foo/ http://backend.example.com/

ProxyPassReverse /mirror/foo/ http://backend.example.com/

ProxyPassReverseCookieDomain backend.example.com public.example.com

ProxyPassReverseCookiePath / /mirror/foo/

</highlight>

<p>will not only cause a local request for the

<code>http://example.com/mirror/foo/bar</code> to be internally converted

into a proxy request to <code>http://backend.example.com/bar</code>

(the functionality <code>ProxyPass</code> provides here). It also takes care

of redirects the server <code>backend.example.com</code> sends: when

<code>http://backend.example.com/bar</code> is redirected by him to

<code>http://backend.example.com/quux</code> Apache httpd adjusts this to

<code>http://example.com/mirror/foo/quux</code> before forwarding the HTTP

redirect response to the client. Note that the hostname used for

constructing the URL is chosen in respect to the setting of the <directive

module="core">UseCanonicalName</directive> directive.</p>

<p>Note that this <directive>ProxyPassReverse</directive> directive can

also be used in conjunction with the proxy pass-through feature

(<code>RewriteRule ... [P]</code>) from <module>mod_rewrite</module>

because it doesn't depend on a corresponding <directive module="mod_proxy"

>ProxyPass</directive> directive.</p>

<p>The optional <var>interpolate</var> keyword (available in

httpd 2.2.9 and later), used together with

<directive>ProxyPassInterpolateEnv</directive>, enables interpolation

of environment variables specified using the format <var>${VARNAME}</var>.

</p>

<p>When used inside a <directive type="section" module="core"

>Location</directive> section, the first argument is omitted and the local

directory is obtained from the <directive type="section" module="core"

>Location</directive>. The same occurs inside a <directive type="section"

module="core">LocationMatch</directive> section, but will probably not work as

intended, as ProxyPassReverse will interpret the regexp literally as a

path; if needed in this situation, specify the ProxyPassReverse outside

the section, or in a separate <directive type="section" module="core"

>Location</directive> section.</p>

<p>This directive is not supported in <directive type="section" module="core"

>Directory</directive> or <directive type="section" module="core"

>Files</directive> sections.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>ProxyPassReverseCookieDomain</name>

<description>Adjusts the Domain string in Set-Cookie headers from a reverse-

proxied server</description>

<syntax>ProxyPassReverseCookieDomain <var>internal-domain</var>

<var>public-domain</var> [<var>interpolate</var>]</syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context>

</contextlist>

<usage>

<p>Usage is basically similar to

<directive module="mod_proxy">ProxyPassReverse</directive>, but instead of

rewriting headers that are a URL, this rewrites the <code>domain</code>

string in <code>Set-Cookie</code> headers.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>ProxyPassReverseCookiePath</name>

<description>Adjusts the Path string in Set-Cookie headers from a reverse-

proxied server</description>

<syntax>ProxyPassReverseCookiePath <var>internal-path</var>

<var>public-path</var> [<var>interpolate</var>]</syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context>

</contextlist>

<usage>

<p>

Useful in conjunction with

<directive module="mod_proxy">ProxyPassReverse</directive>

in situations where backend URL paths are mapped to public paths on the

reverse proxy. This directive rewrites the <code>path</code> string in

<code>Set-Cookie</code> headers. If the beginning of the cookie path matches

<var>internal-path</var>, the cookie path will be replaced with

<var>public-path</var>.

</p><p>

In the example given with

<directive module="mod_proxy">ProxyPassReverse</directive>, the directive:

</p>

<highlight language="config">

ProxyPassReverseCookiePath / /mirror/foo/

</highlight>

<p>