You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by dr...@apache.org on 2015/04/15 19:03:10 UTC
svn commit: r1673873 [13/18] - /httpd/httpd/branches/2.4.x/docs/manual/mod/
Modified: httpd/httpd/branches/2.4.x/docs/manual/mod/mod_proxy.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/mod/mod_proxy.html.en?rev=1673873&r1=1673872&r2=1673873&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/mod/mod_proxy.html.en (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/mod/mod_proxy.html.en Wed Apr 15 17:03:08 2015
@@ -84,7 +84,20 @@
<code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code>. These additional modules will need
to be loaded and configured to take advantage of these features.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#forwardreverse">Forward Proxies and Reverse
+ Proxies/Gateways</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#examples">Basic Examples</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#handler">Access via Handler</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#workers">Workers</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#access">Controlling access to your proxy</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#startup">Slow Startup</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#intranet">Intranet Proxy</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#envsettings">Protocol Adjustments</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#request-bodies">Request Bodies</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#x-headers">Reverse Proxy Request Headers</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#balancergrowth">BalancerGrowth</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#balancerinherit">BalancerInherit</a></li>
@@ -118,20 +131,7 @@
<li><img alt="" src="../images/down.gif" /> <a href="#proxytimeout">ProxyTimeout</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#proxyvia">ProxyVia</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#forwardreverse">Forward Proxies and Reverse
- Proxies/Gateways</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#examples">Basic Examples</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#handler">Access via Handler</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#workers">Workers</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#access">Controlling access to your proxy</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#startup">Slow Startup</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#intranet">Intranet Proxy</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#envsettings">Protocol Adjustments</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#request-bodies">Request Bodies</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#x-headers">Reverse Proxy Request Headers</a></li>
-</ul><h3>See also</h3>
+<h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code></li>
<li><code class="module"><a href="../mod/mod_proxy_ajp.html">mod_proxy_ajp</a></code></li>
@@ -145,1790 +145,1790 @@
<li><code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="BalancerGrowth" id="BalancerGrowth">BalancerGrowth</a> <a name="balancergrowth" id="balancergrowth">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of additional Balancers that can be added Post-configuration</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerGrowth <var>#</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BalancerGrowth 5</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerGrowth is only available in Apache HTTP Server 2.3.13
- and later.</td></tr>
-</table>
- <p>This directive allows for growth potential in the number of
- Balancers available for a virtualhost in addition to the
- number pre-configured. It only takes effect if there is at
- least 1 pre-configured Balancer.</p>
+<div class="section">
+<h2><a name="forwardreverse" id="forwardreverse">Forward Proxies and Reverse
+ Proxies/Gateways</a></h2>
+ <p>Apache HTTP Server can be configured in both a <dfn>forward</dfn> and
+ <dfn>reverse</dfn> proxy (also known as <dfn>gateway</dfn>) mode.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="BalancerInherit" id="BalancerInherit">BalancerInherit</a> <a name="balancerinherit" id="balancerinherit">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Inherit ProxyPassed Balancers/Workers from the main server</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerInherit On|Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BalancerInherit On</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerInherit is only available in Apache HTTP Server 2.4.5 and later.</td></tr>
-</table>
- <p>This directive will cause the current server/vhost to "inherit" ProxyPass
- Balancers and Workers defined in the main server. This can cause issues and
- inconsistent behavior if using the Balancer Manager and so should be disabled
- if using that feature.</p>
- <p>The setting in the global server defines the default for all vhosts.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="BalancerMember" id="BalancerMember">BalancerMember</a> <a name="balancermember" id="balancermember">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a member to a load balancing group</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerMember [<var>balancerurl</var>] <var>url</var> [<var>key=value [key=value ...]]</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerMember is only available in Apache HTTP Server 2.2
- and later.</td></tr>
-</table>
- <p>This directive adds a member to a load balancing group. It could be used
- within a <code><Proxy <var>balancer://</var>...></code> container
- directive, and can take any of the key value pair parameters available to
- <code class="directive"><a href="#proxypass">ProxyPass</a></code> directives.</p>
- <p>One additional parameter is available only to <code class="directive">BalancerMember</code> directives:
- <var>loadfactor</var>. This is the member load factor - a number between 1
- (default) and 100, which defines the weighted load to be applied to the
- member in question.</p>
- <p>The <var>balancerurl</var> is only needed when not in
- <code><Proxy <var>balancer://</var>...></code>
- container directive. It corresponds to the url of a balancer defined in
- <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p>
- <p>The path component of the balancer URL in any
- <code><Proxy <var>balancer://</var>...></code> container directive
- is ignored.</p>
- <p>Trailing slashes should typically be removed from the URL of a
- <code class="directive">BalancerMember</code>.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="BalancerPersist" id="BalancerPersist">BalancerPersist</a> <a name="balancerpersist" id="balancerpersist">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Attempt to persist changes made by the Balancer Manager across restarts.</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerPersist On|Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BalancerPersist Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerPersist is only available in Apache HTTP Server 2.4.4 and later.</td></tr>
-</table>
- <p>This directive will cause the shared memory storage associated
- with the balancers and balancer members to be persisted across
- restarts. This allows these local changes to not be lost during the
- normal restart/graceful state transitions.</p>
-
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="NoProxy" id="NoProxy">NoProxy</a> <a name="noproxy" id="noproxy">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Hosts, domains, or networks that will be connected to
-directly</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>NoProxy <var>host</var> [<var>host</var>] ...</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-</table>
- <p>This directive is only useful for Apache httpd proxy servers within
- intranets. The <code class="directive">NoProxy</code> directive specifies a
- list of subnets, IP addresses, hosts and/or domains, separated by
- spaces. A request to a host which matches one or more of these is
- always served directly, without forwarding to the configured
- <code class="directive"><a href="#proxyremote">ProxyRemote</a></code> proxy server(s).</p>
+ <p>An ordinary <dfn>forward proxy</dfn> is an intermediate
+ server that sits between the client and the <em>origin
+ server</em>. In order to get content from the origin server,
+ the client sends a request to the proxy naming the origin server
+ as the target and the proxy then requests the content from the
+ origin server and returns it to the client. The client must be
+ specially configured to use the forward proxy to access other
+ sites.</p>
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ProxyRemote "*" "http://firewall.example.com:81"
-NoProxy ".example.com" "192.168.112.0/21"</pre>
-</div>
+ <p>A typical usage of a forward proxy is to provide Internet
+ access to internal clients that are otherwise restricted by a
+ firewall. The forward proxy can also use caching (as provided
+ by <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code>) to reduce network usage.</p>
- <p>The <var>host</var> arguments to the <code class="directive">NoProxy</code>
- directive are one of the following type list:</p>
+ <p>The forward proxy is activated using the <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> directive. Because
+ forward proxies allow clients to access arbitrary sites through
+ your server and to hide their true origin, it is essential that
+ you <a href="#access">secure your server</a> so that only
+ authorized clients can access the proxy before activating a
+ forward proxy.</p>
- <dl>
-
- <dt><var><a name="domain" id="domain">Domain</a></var></dt>
- <dd>
- <p>A <dfn>Domain</dfn> is a partially qualified DNS domain name, preceded
- by a period. It represents a list of hosts which logically belong to the
- same DNS domain or zone (<em>i.e.</em>, the suffixes of the hostnames are
- all ending in <var>Domain</var>).</p>
+ <p>A <dfn>reverse proxy</dfn> (or <dfn>gateway</dfn>), by
+ contrast, appears to the client just like an ordinary web
+ server. No special configuration on the client is necessary.
+ The client makes ordinary requests for content in the name-space
+ of the reverse proxy. The reverse proxy then decides where to
+ send those requests, and returns the content as if it was itself
+ the origin.</p>
- <div class="example"><h3>Examples</h3><p><code>
- .com .example.org.
- </code></p></div>
+ <p>A typical usage of a reverse proxy is to provide Internet
+ users access to a server that is behind a firewall. Reverse
+ proxies can also be used to balance load among several back-end
+ servers, or to provide caching for a slower back-end server.
+ In addition, reverse proxies can be used simply to bring
+ several servers into the same URL space.</p>
- <p>To distinguish <var>Domain</var>s from <var><a href="#hostname">Hostname</a></var>s (both syntactically and semantically; a DNS domain can
- have a DNS A record, too!), <var>Domain</var>s are always written with a
- leading period.</p>
+ <p>A reverse proxy is activated using the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive or the
+ <code>[P]</code> flag to the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive. It is
+ <strong>not</strong> necessary to turn <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> on in order to
+ configure a reverse proxy.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="examples" id="examples">Basic Examples</a></h2>
- <div class="note"><h3>Note</h3>
- <p>Domain name comparisons are done without regard to the case, and
- <var>Domain</var>s are always assumed to be anchored in the root of the
- DNS tree, therefore two domains <code>.ExAmple.com</code> and
- <code>.example.com.</code> (note the trailing period) are considered
- equal. Since a domain comparison does not involve a DNS lookup, it is much
- more efficient than subnet comparison.</p>
- </div></dd>
+ <p>The examples below are only a very basic idea to help you
+ get started. Please read the documentation on the individual
+ directives.</p>
-
- <dt><var><a name="subnet" id="subnet">SubNet</a></var></dt>
- <dd>
- <p>A <dfn>SubNet</dfn> is a partially qualified internet address in
- numeric (dotted quad) form, optionally followed by a slash and the netmask,
- specified as the number of significant bits in the <var>SubNet</var>. It is
- used to represent a subnet of hosts which can be reached over a common
- network interface. In the absence of the explicit net mask it is assumed
- that omitted (or zero valued) trailing digits specify the mask. (In this
- case, the netmask can only be multiples of 8 bits wide.) Examples:</p>
+ <p>In addition, if you wish to have caching enabled, consult
+ the documentation from <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code>.</p>
- <dl>
- <dt><code>192.168</code> or <code>192.168.0.0</code></dt>
- <dd>the subnet 192.168.0.0 with an implied netmask of 16 valid bits
- (sometimes used in the netmask form <code>255.255.0.0</code>)</dd>
- <dt><code>192.168.112.0/21</code></dt>
- <dd>the subnet <code>192.168.112.0/21</code> with a netmask of 21
- valid bits (also used in the form <code>255.255.248.0</code>)</dd>
- </dl>
+ <div class="example"><h3>Reverse Proxy</h3><pre class="prettyprint lang-config">ProxyPass "/foo" "http://foo.example.com/bar"
+ProxyPassReverse "/foo" "http://foo.example.com/bar"</pre>
+</div>
- <p>As a degenerate case, a <em>SubNet</em> with 32 valid bits is the
- equivalent to an <var><a href="#ipaddr">IPAddr</a></var>, while a <var>SubNet</var> with zero
- valid bits (<em>e.g.</em>, 0.0.0.0/0) is the same as the constant
- <var>_Default_</var>, matching any IP address.</p></dd>
+ <div class="example"><h3>Forward Proxy</h3><pre class="prettyprint lang-config">ProxyRequests On
+ProxyVia On
-
- <dt><var><a name="ipaddr" id="ipaddr">IPAddr</a></var></dt>
- <dd>
- <p>A <dfn>IPAddr</dfn> represents a fully qualified internet address in
- numeric (dotted quad) form. Usually, this address represents a host, but
- there need not necessarily be a DNS domain name connected with the
- address.</p>
- <div class="example"><h3>Example</h3><p><code>
- 192.168.123.7
- </code></p></div>
+<Proxy "*">
+ Require host internal.example.com
+</Proxy></pre>
+</div>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="handler" id="handler">Access via Handler</a></h2>
- <div class="note"><h3>Note</h3>
- <p>An <var>IPAddr</var> does not need to be resolved by the DNS system, so
- it can result in more effective apache performance.</p>
- </div></dd>
+ <p>You can also force a request to be handled as a reverse-proxy
+ request, by creating a suitable Handler pass-through. The example
+ configuration below will pass all requests for PHP scripts to the
+ specified FastCGI server using reverse proxy:
+ </p>
-
- <dt><var><a name="hostname" id="hostname">Hostname</a></var></dt>
- <dd>
- <p>A <dfn>Hostname</dfn> is a fully qualified DNS domain name which can
- be resolved to one or more <var><a href="#ipaddr">IPAddrs</a></var> via the
- DNS domain name service. It represents a logical host (in contrast to
- <var><a href="#domain">Domain</a></var>s, see above) and must be resolvable
- to at least one <var><a href="#ipaddr">IPAddr</a></var> (or often to a list
- of hosts with different <var><a href="#ipaddr">IPAddr</a></var>s).</p>
+ <div class="example"><h3>Reverse Proxy PHP scripts</h3><pre class="prettyprint lang-config"><FilesMatch "\.php$">
+ # Unix sockets require 2.4.7 or later
+ SetHandler "proxy:unix:/path/to/app.sock|fcgi://localhost/"
+</FilesMatch></pre>
+</div>
- <div class="example"><h3>Examples</h3><p><code>
- prep.ai.example.edu<br />
- www.example.org
- </code></p></div>
+ <p>This feature is available in Apache HTTP Server 2.4.10 and later.</p>
- <div class="note"><h3>Note</h3>
- <p>In many situations, it is more effective to specify an <var><a href="#ipaddr">IPAddr</a></var> in place of a <var>Hostname</var> since a
- DNS lookup can be avoided. Name resolution in Apache httpd can take a remarkable
- deal of time when the connection to the name server uses a slow PPP
- link.</p>
- <p><var>Hostname</var> comparisons are done without regard to the case,
- and <var>Hostname</var>s are always assumed to be anchored in the root
- of the DNS tree, therefore two hosts <code>WWW.ExAmple.com</code>
- and <code>www.example.com.</code> (note the trailing period) are
- considered equal.</p>
- </div></dd>
- </dl>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="workers" id="workers">Workers</a></h2>
+ <p>The proxy manages the configuration of origin servers and their
+ communication parameters in objects called <dfn>workers</dfn>.
+ There are two built-in workers, the default forward proxy worker and the
+ default reverse proxy worker. Additional workers can be configured
+ explicitly.</p>
-<h3>See also</h3>
-<ul>
-<li><a href="../dns-caveats.html">DNS Issues</a></li>
-</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="Proxy" id="Proxy"><Proxy></a> <a name="proxy" id="proxy">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Container for directives applied to proxied resources</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><Proxy <var>wildcard-url</var>> ...</Proxy></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-</table>
- <p>Directives placed in <code class="directive"><Proxy></code>
- sections apply only to matching proxied content. Shell-style wildcards are
- allowed.</p>
+ <p>The two default workers have a fixed configuration
+ and will be used if no other worker matches the request.
+ They do not use HTTP Keep-Alive or connection pooling.
+ The TCP connections to the origin server will instead be
+ opened and closed for each request.</p>
- <p>For example, the following will allow only hosts in
- <code>yournetwork.example.com</code> to access content via your proxy
- server:</p>
+ <p>Explicitly configured workers are identified by their URL.
+ They are usually created and configured using
+ <code class="directive"><a href="#proxypass">ProxyPass</a></code> or
+ <code class="directive"><a href="#proxypassmatch">ProxyPassMatch</a></code> when used
+ for a reverse proxy:</p>
- <pre class="prettyprint lang-config"><Proxy "*">
- Require host yournetwork.example.com
-</Proxy></pre>
+ <pre class="prettyprint lang-config">ProxyPass "/example" "http://backend.example.com" connectiontimeout=5 timeout=30</pre>
- <p>The following example will process all files in the <code>foo</code>
- directory of <code>example.com</code> through the <code>INCLUDES</code>
- filter when they are sent through the proxy server:</p>
+ <p>This will create a worker associated with the origin server URL
+ <code>http://backend.example.com</code> and using the given timeout
+ values. When used in a forward proxy, workers are usually defined
+ via the <code class="directive"><a href="#proxyset">ProxySet</a></code> directive:</p>
- <pre class="prettyprint lang-config"><Proxy "http://example.com/foo/*">
- SetOutputFilter INCLUDES
+ <pre class="prettyprint lang-config">ProxySet "http://backend.example.com" connectiontimeout=5 timeout=30</pre>
+
+
+ <p>or alternatively using <code class="directive"><a href="#proxy">Proxy</a></code>
+ and <code class="directive"><a href="#proxyset">ProxySet</a></code>:</p>
+
+ <pre class="prettyprint lang-config"><Proxy "http://backend.example.com">
+ ProxySet connectiontimeout=5 timeout=30
</Proxy></pre>
- <div class="note"><h3>Differences from the Location configuration section</h3>
- <p>A backend URL matches the configuration section if it begins with the
- the <var>wildcard-url</var> string, even if the last path segment in the
- directive only matches a prefix of the backend URL. For example,
- <Proxy "http://example.com/foo"> matches all of
- http://example.com/foo, http://example.com/foo/bar, and
- http://example.com/foobar. The matching of the final URL differs
- from the behavior of the <code class="directive"><a href="../mod/core.html#location"><Location></a></code> section, which for purposes of this note
- treats the final path component as if it ended in a slash.</p>
- <p>For more control over the matching, see <code class="directive"><ProxyMatch></code>.</p>
- </div>
+ <p>Using explicitly configured workers in the forward mode is
+ not very common, because forward proxies usually communicate with many
+ different origin servers. Creating explicit workers for some of the
+ origin servers can still be useful, if they are used very often.
+ Explicitly configured workers have no concept of forward or reverse
+ proxying by themselves. They encapsulate a common concept of
+ communication with origin servers. A worker created by
+ <code class="directive"><a href="#proxypass">ProxyPass</a></code> for use in a
+ reverse proxy will be also used for forward proxy requests whenever
+ the URL to the origin server matches the worker URL and vice versa.</p>
+ <p>The URL identifying a direct worker is the URL of its
+ origin server including any path components given:</p>
-<h3>See also</h3>
-<ul>
-<li><code class="directive"><a href="#proxymatch"><ProxyMatch></a></code></li>
-</ul>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyAddHeaders" id="ProxyAddHeaders">ProxyAddHeaders</a> <a name="proxyaddheaders" id="proxyaddheaders">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add proxy information in X-Forwarded-* headers</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyAddHeaders Off|On</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyAddHeaders On</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.10 and later</td></tr>
-</table>
- <p>This directive determines whether or not proxy related information should be passed to the
- backend server through X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Server HTTP headers.</p>
- <div class="note"><h3>Effectiveness</h3>
- <p>This option is of use only for HTTP proxying, as handled by <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code>.</p>
- </div>
+ <pre class="prettyprint lang-config">ProxyPass "/examples" "http://backend.example.com/examples"
+ProxyPass "/docs" "http://backend.example.com/docs"</pre>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyBadHeader" id="ProxyBadHeader">ProxyBadHeader</a> <a name="proxybadheader" id="proxybadheader">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines how to handle bad header lines in a
-response</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyBadHeader IsError|Ignore|StartBody</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyBadHeader IsError</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-</table>
- <p>The <code class="directive">ProxyBadHeader</code> directive determines the
- behaviour of <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> if it receives syntactically invalid
- response header lines (<em>i.e.</em> containing no colon) from the origin
- server. The following arguments are possible:</p>
- <dl>
- <dt><code>IsError</code></dt>
- <dd>Abort the request and end up with a 502 (Bad Gateway) response. This is
- the default behaviour.</dd>
+ <p>This example defines two different workers, each using a separate
+ connection pool and configuration.</p>
- <dt><code>Ignore</code></dt>
- <dd>Treat bad header lines as if they weren't sent.</dd>
+ <div class="warning"><h3>Worker Sharing</h3>
+ <p>Worker sharing happens if the worker URLs overlap, which occurs when
+ the URL of some worker is a leading substring of the URL of another
+ worker defined later in the configuration file. In the following example</p>
- <dt><code>StartBody</code></dt>
- <dd>When receiving the first bad header line, finish reading the headers and
- treat the remainder as body. This helps to work around buggy backend servers
- which forget to insert an empty line between the headers and the body.</dd>
- </dl>
+ <pre class="prettyprint lang-config">ProxyPass "/apps" "http://backend.example.com/" timeout=60
+ProxyPass "/examples" "http://backend.example.com/examples" timeout=10</pre>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyBlock" id="ProxyBlock">ProxyBlock</a> <a name="proxyblock" id="proxyblock">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Words, hosts, or domains that are banned from being
-proxied</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyBlock *|<var>word</var>|<var>host</var>|<var>domain</var>
-[<var>word</var>|<var>host</var>|<var>domain</var>] ...</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-</table>
- <p>The <code class="directive">ProxyBlock</code> directive specifies a list of
- words, hosts and/or domains, separated by spaces. HTTP, HTTPS, and
- FTP document requests to sites whose names contain matched words,
- hosts or domains are <em>blocked</em> by the proxy server. The proxy
- module will also attempt to determine IP addresses of list items which
- may be hostnames during startup, and cache them for match test as
- well. That may slow down the startup time of the server.</p>
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ProxyBlock "news.example.com" "auctions.example.com" "friends.example.com"</pre>
-</div>
+ <p>the second worker isn't actually created. Instead the first
+ worker is used. The benefit is, that there is only one connection pool,
+ so connections are more often reused. Note that all configuration attributes
+ given explicitly for the later worker will be ignored. This will be logged
+ as a warning. In the above example the resulting timeout value
+ for the URL <code>/examples</code> will be <code>60</code> instead
+ of <code>10</code>!</p>
- <p>Note that <code>example</code> would also be sufficient to match any
- of these sites.</p>
+ <p>If you want to avoid worker sharing, sort your worker definitions
+ by URL length, starting with the longest worker URLs. If you want to maximize
+ worker sharing use the reverse sort order. See also the related warning about
+ ordering <code class="directive"><a href="#proxypass">ProxyPass</a></code> directives.</p>
- <p>Hosts would also be matched if referenced by IP address.</p>
+ </div>
- <p>Note also that</p>
+ <p>Explicitly configured workers come in two flavors:
+ <dfn>direct workers</dfn> and <dfn>(load) balancer workers</dfn>.
+ They support many important configuration attributes which are
+ described below in the <code class="directive"><a href="#proxypass">ProxyPass</a></code>
+ directive. The same attributes can also be set using
+ <code class="directive"><a href="#proxyset">ProxySet</a></code>.</p>
- <pre class="prettyprint lang-config">ProxyBlock "*"</pre>
+ <p>The set of options available for a direct worker
+ depends on the protocol, which is specified in the origin server URL.
+ Available protocols include <code>ajp</code>, <code>fcgi</code>,
+ <code>ftp</code>, <code>http</code> and <code>scgi</code>.</p>
+ <p>Balancer workers are virtual workers that use direct workers known
+ as their members to actually handle the requests. Each balancer can
+ have multiple members. When it handles a request, it chooses a member
+ based on the configured load balancing algorithm.</p>
- <p>blocks connections to all sites.</p>
+ <p>A balancer worker is created if its worker URL uses
+ <code>balancer</code> as the protocol scheme.
+ The balancer URL uniquely identifies the balancer worker.
+ Members are added to a balancer using
+ <code class="directive"><a href="#balancermember">BalancerMember</a></code>.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyDomain" id="ProxyDomain">ProxyDomain</a> <a name="proxydomain" id="proxydomain">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Default domain name for proxied requests</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyDomain <var>Domain</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-</table>
- <p>This directive is only useful for Apache httpd proxy servers within
- intranets. The <code class="directive">ProxyDomain</code> directive specifies
- the default domain which the apache proxy server will belong to. If a
- request to a host without a domain name is encountered, a redirection
- response to the same host with the configured <var>Domain</var> appended
- will be generated.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="access" id="access">Controlling access to your proxy</a></h2>
+ <p>You can control who can access your proxy via the <code class="directive"><a href="#proxy"><Proxy></a></code> control block as in
+ the following example:</p>
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config"> ProxyRemote "*" "http://firewall.example.com:81"<br />
- NoProxy ".example.com" "192.168.112.0/21"<br />
- ProxyDomain ".example.com"</pre>
-</div>
+ <pre class="prettyprint lang-config"><Proxy "*">
+ Require ip 192.168.0
+</Proxy></pre>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyErrorOverride" id="ProxyErrorOverride">ProxyErrorOverride</a> <a name="proxyerroroverride" id="proxyerroroverride">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Override error pages for proxied content</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyErrorOverride On|Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyErrorOverride Off</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-</table>
- <p>This directive is useful for reverse-proxy setups, where you want to
- have a common look and feel on the error pages seen by the end user.
- This also allows for included files (via
- <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>'s SSI) to get
- the error code and act accordingly (default behavior would display
- the error page of the proxied server, turning this on shows the SSI
- Error message).</p>
- <p>This directive does not affect the processing of informational (1xx),
- normal success (2xx), or redirect (3xx) responses.</p>
+ <p>For more information on access control directives, see
+ <code class="module"><a href="../mod/mod_authz_host.html">mod_authz_host</a></code>.</p>
-</div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyIOBufferSize" id="ProxyIOBufferSize">ProxyIOBufferSize</a> <a name="proxyiobuffersize" id="proxyiobuffersize">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determine size of internal data throughput buffer</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyIOBufferSize <var>bytes</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyIOBufferSize 8192</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
-<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
-<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-</table>
- <p>The <code class="directive">ProxyIOBufferSize</code> directive adjusts the size
- of the internal buffer, which is used as a scratchpad for the data between
- input and output. The size must be at least <code>512</code>.</p>
+ <p>Strictly limiting access is essential if you are using a
+ forward proxy (using the <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> directive).
+ Otherwise, your server can be used by any client to access
+ arbitrary hosts while hiding his or her true identity. This is
+ dangerous both for your network and for the Internet at large.
+ When using a reverse proxy (using the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive with
+ <code>ProxyRequests Off</code>), access control is less
+ critical because clients can only contact the hosts that you
+ have specifically configured.</p>
- <p>In almost every case there's no reason to change that value.</p>
+ <p><strong>See Also</strong> the <a href="mod_proxy_http.html#env">Proxy-Chain-Auth</a> environment variable.</p>
- <p>If used with AJP this directive sets the maximum AJP packet size in
- bytes. Values larger than 65536 are set to 65536. If you change it from
- the default, you must also change the <code>packetSize</code> attribute of
- your AJP connector on the Tomcat side! The attribute
- <code>packetSize</code> is only available in Tomcat <code>5.5.20+</code>
- and <code>6.0.2+</code></p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="startup" id="startup">Slow Startup</a></h2>
+ <p>If you're using the <code class="directive"><a href="#proxyblock">ProxyBlock</a></code> directive, hostnames' IP addresses are looked up
+ and cached during startup for later match test. This may take a few
+ seconds (or more) depending on the speed with which the hostname lookups
+ occur.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="intranet" id="intranet">Intranet Proxy</a></h2>
+ <p>An Apache httpd proxy server situated in an intranet needs to forward
+ external requests through the company's firewall (for this, configure
+ the <code class="directive"><a href="#proxyremote">ProxyRemote</a></code> directive
+ to forward the respective <var>scheme</var> to the firewall proxy).
+ However, when it has to
+ access resources within the intranet, it can bypass the firewall when
+ accessing hosts. The <code class="directive"><a href="#noproxy">NoProxy</a></code>
+ directive is useful for specifying which hosts belong to the intranet and
+ should be accessed directly.</p>
- <p>Normally it is not necessary to change the maximum packet size.
- Problems with the default value have been reported when sending
- certificates or certificate chains.</p>
+ <p>Users within an intranet tend to omit the local domain name from their
+ WWW requests, thus requesting "http://somehost/" instead of
+ <code>http://somehost.example.com/</code>. Some commercial proxy servers
+ let them get away with this and simply serve the request, implying a
+ configured local domain. When the <code class="directive"><a href="#proxydomain">ProxyDomain</a></code> directive is used and the server is <a href="#proxyrequests">configured for proxy service</a>, Apache httpd can return
+ a redirect response and send the client to the correct, fully qualified,
+ server address. This is the preferred method since the user's bookmark
+ files will then contain fully qualified hosts.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="envsettings" id="envsettings">Protocol Adjustments</a></h2>
+ <p>For circumstances where <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> is sending
+ requests to an origin server that doesn't properly implement
+ keepalives or HTTP/1.1, there are two <a href="../env.html">environment variables</a> that can force the
+ request to use HTTP/1.0 with no keepalive. These are set via the
+ <code class="directive"><a href="../mod/mod_env.html#setenv">SetEnv</a></code> directive.</p>
+
+ <p>These are the <code>force-proxy-request-1.0</code> and
+ <code>proxy-nokeepalive</code> notes.</p>
+
+ <pre class="prettyprint lang-config"><Location "/buggyappserver/">
+ ProxyPass "http://buggyappserver:7001/foo/"
+ SetEnv force-proxy-request-1.0 1
+ SetEnv proxy-nokeepalive 1
+</Location></pre>
-</div>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="request-bodies" id="request-bodies">Request Bodies</a></h2>
+
+ <p>Some request methods such as POST include a request body.
+ The HTTP protocol requires that requests which include a body
+ either use chunked transfer encoding or send a
+ <code>Content-Length</code> request header. When passing these
+ requests on to the origin server, <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code>
+ will always attempt to send the <code>Content-Length</code>. But
+ if the body is large and the original request used chunked
+ encoding, then chunked encoding may also be used in the upstream
+ request. You can control this selection using <a href="../env.html">environment variables</a>. Setting
+ <code>proxy-sendcl</code> ensures maximum compatibility with
+ upstream servers by always sending the
+ <code>Content-Length</code>, while setting
+ <code>proxy-sendchunked</code> minimizes resource usage by using
+ chunked encoding.</p>
+
+ <p>Under some circumstances, the server must spool request bodies
+ to disk to satisfy the requested handling of request bodies. For
+ example, this spooling will occur if the original body was sent with
+ chunked encoding (and is large), but the administrator has
+ asked for backend requests to be sent with Content-Length or as HTTP/1.0.
+ This spooling can also occur if the request body already has a
+ Content-Length header, but the server is configured to filter incoming
+ request bodies.</p>
+
+ <p><code class="directive"><a href="../mod/core.html#limitrequestbody">LimitRequestBody</a></code> only applies to
+ request bodies that the server will spool to disk</p>
+
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="x-headers" id="x-headers">Reverse Proxy Request Headers</a></h2>
+
+ <p>When acting in a reverse-proxy mode (using the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive, for example),
+ <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code> adds several request headers in
+ order to pass information to the origin server. These headers
+ are:</p>
+
+ <dl>
+ <dt><code>X-Forwarded-For</code></dt>
+ <dd>The IP address of the client.</dd>
+ <dt><code>X-Forwarded-Host</code></dt>
+ <dd>The original host requested by the client in the <code>Host</code>
+ HTTP request header.</dd>
+ <dt><code>X-Forwarded-Server</code></dt>
+ <dd>The hostname of the proxy server.</dd>
+ </dl>
+
+ <p>Be careful when using these headers on the origin server, since
+ they will contain more than one (comma-separated) value if the
+ original request already contained one of these headers. For
+ example, you can use <code>%{X-Forwarded-For}i</code> in the log
+ format string of the origin server to log the original clients IP
+ address, but you may get more than one address if the request
+ passes through several proxies.</p>
+
+ <p>See also the <code class="directive"><a href="#proxypreservehost">ProxyPreserveHost</a></code> and <code class="directive"><a href="#proxyvia">ProxyVia</a></code> directives, which control
+ other request headers.</p>
+
+ <p>Note: If you need to specify custom request headers to be
+ added to the forwarded request, use the
+ <code class="directive"><a href="../mod/mod_headers.html#requestheader">RequestHeader</a></code>
+ directive.</p>
+
+ </div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyMatch" id="ProxyMatch"><ProxyMatch></a> <a name="proxymatch" id="proxymatch">Directive</a></h2>
+<div class="directive-section"><h2><a name="BalancerGrowth" id="BalancerGrowth">BalancerGrowth</a> <a name="balancergrowth" id="balancergrowth">Directive</a></h2>
<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Container for directives applied to regular-expression-matched
-proxied resources</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><ProxyMatch <var>regex</var>> ...</ProxyMatch></code></td></tr>
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of additional Balancers that can be added Post-configuration</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerGrowth <var>#</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BalancerGrowth 5</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerGrowth is only available in Apache HTTP Server 2.3.13
+ and later.</td></tr>
</table>
- <p>The <code class="directive"><ProxyMatch></code> directive is
- identical to the <code class="directive"><a href="#proxy"><Proxy></a></code> directive, except it matches URLs
- using <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expressions</a>.</p>
-
- <p>From 2.4.8 onwards, named groups and backreferences are captured and
- written to the environment with the corresponding name prefixed with
- "MATCH_" and in upper case. This allows elements of URLs to be referenced
- from within <a href="../expr.html">expressions</a> and modules like
- <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. In order to prevent confusion, numbered
- (unnamed) backreferences are ignored. Use named groups instead.</p>
-
-<pre class="prettyprint lang-config"><ProxyMatch "^http://(?<sitename>[^/]+)">
- Require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example
-</ProxyMatch></pre>
-
+ <p>This directive allows for growth potential in the number of
+ Balancers available for a virtualhost in addition to the
+ number pre-configured. It only takes effect if there is at
+ least 1 pre-configured Balancer.</p>
-<h3>See also</h3>
-<ul>
-<li><code class="directive"><a href="#proxy"><Proxy></a></code></li>
-</ul>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyMaxForwards" id="ProxyMaxForwards">ProxyMaxForwards</a> <a name="proxymaxforwards" id="proxymaxforwards">Directive</a></h2>
+<div class="directive-section"><h2><a name="BalancerInherit" id="BalancerInherit">BalancerInherit</a> <a name="balancerinherit" id="balancerinherit">Directive</a></h2>
<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximium number of proxies that a request can be forwarded
-through</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyMaxForwards <var>number</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyMaxForwards -1</code></td></tr>
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Inherit ProxyPassed Balancers/Workers from the main server</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerInherit On|Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BalancerInherit On</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Default behaviour changed in 2.2.7</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerInherit is only available in Apache HTTP Server 2.4.5 and later.</td></tr>
</table>
- <p>The <code class="directive">ProxyMaxForwards</code> directive specifies the
- maximum number of proxies through which a request may pass, if there's no
- <code>Max-Forwards</code> header supplied with the request. This may
- be set to prevent infinite proxy loops, or a DoS attack.</p>
-
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ProxyMaxForwards 15</pre>
-</div>
-
- <p>Note that setting <code class="directive">ProxyMaxForwards</code> is a
- violation of the HTTP/1.1 protocol (RFC2616), which forbids a Proxy
- setting <code>Max-Forwards</code> if the Client didn't set it.
- Earlier Apache httpd versions would always set it. A negative
- <code class="directive">ProxyMaxForwards</code> value, including the
- default -1, gives you protocol-compliant behaviour, but may
- leave you open to loops.</p>
-
+ <p>This directive will cause the current server/vhost to "inherit" ProxyPass
+ Balancers and Workers defined in the main server. This can cause issues and
+ inconsistent behavior if using the Balancer Manager and so should be disabled
+ if using that feature.</p>
+ <p>The setting in the global server defines the default for all vhosts.</p>
+
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="ProxyPass" id="ProxyPass">ProxyPass</a> <a name="proxypass" id="proxypass">Directive</a></h2>
+<div class="directive-section"><h2><a name="BalancerMember" id="BalancerMember">BalancerMember</a> <a name="balancermember" id="balancermember">Directive</a></h2>
<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maps remote servers into the local server URL-space</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPass [<var>path</var>] !|<var>url</var> [<var>key=value</var>
- <var>[key=value</var> ...]] [nocanon] [interpolate] [noquery]</code></td></tr>
-<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a member to a load balancing group</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerMember [<var>balancerurl</var>] <var>url</var> [<var>key=value [key=value ...]]</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Unix Domain Socket (UDS) support added in 2.4.7</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerMember is only available in Apache HTTP Server 2.2
+ and later.</td></tr>
</table>
- <p>This directive allows remote servers to be mapped into the
- space of the local server; the local server does not act as a
- proxy in the conventional sense, but appears to be a mirror of the
- remote server. The local server is often called a <dfn>reverse
- proxy</dfn> or <dfn>gateway</dfn>. The <var>path</var> is the name of
- a local virtual path; <var>url</var> is a partial URL for the
- remote server and cannot include a query string.</p>
-
- <div class="note"><strong>Note: </strong>This directive cannot be used within a
- <code><Directory></code> context.</div>
-
- <div class="warning">The <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> directive should
- usually be set <strong>off</strong> when using
- <code class="directive">ProxyPass</code>.</div>
-
- <p>In 2.4.7 and later, support for using a Unix Domain Socket is available by using a target
- which prepends <code>unix:/path/lis.sock|</code>. For example, to proxy
- HTTP and target the UDS at /home/www/socket you would use
- <code>unix:/home/www.socket|http://localhost/whatever/</code>.</p>
+ <p>This directive adds a member to a load balancing group. It could be used
+ within a <code><Proxy <var>balancer://</var>...></code> container
+ directive, and can take any of the key value pair parameters available to
+ <code class="directive"><a href="#proxypass">ProxyPass</a></code> directives.</p>
+ <p>One additional parameter is available only to <code class="directive">BalancerMember</code> directives:
+ <var>loadfactor</var>. This is the member load factor - a number between 1
+ (default) and 100, which defines the weighted load to be applied to the
+ member in question.</p>
+ <p>The <var>balancerurl</var> is only needed when not in
+ <code><Proxy <var>balancer://</var>...></code>
+ container directive. It corresponds to the url of a balancer defined in
+ <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p>
+ <p>The path component of the balancer URL in any
+ <code><Proxy <var>balancer://</var>...></code> container directive
+ is ignored.</p>
+ <p>Trailing slashes should typically be removed from the URL of a
+ <code class="directive">BalancerMember</code>.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="BalancerPersist" id="BalancerPersist">BalancerPersist</a> <a name="balancerpersist" id="balancerpersist">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Attempt to persist changes made by the Balancer Manager across restarts.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerPersist On|Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BalancerPersist Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerPersist is only available in Apache HTTP Server 2.4.4 and later.</td></tr>
+</table>
+ <p>This directive will cause the shared memory storage associated
+ with the balancers and balancer members to be persisted across
+ restarts. This allows these local changes to not be lost during the
+ normal restart/graceful state transitions.</p>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="NoProxy" id="NoProxy">NoProxy</a> <a name="noproxy" id="noproxy">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Hosts, domains, or networks that will be connected to
+directly</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>NoProxy <var>host</var> [<var>host</var>] ...</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+</table>
+ <p>This directive is only useful for Apache httpd proxy servers within
+ intranets. The <code class="directive">NoProxy</code> directive specifies a
+ list of subnets, IP addresses, hosts and/or domains, separated by
+ spaces. A request to a host which matches one or more of these is
+ always served directly, without forwarding to the configured
+ <code class="directive"><a href="#proxyremote">ProxyRemote</a></code> proxy server(s).</p>
- <div class="note"><strong>Note:</strong> The path associated with the <code>unix:</code>
- URL is <code class="directive">DefaultRuntimeDir</code> aware.</div>
+ <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ProxyRemote "*" "http://firewall.example.com:81"
+NoProxy ".example.com" "192.168.112.0/21"</pre>
+</div>
- <p>Suppose the local server has address <code>http://example.com/</code>;
- then</p>
+ <p>The <var>host</var> arguments to the <code class="directive">NoProxy</code>
+ directive are one of the following type list:</p>
- <pre class="prettyprint lang-config"><Location "/mirror/foo/">
- ProxyPass "http://backend.example.com/"
-</Location></pre>
+ <dl>
+
+ <dt><var><a name="domain" id="domain">Domain</a></var></dt>
+ <dd>
+ <p>A <dfn>Domain</dfn> is a partially qualified DNS domain name, preceded
+ by a period. It represents a list of hosts which logically belong to the
+ same DNS domain or zone (<em>i.e.</em>, the suffixes of the hostnames are
+ all ending in <var>Domain</var>).</p>
+ <div class="example"><h3>Examples</h3><p><code>
+ .com .example.org.
+ </code></p></div>
- <p>will cause a local request for
- <code>http://example.com/mirror/foo/bar</code> to be internally converted
- into a proxy request to <code>http://backend.example.com/bar</code>.</p>
+ <p>To distinguish <var>Domain</var>s from <var><a href="#hostname">Hostname</a></var>s (both syntactically and semantically; a DNS domain can
+ have a DNS A record, too!), <var>Domain</var>s are always written with a
+ leading period.</p>
- <p>The following alternative syntax is possible, however it can carry a
- performance penalty when present in very large numbers. The advantage of
- the below syntax is that it allows for dynamic control via the
- <a href="mod_proxy_balancer.html#balancer_manager">Balancer Manager</a> interface:</p>
+ <div class="note"><h3>Note</h3>
+ <p>Domain name comparisons are done without regard to the case, and
+ <var>Domain</var>s are always assumed to be anchored in the root of the
+ DNS tree, therefore two domains <code>.ExAmple.com</code> and
+ <code>.example.com.</code> (note the trailing period) are considered
+ equal. Since a domain comparison does not involve a DNS lookup, it is much
+ more efficient than subnet comparison.</p>
+ </div></dd>
- <pre class="prettyprint lang-config">ProxyPass "/mirror/foo/" "http://backend.example.com/"</pre>
+
+ <dt><var><a name="subnet" id="subnet">SubNet</a></var></dt>
+ <dd>
+ <p>A <dfn>SubNet</dfn> is a partially qualified internet address in
+ numeric (dotted quad) form, optionally followed by a slash and the netmask,
+ specified as the number of significant bits in the <var>SubNet</var>. It is
+ used to represent a subnet of hosts which can be reached over a common
+ network interface. In the absence of the explicit net mask it is assumed
+ that omitted (or zero valued) trailing digits specify the mask. (In this
+ case, the netmask can only be multiples of 8 bits wide.) Examples:</p>
+ <dl>
+ <dt><code>192.168</code> or <code>192.168.0.0</code></dt>
+ <dd>the subnet 192.168.0.0 with an implied netmask of 16 valid bits
+ (sometimes used in the netmask form <code>255.255.0.0</code>)</dd>
+ <dt><code>192.168.112.0/21</code></dt>
+ <dd>the subnet <code>192.168.112.0/21</code> with a netmask of 21
+ valid bits (also used in the form <code>255.255.248.0</code>)</dd>
+ </dl>
- <div class="warning">
- <p>If the first argument ends with a trailing <strong>/</strong>, the second
- argument should also end with a trailing <strong>/</strong> and vice
- versa. Otherwise the resulting requests to the backend may miss some
- needed slashes and do not deliver the expected results.
- </p>
- </div>
+ <p>As a degenerate case, a <em>SubNet</em> with 32 valid bits is the
+ equivalent to an <var><a href="#ipaddr">IPAddr</a></var>, while a <var>SubNet</var> with zero
+ valid bits (<em>e.g.</em>, 0.0.0.0/0) is the same as the constant
+ <var>_Default_</var>, matching any IP address.</p></dd>
- <p>The <code>!</code> directive is useful in situations where you don't want
- to reverse-proxy a subdirectory, <em>e.g.</em></p>
+
+ <dt><var><a name="ipaddr" id="ipaddr">IPAddr</a></var></dt>
+ <dd>
+ <p>A <dfn>IPAddr</dfn> represents a fully qualified internet address in
+ numeric (dotted quad) form. Usually, this address represents a host, but
+ there need not necessarily be a DNS domain name connected with the
+ address.</p>
+ <div class="example"><h3>Example</h3><p><code>
+ 192.168.123.7
+ </code></p></div>
- <pre class="prettyprint lang-config"><Location "/mirror/foo/">
- ProxyPass "http://backend.example.com/"
-</Location>
-<Location "/mirror/foo/i">
- ProxyPass "!"
-</Location></pre>
+ <div class="note"><h3>Note</h3>
+ <p>An <var>IPAddr</var> does not need to be resolved by the DNS system, so
+ it can result in more effective apache performance.</p>
+ </div></dd>
+
+ <dt><var><a name="hostname" id="hostname">Hostname</a></var></dt>
+ <dd>
+ <p>A <dfn>Hostname</dfn> is a fully qualified DNS domain name which can
+ be resolved to one or more <var><a href="#ipaddr">IPAddrs</a></var> via the
+ DNS domain name service. It represents a logical host (in contrast to
+ <var><a href="#domain">Domain</a></var>s, see above) and must be resolvable
+ to at least one <var><a href="#ipaddr">IPAddr</a></var> (or often to a list
+ of hosts with different <var><a href="#ipaddr">IPAddr</a></var>s).</p>
- <pre class="prettyprint lang-config">ProxyPass "/mirror/foo/i" "!"
-ProxyPass "/mirror/foo" "http://backend.example.com"</pre>
+ <div class="example"><h3>Examples</h3><p><code>
+ prep.ai.example.edu<br />
+ www.example.org
+ </code></p></div>
+ <div class="note"><h3>Note</h3>
+ <p>In many situations, it is more effective to specify an <var><a href="#ipaddr">IPAddr</a></var> in place of a <var>Hostname</var> since a
+ DNS lookup can be avoided. Name resolution in Apache httpd can take a remarkable
+ deal of time when the connection to the name server uses a slow PPP
+ link.</p>
+ <p><var>Hostname</var> comparisons are done without regard to the case,
+ and <var>Hostname</var>s are always assumed to be anchored in the root
+ of the DNS tree, therefore two hosts <code>WWW.ExAmple.com</code>
+ and <code>www.example.com.</code> (note the trailing period) are
+ considered equal.</p>
+ </div></dd>
+ </dl>
- <p>will proxy all requests to <code>/mirror/foo</code> to
- <code>backend.example.com</code> <em>except</em> requests made to
- <code>/mirror/foo/i</code>.</p>
+<h3>See also</h3>
+<ul>
+<li><a href="../dns-caveats.html">DNS Issues</a></li>
+</ul>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="Proxy" id="Proxy"><Proxy></a> <a name="proxy" id="proxy">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Container for directives applied to proxied resources</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><Proxy <var>wildcard-url</var>> ...</Proxy></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
+</table>
+ <p>Directives placed in <code class="directive"><Proxy></code>
+ sections apply only to matching proxied content. Shell-style wildcards are
+ allowed.</p>
- <div class="warning"><h3>Ordering ProxyPass Directives</h3>
- <p>The configured <code class="directive"><a href="#proxypass">ProxyPass</a></code>
- and <code class="directive"><a href="#proxypassmatch">ProxyPassMatch</a></code>
- rules are checked in the order of configuration. The first rule that
- matches wins. So usually you should sort conflicting
- <code class="directive"><a href="#proxypass">ProxyPass</a></code> 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
- <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive can be placed
- in a <code class="directive"><a href="../mod/core.html#location">Location</a></code> block, and the most
- specific location will take precedence.</p>
+ <p>For example, the following will allow only hosts in
+ <code>yournetwork.example.com</code> to access content via your proxy
+ server:</p>
- <p>For the same reasons exclusions must come <em>before</em> the
- general <code class="directive">ProxyPass</code> directives.</p>
+ <pre class="prettyprint lang-config"><Proxy "*">
+ Require host yournetwork.example.com
+</Proxy></pre>
- </div>
- <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 <code class="directive">ProxyPass</code> directive
- using <code>key=value</code> parameters, described in the table
- below.</p>
+ <p>The following example will process all files in the <code>foo</code>
+ directory of <code>example.com</code> through the <code>INCLUDES</code>
+ filter when they are sent through the proxy server:</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>
+ <pre class="prettyprint lang-config"><Proxy "http://example.com/foo/*">
+ SetOutputFilter INCLUDES
+</Proxy></pre>
- <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>
- <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">ProxyPass "/example" "http://backend.example.com" max=20 ttl=120 retry=300</pre>
-</div>
-
- <table class="bordered"><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
- <code class="directive">ThreadsPerChild</code> 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>enablereuse</td>
- <td>On</td>
- <td>This is the inverse of 'disablereuse' above, provided as a
- convenience for scheme handlers that require opt-in for connection
- reuse (such as <code class="module"><a href="../mod/mod_proxy_fcgi.html">mod_proxy_fcgi</a></code>). 2.4.11 and later only.
- </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 <code class="directive">ProxyIOBufferSize</code> 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
- <code class="module"><a href="../mod/mod_proxy_ajp.html">mod_proxy_ajp</a></code>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 <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code>
- 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
- <code class="directive">ProxyReceiveBufferSize</code> 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><code class="directive"><a href="#proxytimeout">ProxyTimeout</a></code></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 <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code>
- for more information about how the balancer works.
- </p>
- <table class="bordered"><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.<br />
- Available in Apache HTTP Server 2.4.4 and later.
- </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 delimiter/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.<br />
- Available in Apache HTTP Server 2.4.5 and later.
- </td></tr>
- <tr><td>nonce</td>
- <td><auto></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.
- <div class="note"><h3>Note</h3>
- <p>In addition to the nonce, the <code>balancer-manager</code> page
- should be protected via an ACL.</p>
- </div>
- </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>.<br />
- Available in Apache HTTP Server 2.4.2 and later.
- </td></tr>
-
- </table>
- <p>A sample balancer setup</p>
- <pre class="prettyprint lang-config">ProxyPass "/special-area" "http://special.example.com" smax=5 max=10
-ProxyPass "/" "balancer://mycluster/" stickysession=JSESSIONID|jsessionid nofailover=On
-<Proxy "balancer://mycluster">
- 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
-</Proxy></pre>
-
-
- <p>Setting up a hot-standby, that will only be used if no other
- members are available</p>
- <pre class="prettyprint lang-config">ProxyPass "/" "balancer://hotcluster/"
-<Proxy "balancer://hotcluster">
- 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
-</Proxy></pre>
-
-
- <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>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 <code class="directive"><a href="../mod/core.html#location"><Location></a></code> section, the first argument is omitted and the local
- directory is obtained from the <code class="directive"><a href="../mod/core.html#location"><Location></a></code>. The same will occur inside a
- <code class="directive"><a href="../mod/core.html#locationmatch"><LocationMatch></a></code> section,
- however ProxyPass does not interpret the regexp as such, so it is necessary
- to use <code class="directive">ProxyPassMatch</code> in this situation instead.</p>
-
- <p>This directive is not supported in <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> or <code class="directive"><a href="../mod/core.html#files"><Files></a></code> sections.</p>
-
- <p>If you require a more flexible reverse-proxy configuration, see the
- <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive with the
- <code>[P]</code> flag.</p>
-
- <p>The optional <var>interpolate</var> keyword, in combination with
- <code class="directive">ProxyPassInterpolateEnv</code> 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,
[... 1893 lines stripped ...]