diff options
| author | Stefan Fritsch <sf@sfritsch.de> | 2011-12-27 19:42:03 +0100 |
|---|---|---|
| committer | Stefan Fritsch <sf@sfritsch.de> | 2011-12-27 19:42:03 +0100 |
| commit | 80db94fff6a9620fb469ee911347ed973e3f7735 (patch) | |
| tree | 35ccde4018b7e6b84103e5e85dc1085ef9e7d6c2 /docs/manual/mod/mod_proxy.html.en | |
| download | apache2-upstream/2.2.3.tar.gz | |
Upstream tarball 2.2.3upstream/2.2.3
Diffstat (limited to 'docs/manual/mod/mod_proxy.html.en')
| -rw-r--r-- | docs/manual/mod/mod_proxy.html.en | 1131 |
1 files changed, 1131 insertions, 0 deletions
diff --git a/docs/manual/mod/mod_proxy.html.en b/docs/manual/mod/mod_proxy.html.en new file mode 100644 index 00000000..de1253cc --- /dev/null +++ b/docs/manual/mod/mod_proxy.html.en @@ -0,0 +1,1131 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + This file is generated from xml source: DO NOT EDIT + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + --> +<title>mod_proxy - Apache HTTP Server</title> +<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> +<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> +<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /> +<link href="../images/favicon.ico" rel="shortcut icon" /></head> +<body> +<div id="page-header"> +<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p> +<p class="apache">Apache HTTP Server Version 2.2</p> +<img alt="" src="../images/feather.gif" /></div> +<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div> +<div id="path"> +<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.2</a> > <a href="./">Modules</a></div> +<div id="page-content"> +<div id="preamble"><h1>Apache Module mod_proxy</h1> +<div class="toplang"> +<p><span>Available Languages: </span><a href="../en/mod/mod_proxy.html" title="English"> en </a> | +<a href="../ja/mod/mod_proxy.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p> +</div> +<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>HTTP/1.1 proxy/gateway server</td></tr> +<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>proxy_module</td></tr> +<tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_proxy.c</td></tr></table> +<h3>Summary</h3> + + <div class="warning"><h3>Warning</h3> + <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 + network and to the Internet at large.</p> + </div> + + <p>This module implements a proxy/gateway for Apache. It implements + proxying capability for <code>AJP13</code> (Apache JServe Protocol + version 1.3), <code>FTP</code>, <code>CONNECT</code> (for SSL), + <code>HTTP/0.9</code>, <code>HTTP/1.0</code>, and <code>HTTP/1.1</code>. + The module can be configured to connect to other proxy modules for these + and other protocols.</p> + + <p>Apache's proxy features are divided into several modules in + addition to <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>: + <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code>, <code class="module"><a href="../mod/mod_proxy_ftp.html">mod_proxy_ftp</a></code>, + <code class="module"><a href="../mod/mod_proxy_ajp.html">mod_proxy_ajp</a></code>, <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code>, + and <code class="module"><a href="../mod/mod_proxy_connect.html">mod_proxy_connect</a></code>. Thus, if you want to use + one or more of the particular proxy functions, load + <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> <em>and</em> the appropriate module(s) + into the server (either statically at compile-time or dynamically + via the <code class="directive"><a href="../mod/mod_so.html#loadmodule">LoadModule</a></code> + directive).</p> + + <p>In addition, extended features are provided by other modules. + Caching is provided by <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code> and related + modules. The ability to contact remote servers using the SSL/TLS + protocol is provided by the <code>SSLProxy*</code> directives of + <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code>. These additional modules will need + to be loaded and configured to take advantage of these features.</p> +</div> +<div id="quickview"><h3 class="directives">Directives</h3> +<ul id="toc"> +<li><img alt="" src="../images/down.gif" /> <a href="#allowconnect">AllowCONNECT</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#noproxy">NoProxy</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxy"><Proxy></a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxybadheader">ProxyBadHeader</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxyblock">ProxyBlock</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxydomain">ProxyDomain</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxyerroroverride">ProxyErrorOverride</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxyiobuffersize">ProxyIOBufferSize</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxymatch"><ProxyMatch></a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxymaxforwards">ProxyMaxForwards</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxypass">ProxyPass</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxypassreverse">ProxyPassReverse</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxypassreversecookiedomain">ProxyPassReverseCookieDomain</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxypassreversecookiepath">ProxyPassReverseCookiePath</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxypreservehost">ProxyPreserveHost</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxyreceivebuffersize">ProxyReceiveBufferSize</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxyremote">ProxyRemote</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxyremotematch">ProxyRemoteMatch</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxyrequests">ProxyRequests</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxytimeout">ProxyTimeout</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxyvia">ProxyVia</a></li> +</ul> +<h3>Topics</h3> +<ul id="topics"> +<li><img alt="" src="../images/down.gif" /> <a href="#forwardreverse">Forward and Reverse Proxies</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#examples">Basic Examples</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#access">Controlling access to your proxy</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#startup">Slow Startup</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#intranet">Intranet Proxy</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#envsettings">Protocol Adjustments</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#request-bodies">Request Bodys</a></li> +</ul><h3>See also</h3> +<ul class="seealso"> +<li><code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code></li> +<li><code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code></li> +<li><code class="module"><a href="../mod/mod_proxy_ftp.html">mod_proxy_ftp</a></code></li> +<li><code class="module"><a href="../mod/mod_proxy_connect.html">mod_proxy_connect</a></code></li> +<li><code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code></li> +<li><code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code></li> +</ul></div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="forwardreverse" id="forwardreverse">Forward and Reverse Proxies</a></h2> + <p>Apache can be configured in both a <dfn>forward</dfn> and + <dfn>reverse</dfn> proxy mode.</p> + + <p>An ordinary <dfn>forward proxy</dfn> is an intermediate + server that sits between the client and the <em>origin + server</em>. In order to get content from the origin server, + the client sends a request to the proxy naming the origin server + as the target and the proxy then requests the content from the + origin server and returns it to the client. The client must be + specially configured to use the forward proxy to access other + sites.</p> + + <p>A typical usage of a forward proxy is to provide Internet + access to internal clients that are otherwise restricted by a + firewall. The forward proxy can also use caching (as provided + by <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code>) to reduce network usage.</p> + + <p>The forward proxy is activated using the <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> directive. Because + forward proxys allow clients to access arbitrary sites through + your server and to hide their true origin, it is essential that + you <a href="#access">secure your server</a> so that only + authorized clients can access the proxy before activating a + forward proxy.</p> + + <p>A <dfn>reverse proxy</dfn>, by contrast, appears to the + client just like an ordinary web server. No special + configuration on the client is necessary. The client makes + ordinary requests for content in the name-space of the reverse + proxy. The reverse proxy then decides where to send those + requests, and returns the content as if it was itself the + origin.</p> + + <p>A typical usage of a reverse proxy is to provide Internet + users access to a server that is behind a firewall. Reverse + proxies can also be used to balance load among several back-end + servers, or to provide caching for a slower back-end server. + In addition, reverse proxies can be used simply to bring + several servers into the same URL space.</p> + + <p>A reverse proxy is activated using the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive or the + <code>[P]</code> flag to the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive. It is + <strong>not</strong> necessary to turn <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> on in order to + configure a reverse proxy.</p> + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="examples" id="examples">Basic Examples</a></h2> + + <p>The examples below are only a very basic idea to help you + get started. Please read the documentation on the individual + directives.</p> + + <p>In addition, if you wish to have caching enabled, consult + the documentation from <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code>.</p> + + <div class="example"><h3>Forward Proxy</h3><p><code> + ProxyRequests On<br /> + ProxyVia On<br /> + <br /> + <Proxy *><br /> + <span class="indent"> + Order deny,allow<br /> + Deny from all<br /> + Allow from internal.example.com<br /> + </span> + </Proxy> + </code></p></div> + + <div class="example"><h3>Reverse Proxy</h3><p><code> + ProxyRequests Off<br /> + <br /> + <Proxy *><br /> + <span class="indent"> + Order deny,allow<br /> + Allow from all<br /> + </span> + </Proxy><br /> + <br /> + ProxyPass /foo http://foo.example.com/bar<br /> + ProxyPassReverse /foo http://foo.example.com/bar + </code></p></div> + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="access" id="access">Controlling access to your proxy</a></h2> + <p>You can control who can access your proxy via the <code class="directive"><a href="#proxy"><Proxy></a></code> control block as in + the following example:</p> + + <div class="example"><p><code> + <Proxy *><br /> + <span class="indent"> + Order Deny,Allow<br /> + Deny from all<br /> + Allow from 192.168.0<br /> + </span> + </Proxy> + </code></p></div> + + <p>For more information on access control directives, see + <code class="module"><a href="../mod/mod_authz_host.html">mod_authz_host</a></code>.</p> + + <p>Strictly limiting access is essential if you are using a + forward proxy (using the <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> directive). + Otherwise, your server can be used by any client to access + arbitrary hosts while hiding his or her true identity. This is + dangerous both for your network and for the Internet at large. + When using a reverse proxy (using the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive with + <code>ProxyRequests Off</code>), access control is less + critical because clients can only contact the hosts that you + have specifically configured.</p> + + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="startup" id="startup">Slow Startup</a></h2> + <p>If you're using the <code class="directive"><a href="#proxyblock">ProxyBlock</a></code> directive, hostnames' IP addresses are looked up + and cached during startup for later match test. This may take a few + seconds (or more) depending on the speed with which the hostname lookups + occur.</p> + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="intranet" id="intranet">Intranet Proxy</a></h2> + <p>An Apache proxy server situated in an intranet needs to forward + external requests through the company's firewall (for this, configure + the <code class="directive"><a href="#proxyremote">ProxyRemote</a></code> directive + to forward the respective <var>scheme</var> to the firewall proxy). + However, when it has to + access resources within the intranet, it can bypass the firewall when + accessing hosts. The <code class="directive"><a href="#noproxy">NoProxy</a></code> + directive is useful for specifying which hosts belong to the intranet and + should be accessed directly.</p> + + <p>Users within an intranet tend to omit the local domain name from their + WWW requests, thus requesting "http://somehost/" instead of + <code>http://somehost.example.com/</code>. Some commercial proxy servers + let them get away with this and simply serve the request, implying a + configured local domain. When the <code class="directive"><a href="#proxydomain">ProxyDomain</a></code> directive is used and the server is <a href="#proxyrequests">configured for proxy service</a>, Apache can return + a redirect response and send the client to the correct, fully qualified, + server address. This is the preferred method since the user's bookmark + files will then contain fully qualified hosts.</p> + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="envsettings" id="envsettings">Protocol Adjustments</a></h2> + <p>For circumstances where <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> is sending + requests to an origin server that doesn't properly implement + keepalives or HTTP/1.1, there are two <a href="../env.html">environment variables</a> that can force the + request to use HTTP/1.0 with no keepalive. These are set via the + <code class="directive"><a href="../mod/mod_env.html#setenv">SetEnv</a></code> directive.</p> + + <p>These are the <code>force-proxy-request-1.0</code> and + <code>proxy-nokeepalive</code> notes.</p> + + <div class="example"><p><code> + <Location /buggyappserver/><br /> + <span class="indent"> + ProxyPass http://buggyappserver:7001/foo/<br /> + SetEnv force-proxy-request-1.0 1<br /> + SetEnv proxy-nokeepalive 1<br /> + </span> + </Location> + </code></p></div> + + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="request-bodies" id="request-bodies">Request Bodys</a></h2> + + <p>Some request methods such as POST include a request body. + The HTTP protocol requires that requests which include a body + either use chunked transfer encoding or send a + <code>Content-Length</code> request header. When passing these + requests on to the origin server, <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code> + will always attempt to send the <code>Content-Length</code>. But + if the body is large and the original request used chunked + encoding, then chunked encoding may also be used in the upstream + request. You can control this selection using <a href="../env.html">environment variables</a>. Setting + <code>proxy-sendcl</code> ensures maximum compatibility with + upstream servers by always sending the + <code>Content-Length</code>, while setting + <code>proxy-sendchunked</code> minimizes resource usage by using + chunked encoding.</p> + + </div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="AllowCONNECT" id="AllowCONNECT">AllowCONNECT</a> <a name="allowconnect" id="allowconnect">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Ports that are allowed to <code>CONNECT</code> through the +proxy</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AllowCONNECT <var>port</var> [<var>port</var>] ...</code></td></tr> +<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AllowCONNECT 443 563</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +</table> + <p>The <code class="directive">AllowCONNECT</code> directive specifies a list + of port numbers to which the proxy <code>CONNECT</code> method may + connect. Today's browsers use this method when a <code>https</code> + connection is requested and proxy tunneling over HTTP is in effect.</p> + + <p>By default, only the default https port (<code>443</code>) and the + default snews port (<code>563</code>) are enabled. Use the + <code class="directive">AllowCONNECT</code> directive to override this default and + allow connections to the listed ports only.</p> + + <p>Note that you'll need to have <code class="module"><a href="../mod/mod_proxy_connect.html">mod_proxy_connect</a></code> present + in the server in order to get the support for the <code>CONNECT</code> at + all.</p> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="NoProxy" id="NoProxy">NoProxy</a> <a name="noproxy" id="noproxy">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Hosts, domains, or networks that will be connected to +directly</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>NoProxy <var>host</var> [<var>host</var>] ...</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +</table> + <p>This directive is only useful for Apache proxy servers within + intranets. The <code class="directive">NoProxy</code> directive specifies a + list of subnets, IP addresses, hosts and/or domains, separated by + spaces. A request to a host which matches one or more of these is + always served directly, without forwarding to the configured + <code class="directive"><a href="#proxyremote">ProxyRemote</a></code> proxy server(s).</p> + + <div class="example"><h3>Example</h3><p><code> + ProxyRemote * http://firewall.mycompany.com:81<br /> + NoProxy .mycompany.com 192.168.112.0/21 + </code></p></div> + + <p>The <var>host</var> arguments to the <code class="directive">NoProxy</code> + directive are one of the following type list:</p> + + <dl> + + <dt><var><a name="domain" id="domain">Domain</a></var></dt> + <dd> + <p>A <dfn>Domain</dfn> is a partially qualified DNS domain name, preceded + by a period. It represents a list of hosts which logically belong to the + same DNS domain or zone (<em>i.e.</em>, the suffixes of the hostnames are + all ending in <var>Domain</var>).</p> + + <div class="example"><h3>Examples</h3><p><code> + .com .apache.org. + </code></p></div> + + <p>To distinguish <var>Domain</var>s from <var><a href="#hostname">Hostname</a></var>s (both syntactically and semantically; a DNS domain can + have a DNS A record, too!), <var>Domain</var>s are always written with a + leading period.</p> + + <div class="note"><h3>Note</h3> + <p>Domain name comparisons are done without regard to the case, and + <var>Domain</var>s are always assumed to be anchored in the root of the + DNS tree, therefore two domains <code>.MyDomain.com</code> and + <code>.mydomain.com.</code> (note the trailing period) are considered + equal. Since a domain comparison does not involve a DNS lookup, it is much + more efficient than subnet comparison.</p> + </div></dd> + + + <dt><var><a name="subnet" id="subnet">SubNet</a></var></dt> + <dd> + <p>A <dfn>SubNet</dfn> is a partially qualified internet address in + numeric (dotted quad) form, optionally followed by a slash and the netmask, + specified as the number of significant bits in the <var>SubNet</var>. It is + used to represent a subnet of hosts which can be reached over a common + network interface. In the absence of the explicit net mask it is assumed + that omitted (or zero valued) trailing digits specify the mask. (In this + case, the netmask can only be multiples of 8 bits wide.) Examples:</p> + + <dl> + <dt><code>192.168</code> or <code>192.168.0.0</code></dt> + <dd>the subnet 192.168.0.0 with an implied netmask of 16 valid bits + (sometimes used in the netmask form <code>255.255.0.0</code>)</dd> + <dt><code>192.168.112.0/21</code></dt> + <dd>the subnet <code>192.168.112.0/21</code> with a netmask of 21 + valid bits (also used in the form <code>255.255.248.0</code>)</dd> + </dl> + + <p>As a degenerate case, a <em>SubNet</em> with 32 valid bits is the + equivalent to an <var><a href="#ipadr">IPAddr</a></var>, while a <var>SubNet</var> with zero + valid bits (<em>e.g.</em>, 0.0.0.0/0) is the same as the constant + <var>_Default_</var>, matching any IP address.</p></dd> + + + <dt><var><a name="ipaddr" id="ipaddr">IPAddr</a></var></dt> + <dd> + <p>A <dfn>IPAddr</dfn> represents a fully qualified internet address in + numeric (dotted quad) form. Usually, this address represents a host, but + there need not necessarily be a DNS domain name connected with the + address.</p> + <div class="example"><h3>Example</h3><p><code> + 192.168.123.7 + </code></p></div> + + <div class="note"><h3>Note</h3> + <p>An <var>IPAddr</var> does not need to be resolved by the DNS system, so + it can result in more effective apache performance.</p> + </div></dd> + + + <dt><var><a name="hostname" id="hostname">Hostname</a></var></dt> + <dd> + <p>A <dfn>Hostname</dfn> is a fully qualified DNS domain name which can + be resolved to one or more <var><a href="#ipaddr">IPAddrs</a></var> via the + DNS domain name service. It represents a logical host (in contrast to + <var><a href="#domain">Domain</a></var>s, see above) and must be resolvable + to at least one <var><a href="#ipaddr">IPAddr</a></var> (or often to a list + of hosts with different <var><a href="#ipaddr">IPAddr</a></var>s).</p> + + <div class="example"><h3>Examples</h3><p><code> + prep.ai.mit.edu<br /> + www.apache.org + </code></p></div> + + <div class="note"><h3>Note</h3> + <p>In many situations, it is more effective to specify an <var><a href="#ipaddr">IPAddr</a></var> in place of a <var>Hostname</var> since a + DNS lookup can be avoided. Name resolution in Apache can take a remarkable + deal of time when the connection to the name server uses a slow PPP + link.</p> + <p><var>Hostname</var> comparisons are done without regard to the case, + and <var>Hostname</var>s are always assumed to be anchored in the root + of the DNS tree, therefore two hosts <code>WWW.MyDomain.com</code> + and <code>www.mydomain.com.</code> (note the trailing period) are + considered equal.</p> + </div></dd> + </dl> + +<h3>See also</h3> +<ul> +<li><a href="../dns-caveats.html">DNS Issues</a></li> +</ul> +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="Proxy" id="Proxy"><Proxy></a> <a name="proxy" id="proxy">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Container for directives applied to proxied resources</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><Proxy <var>wildcard-url</var>> ...</Proxy></code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +</table> + <p>Directives placed in <code class="directive"><Proxy></code> + sections apply only to matching proxied content. Shell-style wildcards are + allowed.</p> + + <p>For example, the following will allow only hosts in + <code>yournetwork.example.com</code> to access content via your proxy + server:</p> + + <div class="example"><p><code> + <Proxy *><br /> + <span class="indent"> + Order Deny,Allow<br /> + Deny from all<br /> + Allow from yournetwork.example.com<br /> + </span> + </Proxy> + </code></p></div> + + <p>The following example will process all files in the <code>foo</code> + directory of <code>example.com</code> through the <code>INCLUDES</code> + filter when they are sent through the proxy server:</p> + + <div class="example"><p><code> + <Proxy http://example.com/foo/*><br /> + <span class="indent"> + SetOutputFilter INCLUDES<br /> + </span> + </Proxy> + </code></p></div> + + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="ProxyBadHeader" id="ProxyBadHeader">ProxyBadHeader</a> <a name="proxybadheader" id="proxybadheader">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines how to handle bad header lines in a +response</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyBadHeader IsError|Ignore|StartBody</code></td></tr> +<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyBadHeader IsError</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>available in Apache 2.0.44 and later</td></tr> +</table> + <p>The <code class="directive">ProxyBadHeader</code> directive determines the + behaviour of <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> if it receives syntactically invalid + header lines (<em>i.e.</em> containing no colon). The following arguments + are possible:</p> + + <dl> + <dt><code>IsError</code></dt> + <dd>Abort the request and end up with a 502 (Bad Gateway) response. This is + the default behaviour.</dd> + + <dt><code>Ignore</code></dt> + <dd>Treat bad header lines as if they weren't sent.</dd> + + <dt><code>StartBody</code></dt> + <dd>When receiving the first bad header line, finish reading the headers and + treat the remainder as body. This helps to work around buggy backend servers + which forget to insert an empty line between the headers and the body.</dd> + </dl> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="ProxyBlock" id="ProxyBlock">ProxyBlock</a> <a name="proxyblock" id="proxyblock">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Words, hosts, or domains that are banned from being +proxied</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyBlock *|<var>word</var>|<var>host</var>|<var>domain</var> +[<var>word</var>|<var>host</var>|<var>domain</var>] ...</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +</table> + <p>The <code class="directive">ProxyBlock</code> directive specifies a list of + words, hosts and/or domains, separated by spaces. HTTP, HTTPS, and + FTP document requests to sites whose names contain matched words, + hosts or domains are <em>blocked</em> by the proxy server. The proxy + module will also attempt to determine IP addresses of list items which + may be hostnames during startup, and cache them for match test as + well. That may slow down the startup time of the server.</p> + + <div class="example"><h3>Example</h3><p><code> + ProxyBlock joes-garage.com some-host.co.uk rocky.wotsamattau.edu + </code></p></div> + + <p><code>rocky.wotsamattau.edu</code> would also be matched if referenced by + IP address.</p> + + <p>Note that <code>wotsamattau</code> would also be sufficient to match + <code>wotsamattau.edu</code>.</p> + + <p>Note also that</p> + + <div class="example"><p><code> + ProxyBlock * + </code></p></div> + + <p>blocks connections to all sites.</p> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="ProxyDomain" id="ProxyDomain">ProxyDomain</a> <a name="proxydomain" id="proxydomain">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Default domain name for proxied requests</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyDomain <var>Domain</var></code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +</table> + <p>This directive is only useful for Apache proxy servers within + intranets. The <code class="directive">ProxyDomain</code> directive specifies + the default domain which the apache proxy server will belong to. If a + request to a host without a domain name is encountered, a redirection + response to the same host with the configured <var>Domain</var> appended + will be generated.</p> + + <div class="example"><h3>Example</h3><p><code> + ProxyRemote * http://firewall.mycompany.com:81<br /> + NoProxy .mycompany.com 192.168.112.0/21<br /> + ProxyDomain .mycompany.com + </code></p></div> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="ProxyErrorOverride" id="ProxyErrorOverride">ProxyErrorOverride</a> <a name="proxyerroroverride" id="proxyerroroverride">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Override error pages for proxied content</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyErrorOverride On|Off</code></td></tr> +<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyErrorOverride Off</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.0 and later</td></tr> +</table> + <p>This directive is useful for reverse-proxy setups, where you want to + have a common look and feel on the error pages seen by the end user. + This also allows for included files (via + <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>'s SSI) to get + the error code and act accordingly (default behavior would display + the error page of the proxied server, turning this on shows the SSI + Error message).</p> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="ProxyIOBufferSize" id="ProxyIOBufferSize">ProxyIOBufferSize</a> <a name="proxyiobuffersize" id="proxyiobuffersize">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determine size of internal data throughput buffer</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyIOBufferSize <var>bytes</var></code></td></tr> +<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyIOBufferSize 8192</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +</table> + <p>The <code class="directive">ProxyIOBufferSize</code> directive adjusts the size + of the internal buffer, which is used as a scratchpad for the data between + input and output. The size must be less or equal <code>8192</code>.</p> + + <p>In almost every case there's no reason to change that value.</p> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="ProxyMatch" id="ProxyMatch"><ProxyMatch></a> <a name="proxymatch" id="proxymatch">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Container for directives applied to regular-expression-matched +proxied resources</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><ProxyMatch <var>regex</var>> ...</ProxyMatch></code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +</table> + <p>The <code class="directive"><ProxyMatch></code> directive is + identical to the <code class="directive"><a href="#proxy"><Proxy></a></code> directive, except it matches URLs + using <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expressions</a>.</p> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="ProxyMaxForwards" id="ProxyMaxForwards">ProxyMaxForwards</a> <a name="proxymaxforwards" id="proxymaxforwards">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximium number of proxies that a request can be forwarded +through</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyMaxForwards <var>number</var></code></td></tr> +<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyMaxForwards 10</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.0 and later</td></tr> +</table> + <p>The <code class="directive">ProxyMaxForwards</code> directive specifies the + maximum number of proxies through which a request may pass, if there's no + <code>Max-Forwards</code> header supplied with the request. This is + set to prevent infinite proxy loops, or a DoS attack.</p> + + <div class="example"><h3>Example</h3><p><code> + ProxyMaxForwards 15 + </code></p></div> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="ProxyPass" id="ProxyPass">ProxyPass</a> <a name="proxypass" id="proxypass">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maps remote servers into the local server URL-space</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPass [<var>path</var>] !|<var>url</var> [<var>key=value</var> <var>key=value</var> ...]]</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +</table> + <p>This directive allows remote servers to be mapped into the space of + the local server; the local server does not act as a proxy in the + conventional sense, but appears to be a mirror of the remote + server. <var>path</var> is the name of a local virtual path; <var>url</var> + is a partial URL for the remote server and cannot include a query + string.</p> + + <div class="warning">The <code class="directive"><a href="#proxyrequests">ProxyRequests</a></code> directive should + usually be set <strong>off</strong> when using + <code class="directive">ProxyPass</code>.</div> + + <p>Suppose the local server has address <code>http://example.com/</code>; + then</p> + + <div class="example"><p><code> + ProxyPass /mirror/foo/ http://backend.example.com/ + </code></p></div> + + <p>will cause a local request for + <code>http://example.com/mirror/foo/bar</code> to be internally converted + into a proxy request to <code>http://backend.example.com/bar</code>.</p> + + <p>The <code>!</code> directive is useful in situations where you don't want + to reverse-proxy a subdirectory, <em>e.g.</em></p> + + <div class="example"><p><code> + ProxyPass /mirror/foo/i !<br /> + ProxyPass /mirror/foo http://backend.example.com + </code></p></div> + + <p>will proxy all requests to <code>/mirror/foo</code> to + <code>backend.example.com</code> <em>except</em> requests made to + <code>/mirror/foo/i</code>.</p> + + <div class="note"><h3>Note</h3> + <p>Order is important. you need to put the exclusions <em>before</em> the + general <code class="directive">ProxyPass</code> directive.</p> + </div> + + <p>As of Apache 2.1, the ability to use pooled connections to a backend + server is available. Using the <code>key=value</code> parameters it is + possible to tune this connection pooling. The default for a <code>Hard + Maximum</code> for the number of connections is the number of threads per + process in the active MPM. In the Prefork MPM, this is always 1, while with + the Worker MPM it is controlled by the + <code class="directive">ThreadsPerChild</code>.</p> + + <p>Setting <code>min</code> will determine how many connections will always + be open to the backend server. Upto the Soft Maximum or <code>smax</code> + number of connections will be created on demand. Any connections above + <code>smax</code> are subject to a time to live or <code>ttl</code>. Apache + will never create more than the Hard Maximum or <code>max</code> connections + to the backend server.</p> + + <div class="example"><p><code> + ProxyPass /example http://backend.example.com smax=5 max=20 ttl=120 retry=300 + </code></p></div> + + <table> + <tr><th>Parameter</th> + <th>Default</th> + <th>Description</th></tr> + <tr><td>min</td> + <td>0</td> + <td>Minumum number of connections that will always + be open to the backend server.</td></tr> + <tr><td>max</td> + <td>1...n</td> + <td>Hard Maximum number of connections that will be + allowed to the backend server. The default for a Hard Maximum + for the number of connections is the number of threads per process in the + active MPM. In the Prefork MPM, this is always 1, while with the Worker MPM + it is controlled by the <code class="directive">ThreadsPerChild</code>. + Apache will never create more than the Hard Maximum connections + to the backend server.</td></tr> + <tr><td>smax</td> + <td>max</td> + <td>Upto the Soft Maximum + number of connections will be created on demand. Any connections above + <code>smax</code> are subject to a time to live or <code>ttl</code>. + </td></tr> + <tr><td>ttl</td> + <td>-</td> + <td>Time To Live for the inactive connections above the + <code>smax</code> connections in seconds. Apache will close all + connections that has not been used inside that time period. + </td></tr> + <tr><td>timeout</td> + <td><code class="directive">Timeout</code></td> + <td>Connection timeout in seconds. + If not set the Apache will wait until the free connection + is available. This directive is used for limiting the number + of connections to the backend server together with <code>max</code> + parameter. + </td></tr> + <tr><td>acquire</td> + <td>-</td> + <td>If set this will be the maximum time to wait for a free + connection in the connection pool. If there are no free connections + in the pool the Apache will return <code>SERVER_BUSY</code> status to + the client. + </td></tr> + <tr><td>keepalive</td> + <td>Off</td> + <td>This parameter should be used when you have a firewall between your + Apache and the backend server, who tend to drop inactive connections. + This flag will tell the Operating System to send <code>KEEP_ALIVE</code> + messages on inactive connections (interval depends on global OS settings, + generally 120ms), and thus prevent the firewall to drop the connection. + To enable keepalive set this property value to <code>On</code>. + </td></tr> + <tr><td>retry</td> + <td>60</td> + <td>Connection pool worker retry timeout in seconds. + If the connection pool worker to the backend server is in the error state, + Apache will not forward any requests to that server until the timeout + expires. This enables to shut down the backend server for maintenance, + and bring it back online later. + </td></tr> + <tr><td>loadfactor</td> + <td>1</td> + <td>Worker load factor. Used with BalancerMember. + It is a number between 1 and 100 and defines the normalized weighted + load applied to the worker. + </td></tr> + <tr><td>route</td> + <td>-</td> + <td>Route of the worker when used inside load balancer. + The route is a value appended to seesion id. + </td></tr> + <tr><td>redirect</td> + <td>-</td> + <td>Redirection Route of the worker. This value is usually + set dynamically to enable safe removal of the node from + the cluster. If set all requests without session id will be + redirected to the BalancerMember that has route parametar + equal as this value. + </td></tr> + + </table> + + <p>If the Proxy directive scheme starts with the + <code>balancer://</code> then a virtual worker that does not really + communicate with the backend server will be created. Instead it is responsible + for the management of several "real" workers. In that case the special set of + parameters can be add to this virtual worker. + </p> + <table> + <tr><th>Parameter</th> + <th>Default</th> + <th>Description</th></tr> + <tr><td>lbmethod</td> + <td>-</td> + <td>Balancer load-balance method. Select the load-balancing scheduler + method to use. Either <code>byrequests</code>, to perform weighted + request counting or <code>bytraffic</code>, to perform weighted + traffic byte count balancing. Default is <code>byrequests</code>. + </td></tr> + <tr><td>stickysession</td> + <td>-</td> + <td>Balancer sticky session name. The value is usually set to something + like <code>JSESSIONID</code> or <code>PHPSESSIONID</code>, + and it depends on the backend application server that support sessions. + </td></tr> + <tr><td>nofailover</td> + <td>Off</td> + <td>If set to <code>On</code> the session will break if the worker is in + error state or disabled. Set this value to On if backend servers do not + support session replication. + </td></tr> + <tr><td>timeout</td> + <td>0</td> + <td>Balancer timeout in seconds. If set this will be the maximum time + to wait for a free worker. Default is not to wait. + </td></tr> + <tr><td>maxattempts</td> + <td>1</td> + <td>Maximum number of failover attempts before giving up. + </td></tr> + + </table> + <div class="example"><p><code> + ProxyPass /special-area http://special.example.com/ smax=5 max=10<br /> + ProxyPass / balancer://mycluster stickysession=jsessionid nofailover=On<br /> + <Proxy balancer://mycluster><br /> + <span class="indent"> + BalancerMember http://1.2.3.4:8009<br /> + BalancerMember http://1.2.3.5:8009 smax=10<br /> + # Less powerful server, don't send as many requests there<br /> + BalancerMember http://1.2.3.6:8009 smax=1 loadfactor=20<br /> + </span> + </Proxy> + </code></p></div> + + <p>When used inside a <code class="directive"><a href="../mod/core.html#location"><Location></a></code> section, the first argument is omitted and the local + directory is obtained from the <code class="directive"><a href="../mod/core.html#location"><Location></a></code>.</p> + + <p>If you require a more flexible reverse-proxy configuration, see the + <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive with the + <code>[P]</code> flag.</p> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="ProxyPassReverse" id="ProxyPassReverse">ProxyPassReverse</a> <a name="proxypassreverse" id="proxypassreverse">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adjusts the URL in HTTP response headers sent from a reverse +proxied server</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverse [<var>path</var>] <var>url</var></code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +</table> + <p>This directive lets Apache adjust the URL in the <code>Location</code>, + <code>Content-Location</code> and <code>URI</code> headers on HTTP redirect + responses. This is essential when Apache is used as a reverse proxy to avoid + by-passing the reverse proxy because of HTTP redirects on the backend + servers which stay behind the reverse proxy.</p> + + <p>Only the HTTP response headers specifically mentioned above + will be rewritten. Apache will not rewrite other response + headers, nor will it rewrite URL references inside HTML pages. + This means that if the proxied content contains absolute URL + references, they will by-pass the proxy. A third-party module + that will look inside the HTML and rewrite URL references is Nick + Kew's <a href="http://apache.webthing.com/mod_proxy_html/">mod_proxy_html</a>.</p> + + <p><var>path</var> is the name of a local virtual path. <var>url</var> is a + partial URL for the remote server - the same way they are used for the + <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p> + + <p>For example, suppose the local server has address + <code>http://example.com/</code>; then</p> + + <div class="example"><p><code> + ProxyPass /mirror/foo/ http://backend.example.com/<br /> + ProxyPassReverse /mirror/foo/ http://backend.example.com/<br /> + ProxyPassReverseCookieDomain backend.example.com public.example.com<br /> + ProxyPassReverseCookiePath / /mirror/foo/ + </code></p></div> + + <p>will not only cause a local request for the + <code>http://example.com/mirror/foo/bar</code> to be internally converted + into a proxy request to <code>http://backend.example.com/bar</code> + (the functionality <code>ProxyPass</code> provides here). It also takes care + of redirects the server <code>backend.example.com</code> sends: when + <code>http://backend.example.com/bar</code> is redirected by him to + <code>http://backend.example.com/quux</code> Apache adjusts this to + <code>http://example.com/mirror/foo/quux</code> before forwarding the HTTP + redirect response to the client. Note that the hostname used for + constructing the URL is chosen in respect to the setting of the <code class="directive"><a href="../mod/core.html#usecanonicalname">UseCanonicalName</a></code> directive.</p> + + <p>Note that this <code class="directive">ProxyPassReverse</code> directive can + also be used in conjunction with the proxy pass-through feature + (<code>RewriteRule ... [P]</code>) from <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> + because it doesn't depend on a corresponding <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p> + + <p>When used inside a <code class="directive"><a href="../mod/core.html#location"><Location></a></code> section, the first argument is omitted and the local + directory is obtained from the <code class="directive"><a href="../mod/core.html#location"><Location></a></code>.</p> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="ProxyPassReverseCookieDomain" id="ProxyPassReverseCookieDomain">ProxyPassReverseCookieDomain</a> <a name="proxypassreversecookiedomain" id="proxypassreversecookiedomain">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adjusts the Domain string in Set-Cookie headers from a reverse- +proxied server</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverseCookieDomain <var>internal-domain</var> <var>public-domain</var></code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +</table> +<p>Usage is basically similar to +<code class="directive"><a href="#proxypassreverse">ProxyPassReverse</a></code>, but instead of +rewriting headers that are a URL, this rewrites the <code>domain</code> +string in <code>Set-Cookie</code> headers.</p> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="ProxyPassReverseCookiePath" id="ProxyPassReverseCookiePath">ProxyPassReverseCookiePath</a> <a name="proxypassreversecookiepath" id="proxypassreversecookiepath">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adjusts the Path string in Set-Cookie headers from a reverse- +proxied server</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverseCookiePath <var>internal-path</var> <var>public-path</var></code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +</table> +<p>Usage is basically similar to +<code class="directive"><a href="#proxypassreverse">ProxyPassReverse</a></code>, but instead of +rewriting headers that are a URL, this rewrites the <code>path</code> +string in <code>Set-Cookie</code> headers.</p> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="ProxyPreserveHost" id="ProxyPreserveHost">ProxyPreserveHost</a> <a name="proxypreservehost" id="proxypreservehost">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use incoming Host HTTP request header for proxy +request</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPreserveHost On|Off</code></td></tr> +<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyPreserveHost Off</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.0.31 and later.</td></tr> +</table> + <p>When enabled, this option will pass the Host: line from the incoming + request to the proxied host, instead of the hostname specified in the + <code class="directive">ProxyPass</code> line.</p> + + <p>This option should normally be turned <code>Off</code>. It is mostly + useful in special configurations like proxied mass name-based virtual + hosting, where the original Host header needs to be evaluated by the + backend server.</p> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="ProxyReceiveBufferSize" id="ProxyReceiveBufferSize">ProxyReceiveBufferSize</a> <a name="proxyreceivebuffersize" id="proxyreceivebuffersize">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Network buffer size for proxied HTTP and FTP +connections</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyReceiveBufferSize <var>bytes</var></code></td></tr> +<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyReceiveBufferSize 0</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +</table> + <p>The <code class="directive">ProxyReceiveBufferSize</code> directive specifies an + explicit (TCP/IP) network buffer size for proxied HTTP and FTP connections, + for increased throughput. It has to be greater than <code>512</code> or set + to <code>0</code> to indicate that the system's default buffer size should + be used.</p> + + <div class="example"><h3>Example</h3><p><code> + ProxyReceiveBufferSize 2048 + </code></p></div> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="ProxyRemote" id="ProxyRemote">ProxyRemote</a> <a name="proxyremote" id="proxyremote">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Remote proxy used to handle certain requests</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyRemote <var>match</var> <var>remote-server</var></code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +</table> + <p>This defines remote proxies to this proxy. <var>match</var> is either the + name of a URL-scheme that the remote server supports, or a partial URL + for which the remote server should be used, or <code>*</code> to indicate + the server should be contacted for all requests. <var>remote-server</var> is + a partial URL for the remote server. Syntax:</p> + + <div class="example"><p><code> + <dfn>remote-server</dfn> = + <var>scheme</var>://<var>hostname</var>[:<var>port</var>] + </code></p></div> + + <p><var>scheme</var> is effectively the protocol that should be used to + communicate with the remote server; only <code>http</code> is supported by + this module.</p> + + <div class="example"><h3>Example</h3><p><code> + ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000<br /> + ProxyRemote * http://cleversite.com<br /> + ProxyRemote ftp http://ftpproxy.mydomain.com:8080 + </code></p></div> + + <p>In the last example, the proxy will forward FTP requests, encapsulated + as yet another HTTP proxy request, to another proxy which can handle + them.</p> + + <p>This option also supports reverse proxy configuration - a backend + webserver can be embedded within a virtualhost URL space even if that + server is hidden by another forward proxy.</p> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="ProxyRemoteMatch" id="ProxyRemoteMatch">ProxyRemoteMatch</a> <a name="proxyremotematch" id="proxyremotematch">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Remote proxy used to handle requests matched by regular +expressions</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyRemoteMatch <var>regex</var> <var>remote-server</var></code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +</table> + <p>The <code class="directive">ProxyRemoteMatch</code> is identical to the + <code class="directive"><a href="#proxyremote">ProxyRemote</a></code> directive, except the + first argument is a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a> + match against the requested URL.</p> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="ProxyRequests" id="ProxyRequests">ProxyRequests</a> <a name="proxyrequests" id="proxyrequests">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables forward (standard) proxy requests</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyRequests On|Off</code></td></tr> +<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyRequests Off</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +</table> + <p>This allows or prevents Apache from functioning as a forward proxy + server. (Setting ProxyRequests to <code>Off</code> does not disable use of + the <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.)</p> + + <p>In a typical reverse proxy configuration, this option should be set to + <code>Off</code>.</p> + + <p>In order to get the functionality of proxying HTTP or FTP sites, you + 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> + (or both) present in the server.</p> + + <div class="warning"><h3>Warning</h3> + <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 network and to the Internet at large.</p> + </div> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="ProxyTimeout" id="ProxyTimeout">ProxyTimeout</a> <a name="proxytimeout" id="proxytimeout">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Network timeout for proxied requests</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyTimeout <var>seconds</var></code></td></tr> +<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyTimeout 300</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.0.31 and later</td></tr> +</table> + <p>This directive allows a user to specifiy a timeout on proxy requests. + This is useful when you have a slow/buggy appserver which hangs, and you + would rather just return a timeout and fail gracefully instead of waiting + however long it takes the server to return.</p> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="ProxyVia" id="ProxyVia">ProxyVia</a> <a name="proxyvia" id="proxyvia">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Information provided in the <code>Via</code> HTTP response +header for proxied requests</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyVia On|Off|Full|Block</code></td></tr> +<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyVia Off</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> +<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> +<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> +</table> + <p>This directive controls the use of the <code>Via:</code> HTTP + header by the proxy. Its intended use is to control the flow of + 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 + 14.45 for an explanation of <code>Via:</code> header lines.</p> + + <ul> + <li>If set to <code>Off</code>, which is the default, no special processing + is performed. If a request or reply contains a <code>Via:</code> header, + it is passed through unchanged.</li> + + <li>If set to <code>On</code>, each request and reply will get a + <code>Via:</code> header line added for the current host.</li> + + <li>If set to <code>Full</code>, each generated <code>Via:</code> header + line will additionally have the Apache server version shown as a + <code>Via:</code> comment field.</li> + + <li>If set to <code>Block</code>, every proxy request will have all its + <code>Via:</code> header lines removed. No new <code>Via:</code> header will + be generated.</li> + </ul> + +</div> +</div> +<div class="bottomlang"> +<p><span>Available Languages: </span><a href="../en/mod/mod_proxy.html" title="English"> en </a> | +<a href="../ja/mod/mod_proxy.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p> +</div><div id="footer"> +<p class="apache">Copyright 2006 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> +<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div> +</body></html>
\ No newline at end of file |