<body>
<div id="page-header">
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
-<p class="apache">Apache HTTP Server Version 2.1</p>
+<p class="apache">Apache HTTP Server Version 2.3</p>
<img alt="" src="../images/feather.gif" /></div>
<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
<div id="path">
-<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs
-project/">Documentation</a> > <a href="../">Version 2.1</a> > <a href="./">Modules</a></div>
+<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs
/">Documentation</a> > <a href="../">Version 2.3</a> > <a href="./">Modules</a></div>
<div id="page-content">
<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></p>
+<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>
<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</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>
<li><img alt="" src="../images/down.gif" /> <a href="#proxybadheader">ProxyBadHeader</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#proxymatch"><ProxyMatch></a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#proxymaxforwards">ProxyMaxForwards</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#proxypass">ProxyPass</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#proxypassinterpolateenv">ProxyPassInterpolateEnv</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#proxypassmatch">ProxyPassMatch</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#proxypassreverse">ProxyPassReverse</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#proxypassreversecookiedomain">ProxyPassReverseCookieDomain</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#proxypassreversecookiepath">ProxyPassReverseCookiePath</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#proxyremote">ProxyRemote</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#proxyremotematch">ProxyRemoteMatch</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#proxyrequests">ProxyRequests</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#proxyset">ProxySet</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#proxystatus">ProxyStatus</a></li>
<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 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="#ftp-proxy">FTP 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>
<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_http.html">mod_proxy_http</a></code></li>
<li><code class="module"><a href="../mod/mod_proxy_ftp.html">mod_proxy_ftp</a></code></li>
<li><code class="module"><a href="../mod/mod_proxy_connect.html">mod_proxy_connect</a></code></li>
+<li><code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code></li>
<li><code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code></li>
</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
by <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code>) to reduce network usage.</p>
<p>The forward proxy is activated using the <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> directive. Because
- forward proxys allow clients to access arbitrary sites through
+ 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>
- <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>
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="ftp-proxy" id="ftp-proxy">FTP Proxy</a></h2>
-
-
- <h3><a name="mimetypes" id="mimetypes">Why doesn't file type <var>xxx</var>
- download via FTP?</a></h3>
- <p>You probably don't have that particular file type defined as
- <code>application/octet-stream</code> in your proxy's mime.types
- configuration file. A useful line can be</p>
-
- <div class="example"><pre>application/octet-stream bin dms lha lzh exe class tgz taz</pre></div>
- <p>Alternatively you may prefer to default everything to binary:</p>
- <div class="example"><pre>DefaultType application/octet-stream</pre></div>
-
-
- <h3><a name="type" id="type">How can I force an FTP ASCII download of
- File <var>xxx</var>?</a></h3>
- <p>In the rare situation where you must download a specific file using the
- FTP <code>ASCII</code> transfer method (while the default transfer is in
- <code>binary</code> mode), you can override <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>'s
- default by suffixing the request with <code>;type=a</code> to force an
- ASCII transfer. (FTP Directory listings are always executed in ASCII mode,
- however.)</p>
-
-
- <h3><a name="ftpnonget" id="ftpnonget">How can I do FTP upload?</a></h3>
- <p>Currently, only GET is supported for FTP in mod_proxy. You can
- of course use HTTP upload (POST or PUT) through an Apache proxy.</p>
-
-
- <h3><a name="percent2fhck" id="percent2fhck">How can I access FTP files outside
- of my home directory?</a></h3>
- <p>An FTP URI is interpreted relative to the home directory of the user
- who is logging in. Alas, to reach higher directory levels you cannot
- use /../, as the dots are interpreted by the browser and not actually
- sent to the FTP server. To address this problem, the so called <dfn>Squid
- %2f hack</dfn> was implemented in the Apache FTP proxy; it is a
- solution which is also used by other popular proxy servers like the <a href="http://www.squid-cache.org/">Squid Proxy Cache</a>. By
- prepending <code>/%2f</code> to the path of your request, you can make
- such a proxy change the FTP starting directory to <code>/</code> (instead
- of the home directory). For example, to retrieve the file
- <code>/etc/motd</code>, you would use the URL:</p>
-
- <div class="example"><p><code>
- ftp://<var>user</var>@<var>host</var>/%2f/etc/motd
- </code></p></div>
-
-
- <h3><a name="ftppass" id="ftppass">How can I hide the FTP cleartext password
- in my browser's URL line?</a></h3>
- <p>To log in to an FTP server by username and password, Apache uses
- different strategies. In absense of a user name and password in the URL
- altogether, Apache sends an anonymous login to the FTP server,
- <em>i.e.</em>,</p>
-
- <div class="example"><p><code>
- user: anonymous<br />
- password: apache_proxy@
- </code></p></div>
-
- <p>This works for all popular FTP servers which are configured for
- anonymous access.</p>
+ <p><strong>See Also</strong> the <a href="mod_proxy_http.html#env">Proxy-Chain-Auth</a> environment variable.</p>
- <p>For a personal login with a specific username, you can embed the user
- name into the URL, like in:</p>
-
- <div class="example"><p><code>
- ftp://<var>username</var>@<var>host</var>/myfile
- </code></p></div>
-
- <p>If the FTP server asks for a password when given this username (which
- it should), then Apache will reply with a <code>401</code> (Authorization
- required) response, which causes the Browser to pop up the
- username/password dialog. Upon entering the password, the connection
- attempt is retried, and if successful, the requested resource is
- presented. The advantage of this procedure is that your browser does not
- display the password in cleartext (which it would if you had used</p>
-
- <div class="example"><p><code>
- ftp://<var>username</var>:<var>password</var>@<var>host</var>/myfile
- </code></p></div>
-
- <p>in the first place).</p>
-
- <div class="note"><h3>Note</h3>
- <p>The password which is transmitted in such a way is not encrypted on
- its way. It travels between your browser and the Apache proxy server in
- a base64-encoded cleartext string, and between the Apache proxy and the
- FTP server as plaintext. You should therefore think twice before
- accessing your FTP server via HTTP (or before accessing your personal
- files via FTP at all!) When using unsecure channels, an eavesdropper
- might intercept your password on its way.</p>
- </div>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+ </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
</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 you have a application server which doesn't
- implement keepalives or HTTP/1.1 properly, there are 2 environment
- variables which when set send a 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>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>
</span>
</Location>
</code></p></div>
- </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>
+
+ </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>
+
+ </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>
+<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>Ports that are allowed to CONNECT 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#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 2.2
+ and later.</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>
+ <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"><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>
</Proxy>
</code></p></div>
- <p>New in Apache 2.1, is the ability to set the various connection
- parameters to a backend server. The connection parameters are in
- the form <code>key=value</code>.
- </p>
- <table>
- <tr><th>Parameter</th>
- <th>Default</th>
- <th>Description</th></tr>
- <tr><td>min</td>
- <td>0</td>
- <td>Minumum number of connections that will always
- be open to the backend server.</td></tr>
- <tr><td>max</td>
- <td>1...n</td>
- <td>Hard Maximum number of connections that will be
- allowed to the backend server. The default for a Hard Maximum
- for the number of connections is the number of threads per process in the
- active MPM. In the Prefork MPM, this is always 1, while with the Worker MPM
- it is controlled by the <code class="directive">ThreadsPerChild</code>.
- Apache will never create more than the Hard Maximum connections
- to the backend server.</td></tr>
- <tr><td>smax</td>
- <td>max</td>
- <td>Upto the Soft Maximum
- number of connections will be created on demand. Any connections above
- <code>smax</code> are subject to a time to live or <code>ttl</code>.
- </td></tr>
- <tr><td>ttl</td>
- <td>-</td>
- <td>Time To Live for the inactive connections above the
- <code>smax</code> connections in seconds. Apache will close all
- connections that has not been used inside that time period.
- </td></tr>
- <tr><td>timeout</td>
- <td><code class="directive">Timeout</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.
- </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. If there is no free connections
- in the pool the Apache will return <code>SERVER_BUSY</code> status to
- the client.
- </td></tr>
- <tr><td>keepalive</td>
- <td>Off</td>
- <td>This parameter should be used when you have a firewall between your
- Apache and the backend server, who tend to drop inactive connections.
- This flag will told Operating System to send <code>KEEP_ALIVE</code> message
- on inactive connections (interval depend on global OS settings,
- generally 120ms), and thus prevent the firewall to cut the connection.
- To enable keepalive set this property value to the <code>On</code>.
- </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,
- the Apache will not forward any request to that servers untill that timeout
- expires. This enables to shut down the backend server for maintenance,
- and bring it back online.
- </td></tr>
- <tr><td>loadfactor</td>
- <td>1</td>
- <td>Worker load factor. Used with BalancerMamber.
- It is a number between 1 and 100 and defined the load aplied to
- the worker.
- </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.
- </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 parametar
- equal as this value.
- </td></tr>
-
- </table>
-
- <p>If the Proxy directive scheme starts with the
- <code>balancer://</code> 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.
- </p>
- <table>
- <tr><th>Parameter</th>
- <th>Default</th>
- <th>Description</th></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.
- </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>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>maxattempts</td>
- <td>1</td>
- <td>Maximum number of failover attempts before giving up.
- </td></tr>
-
- </table>
- <div class="example"><p><code>
- <Proxy balancer://mycluster stickysession=jsessionid nofailover=On><br />
- <span class="indent">
- BalancerMember http://1.2.3.4:8009<br />
- BalancerMember http://1.2.3.5:8009<br />
- BalancerMember http://1.2.3.6:8009<br />
- </span>
- </Proxy>
- </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>
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>
+
</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>
<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>
</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 regular expressions.</p>
+ 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>
+<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]</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 class="directive">ProxyPass</code>.</div>
<p>Suppose the local server has address <code>http://example.com/</code>;
then</p>
<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>
+ <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>The <code>!</code> directive is useful in situations where you don't want
to reverse-proxy a subdirectory, <em>e.g.</em></p>
<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>
- <p>New in Apache 2.1, is the ability to use pooled connections to a
- backend server. Using the <code>key=value</code> parameters it is possible
- to tune this connection pooling. The default for a <code>Hard Maximum</code>
- for the number of connections is the number of threads per process in the
- active MPM. In the Prefork MPM, this is always 1, while with the Worker MPM
- it is controlled by the <code class="directive">ThreadsPerChild</code>.</p>
+ <p>As of Apache 2.1, the ability to use pooled connections to a backend
+ server is available. Using the <code>key=value</code> parameters it is
+ possible to tune this connection pooling. The default for a <code>Hard
+ Maximum</code> for the number of connections is the number of threads per
+ process in the active MPM. In the Prefork MPM, this is always 1, while with
+ the Worker MPM it is controlled by the
+ <code class="directive">ThreadsPerChild</code>.</p>
<p>Setting <code>min</code> will determine how many connections will always
be open to the backend server. Upto the Soft Maximum or <code>smax</code>
ProxyPass /example http://backend.example.com smax=5 max=20 ttl=120 retry=300
</code></p></div>
+ <table>
+ <tr><th>Parameter</th>
+ <th>Default</th>
+ <th>Description</th></tr>
+ <tr><td>min</td>
+ <td>0</td>
+ <td>Minimum number of connections that will always
+ be open to the backend server.</td></tr>
+ <tr><td>max</td>
+ <td>1...n</td>
+ <td>Hard Maximum number of connections that will be
+ allowed to the backend server. The default for a Hard Maximum
+ for the number of connections is the number of threads per process in the
+ active MPM. In the Prefork MPM, this is always 1, while with the Worker MPM
+ it is controlled by the <code class="directive">ThreadsPerChild</code>.
+ Apache will never create more than the Hard Maximum connections
+ to the backend server.</td></tr>
+ <tr><td>smax</td>
+ <td>max</td>
+ <td>Upto the Soft Maximum
+ number of connections will be created on demand. Any connections above
+ <code>smax</code> are subject to a time to live or <code>ttl</code>.
+ </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 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>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>This parameter should be used when you have a firewall between your
+ Apache 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 (interval depends on global OS settings,
+ generally 120ms), and thus prevent the firewall to drop the connection.
+ To enable keepalive set this property value to <code>On</code>.
+ </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 webserver to send a <code>CPING</code>
+ request on ajp13 connection before forwarding a request.
+ The parameter is the delay in seconds to wait for the
+ <code>CPONG</code> reply.
+ This features has been added to avoid problem with hung and
+ busy Tomcat's and require ajp13 ping/pong support which has
+ been implemented on Tomcat 3.3.2+, 4.1.28+ and 5.0.13+.
+ 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.
+ 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>
+ <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 parametar
+ 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 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: '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
+ 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 waits for data sent by / to the backend.
+ </td></tr>
+ <tr><td>ttl</td>
+ <td>-</td>
+ <td>Time To Live for the inactive connections above the
+ <code>smax</code> connections in seconds. Apache will close all
+ connections that has not been used inside that time period.
+ </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>
+ <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>1</td>
+ <td>Maximum number of failover attempts before giving up.
+ </td></tr>
+ <tr><td>nofailover</td>
+ <td>Off</td>
+ <td>If set to <code>On</code> the session will break if the worker is in
+ error state or disabled. Set this value to On if backend servers do not
+ support session replication.
+ </td></tr>
+ <tr><td>stickysession</td>
+ <td>-</td>
+ <td>Balancer sticky session name. The value is usually set to something
+ like <code>JSESSIONID</code> or <code>PHPSESSIONID</code>,
+ and it depends on the backend application server that support sessions.
+ If the backend application server uses different name for cookies
+ and url encoded id (like servlet containers) use | to to separate them.
+ The first part is for the cookie the second for the path.
+ </td></tr>
+ <tr><td>scolonpathdelim</td>
+ <td>Off</td>
+ <td>If set to <code>On</code> the semi-colon character ';' will be
+ used as an additional sticky session path deliminator/separator. This
+ is mainly used to emulate mod_jk's behavior when dealing with paths such
+ as <code>JSESSIONID=6736bcf34;foo=aabfa</code>
+ </td></tr>
+ <tr><td>timeout</td>
+ <td>0</td>
+ <td>Balancer timeout in seconds. If set this will be the maximum time
+ to wait for a free worker. Default is not to wait.
+ </td></tr>
+
+ </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 / balancer://mycluster/ stickysession=JSESSIONID|jsessionid nofailover=On<br />
+ <Proxy balancer://mycluster><br />
+ <span class="indent">
+ BalancerMember http://1.2.3.4:8009<br />
+ BalancerMember http://1.2.3.5:8009 smax=10<br />
+ # Less powerful server, don't send as many requests there<br />
+ BalancerMember http://1.2.3.6:8009 smax=1 loadfactor=20<br />
+ </span>
+ </Proxy>
+ </code></p></div>
+
+ <p>Setting up a hot-standby, that will only be used if no other
+ members are available</p>
+ <div class="example"><p><code>
+ ProxyPass / balancer://hotcluster/ <br />
+ <Proxy balancer://hotcluster><br />
+ <span class="indent">
+ BalancerMember http://1.2.3.4:8009 loadfactor=1<br />
+ BalancerMember http://1.2.3.5:8009 loadfactor=2<br />
+ # The below is the hot standby<br />
+ BalancerMember http://1.2.3.6:8009 status=+H<br />
+ ProxySet lbmethod=bytraffic
+ </span>
+ </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>
- <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>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>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyPassInterpolateEnv" id="ProxyPassInterpolateEnv">ProxyPassInterpolateEnv</a> <a name="proxypassinterpolateenv" id="proxypassinterpolateenv">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable Environment Variable interpolation in Reverse Proxy configurations</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassInterpolateEnv On|Off</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyPassInterpolateEnv 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>
+<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, 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 class="directive">ProxyPassReverse</code>,
+ <code class="directive">ProxyPassReverseCookieDomain</code>, and
+ <code class="directive">ProxyPassReverseCookiePath</code> directives,
+ and causes them to substitute the value of an environment
+ variable <code>varname</code> for the string <code>${varname}</code>
+ in configuration directives.</p>
+ <p>Keep this turned off (for server performance) unless you need it!</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="ProxyPassMatch" id="ProxyPassMatch">ProxyPassMatch</a> <a name="proxypassmatch" id="proxypassmatch">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 using regular expressions</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassMatch [<var>regex</var>] !|<var>url</var> [<var>key=value</var>
+ <var>[key=value</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 is equivalent to <code class="directive"><a href="#proxypass">ProxyPass</a></code>,
+ but makes use of regular expressions, instead of simple prefix matching. The
+ supplied regular expression is matched against the <var>url</var>, and if it
+ matches, the server will substitute any parenthesized matches into the given
+ string and use it as a new <var>url</var>.</p>
+
+ <p>Suppose the local server has address <code>http://example.com/</code>;
+ then</p>
+
+ <div class="example"><p><code>
+ ProxyPassMatch ^(/.*\.gif)$ http://backend.example.com$1
+ </code></p></div>
+
+ <p>will cause a local request for
+ <code>http://example.com/foo/bar.gif</code> to be internally converted
+ into a proxy request to <code>http://backend.example.com/foo/bar.gif</code>.</p>
+ <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>
+
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="ProxyPassReverse" id="ProxyPassReverse">ProxyPassReverse</a> <a name="proxypassreverse" id="proxypassreverse">Directive</a></h2>
<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
This means that if the proxied content contains absolute URL
references, they will by-pass the proxy. A third-party module
that will look inside the HTML and rewrite URL references is Nick
- Kew's <a href="http://apache.webthing.com/software/mod_proxy_html/">mod_proxy_html</a>.</p>
+ Kew's <a href="http://apache.webthing.com/mod_proxy_html/">mod_proxy_html</a>.</p>
<p><var>path</var> is the name of a local virtual path. <var>url</var> is a
partial URL for the remote server - the same way they are used for the
<p>Note that this <code class="directive">ProxyPassReverse</code> directive can
also be used in conjunction with the proxy pass-through feature
(<code>RewriteRule ... [P]</code>) from <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
- because its doesn't depend on a corresponding <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p>
+ 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
</table>
<p>The <code class="directive">ProxyRemoteMatch</code> is identical to the
<code class="directive"><a href="#proxyremote">ProxyRemote</a></code> directive, except the
- first argument is a regular expression match against the requested URL.</p>
+ first argument is a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>
+ match against the requested URL.</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
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>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set various Proxy balancer or member parameters</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxySet <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>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 workers normally done via the
+ <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive. If used
+ 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 />
+ <span class="indent">
+ BalancerMember http://www2.example.com:8009 loadfactor=1<br />
+ BalancerMember http://www3.example.com:8009 loadfactor=2<br />
+ ProxySet lbmethod=bytraffic<br />
+ </span>
+ </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>
+<div class="directive-section"><h2><a name="ProxyStatus" id="ProxyStatus">ProxyStatus</a> <a name="proxystatus" id="proxystatus">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Show Proxy LoadBalancer status in mod_status</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyStatus Off|On|Full</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyStatus 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>Available in version 2.2 and later</td></tr>
+</table>
+ <p>This directive determines whether or not proxy
+ loadbalancer status data is displayed via the <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>
+ server-status page.</p>
+ <div class="note"><h3>Note</h3>
+ <p><strong>Full</strong> is synonymous with <strong>On</strong></p>
+ </div>
+
+
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="ProxyTimeout" id="ProxyTimeout">ProxyTimeout</a> <a name="proxytimeout" id="proxytimeout">Directive</a></h2>
<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 class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="ProxyVia" id="ProxyVia">ProxyVia</a> <a name="proxyvia" id="proxyvia">Directive</a></h2>
<table class="directive">
-<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Information provided in the Via HTTP response
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Information provided in the <code>Via</code> HTTP response
header for proxied requests</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyVia On|Off|Full|Block</code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyVia Off</code></td></tr>
</div>
</div>
<div class="bottomlang">
-<p><span>Available Languages: </span><a href="../en/mod/mod_proxy.html" title="English"> en </a></p>
+<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
1999-2004 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
2010 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