<div id="preamble"><h1>Apache Module mod_proxy</h1>
<div class="toplang">
<p><span>Available Languages: </span><a href="../en/mod/mod_proxy.html" title="English"> en </a> |
+<a href="../fr/mod/mod_proxy.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
<a href="../ja/mod/mod_proxy.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p>
</div>
<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>HTTP/1.1 proxy/gateway server</td></tr>
</div>
<div id="quickview"><h3 class="directives">Directives</h3>
<ul id="toc">
-<li><img alt="" src="../images/down.gif" /> <a href="#allowconnect">AllowCONNECT</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#balancermember">BalancerMember</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#noproxy">NoProxy</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#proxy"><Proxy></a></li>
</ul>
<h3>Topics</h3>
<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#forwardreverse">Forward and Reverse Proxies</a></li>
+<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="#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 Bodys</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>
<ul class="seealso">
</ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
-<h2><a name="forwardreverse" id="forwardreverse">Forward and Reverse Proxies</a></h2>
+<h2><a name="forwardreverse" id="forwardreverse">Forward Proxies and Reverse
+ Proxies/Gateways</a></h2>
<p>Apache can be configured in both a <dfn>forward</dfn> and
- <dfn>reverse</dfn> proxy mode.</p>
+ <dfn>reverse</dfn> proxy (also known as <dfn>gateway</dfn>) mode.</p>
<p>An ordinary <dfn>forward proxy</dfn> is an intermediate
server that sits between the client and the <em>origin
authorized clients can access the proxy before activating a
forward proxy.</p>
- <p>A <dfn>reverse proxy</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>
+ <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>
<p>A typical usage of a reverse proxy is to provide Internet
users access to a server that is behind a firewall. Reverse
critical because clients can only contact the hosts that you
have specifically configured.</p>
+ <p><strong>See Also</strong> the <a href="mod_proxy_http.html#env">Proxy-Chain-Auth</a> environment variable.</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>
</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 Bodys</a></h2>
+<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
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="directive-section"><h2><a name="AllowCONNECT" id="AllowCONNECT">AllowCONNECT</a> <a name="allowconnect" id="allowconnect">Directive</a></h2>
-<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Ports that are allowed to <code>CONNECT</code> through the
-proxy</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AllowCONNECT <var>port</var> [<var>port</var>] ...</code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AllowCONNECT 443 563</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">AllowCONNECT</code> directive specifies a list
- of port numbers to which the proxy <code>CONNECT</code> method may
- connect. Today's browsers use this method when a <code>https</code>
- connection is requested and proxy tunneling over HTTP is in effect.</p>
-
- <p>By default, only the default https port (<code>443</code>) and the
- default snews port (<code>563</code>) are enabled. Use the
- <code class="directive">AllowCONNECT</code> directive to override this default and
- allow connections to the listed ports only.</p>
-
- <p>Note that you'll need to have <code class="module"><a href="../mod/mod_proxy_connect.html">mod_proxy_connect</a></code> present
- in the server in order to get the support for the <code>CONNECT</code> at
- all.</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>url</var> [<var>key=value [key=value ...]]</var></code></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 2.2.0
- and later.</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerMember is only available in Apache 2.2
+ and later.</td></tr>
</table>
- <p>This directive adds a member to a load balancing group. It must be used
+ <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 parameters available to
+ 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"><a href="#balancermember">BalancerMember</a></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 balancerurl 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>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<code class="directive"><a href="#proxyremote">ProxyRemote</a></code> proxy server(s).</p>
<div class="example"><h3>Example</h3><p><code>
- ProxyRemote * http://firewall.mycompany.com:81<br />
- NoProxy .mycompany.com 192.168.112.0/21
+ ProxyRemote * http://firewall.example.com:81<br />
+ NoProxy .example.com 192.168.112.0/21
</code></p></div>
<p>The <var>host</var> arguments to the <code class="directive">NoProxy</code>
<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>.MyDomain.com</code> and
- <code>.mydomain.com.</code> (note the trailing period) are considered
+ 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>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
+ <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>Examples</h3><p><code>
- prep.ai.mit.edu<br />
+ prep.ai.example.com<br />
www.apache.org
</code></p></div>
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.MyDomain.com</code>
- and <code>www.mydomain.com.</code> (note the trailing period) are
+ 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>
</code></p></div>
+<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="ProxyBadHeader" id="ProxyBadHeader">ProxyBadHeader</a> <a name="proxybadheader" id="proxybadheader">Directive</a></h2>
<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>available in Apache 2.0.44 and later</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.0.44 and later</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
will be generated.</p>
<div class="example"><h3>Example</h3><p><code>
- ProxyRemote * http://firewall.mycompany.com:81<br />
- NoProxy .mycompany.com 192.168.112.0/21<br />
- ProxyDomain .mycompany.com
+ ProxyRemote * http://firewall.example.com:81<br />
+ NoProxy .example.com 192.168.112.0/21<br />
+ ProxyDomain .example.com
</code></p></div>
</div>
</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 less or equal <code>8192</code>.</p>
+ input and output. The size must be at least <code>512</code>.</p>
<p>In almost every case there's no reason to change that value.</p>
+ <p>If used with AJP this directive sets the maximum AJP packet size in
+ bytes. 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>
+ <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>
+
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
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>
+<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>
<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 10</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#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>Available in Apache 2.0 and later</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.0 and later;
+ default behaviour changed in 2.2.7/2.3</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 is
- set to prevent infinite proxy loops, or a DoS attack.</p>
+ <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><p><code>
ProxyMaxForwards 15
</code></p></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 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>
+
</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>
<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> ...]]</code></td></tr>
+ <var>[key=value</var> ...]] [nocanon] [interpolate]</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 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. <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>
+ <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="warning">The <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> directive should
usually be set <strong>off</strong> when using
<code>/mirror/foo/i</code>.</p>
<div class="note"><h3>Note</h3>
- <p>Order is important. you need to put the exclusions <em>before</em> the
+ <p>Order is important: exclusions must come <em>before</em> the
general <code class="directive">ProxyPass</code> directive.</p>
</div>
<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. If there are no free connections
- in the pool the Apache will return <code>SERVER_BUSY</code> status to
- the client.
+ connection in the connection pool, in milliseconds. If there are no free
+ connections in the pool the Apache 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 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 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>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>This parameter should be used when you have a firewall between your
which could be an issue, but it will lower the
traffic in case some of the cluster nodes are down or busy.
Currently this has an effect only for AJP.
+ 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>
If the connection pool worker to the backend server is in the error state,
Apache 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.
+ 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 seesion id.
+ 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: 'D' is disabled, 'S' is stopped, 'I' is ignore-errors,
- 'H' is hot-standby and 'E' is in an error state. Status
- can be set (which is the default) by prepending with '+' or
+ 'H' is hot-standby and 'E' is in an error state. 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">Timeout</code></td>
+ <td><code class="directive"><a href="#proxytimeout">ProxyTimeout</a></code></td>
<td>Connection timeout in seconds.
- If not set the Apache will wait until the free connection
- is available. This directive is used for limiting the number
- of connections to the backend server together with <code>max</code>
- parameter.
+ The number of seconds Apache waits for data sent by / to the backend.
</td></tr>
<tr><td>ttl</td>
<td>-</td>
</table>
<p>If the Proxy directive scheme starts with the
- <code>balancer://</code> then a virtual worker that does not really
+ <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>
<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 or <code>bytraffic</code>, to perform weighted
- traffic byte count balancing. Default is <code>byrequests</code>.
+ 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>1</td>
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>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
</table>
<p>A sample balancer setup</p>
<div class="example"><p><code>
- ProxyPass /special-area http://special.example.com/ smax=5 max=10<br />
+ ProxyPass /special-area http://special.example.com smax=5 max=10<br />
ProxyPass / balancer://mycluster/ stickysession=JSESSIONID|jsessionid nofailover=On<br />
<Proxy balancer://mycluster><br />
<span class="indent">
</Proxy>
</code></p></div>
+ <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
+ <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,
+ so you may still have to resort to <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
+ for complex rules.</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>.</p>
<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 trunk only</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.2.9 and later</td></tr>
</table>
- <p>This directive enables reverse proxies to be dynamically
+ <p>This directive, together with the <var>interpolate</var> argument to
+ <code class="directive">ProxyPass</code>, <code class="directive">ProxyPassReverse</code>,
+ <code class="directive">ProxyPassReverseCookieDomain</code> and
+ <code class="directive">ProxyPassReverseCookiePath</code>
+ enables reverse proxies to be dynamically
configured using environment variables, which may be set by
another module such as <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>.
It affects the <code class="directive">ProxyPass</code>,
</code></p></div>
<p>will cause a local request for
- <code>http://example.com/mirror/foo/bar.gif</code> to be internally converted
+ <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>
-
+ <div class="note"><h3>Note</h3>
+ <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>
+ <div class="example"><p><code>
+ ProxyPassMatch ^(/.*\.gif)$ http://backend.example.com:8000$1
+ </code></p></div>
+ <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>
+ <div class="example"><p><code>
+ ProxyPassMatch ^/(.*\.gif)$ http://backend.example.com:8000/$1
+ </code></p></div>
+ </div>
<p>The <code>!</code> directive is useful in situations where you don't want
to reverse-proxy a subdirectory.</p>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adjusts the URL in HTTP response headers sent from a reverse
proxied server</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverse [<var>path</var>] <var>url</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverse [<var>path</var>] <var>url</var>
+[<var>interpolate</var>]</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 lets Apache 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 is used as a reverse proxy to avoid
- by-passing the reverse proxy because of HTTP redirects on the backend
- servers which stay behind the reverse proxy.</p>
+ <code>Content-Location</code> and <code>URI</code> headers on HTTP
+ redirect responses. This is essential when Apache 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 will not rewrite other response
(<code>RewriteRule ... [P]</code>) from <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
because it doesn't depend on a corresponding <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p>
+ <p>The optional <var>interpolate</var> keyword (available in
+ httpd 2.2.9 and later), used together with
+ <code class="directive">ProxyPassInterpolateEnv</code>, enables interpolation
+ of environment variables specified using the format <var>${VARNAME}</var>.
+ </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>.</p>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adjusts the Domain string in Set-Cookie headers from a reverse-
proxied server</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverseCookieDomain <var>internal-domain</var> <var>public-domain</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverseCookieDomain <var>internal-domain</var>
+<var>public-domain</var> [<var>interpolate</var>]</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 class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adjusts the Path string in Set-Cookie headers from a reverse-
proxied server</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverseCookiePath <var>internal-path</var> <var>public-path</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverseCookiePath <var>internal-path</var>
+<var>public-path</var> [<var>interpolate</var>]</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>
request</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPreserveHost On|Off</code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyPreserveHost 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#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 Apache 2.0.31 and later.</td></tr>
</code></p></div>
<p><var>scheme</var> is effectively the protocol that should be used to
- communicate with the remote server; only <code>http</code> is supported by
- this module.</p>
+ communicate with the remote server; only <code>http</code> and <code>https</code>
+ are supported by this module. When using <code>https</code>, the requests
+ are forwarded through the remote proxy using the HTTP CONNECT method.</p>
<div class="example"><h3>Example</h3><p><code>
- ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000<br />
- ProxyRemote * http://cleversite.com<br />
- ProxyRemote ftp http://ftpproxy.mydomain.com:8080
+ ProxyRemote http://goodguys.example.com/ http://mirrorguys.example.com:8000<br />
+ ProxyRemote * http://cleverproxy.localdomain<br />
+ ProxyRemote ftp http://ftpproxy.mydomain:8080
</code></p></div>
<p>In the last example, the proxy will forward FTP requests, encapsulated
server. (Setting ProxyRequests to <code>Off</code> does not disable use of
the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.)</p>
- <p>In a typical reverse proxy configuration, this option should be set to
+ <p>In a typical reverse proxy or gateway configuration, this
+ option should be set to
<code>Off</code>.</p>
<p>In order to get the functionality of proxying HTTP or FTP sites, you
both to your network and to the Internet at large.</p>
</div>
+<h3>See also</h3>
+<ul>
+<li><a href="#forwardreverse">Forward and Reverse Proxies/Gateways</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="ProxySet" id="ProxySet">ProxySet</a> <a name="proxyset" id="proxyset">Directive</a></h2>
<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>ProxySet is only available in Apache 2.2.0
- and later.</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>ProxySet is only available in Apache 2.2
+ and later.</td></tr>
</table>
<p>This directive is used as an alternate method of setting any of the
- parameters available to Proxy balancers and members normally done via the
+ parameters available to Proxy balancers and workers normally done via the
<code class="directive"><a href="#proxypass">ProxyPass</a></code> directive. If used
- within a <code><Proxy <var>balancer://</var>...></code> container
- directive, the <var>url</var> argument is not required.</p>
+ within a <code><Proxy <var>balancer url|worker url</var>></code>
+ container directive, the <var>url</var> argument is not required. As a side
+ effect the respective balancer or worker gets created. This can be useful
+ when doing reverse proxying via a
+ <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> instead of a
+ <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p>
<div class="example"><p><code>
<Proxy balancer://hotcluster><br />
</Proxy>
</code></p></div>
+ <div class="example"><p><code>
+ <Proxy http://backend><br />
+ <span class="indent">
+ ProxySet keepalive=On<br />
+ </span>
+ </Proxy>
+ </code></p></div>
+
<div class="example"><p><code>
ProxySet balancer://foo lbmethod=bytraffic timeout=15
</code></p></div>
+ <div class="example"><p><code>
+ ProxySet ajp://backend:7001 timeout=15
+ </code></p></div>
+
+ <div class="warning"><h3>Warning</h3>
+ <p>Keep in mind that the same parameter key can have a different meaning
+ depending whether it is applied to a balancer or a worker as shown by the two
+ examples above regarding timeout.</p>
+ </div>
+
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Network timeout for proxied requests</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyTimeout <var>seconds</var></code></td></tr>
-<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyTimeout 300</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Value of <code class="directive"><a href="../mod/core.html#timeout">Timeout</a></code></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>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_proxy.html" title="English"> en </a> |
+<a href="../fr/mod/mod_proxy.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
<a href="../ja/mod/mod_proxy.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p>
</div><div id="footer">
-<p class="apache">Copyright 20
07 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
+<p class="apache">Copyright 20
10 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
</body></html>
\ No newline at end of file
projects / apache / blobdiff