granicus.if.org Git - apache/blob - docs/manual/mod/mod_proxy.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>mod_proxy - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
  12 <script src="../style/scripts/prettify.js" type="text/javascript">
  13 </script>
  14
  15 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  16 <body>
  17 <div id="page-header">
  18 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  19 <p class="apache">Apache HTTP Server Version 2.5</p>
  20 <img alt="" src="../images/feather.gif" /></div>
  21 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  22 <div id="path">
  23 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Modules</a></div>
  24 <div id="page-content">
  25 <div id="preamble"><h1>Apache Module mod_proxy</h1>
  26 <div class="toplang">
  27 <p><span>Available Languages: </span><a href="../en/mod/mod_proxy.html" title="English">&nbsp;en&nbsp;</a> |
  28 <a href="../fr/mod/mod_proxy.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
  29 <a href="../ja/mod/mod_proxy.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a></p>
  30 </div>
  31 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Multi-protocol proxy/gateway server</td></tr>
  32 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  33 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>proxy_module</td></tr>
  34 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_proxy.c</td></tr></table>
  35 <h3>Summary</h3>
  36
  37     <div class="warning"><h3>Warning</h3>
  38       <p>Do not enable proxying with <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> until you have <a href="#access">secured your server</a>. Open proxy servers are dangerous both to your
  39       network and to the Internet at large.</p>
  40     </div>
  41
  42     <p><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> and related modules implement a
  43     proxy/gateway for Apache HTTP Server, supporting a number of popular
  44     protocols as well as several different load balancing algorithms.
  45     Third-party modules can add support for additional protocols and
  46     load balancing algorithms.</p>
  47
  48     <p>A set of modules must be loaded into the server to provide the
  49     necessary features.  These modules can be included statically at
  50     build time or dynamically via the
  51     <code class="directive"><a href="../mod/mod_so.html#loadmodule">LoadModule</a></code> directive).
  52     The set must include:</p>
  53
  54     <ul>
  55       <li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, which provides basic proxy
  56       capabilities</li>
  57
  58       <li><code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code> and one or more
  59       balancer modules, if load balancing is required.  (See
  60       <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code> for more information.)</li>
  61
  62       <li>one or more proxy scheme, or protocol, modules:
  63
  64         <table class="bordered">
  65         <tr><th>Protocol</th><th>Module</th></tr>
  66         <tr><td>AJP13 (Apache JServe Protocol version
  67           1.3)</td><td><code class="module"><a href="../mod/mod_proxy_ajp.html">mod_proxy_ajp</a></code></td></tr>
  68         <tr><td>CONNECT (for
  69           SSL)</td><td><code class="module"><a href="../mod/mod_proxy_connect.html">mod_proxy_connect</a></code></td></tr>
  70         <tr><td>FastCGI</td><td><code class="module"><a href="../mod/mod_proxy_fcgi.html">mod_proxy_fcgi</a></code></td></tr>
  71         <tr><td>ftp</td><td><code class="module"><a href="../mod/mod_proxy_ftp.html">mod_proxy_ftp</a></code></td></tr>
  72         <tr><td>HTTP/0.9, HTTP/1.0, and
  73           HTTP/1.1</td><td><code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code></td></tr>
  74         <tr><td>SCGI</td><td><code class="module"><a href="../mod/mod_proxy_scgi.html">mod_proxy_scgi</a></code></td></tr>
  75         </table>
  76       </li>
  77     </ul>
  78
  79     <p>In addition, extended features are provided by other modules.
  80     Caching is provided by <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code> and related
  81     modules.  The ability to contact remote servers using the SSL/TLS
  82     protocol is provided by the <code>SSLProxy*</code> directives of
  83     <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code>.  These additional modules will need
  84     to be loaded and configured to take advantage of these features.</p>
  85 </div>
  86 <div id="quickview"><h3 class="directives">Directives</h3>
  87 <ul id="toc">
  88 <li><img alt="" src="../images/down.gif" /> <a href="#balancergrowth">BalancerGrowth</a></li>
  89 <li><img alt="" src="../images/down.gif" /> <a href="#balancerinherit">BalancerInherit</a></li>
  90 <li><img alt="" src="../images/down.gif" /> <a href="#balancermember">BalancerMember</a></li>
  91 <li><img alt="" src="../images/down.gif" /> <a href="#balancerpersist">BalancerPersist</a></li>
  92 <li><img alt="" src="../images/down.gif" /> <a href="#noproxy">NoProxy</a></li>
  93 <li><img alt="" src="../images/down.gif" /> <a href="#proxy">&lt;Proxy&gt;</a></li>
  94 <li><img alt="" src="../images/down.gif" /> <a href="#proxyaddheaders">ProxyAddHeaders</a></li>
  95 <li><img alt="" src="../images/down.gif" /> <a href="#proxybadheader">ProxyBadHeader</a></li>
  96 <li><img alt="" src="../images/down.gif" /> <a href="#proxyblock">ProxyBlock</a></li>
  97 <li><img alt="" src="../images/down.gif" /> <a href="#proxydomain">ProxyDomain</a></li>
  98 <li><img alt="" src="../images/down.gif" /> <a href="#proxyerroroverride">ProxyErrorOverride</a></li>
  99 <li><img alt="" src="../images/down.gif" /> <a href="#proxyiobuffersize">ProxyIOBufferSize</a></li>
 100 <li><img alt="" src="../images/down.gif" /> <a href="#proxymatch">&lt;ProxyMatch&gt;</a></li>
 101 <li><img alt="" src="../images/down.gif" /> <a href="#proxymaxforwards">ProxyMaxForwards</a></li>
 102 <li><img alt="" src="../images/down.gif" /> <a href="#proxypass">ProxyPass</a></li>
 103 <li><img alt="" src="../images/down.gif" /> <a href="#proxypassinherit">ProxyPassInherit</a></li>
 104 <li><img alt="" src="../images/down.gif" /> <a href="#proxypassinterpolateenv">ProxyPassInterpolateEnv</a></li>
 105 <li><img alt="" src="../images/down.gif" /> <a href="#proxypassmatch">ProxyPassMatch</a></li>
 106 <li><img alt="" src="../images/down.gif" /> <a href="#proxypassreverse">ProxyPassReverse</a></li>
 107 <li><img alt="" src="../images/down.gif" /> <a href="#proxypassreversecookiedomain">ProxyPassReverseCookieDomain</a></li>
 108 <li><img alt="" src="../images/down.gif" /> <a href="#proxypassreversecookiepath">ProxyPassReverseCookiePath</a></li>
 109 <li><img alt="" src="../images/down.gif" /> <a href="#proxypreservehost">ProxyPreserveHost</a></li>
 110 <li><img alt="" src="../images/down.gif" /> <a href="#proxyreceivebuffersize">ProxyReceiveBufferSize</a></li>
 111 <li><img alt="" src="../images/down.gif" /> <a href="#proxyremote">ProxyRemote</a></li>
 112 <li><img alt="" src="../images/down.gif" /> <a href="#proxyremotematch">ProxyRemoteMatch</a></li>
 113 <li><img alt="" src="../images/down.gif" /> <a href="#proxyrequests">ProxyRequests</a></li>
 114 <li><img alt="" src="../images/down.gif" /> <a href="#proxyset">ProxySet</a></li>
 115 <li><img alt="" src="../images/down.gif" /> <a href="#proxysourceaddress">ProxySourceAddress</a></li>
 116 <li><img alt="" src="../images/down.gif" /> <a href="#proxystatus">ProxyStatus</a></li>
 117 <li><img alt="" src="../images/down.gif" /> <a href="#proxytimeout">ProxyTimeout</a></li>
 118 <li><img alt="" src="../images/down.gif" /> <a href="#proxyvia">ProxyVia</a></li>
 119 </ul>
 120 <h3>Topics</h3>
 121 <ul id="topics">
 122 <li><img alt="" src="../images/down.gif" /> <a href="#forwardreverse">Forward Proxies and Reverse
 123        Proxies/Gateways</a></li>
 124 <li><img alt="" src="../images/down.gif" /> <a href="#examples">Basic Examples</a></li>
 125 <li><img alt="" src="../images/down.gif" /> <a href="#workers">Workers</a></li>
 126 <li><img alt="" src="../images/down.gif" /> <a href="#access">Controlling access to your proxy</a></li>
 127 <li><img alt="" src="../images/down.gif" /> <a href="#startup">Slow Startup</a></li>
 128 <li><img alt="" src="../images/down.gif" /> <a href="#intranet">Intranet Proxy</a></li>
 129 <li><img alt="" src="../images/down.gif" /> <a href="#envsettings">Protocol Adjustments</a></li>
 130 <li><img alt="" src="../images/down.gif" /> <a href="#request-bodies">Request Bodies</a></li>
 131 <li><img alt="" src="../images/down.gif" /> <a href="#x-headers">Reverse Proxy Request Headers</a></li>
 132 </ul><h3>See also</h3>
 133 <ul class="seealso">
 134 <li><code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code></li>
 135 <li><code class="module"><a href="../mod/mod_proxy_ajp.html">mod_proxy_ajp</a></code></li>
 136 <li><code class="module"><a href="../mod/mod_proxy_connect.html">mod_proxy_connect</a></code></li>
 137 <li><code class="module"><a href="../mod/mod_proxy_fcgi.html">mod_proxy_fcgi</a></code></li>
 138 <li><code class="module"><a href="../mod/mod_proxy_ftp.html">mod_proxy_ftp</a></code></li>
 139 <li><code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code></li>
 140 <li><code class="module"><a href="../mod/mod_proxy_scgi.html">mod_proxy_scgi</a></code></li>
 141 <li><code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code></li>
 142 <li><code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code></li>
 143 </ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
 144 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 145 <div class="section">
 146 <h2><a name="forwardreverse" id="forwardreverse">Forward Proxies and Reverse
 147        Proxies/Gateways</a></h2>
 148       <p>Apache HTTP Server can be configured in both a <dfn>forward</dfn> and
 149       <dfn>reverse</dfn> proxy (also known as <dfn>gateway</dfn>) mode.</p>
 150
 151       <p>An ordinary <dfn>forward proxy</dfn> is an intermediate
 152       server that sits between the client and the <em>origin
 153       server</em>.  In order to get content from the origin server,
 154       the client sends a request to the proxy naming the origin server
 155       as the target and the proxy then requests the content from the
 156       origin server and returns it to the client.  The client must be
 157       specially configured to use the forward proxy to access other
 158       sites.</p>
 159
 160       <p>A typical usage of a forward proxy is to provide Internet
 161       access to internal clients that are otherwise restricted by a
 162       firewall.  The forward proxy can also use caching (as provided
 163       by <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code>) to reduce network usage.</p>
 164
 165       <p>The forward proxy is activated using the <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> directive.  Because
 166       forward proxies allow clients to access arbitrary sites through
 167       your server and to hide their true origin, it is essential that
 168       you <a href="#access">secure your server</a> so that only
 169       authorized clients can access the proxy before activating a
 170       forward proxy.</p>
 171
 172       <p>A <dfn>reverse proxy</dfn> (or <dfn>gateway</dfn>), by
 173       contrast, appears to the client just like an ordinary web
 174       server.  No special configuration on the client is necessary.
 175       The client makes ordinary requests for content in the name-space
 176       of the reverse proxy.  The reverse proxy then decides where to
 177       send those requests, and returns the content as if it was itself
 178       the origin.</p>
 179
 180       <p>A typical usage of a reverse proxy is to provide Internet
 181       users access to a server that is behind a firewall.  Reverse
 182       proxies can also be used to balance load among several back-end
 183       servers, or to provide caching for a slower back-end server.
 184       In addition, reverse proxies can be used simply to bring
 185       several servers into the same URL space.</p>
 186
 187       <p>A reverse proxy is activated using the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive or the
 188       <code>[P]</code> flag to the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive.  It is
 189       <strong>not</strong> necessary to turn <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> on in order to
 190       configure a reverse proxy.</p>
 191     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 192 <div class="section">
 193 <h2><a name="examples" id="examples">Basic Examples</a></h2>
 194
 195     <p>The examples below are only a very basic idea to help you
 196     get started.  Please read the documentation on the individual
 197     directives.</p>
 198
 199     <p>In addition, if you wish to have caching enabled, consult
 200     the documentation from <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code>.</p>
 201
 202     <div class="example"><h3>Reverse Proxy</h3><pre class="prettyprint lang-config">
 203 ProxyPass /foo http://foo.example.com/bar
 204 ProxyPassReverse /foo http://foo.example.com/bar
 205     </pre>
 206 </div>
 207
 208     <div class="example"><h3>Forward Proxy</h3><pre class="prettyprint lang-config">
 209 ProxyRequests On
 210 ProxyVia On
 211
 212 &lt;Proxy *&gt;
 213   Require host internal.example.com
 214 &lt;/Proxy&gt;
 215     </pre>
 216 </div>
 217     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 218 <div class="section">
 219 <h2><a name="workers" id="workers">Workers</a></h2>
 220       <p>The proxy manages the configuration of origin servers and their
 221       communication parameters in objects called <dfn>workers</dfn>.
 222       There are two built-in workers, the default forward proxy worker and the
 223       default reverse proxy worker. Additional workers can be configured
 224       explicitly.</p>
 225
 226       <p>The two default workers have a fixed configuration
 227       and will be used if no other worker matches the request.
 228       They do not use HTTP Keep-Alive or connection pooling.
 229       The TCP connections to the origin server will instead be
 230       opened and closed for each request.</p>
 231
 232       <p>Explicitly configured workers are identified by their URL.
 233       They are usually created and configured using
 234       <code class="directive"><a href="#proxypass">ProxyPass</a></code> or
 235       <code class="directive"><a href="#proxypassmatch">ProxyPassMatch</a></code> when used
 236       for a reverse proxy:</p>
 237
 238       <pre class="prettyprint lang-config">
 239           ProxyPass /example http://backend.example.com connectiontimeout=5 timeout=30
 240       </pre>
 241
 242
 243       <p>This will create a worker associated with the origin server URL
 244       <code>http://backend.example.com</code> and using the given timeout
 245       values. When used in a forward proxy, workers are usually defined
 246       via the <code class="directive"><a href="#proxyset">ProxySet</a></code> directive:</p>
 247
 248       <pre class="prettyprint lang-config">
 249           ProxySet http://backend.example.com connectiontimeout=5 timeout=30
 250       </pre>
 251
 252
 253       <p>or alternatively using <code class="directive"><a href="#proxy">Proxy</a></code>
 254       and <code class="directive"><a href="#proxyset">ProxySet</a></code>:</p>
 255
 256       <pre class="prettyprint lang-config">
 257 &lt;Proxy http://backend.example.com&gt;
 258   ProxySet connectiontimeout=5 timeout=30
 259 &lt;/Proxy&gt;
 260       </pre>
 261
 262
 263       <p>Using explicitly configured workers in the forward mode is
 264       not very common, because forward proxies usually communicate with many
 265       different origin servers. Creating explicit workers for some of the
 266       origin servers can still be useful, if they are used very often.
 267       Explicitly configured workers have no concept of forward or reverse
 268       proxying by themselves. They encapsulate a common concept of
 269       communication with origin servers. A worker created by
 270       <code class="directive"><a href="#proxypass">ProxyPass</a></code> for use in a
 271       reverse proxy will be also used for forward proxy requests whenever
 272       the URL to the origin server matches the worker URL and vice versa.</p>
 273
 274       <p>The URL identifying a direct worker is the URL of its
 275       origin server including any path components given:</p>
 276
 277      <pre class="prettyprint lang-config">
 278 ProxyPass /examples http://backend.example.com/examples
 279 ProxyPass /docs http://backend.example.com/docs
 280       </pre>
 281
 282
 283       <p>This example defines two different workers, each using a separate
 284       connection pool and configuration.</p>
 285
 286       <div class="warning"><h3>Worker Sharing</h3>
 287         <p>Worker sharing happens if the worker URLs overlap, which occurs when
 288         the URL of some worker is a leading substring of the URL of another
 289         worker defined later in the configuration file. In the following example</p>
 290
 291         <pre class="prettyprint lang-config">
 292 ProxyPass /apps http://backend.example.com/ timeout=60
 293 ProxyPass /examples http://backend.example.com/examples timeout=10
 294         </pre>
 295
 296
 297         <p>the second worker isn't actually created. Instead the first
 298         worker is used. The benefit is, that there is only one connection pool,
 299         so connections are more often reused. Note that all configuration attributes
 300         given explicitly for the later worker will be ignored. This will be logged
 301         as a warning. In the above example the resulting timeout value
 302         for the URL <code>/examples</code> will be <code>60</code> instead
 303         of <code>10</code>!</p>
 304
 305         <p>If you want to avoid worker sharing, sort your worker definitions
 306         by URL length, starting with the longest worker URLs. If you want to maximize
 307         worker sharing use the reverse sort order. See also the related warning about
 308         ordering <code class="directive"><a href="#proxypass">ProxyPass</a></code> directives.</p>
 309
 310       </div>
 311
 312       <p>Explicitly configured workers come in two flavors:
 313       <dfn>direct workers</dfn> and <dfn>(load) balancer workers</dfn>.
 314       They support many important configuration attributes which are
 315       described below in the <code class="directive"><a href="#proxypass">ProxyPass</a></code>
 316       directive. The same attributes can also be set using
 317       <code class="directive"><a href="#proxyset">ProxySet</a></code>.</p>
 318
 319       <p>The set of options available for a direct worker
 320       depends on the protocol, which is specified in the origin server URL.
 321       Available protocols include <code>ajp</code>, <code>fcgi</code>,
 322       <code>ftp</code>, <code>http</code> and <code>scgi</code>.</p>
 323
 324       <p>Balancer workers are virtual workers that use direct workers known
 325       as their members to actually handle the requests. Each balancer can
 326       have multiple members. When it handles a request, it chooses a member
 327       based on the configured load balancing algorithm.</p>
 328
 329       <p>A balancer worker is created if its worker URL uses
 330       <code>balancer</code> as the protocol scheme.
 331       The balancer URL uniquely identifies the balancer worker.
 332       Members are added to a balancer using
 333       <code class="directive"><a href="#balancermember">BalancerMember</a></code>.</p>
 334
 335     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 336 <div class="section">
 337 <h2><a name="access" id="access">Controlling access to your proxy</a></h2>
 338       <p>You can control who can access your proxy via the <code class="directive"><a href="#proxy">&lt;Proxy&gt;</a></code> control block as in
 339       the following example:</p>
 340
 341       <pre class="prettyprint lang-config">
 342 &lt;Proxy *&gt;
 343   Require ip 192.168.0
 344 &lt;/Proxy&gt;
 345       </pre>
 346
 347
 348       <p>For more information on access control directives, see
 349       <code class="module"><a href="../mod/mod_authz_host.html">mod_authz_host</a></code>.</p>
 350
 351       <p>Strictly limiting access is essential if you are using a
 352       forward proxy (using the <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> directive).
 353       Otherwise, your server can be used by any client to access
 354       arbitrary hosts while hiding his or her true identity.  This is
 355       dangerous both for your network and for the Internet at large.
 356       When using a reverse proxy (using the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive with
 357       <code>ProxyRequests Off</code>), access control is less
 358       critical because clients can only contact the hosts that you
 359       have specifically configured.</p>
 360
 361       <p><strong>See Also</strong> the <a href="mod_proxy_http.html#env">Proxy-Chain-Auth</a> environment variable.</p>
 362
 363     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 364 <div class="section">
 365 <h2><a name="startup" id="startup">Slow Startup</a></h2>
 366       <p>If you're using the <code class="directive"><a href="#proxyblock">ProxyBlock</a></code> directive, hostnames' IP addresses are looked up
 367       and cached during startup for later match test. This may take a few
 368       seconds (or more) depending on the speed with which the hostname lookups
 369       occur.</p>
 370     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 371 <div class="section">
 372 <h2><a name="intranet" id="intranet">Intranet Proxy</a></h2>
 373       <p>An Apache httpd proxy server situated in an intranet needs to forward
 374       external requests through the company's firewall (for this, configure
 375       the <code class="directive"><a href="#proxyremote">ProxyRemote</a></code> directive
 376       to forward the respective <var>scheme</var> to the firewall proxy).
 377       However, when it has to
 378       access resources within the intranet, it can bypass the firewall when
 379       accessing hosts. The <code class="directive"><a href="#noproxy">NoProxy</a></code>
 380       directive is useful for specifying which hosts belong to the intranet and
 381       should be accessed directly.</p>
 382
 383       <p>Users within an intranet tend to omit the local domain name from their
 384       WWW requests, thus requesting "http://somehost/" instead of
 385       <code>http://somehost.example.com/</code>. Some commercial proxy servers
 386       let them get away with this and simply serve the request, implying a
 387       configured local domain. When the <code class="directive"><a href="#proxydomain">ProxyDomain</a></code> directive is used and the server is <a href="#proxyrequests">configured for proxy service</a>, Apache httpd can return
 388       a redirect response and send the client to the correct, fully qualified,
 389       server address. This is the preferred method since the user's bookmark
 390       files will then contain fully qualified hosts.</p>
 391     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 392 <div class="section">
 393 <h2><a name="envsettings" id="envsettings">Protocol Adjustments</a></h2>
 394       <p>For circumstances where <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> is sending
 395       requests to an origin server that doesn't properly implement
 396       keepalives or HTTP/1.1, there are two <a href="../env.html">environment variables</a> that can force the
 397       request to use HTTP/1.0 with no keepalive. These are set via the
 398       <code class="directive"><a href="../mod/mod_env.html#setenv">SetEnv</a></code> directive.</p>
 399
 400       <p>These are the <code>force-proxy-request-1.0</code> and
 401       <code>proxy-nokeepalive</code> notes.</p>
 402
 403       <pre class="prettyprint lang-config">
 404 &lt;Location /buggyappserver/&gt;
 405   ProxyPass http://buggyappserver:7001/foo/
 406   SetEnv force-proxy-request-1.0 1
 407   SetEnv proxy-nokeepalive 1
 408 &lt;/Location&gt;
 409         </pre>
 410
 411
 412     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 413 <div class="section">
 414 <h2><a name="request-bodies" id="request-bodies">Request Bodies</a></h2>
 415
 416     <p>Some request methods such as POST include a request body.
 417     The HTTP protocol requires that requests which include a body
 418     either use chunked transfer encoding or send a
 419     <code>Content-Length</code> request header.  When passing these
 420     requests on to the origin server, <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code>
 421     will always attempt to send the <code>Content-Length</code>.  But
 422     if the body is large and the original request used chunked
 423     encoding, then chunked encoding may also be used in the upstream
 424     request.  You can control this selection using <a href="../env.html">environment variables</a>.  Setting
 425     <code>proxy-sendcl</code> ensures maximum compatibility with
 426     upstream servers by always sending the
 427     <code>Content-Length</code>, while setting
 428     <code>proxy-sendchunked</code> minimizes resource usage by using
 429     chunked encoding.</p>
 430
 431     <p>Under some circumstances, the server must spool request bodies
 432     to disk to satisfy the requested handling of request bodies.  For
 433     example, this spooling will occur if the original body was sent with
 434     chunked encoding (and is large), but the administrator has
 435     asked for backend requests to be sent with Content-Length or as HTTP/1.0.
 436     This spooling can also occur if the request body already has a
 437     Content-Length header, but the server is configured to filter incoming
 438     request bodies.</p>
 439
 440     <p><code class="directive"><a href="../mod/core.html#limitrequestbody">LimitRequestBody</a></code> only applies to
 441     request bodies that the server will spool to disk</p>
 442
 443     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 444 <div class="section">
 445 <h2><a name="x-headers" id="x-headers">Reverse Proxy Request Headers</a></h2>
 446
 447     <p>When acting in a reverse-proxy mode (using the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive, for example),
 448     <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code> adds several request headers in
 449     order to pass information to the origin server. These headers
 450     are:</p>
 451
 452     <dl>
 453       <dt><code>X-Forwarded-For</code></dt>
 454       <dd>The IP address of the client.</dd>
 455       <dt><code>X-Forwarded-Host</code></dt>
 456       <dd>The original host requested by the client in the <code>Host</code>
 457        HTTP request header.</dd>
 458       <dt><code>X-Forwarded-Server</code></dt>
 459       <dd>The hostname of the proxy server.</dd>
 460     </dl>
 461
 462     <p>Be careful when using these headers on the origin server, since
 463     they will contain more than one (comma-separated) value if the
 464     original request already contained one of these headers. For
 465     example, you can use <code>%{X-Forwarded-For}i</code> in the log
 466     format string of the origin server to log the original clients IP
 467     address, but you may get more than one address if the request
 468     passes through several proxies.</p>
 469
 470     <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
 471     other request headers.</p>
 472
 473    </div>
 474 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 475 <div class="directive-section"><h2><a name="BalancerGrowth" id="BalancerGrowth">BalancerGrowth</a> <a name="balancergrowth" id="balancergrowth">Directive</a></h2>
 476 <table class="directive">
 477 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of additional Balancers that can be added Post-configuration</td></tr>
 478 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerGrowth <var>#</var></code></td></tr>
 479 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BalancerGrowth 5</code></td></tr>
 480 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 481 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 482 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
 483 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerGrowth is only available in Apache HTTP Server 2.3.13
 484   and later.</td></tr>
 485 </table>
 486     <p>This directive allows for growth potential in the number of
 487     Balancers available for a virtualhost in addition to the
 488     number pre-configured. It only takes effect if there is at
 489     least 1 pre-configured Balancer.</p>
 490
 491 </div>
 492 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 493 <div class="directive-section"><h2><a name="BalancerInherit" id="BalancerInherit">BalancerInherit</a> <a name="balancerinherit" id="balancerinherit">Directive</a></h2>
 494 <table class="directive">
 495 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Inherit proxy Balancers/Workers defined from the main server</td></tr>
 496 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerInherit On|Off</code></td></tr>
 497 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BalancerInherit On</code></td></tr>
 498 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 499 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 500 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
 501 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerInherit is only available in Apache HTTP Server 2.4.4 and later.
 502         and later.</td></tr>
 503 </table>
 504         <p>This directive will cause the current server/vhost to "inherit"
 505             Balancers and Workers defined in the main server. This can cause issues and
 506             inconsistent behavior if using the Balancer Manager for dynamic changes
 507             and so should be disabled if using that feature.</p>
 508         <p>The setting in the global server defines the default for all vhosts.</p>
 509         <p>Disabling <code class="directive"><a href="#proxypassinherit">ProxyPassInherit</a></code> also disables BalancerInherit.</p>
 510
 511 </div>
 512 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 513 <div class="directive-section"><h2><a name="BalancerMember" id="BalancerMember">BalancerMember</a> <a name="balancermember" id="balancermember">Directive</a></h2>
 514 <table class="directive">
 515 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add a member to a load balancing group</td></tr>
 516 <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>
 517 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
 518 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 519 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
 520 </table>
 521         <p>This directive adds a member to a load balancing group. It could be used
 522             within a <code>&lt;Proxy <var>balancer://</var>...&gt;</code> container
 523             directive, and can take any of the key value pair parameters available to
 524             <code class="directive"><a href="#proxypass">ProxyPass</a></code> directives.</p>
 525         <p>One additional parameter is available only to <code class="directive"><a href="#balancermember">BalancerMember</a></code> directives:
 526             <var>loadfactor</var>. This is the member load factor - a number between 1
 527             (default) and 100, which defines the weighted load to be applied to the
 528             member in question.</p>
 529         <p>The balancerurl is only needed when not in <code>&lt;Proxy <var>balancer://</var>...&gt;</code>
 530             container directive. It corresponds to the url of a balancer defined in
 531             <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p>
 532         <p>The path component of the balancer URL in any
 533             <code>&lt;Proxy <var>balancer://</var>...&gt;</code> container directive
 534             is ignored.</p>
 535         <p>Trailing slashes should typically be removed from the URL of a
 536             <code>BalancerMember</code>.</p>
 537
 538 </div>
 539 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 540 <div class="directive-section"><h2><a name="BalancerPersist" id="BalancerPersist">BalancerPersist</a> <a name="balancerpersist" id="balancerpersist">Directive</a></h2>
 541 <table class="directive">
 542 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Attempt to persist changes made by the Balancer Manager across restarts.</td></tr>
 543 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>BalancerPersist On|Off</code></td></tr>
 544 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>BalancerPersist Off</code></td></tr>
 545 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 546 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 547 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
 548 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>BalancerPersist is only available in Apache HTTP Server 2.5.0
 549         and later.</td></tr>
 550 </table>
 551         <p>This directive will cause the shared memory storage associated
 552         with the balancers and balancer members to be persisted across
 553         restarts. This allows these local changes to not be lost during the
 554         normal restart/graceful state transitions.</p>
 555
 556 </div>
 557 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 558 <div class="directive-section"><h2><a name="NoProxy" id="NoProxy">NoProxy</a> <a name="noproxy" id="noproxy">Directive</a></h2>
 559 <table class="directive">
 560 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Hosts, domains, or networks that will be connected to
 561 directly</td></tr>
 562 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>NoProxy <var>host</var> [<var>host</var>] ...</code></td></tr>
 563 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 564 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 565 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
 566 </table>
 567     <p>This directive is only useful for Apache httpd proxy servers within
 568     intranets.  The <code class="directive">NoProxy</code> directive specifies a
 569     list of subnets, IP addresses, hosts and/or domains, separated by
 570     spaces. A request to a host which matches one or more of these is
 571     always served directly, without forwarding to the configured
 572     <code class="directive"><a href="#proxyremote">ProxyRemote</a></code> proxy server(s).</p>
 573
 574     <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">
 575 ProxyRemote  *  http://firewall.example.com:81
 576 NoProxy         .example.com 192.168.112.0/21
 577     </pre>
 578 </div>
 579
 580     <p>The <var>host</var> arguments to the <code class="directive">NoProxy</code>
 581     directive are one of the following type list:</p>
 582
 583     <dl>
 584
 585     <dt><var><a name="domain" id="domain">Domain</a></var></dt>
 586     <dd>
 587     <p>A <dfn>Domain</dfn> is a partially qualified DNS domain name, preceded
 588     by a period. It represents a list of hosts which logically belong to the
 589     same DNS domain or zone (<em>i.e.</em>, the suffixes of the hostnames are
 590     all ending in <var>Domain</var>).</p>
 591
 592     <div class="example"><h3>Examples</h3><p><code>
 593       .com .example.org.
 594     </code></p></div>
 595
 596     <p>To distinguish <var>Domain</var>s from <var><a href="#hostname">Hostname</a></var>s (both syntactically and semantically; a DNS domain can
 597     have a DNS A record, too!), <var>Domain</var>s are always written with a
 598     leading period.</p>
 599
 600     <div class="note"><h3>Note</h3>
 601       <p>Domain name comparisons are done without regard to the case, and
 602       <var>Domain</var>s are always assumed to be anchored in the root of the
 603       DNS tree, therefore two domains <code>.ExAmple.com</code> and
 604       <code>.example.com.</code> (note the trailing period) are considered
 605       equal. Since a domain comparison does not involve a DNS lookup, it is much
 606       more efficient than subnet comparison.</p>
 607     </div></dd>
 608
 609
 610     <dt><var><a name="subnet" id="subnet">SubNet</a></var></dt>
 611     <dd>
 612     <p>A <dfn>SubNet</dfn> is a partially qualified internet address in
 613     numeric (dotted quad) form, optionally followed by a slash and the netmask,
 614     specified as the number of significant bits in the <var>SubNet</var>. It is
 615     used to represent a subnet of hosts which can be reached over a common
 616     network interface. In the absence of the explicit net mask it is assumed
 617     that omitted (or zero valued) trailing digits specify the mask. (In this
 618     case, the netmask can only be multiples of 8 bits wide.) Examples:</p>
 619
 620     <dl>
 621     <dt><code>192.168</code> or <code>192.168.0.0</code></dt>
 622     <dd>the subnet 192.168.0.0 with an implied netmask of 16 valid bits
 623     (sometimes used in the netmask form <code>255.255.0.0</code>)</dd>
 624     <dt><code>192.168.112.0/21</code></dt>
 625     <dd>the subnet <code>192.168.112.0/21</code> with a netmask of 21
 626     valid bits (also used in the form <code>255.255.248.0</code>)</dd>
 627     </dl>
 628
 629     <p>As a degenerate case, a <em>SubNet</em> with 32 valid bits is the
 630     equivalent to an <var><a href="#ipaddr">IPAddr</a></var>, while a <var>SubNet</var> with zero
 631     valid bits (<em>e.g.</em>, 0.0.0.0/0) is the same as the constant
 632     <var>_Default_</var>, matching any IP address.</p></dd>
 633
 634
 635     <dt><var><a name="ipaddr" id="ipaddr">IPAddr</a></var></dt>
 636     <dd>
 637     <p>A <dfn>IPAddr</dfn> represents a fully qualified internet address in
 638     numeric (dotted quad) form. Usually, this address represents a host, but
 639     there need not necessarily be a DNS domain name connected with the
 640     address.</p>
 641     <div class="example"><h3>Example</h3><p><code>
 642       192.168.123.7
 643     </code></p></div>
 644
 645     <div class="note"><h3>Note</h3>
 646       <p>An <var>IPAddr</var> does not need to be resolved by the DNS system, so
 647       it can result in more effective apache performance.</p>
 648     </div></dd>
 649
 650
 651     <dt><var><a name="hostname" id="hostname">Hostname</a></var></dt>
 652     <dd>
 653     <p>A <dfn>Hostname</dfn> is a fully qualified DNS domain name which can
 654     be resolved to one or more <var><a href="#ipaddr">IPAddrs</a></var> via the
 655     DNS domain name service. It represents a logical host (in contrast to
 656     <var><a href="#domain">Domain</a></var>s, see above) and must be resolvable
 657     to at least one <var><a href="#ipaddr">IPAddr</a></var> (or often to a list
 658     of hosts with different <var><a href="#ipaddr">IPAddr</a></var>s).</p>
 659
 660     <div class="example"><h3>Examples</h3><p><code>
 661       prep.ai.example.edu<br />
 662       www.example.org
 663     </code></p></div>
 664
 665     <div class="note"><h3>Note</h3>
 666       <p>In many situations, it is more effective to specify an <var><a href="#ipaddr">IPAddr</a></var> in place of a <var>Hostname</var> since a
 667       DNS lookup can be avoided. Name resolution in Apache httpd can take a remarkable
 668       deal of time when the connection to the name server uses a slow PPP
 669       link.</p>
 670       <p><var>Hostname</var> comparisons are done without regard to the case,
 671       and <var>Hostname</var>s are always assumed to be anchored in the root
 672       of the DNS tree, therefore two hosts <code>WWW.ExAmple.com</code>
 673       and <code>www.example.com.</code> (note the trailing period) are
 674       considered equal.</p>
 675      </div></dd>
 676     </dl>
 677
 678 <h3>See also</h3>
 679 <ul>
 680 <li><a href="../dns-caveats.html">DNS Issues</a></li>
 681 </ul>
 682 </div>
 683 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 684 <div class="directive-section"><h2><a name="Proxy" id="Proxy">&lt;Proxy&gt;</a> <a name="proxy" id="proxy">Directive</a></h2>
 685 <table class="directive">
 686 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Container for directives applied to proxied resources</td></tr>
 687 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;Proxy <var>wildcard-url</var>&gt; ...&lt;/Proxy&gt;</code></td></tr>
 688 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 689 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 690 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
 691 </table>
 692     <p>Directives placed in <code class="directive">&lt;Proxy&gt;</code>
 693     sections apply only to matching proxied content.  Shell-style wildcards are
 694     allowed.</p>
 695
 696     <p>For example, the following will allow only hosts in
 697     <code>yournetwork.example.com</code> to access content via your proxy
 698     server:</p>
 699
 700     <pre class="prettyprint lang-config">
 701 &lt;Proxy *&gt;
 702   Require host yournetwork.example.com
 703 &lt;/Proxy&gt;
 704     </pre>
 705
 706
 707     <p>The following example will process all files in the <code>foo</code>
 708     directory of <code>example.com</code> through the <code>INCLUDES</code>
 709     filter when they are sent through the proxy server:</p>
 710
 711    <pre class="prettyprint lang-config">
 712 &lt;Proxy http://example.com/foo/*&gt;
 713   SetOutputFilter INCLUDES
 714 &lt;/Proxy&gt;
 715     </pre>
 716
 717
 718
 719 <h3>See also</h3>
 720 <ul>
 721 <li><code class="directive"><a href="#proxymatch">&lt;ProxyMatch&gt;</a></code></li>
 722 </ul>
 723 </div>
 724 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 725 <div class="directive-section"><h2><a name="ProxyAddHeaders" id="ProxyAddHeaders">ProxyAddHeaders</a> <a name="proxyaddheaders" id="proxyaddheaders">Directive</a></h2>
 726 <table class="directive">
 727 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add proxy information in X-Forwarded-* headers</td></tr>
 728 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyAddHeaders Off|On</code></td></tr>
 729 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyAddHeaders On</code></td></tr>
 730 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
 731 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 732 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
 733 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.10 and later</td></tr>
 734 </table>
 735     <p>This directive determines whether or not proxy related information should be passed to the
 736     backend server through X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Server HTTP headers.</p>
 737     <div class="note"><h3>Effectiveness</h3>
 738      <p>This option is of use only for HTTP proxying, as handled by <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code>.</p>
 739     </div>
 740
 741 </div>
 742 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 743 <div class="directive-section"><h2><a name="ProxyBadHeader" id="ProxyBadHeader">ProxyBadHeader</a> <a name="proxybadheader" id="proxybadheader">Directive</a></h2>
 744 <table class="directive">
 745 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines how to handle bad header lines in a
 746 response</td></tr>
 747 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyBadHeader IsError|Ignore|StartBody</code></td></tr>
 748 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyBadHeader IsError</code></td></tr>
 749 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 750 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 751 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
 752 </table>
 753     <p>The <code class="directive">ProxyBadHeader</code> directive determines the
 754     behaviour of <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> if it receives syntactically invalid
 755     response header lines (<em>i.e.</em> containing no colon) from the origin
 756     server. The following arguments are possible:</p>
 757
 758     <dl>
 759     <dt><code>IsError</code></dt>
 760     <dd>Abort the request and end up with a 502 (Bad Gateway) response. This is
 761     the default behaviour.</dd>
 762
 763     <dt><code>Ignore</code></dt>
 764     <dd>Treat bad header lines as if they weren't sent.</dd>
 765
 766     <dt><code>StartBody</code></dt>
 767     <dd>When receiving the first bad header line, finish reading the headers and
 768     treat the remainder as body. This helps to work around buggy backend servers
 769     which forget to insert an empty line between the headers and the body.</dd>
 770     </dl>
 771
 772 </div>
 773 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 774 <div class="directive-section"><h2><a name="ProxyBlock" id="ProxyBlock">ProxyBlock</a> <a name="proxyblock" id="proxyblock">Directive</a></h2>
 775 <table class="directive">
 776 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Disallow proxy requests to certain hosts</td></tr>
 777 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyBlock *|<var>hostname</var>|<var>partial-hostname</var> [<var>hostname</var>|<var>partial-hostname</var>]...</code></td></tr>
 778 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 779 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 780 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
 781 </table>
 782     <p>The <code class="directive">ProxyBlock</code> directive can be used to
 783     block FTP or HTTP access to certain hosts via the proxy, based on
 784     a full or partial hostname match, or, if applicable, an IP address
 785     comparison.</p>
 786
 787     <p>Each of the arguments to the <code class="directive">ProxyBlock</code>
 788     directive can be either <code>*</code> or a alphanumeric string.
 789     At startup, the module will attempt to resolve every alphanumeric
 790     string from a DNS name to a set of IP addresses, but any DNS errors
 791     are ignored.</p>
 792
 793     <p>If an asterisk "<code>*</code>" argument is specified,
 794     <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> will deny access to all FTP or HTTP
 795     sites.</p>
 796
 797     <p>Otherwise, for any request for an HTTP or FTP resource via the
 798     proxy, <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> will check the hostname of the
 799     request URI against each specified string.  If a partial string
 800     match is found, access is denied.  If no matches against hostnames
 801     are found, and a remote (forward) proxy is configured using
 802     <code class="directive">ProxyRemote</code> or
 803     <code class="directive">ProxyRemoteMatch</code>, access is allowed.  If no
 804     remote (forward) proxy is configured, the IP address of the
 805     hostname from the URI is compared against all resolved IP
 806     addresses determined at startup.  Access is denied if any match is
 807     found.</p>
 808
 809     <p>Note that the DNS lookups may slow down the startup time of the
 810     server.</p>
 811
 812     <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">
 813       ProxyBlock news.example.com auctions.example.com friends.example.com
 814       </pre>
 815 </div>
 816
 817     <p>Note that <code>example</code> would also be sufficient to match any
 818     of these sites.</p>
 819
 820     <p>Hosts would also be matched if referenced by IP address.</p>
 821
 822     <p>Note also that</p>
 823
 824     <pre class="prettyprint lang-config">
 825       ProxyBlock *
 826     </pre>
 827
 828
 829     <p>blocks connections to all sites.</p>
 830
 831 </div>
 832 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 833 <div class="directive-section"><h2><a name="ProxyDomain" id="ProxyDomain">ProxyDomain</a> <a name="proxydomain" id="proxydomain">Directive</a></h2>
 834 <table class="directive">
 835 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Default domain name for proxied requests</td></tr>
 836 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyDomain <var>Domain</var></code></td></tr>
 837 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 838 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 839 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
 840 </table>
 841     <p>This directive is only useful for Apache httpd proxy servers within
 842     intranets. The <code class="directive">ProxyDomain</code> directive specifies
 843     the default domain which the apache proxy server will belong to. If a
 844     request to a host without a domain name is encountered, a redirection
 845     response to the same host with the configured <var>Domain</var> appended
 846     will be generated.</p>
 847
 848     <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">
 849       ProxyRemote  *  http://firewall.example.com:81<br />
 850       NoProxy         .example.com 192.168.112.0/21<br />
 851       ProxyDomain     .example.com
 852       </pre>
 853 </div>
 854
 855 </div>
 856 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 857 <div class="directive-section"><h2><a name="ProxyErrorOverride" id="ProxyErrorOverride">ProxyErrorOverride</a> <a name="proxyerroroverride" id="proxyerroroverride">Directive</a></h2>
 858 <table class="directive">
 859 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Override error pages for proxied content</td></tr>
 860 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyErrorOverride On|Off</code></td></tr>
 861 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyErrorOverride Off</code></td></tr>
 862 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
 863 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 864 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
 865 </table>
 866     <p>This directive is useful for reverse-proxy setups, where you want to
 867     have a common look and feel on the error pages seen by the end user.
 868     This also allows for included files (via
 869     <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>'s SSI) to get
 870     the error code and act accordingly (default behavior would display
 871     the error page of the proxied server, turning this on shows the SSI
 872     Error message).</p>
 873
 874     <p>This directive does not affect the processing of informational (1xx),
 875     normal success (2xx), or redirect (3xx) responses.</p>
 876
 877 </div>
 878 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 879 <div class="directive-section"><h2><a name="ProxyIOBufferSize" id="ProxyIOBufferSize">ProxyIOBufferSize</a> <a name="proxyiobuffersize" id="proxyiobuffersize">Directive</a></h2>
 880 <table class="directive">
 881 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determine size of internal data throughput buffer</td></tr>
 882 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyIOBufferSize <var>bytes</var></code></td></tr>
 883 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyIOBufferSize 8192</code></td></tr>
 884 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 885 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 886 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
 887 </table>
 888     <p>The <code class="directive">ProxyIOBufferSize</code> directive adjusts the size
 889     of the internal buffer, which is used as a scratchpad for the data between
 890     input and output. The size must be at least <code>512</code>.</p>
 891
 892     <p>In almost every case there's no reason to change that value.</p>
 893
 894     <p>If used with AJP this directive sets the maximum AJP packet size in
 895     bytes. Values larger than 65536 are set to 65536. If you change it from
 896     the default, you must also change the <code>packetSize</code> attribute of
 897     your AJP connector on the Tomcat side! The attribute
 898     <code>packetSize</code> is only available in Tomcat <code>5.5.20+</code>
 899     and <code>6.0.2+</code></p>
 900
 901     <p>Normally it is not necessary to change the maximum packet size.
 902     Problems with the default value have been reported when sending
 903     certificates or certificate chains.</p>
 904
 905
 906 </div>
 907 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 908 <div class="directive-section"><h2><a name="ProxyMatch" id="ProxyMatch">&lt;ProxyMatch&gt;</a> <a name="proxymatch" id="proxymatch">Directive</a></h2>
 909 <table class="directive">
 910 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Container for directives applied to regular-expression-matched
 911 proxied resources</td></tr>
 912 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>&lt;ProxyMatch <var>regex</var>&gt; ...&lt;/ProxyMatch&gt;</code></td></tr>
 913 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 914 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 915 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
 916 </table>
 917     <p>The <code class="directive">&lt;ProxyMatch&gt;</code> directive is
 918     identical to the <code class="directive"><a href="#proxy">&lt;Proxy&gt;</a></code> directive, except it matches URLs
 919     using <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expressions</a>.</p>
 920
 921 <h3>See also</h3>
 922 <ul>
 923 <li><code class="directive"><a href="#proxy">&lt;Proxy&gt;</a></code></li>
 924 </ul>
 925 </div>
 926 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 927 <div class="directive-section"><h2><a name="ProxyMaxForwards" id="ProxyMaxForwards">ProxyMaxForwards</a> <a name="proxymaxforwards" id="proxymaxforwards">Directive</a></h2>
 928 <table class="directive">
 929 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximium number of proxies that a request can be forwarded
 930 through</td></tr>
 931 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyMaxForwards <var>number</var></code></td></tr>
 932 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyMaxForwards -1</code></td></tr>
 933 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 934 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 935 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
 936 </table>
 937     <p>The <code class="directive">ProxyMaxForwards</code> directive specifies the
 938     maximum number of proxies through which a request may pass, if there's no
 939     <code>Max-Forwards</code> header supplied with the request. This may
 940     be set to prevent infinite proxy loops, or a DoS attack.</p>
 941
 942     <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">
 943       ProxyMaxForwards 15
 944       </pre>
 945 </div>
 946
 947     <p>Note that setting <code class="directive">ProxyMaxForwards</code> is a
 948     violation of the HTTP/1.1 protocol (RFC2616), which forbids a Proxy
 949     setting <code>Max-Forwards</code> if the Client didn't set it.
 950     Earlier Apache httpd versions would always set it.  A negative
 951     <code class="directive">ProxyMaxForwards</code> value, including the
 952     default -1, gives you protocol-compliant behaviour, but may
 953     leave you open to loops.</p>
 954
 955 </div>
 956 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 957 <div class="directive-section"><h2><a name="ProxyPass" id="ProxyPass">ProxyPass</a> <a name="proxypass" id="proxypass">Directive</a></h2>
 958 <table class="directive">
 959 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maps remote servers into the local server URL-space</td></tr>
 960 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPass [<var>path</var>] !|<var>url</var> [<var>key=value</var>
 961   <var>[key=value</var> ...]] [nocanon] [interpolate] [noquery]</code></td></tr>
 962 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
 963 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 964 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
 965 </table>
 966     <p>This directive allows remote servers to be mapped into the
 967     space of the local server; the local server does not act as a
 968     proxy in the conventional sense, but appears to be a mirror of the
 969     remote server. The local server is often called a <dfn>reverse
 970     proxy</dfn> or <dfn>gateway</dfn>. The <var>path</var> is the name of
 971     a local virtual path; <var>url</var> is a partial URL for the
 972     remote server and cannot include a query string.</p>
 973
 974     <div class="note"><strong>Note: </strong>This directive cannot be used within a
 975     <code>&lt;Directory&gt;</code> context.</div>
 976
 977     <div class="warning">The <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> directive should
 978     usually be set <strong>off</strong> when using
 979     <code class="directive">ProxyPass</code>.</div>
 980
 981     <p>Suppose the local server has address <code>http://example.com/</code>;
 982     then</p>
 983
 984     <pre class="prettyprint lang-config">
 985 &lt;Location /mirror/foo/&gt;
 986     ProxyPass http://backend.example.com/
 987 &lt;/Location&gt;
 988     </pre>
 989
 990
 991     <p>will cause a local request for
 992     <code>http://example.com/mirror/foo/bar</code> to be internally converted
 993     into a proxy request to <code>http://backend.example.com/bar</code>.</p>
 994
 995     <p>The following alternative syntax is possible, however it can carry a
 996     performance penalty when present in very large numbers. The advantage of
 997     the below syntax is that it allows for dynamic control via the
 998     <a href="mod_proxy_balancer.html#balancer_manager">Balancer Manager</a> interface:</p>
 999
1000     <pre class="prettyprint lang-config">
1001         ProxyPass /mirror/foo/ http://backend.example.com/
1002     </pre>
1003
1004
1005     <div class="warning">
1006     <p>If the first argument ends with a trailing <strong>/</strong>, the second
1007        argument should also end with a trailing <strong>/</strong> and vice
1008        versa. Otherwise the resulting requests to the backend may miss some
1009        needed slashes and do not deliver the expected results.
1010     </p>
1011     </div>
1012
1013     <p>The <code>!</code> directive is useful in situations where you don't want
1014     to reverse-proxy a subdirectory, <em>e.g.</em></p>
1015
1016     <pre class="prettyprint lang-config">
1017 &lt;Location /mirror/foo/&gt;
1018     ProxyPass http://backend.example.com/
1019 &lt;/Location&gt;
1020 &lt;Location /mirror/foo/i&gt;
1021     ProxyPass !
1022 &lt;/Location&gt;
1023     </pre>
1024
1025
1026     <pre class="prettyprint lang-config">
1027 ProxyPass /mirror/foo/i !
1028 ProxyPass /mirror/foo http://backend.example.com
1029     </pre>
1030
1031
1032     <p>will proxy all requests to <code>/mirror/foo</code> to
1033     <code>backend.example.com</code> <em>except</em> requests made to
1034     <code>/mirror/foo/i</code>.</p>
1035
1036     <div class="warning"><h3>Ordering ProxyPass Directives</h3>
1037       <p>The configured <code class="directive"><a href="#proxypass">ProxyPass</a></code>
1038       and <code class="directive"><a href="#proxypassmatch">ProxyPassMatch</a></code>
1039       rules are checked in the order of configuration. The first rule that
1040       matches wins. So usually you should sort conflicting
1041       <code class="directive"><a href="#proxypass">ProxyPass</a></code> rules starting with the
1042       longest URLs first. Otherwise later rules for longer URLS will be hidden
1043       by any earlier rule which uses a leading substring of the URL. Note that
1044       there is some relation with worker sharing. In contrast, only one
1045       <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive can be placed
1046       in a <code class="directive"><a href="../mod/core.html#location">Location</a></code> block, and the most
1047       specific location will take precedence.</p>
1048
1049       <p>For the same reasons exclusions must come <em>before</em> the
1050       general <code class="directive">ProxyPass</code> directives.</p>
1051
1052     </div>
1053
1054     <p>In Apache HTTP Server 2.1 and later, mod_proxy supports pooled
1055     connections to a backend server.  Connections created on demand
1056     can be retained in a pool for future use.  Limits on the pool size
1057     and other settings can be coded on
1058     the <code class="directive">ProxyPass</code> directive
1059     using  <code>key=value</code> parameters, described in the table
1060     below.</p>
1061
1062     <p>By default, mod_proxy will allow and retain the maximum number of
1063     connections that could be used simultaneously by that web server child
1064     process.  Use the <code>max</code> parameter to reduce the number from
1065     the default.  Use the <code>ttl</code> parameter to set an optional
1066     time to live; connections which have been unused for at least
1067     <code>ttl</code> seconds will be closed.  <code>ttl</code> can be used
1068     to avoid using a connection which is subject to closing because of the
1069     backend server's keep-alive timeout.</p>
1070
1071     <p>The pool of connections is maintained per web server child
1072     process, and <code>max</code> and other settings are not coordinated
1073     among all child processes, except when only one child process is allowed
1074     by configuration or MPM design.</p>
1075
1076     <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">
1077         ProxyPass /example http://backend.example.com max=20 ttl=120 retry=300
1078         </pre>
1079 </div>
1080
1081     <table class="bordered"><tr><th>BalancerMember parameters</th></tr></table>
1082     <table>
1083     <tr><th>Parameter</th>
1084         <th>Default</th>
1085         <th>Description</th></tr>
1086     <tr><td>min</td>
1087         <td>0</td>
1088         <td>Minimum number of connection pool entries, unrelated to the
1089     actual number of connections.  This only needs to be modified from the
1090     default for special circumstances where heap memory associated with the
1091     backend connections should be preallocated or retained.</td></tr>
1092     <tr><td>max</td>
1093         <td>1...n</td>
1094         <td>Maximum number of connections that will be allowed to the
1095     backend server. The default for this limit is the number of threads
1096     per process in the active MPM. In the Prefork MPM, this is always 1,
1097     while with other MPMs it is controlled by the
1098     <code class="directive">ThreadsPerChild</code> directive.</td></tr>
1099     <tr><td>smax</td>
1100         <td>max</td>
1101         <td>Retained connection pool entries above this limit are freed
1102     during certain operations if they have been unused for longer than
1103     the time to live, controlled by the <code>ttl</code> parameter.  If
1104     the connection pool entry has an associated connection, it will be
1105     closed.  This only needs to be modified from the default for special
1106     circumstances where connection pool entries and any associated
1107     connections which have exceeded the time to live need to be freed or
1108     closed more aggressively.</td></tr>
1109     <tr><td>acquire</td>
1110         <td>-</td>
1111         <td>If set this will be the maximum time to wait for a free
1112     connection in the connection pool, in milliseconds. If there are no free
1113     connections in the pool the Apache httpd will return <code>SERVER_BUSY</code>
1114     status to the client.
1115     </td></tr>
1116     <tr><td>connectiontimeout</td>
1117         <td>timeout</td>
1118         <td>Connect timeout in seconds.
1119         The number of seconds Apache httpd waits for the creation of a connection to
1120         the backend to complete. By adding a postfix of ms the timeout can be
1121         also set in milliseconds.
1122     </td></tr>
1123     <tr><td>disablereuse</td>
1124         <td>Off</td>
1125         <td>This parameter should be used when you want to force mod_proxy
1126     to immediately close a connection to the backend after being used, and
1127     thus, disable its persistent connection and pool for that backend.
1128     This helps in various situations where a firewall between Apache
1129     httpd and
1130     the backend server (regardless of protocol) tends to silently
1131     drop connections or when backends themselves may be under round-
1132     robin DNS. To disable connection pooling reuse,
1133     set this property value to <code>On</code>.
1134     </td></tr>
1135     <tr><td>flushpackets</td>
1136         <td>off</td>
1137         <td>Determines whether the proxy module will auto-flush the output
1138         brigade after each "chunk" of data. 'off' means that it will flush
1139         only when needed, 'on' means after each chunk is sent and
1140         'auto' means poll/wait for a period of time and flush if
1141         no input has been received for 'flushwait' milliseconds.
1142         Currently this is in effect only for AJP.
1143     </td></tr>
1144     <tr><td>flushwait</td>
1145         <td>10</td>
1146         <td>The time to wait for additional input, in milliseconds, before
1147         flushing the output brigade if 'flushpackets' is 'auto'.
1148     </td></tr>
1149     <tr><td>iobuffersize</td>
1150         <td>8192</td>
1151         <td>Adjusts the size of the internal scratchpad IO buffer. This allows you
1152         to override the <code class="directive">ProxyIOBufferSize</code> for a specific worker.
1153         This must be at least 512 or set to 0 for the system default of 8192.
1154     </td></tr>
1155     <tr><td>keepalive</td>
1156         <td>Off</td>
1157         <td><p>This parameter should be used when you have a firewall between your
1158     Apache httpd and the backend server, who tend to drop inactive connections.
1159     This flag will tell the Operating System to send <code>KEEP_ALIVE</code>
1160     messages on inactive connections  and thus prevent the firewall to drop the connection.
1161     To enable keepalive set this property value to <code>On</code>. </p>
1162     <p>The frequency of initial and subsequent TCP keepalive probes
1163     depends on global OS settings, and may be as high as 2 hours. To be useful,
1164     the frequency configured in the OS must be smaller than the threshold used
1165     by the firewall.</p>
1166     </td></tr>
1167     <tr><td>lbset</td>
1168         <td>0</td>
1169         <td>Sets the load balancer cluster set that the worker is a member
1170          of. The load balancer will try all members of a lower numbered
1171          lbset before trying higher numbered ones.
1172     </td></tr>
1173     <tr><td>ping</td>
1174         <td>0</td>
1175         <td>Ping property tells the webserver to "test" the connection to
1176         the backend before forwarding the request. For AJP, it causes
1177         <code class="module"><a href="../mod/mod_proxy_ajp.html">mod_proxy_ajp</a></code>to send a <code>CPING</code>
1178         request on the ajp13 connection (implemented on Tomcat 3.3.2+, 4.1.28+
1179         and 5.0.13+). For HTTP, it causes <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code>
1180         to send a <code>100-Continue</code> to the backend (only valid for
1181         HTTP/1.1 - for non HTTP/1.1 backends, this property has no
1182         effect). In both cases the parameter is the delay in seconds to wait
1183         for the reply.
1184         This feature has been added to avoid problems with hung and
1185         busy backends.
1186         This will increase the network traffic during the normal operation
1187         which could be an issue, but it will lower the
1188         traffic in case some of the cluster nodes are down or busy.
1189         By adding a postfix of ms the delay can be also set in
1190         milliseconds.
1191     </td></tr>
1192     <tr><td>receivebuffersize</td>
1193         <td>0</td>
1194         <td>Adjusts the size of the explicit (TCP/IP) network buffer size for
1195         proxied connections. This allows you to override the
1196         <code class="directive">ProxyReceiveBufferSize</code> for a specific worker.
1197         This must be at least 512 or set to 0 for the system default.
1198     </td></tr>
1199     <tr><td>redirect</td>
1200         <td>-</td>
1201         <td>Redirection Route of the worker. This value is usually
1202         set dynamically to enable safe removal of the node from
1203         the cluster. If set all requests without session id will be
1204         redirected to the BalancerMember that has route parameter
1205         equal as this value.
1206     </td></tr>
1207     <tr><td>retry</td>
1208         <td>60</td>
1209         <td>Connection pool worker retry timeout in seconds.
1210     If the connection pool worker to the backend server is in the error state,
1211     Apache httpd will not forward any requests to that server until the timeout
1212     expires. This enables to shut down the backend server for maintenance,
1213     and bring it back online later. A value of 0 means always retry workers
1214     in an error state with no timeout.
1215     </td></tr>
1216     <tr><td>route</td>
1217         <td>-</td>
1218         <td>Route of the worker when used inside load balancer.
1219         The route is a value appended to session id.
1220     </td></tr>
1221     <tr><td>status</td>
1222         <td>-</td>
1223         <td>Single letter value defining the initial status of
1224         this worker.
1225         <table>
1226          <tr><td>D: Worker is disabled and will not accept any requests.</td></tr>
1227          <tr><td>S: Worker is administratively stopped.</td></tr>
1228          <tr><td>I: Worker is in ignore-errors mode, and will always be considered available.</td></tr>
1229          <tr><td>H: Worker is in hot-standby mode and will only be used if no other
1230                     viable workers are available.</td></tr>
1231          <tr><td>E: Worker is in an error state.</td></tr>
1232          <tr><td>N: Worker is in drain mode, and will only accept existing sticky sessions
1233                     destined for itself and ignore all other requests.</td></tr>
1234         </table>Status
1235         can be set (which is the default) by prepending with '+' or
1236         cleared by prepending with '-'.
1237         Thus, a setting of 'S-E' sets this worker to Stopped and
1238         clears the in-error flag.
1239     </td></tr>
1240     <tr><td>timeout</td>
1241         <td><code class="directive"><a href="#proxytimeout">ProxyTimeout</a></code></td>
1242         <td>Connection timeout in seconds.
1243         The number of seconds Apache httpd waits for data sent by / to the backend.
1244     </td></tr>
1245     <tr><td>ttl</td>
1246         <td>-</td>
1247         <td>Time to live for inactive connections and associated connection
1248         pool entries, in seconds.  Once reaching this limit, a
1249         connection will not be used again; it will be closed at some
1250         later time.
1251     </td></tr>
1252
1253     </table>
1254
1255     <p>If the Proxy directive scheme starts with the
1256     <code>balancer://</code> (eg: <code>balancer://cluster</code>,
1257     any path information is ignored)  then a virtual worker that does not really
1258     communicate with the backend server will be created. Instead it is responsible
1259     for the management of several "real" workers. In that case the special set of
1260     parameters can be add to this virtual worker. See <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code>
1261     for more information about how the balancer works.
1262     </p>
1263     <table class="bordered"><tr><th>Balancer parameters</th></tr></table>
1264     <table>
1265     <tr><th>Parameter</th>
1266         <th>Default</th>
1267         <th>Description</th></tr>
1268     <tr><td>lbmethod</td>
1269         <td>byrequests</td>
1270         <td>Balancer load-balance method. Select the load-balancing scheduler
1271         method to use. Either <code>byrequests</code>, to perform weighted
1272         request counting, <code>bytraffic</code>, to perform weighted
1273         traffic byte count balancing, or <code>bybusyness</code>, to perform
1274         pending request balancing. Default is <code>byrequests</code>.
1275     </td></tr>
1276     <tr><td>maxattempts</td>
1277         <td>One less than the number of workers, or 1 with a single worker.</td>
1278         <td>Maximum number of failover attempts before giving up.
1279     </td></tr>
1280     <tr><td>nofailover</td>
1281         <td>Off</td>
1282         <td>If set to <code>On</code> the session will break if the worker is in
1283         error state or disabled. Set this value to On if backend servers do not
1284         support session replication.
1285     </td></tr>
1286     <tr><td>stickysession</td>
1287         <td>-</td>
1288         <td>Balancer sticky session name. The value is usually set to something
1289         like <code>JSESSIONID</code> or <code>PHPSESSIONID</code>,
1290         and it depends on the backend application server that support sessions.
1291         If the backend application server uses different name for cookies
1292         and url encoded id (like servlet containers) use | to to separate them.
1293         The first part is for the cookie the second for the path.
1294     </td></tr>
1295     <tr><td>stickysessionsep</td>
1296         <td>"."</td>
1297         <td>Sets the separation symbol in the session cookie. Some backend application servers
1298         do not use the '.' as the symbol. For example the Oracle Weblogic server uses
1299         '!'. The correct symbol can be set using this option. The setting of 'Off'
1300         signifies that no symbol is used.
1301     </td></tr>
1302     <tr><td>scolonpathdelim</td>
1303         <td>Off</td>
1304         <td>If set to <code>On</code> the semi-colon character ';' will be
1305         used as an additional sticky session path deliminator/separator. This
1306         is mainly used to emulate mod_jk's behavior when dealing with paths such
1307         as <code>JSESSIONID=6736bcf34;foo=aabfa</code>
1308     </td></tr>
1309     <tr><td>timeout</td>
1310         <td>0</td>
1311         <td>Balancer timeout in seconds. If set this will be the maximum time
1312         to wait for a free worker. Default is not to wait.
1313     </td></tr>
1314     <tr><td>failonstatus</td>
1315         <td>-</td>
1316         <td>A single or comma-separated list of HTTP status codes. If set this will
1317         force the worker into error state when the backend returns any status code
1318         in the list. Worker recovery behaves the same as other worker errors.
1319     </td></tr>
1320     <tr><td>failontimeout</td>
1321         <td>Off</td>
1322         <td>If set, an IO read timeout after a request is sent to the backend will
1323         force the worker into error state. Worker recovery behaves the same as other
1324         worker errors.
1325     </td></tr>
1326     <tr><td>nonce</td>
1327         <td>&lt;auto&gt;</td>
1328         <td>The protective nonce used in the <code>balancer-manager</code> application page.
1329         The default is to use an automatically determined UUID-based
1330         nonce, to provide for further protection for the page. If set,
1331         then the nonce is set to that value. A setting of <code>None</code>
1332         disables all nonce checking.
1333     <div class="note"><h3>Note</h3>
1334       <p>In addition to the nonce, the <code>balancer-manager</code> page
1335       should be protected via an ACL.</p>
1336     </div>
1337      </td></tr>
1338     <tr><td>growth</td>
1339         <td>0</td>
1340         <td>Number of additional BalancerMembers to allow to be added
1341         to this balancer in addition to those defined at configuration.
1342     </td></tr>
1343     <tr><td>forcerecovery</td>
1344         <td>On</td>
1345         <td>Force the immediate recovery of all workers without considering the
1346         retry parameter of the workers if all workers of a balancer are
1347         in error state. There might be cases where an already overloaded backend
1348         can get into deeper trouble if the recovery of all workers is enforced
1349         without considering the retry parameter of each worker. In this case
1350         set to <code>Off</code>.
1351     </td></tr>
1352
1353     </table>
1354     <p>A sample balancer setup</p>
1355     <pre class="prettyprint lang-config">
1356 ProxyPass /special-area http://special.example.com smax=5 max=10
1357 ProxyPass / balancer://mycluster/ stickysession=JSESSIONID|jsessionid nofailover=On
1358 &lt;Proxy balancer://mycluster&gt;
1359     BalancerMember ajp://1.2.3.4:8009
1360     BalancerMember ajp://1.2.3.5:8009 loadfactor=20
1361     # Less powerful server, don't send as many requests there,
1362     BalancerMember ajp://1.2.3.6:8009 loadfactor=5
1363 &lt;/Proxy&gt;
1364     </pre>
1365
1366
1367     <p>Setting up a hot-standby, that will only be used if no other
1368      members are available</p>
1369     <pre class="prettyprint lang-config">
1370 ProxyPass / balancer://hotcluster/
1371 &lt;Proxy balancer://hotcluster&gt;
1372     BalancerMember ajp://1.2.3.4:8009 loadfactor=1
1373     BalancerMember ajp://1.2.3.5:8009 loadfactor=2
1374     # The server below is on hot standby
1375     BalancerMember ajp://1.2.3.6:8009 status=+H
1376     ProxySet lbmethod=bytraffic
1377 &lt;/Proxy&gt;
1378     </pre>
1379
1380
1381     <p>Normally, mod_proxy will canonicalise ProxyPassed URLs.
1382     But this may be incompatible with some backends, particularly those
1383     that make use of <var>PATH_INFO</var>.  The optional <var>nocanon</var>
1384     keyword suppresses this, and passes the URL path "raw" to the
1385     backend.  Note that may affect the security of your backend, as it
1386     removes the normal limited protection against URL-based attacks
1387     provided by the proxy.</p>
1388
1389     <p>The optional <var>interpolate</var> keyword (available in
1390     httpd 2.2.9 and later), in combination with
1391     <code class="directive">ProxyPassInterpolateEnv</code> causes the ProxyPass
1392     to interpolate environment variables, using the syntax
1393     <var>${VARNAME}</var>.  Note that many of the standard CGI-derived
1394     environment variables will not exist when this interpolation happens,
1395     so you may still have to resort to <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
1396     for complex rules.</p>
1397
1398     <p>Normally, mod_proxy will include the query string when
1399     generating the <var>SCRIPT_FILENAME</var> environment variable.
1400     The optional <var>noquery</var> keyword (available in
1401     httpd 2.4.1 and later) prevents this.</p>
1402
1403     <p>When used inside a <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code> section, the first argument is omitted and the local
1404     directory is obtained from the <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code>. The same will occur inside a
1405     <code class="directive"><a href="../mod/core.html#locationmatch">&lt;LocationMatch&gt;</a></code> section,
1406     however ProxyPass does not interpret the regexp as such, so it is necessary
1407     to use <code class="directive">ProxyPassMatch</code> in this situation instead.</p>
1408
1409     <p>This directive is not supported in <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> or <code class="directive"><a href="../mod/core.html#files">&lt;Files&gt;</a></code> sections.</p>
1410
1411     <p>If you require a more flexible reverse-proxy configuration, see the
1412     <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive with the
1413     <code>[P]</code> flag.</p>
1414
1415
1416 </div>
1417 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1418 <div class="directive-section"><h2><a name="ProxyPassInherit" id="ProxyPassInherit">ProxyPassInherit</a> <a name="proxypassinherit" id="proxypassinherit">Directive</a></h2>
1419 <table class="directive">
1420 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Inherit ProxyPass directives defined from the main server</td></tr>
1421 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassInherit On|Off</code></td></tr>
1422 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyPassInherit On</code></td></tr>
1423 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1424 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1425 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
1426 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>ProxyPassInherit is only available in Apache HTTP Server 2.5.0 and later.
1427         and later.</td></tr>
1428 </table>
1429         <p>This directive will cause the current server/vhost to "inherit"
1430             <code class="directive"><a href="#proxypass">ProxyPass</a></code>
1431             directives defined in the main server. This can cause issues and
1432             inconsistent behavior if using the Balancer Manager for dynamic changes
1433             and so should be disabled if using that feature.</p>
1434         <p>The setting in the global server defines the default for all vhosts.</p>
1435         <p>Disabling ProxyPassInherit also disables <code class="directive"><a href="#balancerinherit">BalancerInherit</a></code>.</p>
1436
1437 </div>
1438 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1439 <div class="directive-section"><h2><a name="ProxyPassInterpolateEnv" id="ProxyPassInterpolateEnv">ProxyPassInterpolateEnv</a> <a name="proxypassinterpolateenv" id="proxypassinterpolateenv">Directive</a></h2>
1440 <table class="directive">
1441 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable Environment Variable interpolation in Reverse Proxy configurations</td></tr>
1442 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassInterpolateEnv On|Off</code></td></tr>
1443 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyPassInterpolateEnv Off</code></td></tr>
1444 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
1445 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1446 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
1447 </table>
1448     <p>This directive, together with the <var>interpolate</var> argument to
1449     <code class="directive">ProxyPass</code>, <code class="directive">ProxyPassReverse</code>,
1450     <code class="directive">ProxyPassReverseCookieDomain</code> and
1451     <code class="directive">ProxyPassReverseCookiePath</code>
1452     enables reverse proxies to be dynamically
1453     configured using environment variables, which may be set by
1454     another module such as <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>.
1455     It affects the <code class="directive">ProxyPass</code>,
1456     <code class="directive">ProxyPassReverse</code>,
1457     <code class="directive">ProxyPassReverseCookieDomain</code>, and
1458     <code class="directive">ProxyPassReverseCookiePath</code> directives,
1459     and causes them to substitute the value of an environment
1460     variable <code>varname</code> for the string <code>${varname}</code>
1461     in configuration directives (if the <var>interpolate</var> option is set).</p>
1462     <p>Keep this turned off (for server performance) unless you need it!</p>
1463
1464 </div>
1465 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1466 <div class="directive-section"><h2><a name="ProxyPassMatch" id="ProxyPassMatch">ProxyPassMatch</a> <a name="proxypassmatch" id="proxypassmatch">Directive</a></h2>
1467 <table class="directive">
1468 <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>
1469 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassMatch [<var>regex</var>] !|<var>url</var> [<var>key=value</var>
1470         <var>[key=value</var> ...]]</code></td></tr>
1471 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
1472 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1473 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
1474 </table>
1475     <p>This directive is equivalent to <code class="directive"><a href="#proxypass">ProxyPass</a></code>,
1476        but makes use of regular expressions, instead of simple prefix matching. The
1477        supplied regular expression is matched against the <var>url</var>, and if it
1478        matches, the server will substitute any parenthesized matches into the given
1479        string and use it as a new <var>url</var>.</p>
1480
1481     <div class="note"><strong>Note: </strong>This directive cannot be used within a
1482     <code>&lt;Directory&gt;</code> context.</div>
1483
1484     <p>Suppose the local server has address <code>http://example.com/</code>;
1485     then</p>
1486
1487     <pre class="prettyprint lang-config">
1488       ProxyPassMatch ^(/.*\.gif)$ http://backend.example.com$1
1489     </pre>
1490
1491
1492     <p>will cause a local request for
1493     <code>http://example.com/foo/bar.gif</code> to be internally converted
1494     into a proxy request to <code>http://backend.example.com/foo/bar.gif</code>.</p>
1495     <div class="note"><h3>Note</h3>
1496       <p>The URL argument must be parsable as a URL <em>before</em> regexp
1497       substitutions (as well as after).  This limits the matches you can use.
1498       For instance, if we had used</p>
1499       <pre class="prettyprint lang-config">
1500         ProxyPassMatch ^(/.*\.gif)$ http://backend.example.com:8000$1
1501       </pre>
1502
1503       <p>in our previous example, it would fail with a syntax error
1504       at server startup.  This is a bug (PR 46665 in the ASF bugzilla),
1505       and the workaround is to reformulate the match:</p>
1506       <pre class="prettyprint lang-config">
1507         ProxyPassMatch ^/(.*\.gif)$ http://backend.example.com:8000/$1
1508       </pre>
1509
1510     </div>
1511     <p>The <code>!</code> directive is useful in situations where you don't want
1512     to reverse-proxy a subdirectory.</p>
1513
1514     <p>When used inside a <code class="directive"><a href="../mod/core.html#locationmatch">&lt;LocationMatch&gt;</a></code> section, the first argument is omitted and the
1515     regexp is obtained from the <code class="directive"><a href="../mod/core.html#locationmatch">&lt;LocationMatch&gt;</a></code>.</p>
1516
1517     <p>If you require a more flexible reverse-proxy configuration, see the
1518     <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive with the
1519     <code>[P]</code> flag.</p>
1520
1521     <div class="warning">
1522       <h3>Security Warning</h3>
1523       <p>Take care when constructing the target URL of the rule, considering
1524         the security impact from allowing the client influence over the set of
1525         URLs to which your server will act as a proxy.  Ensure that the scheme
1526         and hostname part of the URL is either fixed, or does not allow the
1527         client undue influence.</p>
1528     </div>
1529
1530 </div>
1531 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1532 <div class="directive-section"><h2><a name="ProxyPassReverse" id="ProxyPassReverse">ProxyPassReverse</a> <a name="proxypassreverse" id="proxypassreverse">Directive</a></h2>
1533 <table class="directive">
1534 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adjusts the URL in HTTP response headers sent from a reverse
1535 proxied server</td></tr>
1536 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverse [<var>path</var>] <var>url</var>
1537 [<var>interpolate</var>]</code></td></tr>
1538 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
1539 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1540 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
1541 </table>
1542     <p>This directive lets Apache httpd adjust the URL in the <code>Location</code>,
1543     <code>Content-Location</code> and <code>URI</code> headers on HTTP
1544     redirect responses. This is essential when Apache httpd is used as a
1545     reverse proxy (or gateway) to avoid by-passing the reverse proxy
1546     because of HTTP redirects on the backend servers which stay behind
1547     the reverse proxy.</p>
1548
1549     <p>Only the HTTP response headers specifically mentioned above
1550     will be rewritten. Apache httpd will not rewrite other response
1551     headers, nor will it by default rewrite URL references inside HTML pages.
1552     This means that if the proxied content contains absolute URL
1553     references, they will by-pass the proxy. To rewrite HTML content to
1554     match the proxy, you must load and enable <code class="module"><a href="../mod/mod_proxy_html.html">mod_proxy_html</a></code>.
1555     </p>
1556
1557     <p><var>path</var> is the name of a local virtual path. <var>url</var> is a
1558     partial URL for the remote server - the same way they are used for the
1559     <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p>
1560
1561     <p>For example, suppose the local server has address
1562     <code>http://example.com/</code>; then</p>
1563
1564     <pre class="prettyprint lang-config">
1565 ProxyPass         /mirror/foo/ http://backend.example.com/
1566 ProxyPassReverse  /mirror/foo/ http://backend.example.com/
1567 ProxyPassReverseCookieDomain  backend.example.com  public.example.com
1568 ProxyPassReverseCookiePath  /  /mirror/foo/
1569     </pre>
1570
1571
1572     <p>will not only cause a local request for the
1573     <code>http://example.com/mirror/foo/bar</code> to be internally converted
1574     into a proxy request to <code>http://backend.example.com/bar</code>
1575     (the functionality <code>ProxyPass</code> provides here). It also takes care
1576     of redirects the server <code>backend.example.com</code> sends: when
1577     <code>http://backend.example.com/bar</code> is redirected by him to
1578     <code>http://backend.example.com/quux</code> Apache httpd adjusts this to
1579     <code>http://example.com/mirror/foo/quux</code> before forwarding the HTTP
1580     redirect response to the client. Note that the hostname used for
1581     constructing the URL is chosen in respect to the setting of the <code class="directive"><a href="../mod/core.html#usecanonicalname">UseCanonicalName</a></code> directive.</p>
1582
1583     <p>Note that this <code class="directive">ProxyPassReverse</code> directive can
1584     also be used in conjunction with the proxy pass-through feature
1585     (<code>RewriteRule ...  [P]</code>) from <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
1586     because it doesn't depend on a corresponding <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p>
1587
1588     <p>The optional <var>interpolate</var> keyword (available in
1589     httpd 2.2.9 and later), used together with
1590     <code class="directive">ProxyPassInterpolateEnv</code>, enables interpolation
1591     of environment variables specified using the format <var>${VARNAME}</var>.
1592     </p>
1593
1594     <p>When used inside a <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code> section, the first argument is omitted and the local
1595     directory is obtained from the <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code>. The same occurs inside a <code class="directive"><a href="../mod/core.html#locationmatch">&lt;LocationMatch&gt;</a></code> section, but will probably not work as
1596     intended, as ProxyPassReverse will interpret the regexp literally as a
1597     path; if needed in this situation, specify the ProxyPassReverse outside
1598     the section, or in a separate <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code> section.</p>
1599
1600     <p>This directive is not supported in <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> or <code class="directive"><a href="../mod/core.html#files">&lt;Files&gt;</a></code> sections.</p>
1601
1602 </div>
1603 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1604 <div class="directive-section"><h2><a name="ProxyPassReverseCookieDomain" id="ProxyPassReverseCookieDomain">ProxyPassReverseCookieDomain</a> <a name="proxypassreversecookiedomain" id="proxypassreversecookiedomain">Directive</a></h2>
1605 <table class="directive">
1606 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adjusts the Domain string in Set-Cookie headers from a reverse-
1607 proxied server</td></tr>
1608 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverseCookieDomain <var>internal-domain</var>
1609 <var>public-domain</var> [<var>interpolate</var>]</code></td></tr>
1610 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
1611 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1612 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
1613 </table>
1614 <p>Usage is basically similar to
1615 <code class="directive"><a href="#proxypassreverse">ProxyPassReverse</a></code>, but instead of
1616 rewriting headers that are a URL, this rewrites the <code>domain</code>
1617 string in <code>Set-Cookie</code> headers.</p>
1618
1619 </div>
1620 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1621 <div class="directive-section"><h2><a name="ProxyPassReverseCookiePath" id="ProxyPassReverseCookiePath">ProxyPassReverseCookiePath</a> <a name="proxypassreversecookiepath" id="proxypassreversecookiepath">Directive</a></h2>
1622 <table class="directive">
1623 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adjusts the Path string in Set-Cookie headers from a reverse-
1624 proxied server</td></tr>
1625 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverseCookiePath <var>internal-path</var>
1626 <var>public-path</var> [<var>interpolate</var>]</code></td></tr>
1627 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
1628 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1629 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
1630 </table>
1631 <p>
1632 Useful in conjunction with
1633 <code class="directive"><a href="#proxypassreverse">ProxyPassReverse</a></code>
1634 in situations where backend URL paths are mapped to public paths on the
1635 reverse proxy. This directive rewrites the <code>path</code> string in
1636 <code>Set-Cookie</code> headers. If the beginning of the cookie path matches
1637 <var>internal-path</var>, the cookie path will be replaced with
1638 <var>public-path</var>.
1639 </p><p>
1640 In the example given with
1641 <code class="directive"><a href="#proxypassreverse">ProxyPassReverse</a></code>, the directive:
1642 </p>
1643     <pre class="prettyprint lang-config">
1644       ProxyPassReverseCookiePath  /  /mirror/foo/
1645     </pre>
1646
1647 <p>
1648 will rewrite a cookie with backend path <code>/</code> (or
1649 <code>/example</code> or, in fact, anything) to <code>/mirror/foo/</code>.
1650 </p>
1651
1652 </div>
1653 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1654 <div class="directive-section"><h2><a name="ProxyPreserveHost" id="ProxyPreserveHost">ProxyPreserveHost</a> <a name="proxypreservehost" id="proxypreservehost">Directive</a></h2>
1655 <table class="directive">
1656 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use incoming Host HTTP request header for proxy
1657 request</td></tr>
1658 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPreserveHost On|Off</code></td></tr>
1659 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyPreserveHost Off</code></td></tr>
1660 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
1661 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1662 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
1663 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Usable in directory
1664 context in 2.3.3 and later.</td></tr>
1665 </table>
1666     <p>When enabled, this option will pass the Host: line from the incoming
1667     request to the proxied host, instead of the hostname specified in the
1668     <code class="directive">ProxyPass</code> line.</p>
1669
1670     <p>This option should normally be turned <code>Off</code>. It is mostly
1671     useful in special configurations like proxied mass name-based virtual
1672     hosting, where the original Host header needs to be evaluated by the
1673     backend server.</p>
1674
1675 </div>
1676 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1677 <div class="directive-section"><h2><a name="ProxyReceiveBufferSize" id="ProxyReceiveBufferSize">ProxyReceiveBufferSize</a> <a name="proxyreceivebuffersize" id="proxyreceivebuffersize">Directive</a></h2>
1678 <table class="directive">
1679 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Network buffer size for proxied HTTP and FTP
1680 connections</td></tr>
1681 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyReceiveBufferSize <var>bytes</var></code></td></tr>
1682 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyReceiveBufferSize 0</code></td></tr>
1683 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1684 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1685 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
1686 </table>
1687     <p>The <code class="directive">ProxyReceiveBufferSize</code> directive specifies an
1688     explicit (TCP/IP) network buffer size for proxied HTTP and FTP connections,
1689     for increased throughput. It has to be greater than <code>512</code> or set
1690     to <code>0</code> to indicate that the system's default buffer size should
1691     be used.</p>
1692
1693     <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">
1694       ProxyReceiveBufferSize 2048
1695       </pre>
1696 </div>
1697
1698 </div>
1699 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1700 <div class="directive-section"><h2><a name="ProxyRemote" id="ProxyRemote">ProxyRemote</a> <a name="proxyremote" id="proxyremote">Directive</a></h2>
1701 <table class="directive">
1702 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Remote proxy used to handle certain requests</td></tr>
1703 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyRemote <var>match</var> <var>remote-server</var></code></td></tr>
1704 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1705 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1706 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
1707 </table>
1708     <p>This defines remote proxies to this proxy. <var>match</var> is either the
1709     name of a URL-scheme that the remote server supports, or a partial URL
1710     for which the remote server should be used, or <code>*</code> to indicate
1711     the server should be contacted for all requests. <var>remote-server</var> is
1712     a partial URL for the remote server. Syntax:</p>
1713
1714     <div class="example"><p><code>
1715       <dfn>remote-server</dfn> =
1716           <var>scheme</var>://<var>hostname</var>[:<var>port</var>]
1717     </code></p></div>
1718
1719     <p><var>scheme</var> is effectively the protocol that should be used to
1720     communicate with the remote server; only <code>http</code> and <code>https</code>
1721     are supported by this module. When using <code>https</code>, the requests
1722     are forwarded through the remote proxy using the HTTP CONNECT method.</p>
1723
1724     <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">
1725 ProxyRemote http://goodguys.example.com/ http://mirrorguys.example.com:8000
1726 ProxyRemote * http://cleverproxy.localdomain
1727 ProxyRemote ftp http://ftpproxy.mydomain:8080
1728     </pre>
1729 </div>
1730
1731     <p>In the last example, the proxy will forward FTP requests, encapsulated
1732     as yet another HTTP proxy request, to another proxy which can handle
1733     them.</p>
1734
1735     <p>This option also supports reverse proxy configuration - a backend
1736     webserver can be embedded within a virtualhost URL space even if that
1737     server is hidden by another forward proxy.</p>
1738
1739 </div>
1740 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1741 <div class="directive-section"><h2><a name="ProxyRemoteMatch" id="ProxyRemoteMatch">ProxyRemoteMatch</a> <a name="proxyremotematch" id="proxyremotematch">Directive</a></h2>
1742 <table class="directive">
1743 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Remote proxy used to handle requests matched by regular
1744 expressions</td></tr>
1745 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyRemoteMatch <var>regex</var> <var>remote-server</var></code></td></tr>
1746 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1747 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1748 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
1749 </table>
1750     <p>The <code class="directive">ProxyRemoteMatch</code> is identical to the
1751     <code class="directive"><a href="#proxyremote">ProxyRemote</a></code> directive, except the
1752     first argument is a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>
1753     match against the requested URL.</p>
1754
1755 </div>
1756 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1757 <div class="directive-section"><h2><a name="ProxyRequests" id="ProxyRequests">ProxyRequests</a> <a name="proxyrequests" id="proxyrequests">Directive</a></h2>
1758 <table class="directive">
1759 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables forward (standard) proxy requests</td></tr>
1760 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyRequests On|Off</code></td></tr>
1761 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyRequests Off</code></td></tr>
1762 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1763 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1764 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
1765 </table>
1766     <p>This allows or prevents Apache httpd from functioning as a forward proxy
1767     server. (Setting ProxyRequests to <code>Off</code> does not disable use of
1768     the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.)</p>
1769
1770     <p>In a typical reverse proxy or gateway configuration, this
1771     option should be set to
1772     <code>Off</code>.</p>
1773
1774     <p>In order to get the functionality of proxying HTTP or FTP sites, you
1775     need also <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code> or <code class="module"><a href="../mod/mod_proxy_ftp.html">mod_proxy_ftp</a></code>
1776     (or both) present in the server.</p>
1777
1778     <p>In order to get the functionality of (forward) proxying HTTPS sites, you
1779     need <code class="module"><a href="../mod/mod_proxy_connect.html">mod_proxy_connect</a></code> enabled in the server.</p>
1780
1781     <div class="warning"><h3>Warning</h3>
1782       <p>Do not enable proxying with <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> until you have <a href="#access">secured your server</a>.  Open proxy servers are dangerous
1783       both to your network and to the Internet at large.</p>
1784     </div>
1785
1786 <h3>See also</h3>
1787 <ul>
1788 <li><a href="#forwardreverse">Forward and Reverse Proxies/Gateways</a></li>
1789 </ul>
1790 </div>
1791 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1792 <div class="directive-section"><h2><a name="ProxySet" id="ProxySet">ProxySet</a> <a name="proxyset" id="proxyset">Directive</a></h2>
1793 <table class="directive">
1794 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set various Proxy balancer or member parameters</td></tr>
1795 <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>
1796 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
1797 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1798 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
1799 </table>
1800     <p>This directive is used as an alternate method of setting any of the
1801     parameters available to Proxy balancers and workers normally done via the
1802     <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive. If used
1803     within a <code>&lt;Proxy <var>balancer url|worker url</var>&gt;</code>
1804     container directive, the <var>url</var> argument is not required. As a side
1805     effect the respective balancer or worker gets created. This can be useful
1806     when doing reverse proxying via a
1807     <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> instead of a
1808     <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p>
1809
1810     <div class="example"><pre class="prettyprint lang-config">
1811 &lt;Proxy balancer://hotcluster&gt;
1812     BalancerMember http://www2.example.com:8080 loadfactor=1
1813     BalancerMember http://www3.example.com:8080 loadfactor=2
1814     ProxySet lbmethod=bytraffic
1815 &lt;/Proxy&gt;
1816       </pre>
1817 </div>
1818
1819     <pre class="prettyprint lang-config">
1820 &lt;Proxy http://backend&gt;
1821     ProxySet keepalive=On
1822 &lt;/Proxy&gt;
1823     </pre>
1824
1825
1826     <pre class="prettyprint lang-config">
1827         ProxySet balancer://foo lbmethod=bytraffic timeout=15
1828     </pre>
1829
1830
1831     <pre class="prettyprint lang-config">
1832         ProxySet ajp://backend:7001 timeout=15
1833     </pre>
1834
1835
1836    <div class="warning"><h3>Warning</h3>
1837       <p>Keep in mind that the same parameter key can have a different meaning
1838       depending whether it is applied to a balancer or a worker as shown by the two
1839       examples above regarding timeout.</p>
1840    </div>
1841
1842
1843 </div>
1844 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1845 <div class="directive-section"><h2><a name="ProxySourceAddress" id="ProxySourceAddress">ProxySourceAddress</a> <a name="proxysourceaddress" id="proxysourceaddress">Directive</a></h2>
1846 <table class="directive">
1847 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set local IP address for outgoing proxy connections</td></tr>
1848 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxySourceAddress <var>address</var></code></td></tr>
1849 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1850 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1851 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
1852 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.9 and later</td></tr>
1853 </table>
1854     <p>This directive allows to set a specific local address to bind to when connecting
1855     to a backend server.</p>
1856
1857 </div>
1858 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1859 <div class="directive-section"><h2><a name="ProxyStatus" id="ProxyStatus">ProxyStatus</a> <a name="proxystatus" id="proxystatus">Directive</a></h2>
1860 <table class="directive">
1861 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Show Proxy LoadBalancer status in mod_status</td></tr>
1862 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyStatus Off|On|Full</code></td></tr>
1863 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyStatus Off</code></td></tr>
1864 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1865 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1866 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
1867 </table>
1868     <p>This directive determines whether or not proxy
1869     loadbalancer status data is displayed via the <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>
1870     server-status page.</p>
1871     <div class="note"><h3>Note</h3>
1872       <p><strong>Full</strong> is synonymous with <strong>On</strong></p>
1873     </div>
1874
1875
1876 </div>
1877 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1878 <div class="directive-section"><h2><a name="ProxyTimeout" id="ProxyTimeout">ProxyTimeout</a> <a name="proxytimeout" id="proxytimeout">Directive</a></h2>
1879 <table class="directive">
1880 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Network timeout for proxied requests</td></tr>
1881 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyTimeout <var>seconds</var></code></td></tr>
1882 <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>
1883 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1884 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1885 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
1886 </table>
1887     <p>This directive allows a user to specifiy a timeout on proxy requests.
1888     This is useful when you have a slow/buggy appserver which hangs, and you
1889     would rather just return a timeout and fail gracefully instead of waiting
1890     however long it takes the server to return.</p>
1891
1892 </div>
1893 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1894 <div class="directive-section"><h2><a name="ProxyVia" id="ProxyVia">ProxyVia</a> <a name="proxyvia" id="proxyvia">Directive</a></h2>
1895 <table class="directive">
1896 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Information provided in the <code>Via</code> HTTP response
1897 header for proxied requests</td></tr>
1898 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyVia On|Off|Full|Block</code></td></tr>
1899 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyVia Off</code></td></tr>
1900 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1901 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1902 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr>
1903 </table>
1904     <p>This directive controls the use of the <code>Via:</code> HTTP
1905     header by the proxy. Its intended use is to control the flow of
1906     proxy requests along a chain of proxy servers.  See <a href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a> (HTTP/1.1), section
1907     14.45 for an explanation of <code>Via:</code> header lines.</p>
1908
1909     <ul>
1910     <li>If set to <code>Off</code>, which is the default, no special processing
1911     is performed. If a request or reply contains a <code>Via:</code> header,
1912     it is passed through unchanged.</li>
1913
1914     <li>If set to <code>On</code>, each request and reply will get a
1915     <code>Via:</code> header line added for the current host.</li>
1916
1917     <li>If set to <code>Full</code>, each generated <code>Via:</code> header
1918     line will additionally have the Apache httpd server version shown as a
1919     <code>Via:</code> comment field.</li>
1920
1921     <li>If set to <code>Block</code>, every proxy request will have all its
1922     <code>Via:</code> header lines removed. No new <code>Via:</code> header will
1923     be generated.</li>
1924     </ul>
1925
1926 </div>
1927 </div>
1928 <div class="bottomlang">
1929 <p><span>Available Languages: </span><a href="../en/mod/mod_proxy.html" title="English">&nbsp;en&nbsp;</a> |
1930 <a href="../fr/mod/mod_proxy.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
1931 <a href="../ja/mod/mod_proxy.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a></p>
1932 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
1933 <script type="text/javascript"><!--//--><![CDATA[//><!--
1934 var comments_shortname = 'httpd';
1935 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_proxy.html';
1936 (function(w, d) {
1937     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
1938         d.write('<div id="comments_thread"><\/div>');
1939         var s = d.createElement('script');
1940         s.type = 'text/javascript';
1941         s.async = true;
1942         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
1943         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
1944     }
1945     else {
1946         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
1947     }
1948 })(window, document);
1949 //--><!]]></script></div><div id="footer">
1950 <p class="apache">Copyright 2013 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>
1951 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
1952 if (typeof(prettyPrint) !== 'undefined') {
1953     prettyPrint();
1954 }
1955 //--><!]]></script>
1956 </body></html>