mirror of
https://github.com/apache/httpd.git
synced 2025-10-27 09:35:38 +03:00
0848891b92
Add Proxy100Continue directive to allow for 100-continue forwarding opt-out. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1856036 13f79535-47bb-0310-9956-ffa450edef68
2170 lines
97 KiB
XML
2170 lines
97 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
|
|
<!-- $LastChangedRevision$ -->
|
|
|
|
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
|
|
<modulesynopsis metafile="mod_proxy.xml.meta">
|
|
|
|
<name>mod_proxy</name>
|
|
<description>Multi-protocol proxy/gateway server</description>
|
|
<status>Extension</status>
|
|
<sourcefile>mod_proxy.c</sourcefile>
|
|
<identifier>proxy_module</identifier>
|
|
|
|
<summary>
|
|
<note type="warning"><title>Warning</title>
|
|
<p>Do not enable proxying with <directive module="mod_proxy"
|
|
>ProxyRequests</directive> 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>
|
|
</note>
|
|
|
|
<p><module>mod_proxy</module> and related modules implement a
|
|
proxy/gateway for Apache HTTP Server, supporting a number of popular
|
|
protocols as well as several different load balancing algorithms.
|
|
Third-party modules can add support for additional protocols and
|
|
load balancing algorithms.</p>
|
|
|
|
<p>A set of modules must be loaded into the server to provide the
|
|
necessary features. These modules can be included statically at
|
|
build time or dynamically via the
|
|
<directive module="mod_so">LoadModule</directive> directive).
|
|
The set must include:</p>
|
|
|
|
<ul>
|
|
<li><module>mod_proxy</module>, which provides basic proxy
|
|
capabilities</li>
|
|
|
|
<li><module>mod_proxy_balancer</module> and one or more
|
|
balancer modules if load balancing is required. (See
|
|
<module>mod_proxy_balancer</module> for more information.)</li>
|
|
|
|
<li>one or more proxy scheme, or protocol, modules:
|
|
|
|
<table border="1">
|
|
<tr><th>Protocol</th><th>Module</th></tr>
|
|
<tr><td>AJP13 (Apache JServe Protocol version
|
|
1.3)</td><td><module>mod_proxy_ajp</module></td></tr>
|
|
<tr><td>CONNECT (for
|
|
SSL)</td><td><module>mod_proxy_connect</module></td></tr>
|
|
<tr><td>FastCGI</td><td><module>mod_proxy_fcgi</module></td></tr>
|
|
<tr><td>ftp</td><td><module>mod_proxy_ftp</module></td></tr>
|
|
<tr><td>HTTP/0.9, HTTP/1.0, and
|
|
HTTP/1.1</td><td><module>mod_proxy_http</module></td></tr>
|
|
<tr><td>SCGI</td><td><module>mod_proxy_scgi</module></td></tr>
|
|
<tr><td>WS and WSS (Web-sockets)</td><td><module>mod_proxy_wstunnel</module></td></tr>
|
|
</table>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>In addition, extended features are provided by other modules.
|
|
Caching is provided by <module>mod_cache</module> and related
|
|
modules. The ability to contact remote servers using the SSL/TLS
|
|
protocol is provided by the <code>SSLProxy*</code> directives of
|
|
<module>mod_ssl</module>. These additional modules will need
|
|
to be loaded and configured to take advantage of these features.</p>
|
|
</summary>
|
|
<seealso><module>mod_cache</module></seealso>
|
|
<seealso><module>mod_proxy_ajp</module></seealso>
|
|
<seealso><module>mod_proxy_balancer</module></seealso>
|
|
<seealso><module>mod_proxy_connect</module></seealso>
|
|
<seealso><module>mod_proxy_fcgi</module></seealso>
|
|
<seealso><module>mod_proxy_ftp</module></seealso>
|
|
<seealso><module>mod_proxy_hcheck</module></seealso>
|
|
<seealso><module>mod_proxy_http</module></seealso>
|
|
<seealso><module>mod_proxy_scgi</module></seealso>
|
|
<seealso><module>mod_proxy_wstunnel</module></seealso>
|
|
<seealso><module>mod_ssl</module></seealso>
|
|
|
|
<section id="forwardreverse"><title>Forward Proxies and Reverse
|
|
Proxies/Gateways</title>
|
|
<p>Apache HTTP Server can be configured in both a <dfn>forward</dfn> and
|
|
<dfn>reverse</dfn> proxy (also known as <dfn>gateway</dfn>) mode.</p>
|
|
|
|
<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. 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 <module>mod_cache</module>) to reduce network usage.</p>
|
|
|
|
<p>The forward proxy is activated using the <directive
|
|
module="mod_proxy">ProxyRequests</directive> directive. Because
|
|
forward proxies allow clients to access arbitrary sites through
|
|
your server and to hide their true origin, it is essential that
|
|
you <a href="#access">secure your server</a> so that only
|
|
authorized clients can access the proxy before activating a
|
|
forward proxy.</p>
|
|
|
|
<p>A <dfn>reverse proxy</dfn> (or <dfn>gateway</dfn>), by
|
|
contrast, appears to the client just like an ordinary web
|
|
server. No special configuration on the client is necessary.
|
|
The client makes ordinary requests for content in the namespace
|
|
of the reverse proxy. The reverse proxy then decides where to
|
|
send those requests and returns the content as if it were 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 <directive
|
|
module="mod_proxy">ProxyPass</directive> directive or the
|
|
<code>[P]</code> flag to the <directive
|
|
module="mod_rewrite">RewriteRule</directive> directive. It is
|
|
<strong>not</strong> necessary to turn <directive
|
|
module="mod_proxy">ProxyRequests</directive> on in order to
|
|
configure a reverse proxy.</p>
|
|
</section> <!-- /forwardreverse -->
|
|
|
|
<section id="examples"><title>Basic Examples</title>
|
|
|
|
<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 <module>mod_cache</module>.</p>
|
|
|
|
<example><title>Reverse Proxy</title>
|
|
<highlight language="config">
|
|
ProxyPass "/foo" "http://foo.example.com/bar"
|
|
ProxyPassReverse "/foo" "http://foo.example.com/bar"
|
|
</highlight>
|
|
</example>
|
|
|
|
<example><title>Forward Proxy</title>
|
|
<highlight language="config">
|
|
ProxyRequests On
|
|
ProxyVia On
|
|
|
|
<Proxy *>
|
|
Require host internal.example.com
|
|
</Proxy>
|
|
</highlight>
|
|
</example>
|
|
</section> <!-- /examples -->
|
|
|
|
<section id="handler"><title>Access via Handler</title>
|
|
|
|
<p>You can also force a request to be handled as a reverse-proxy
|
|
request, by creating a suitable Handler pass-through. The example
|
|
configuration below will pass all requests for PHP scripts to the
|
|
specified FastCGI server using reverse proxy:
|
|
</p>
|
|
|
|
<example><title>Reverse Proxy PHP scripts</title>
|
|
<highlight language="config">
|
|
<FilesMatch "\.php$">
|
|
SetHandler "proxy:unix:/path/to/app.sock|fcgi://localhost/"
|
|
</FilesMatch>
|
|
</highlight>
|
|
</example>
|
|
|
|
<p>This feature is available in Apache HTTP Server 2.4.10 and later.</p>
|
|
|
|
</section> <!-- /handler -->
|
|
|
|
<section id="workers"><title>Workers</title>
|
|
<p>The proxy manages the configuration of origin servers and their
|
|
communication parameters in objects called <dfn>workers</dfn>.
|
|
There are two built-in workers: the default forward proxy worker and the
|
|
default reverse proxy worker. Additional workers can be configured
|
|
explicitly.</p>
|
|
|
|
<p>The two default workers have a fixed configuration
|
|
and will be used if no other worker matches the request.
|
|
They do not use HTTP Keep-Alive or connection reuse.
|
|
The TCP connections to the origin server will instead be
|
|
opened and closed for each request.</p>
|
|
|
|
<p>Explicitly configured workers are identified by their URL.
|
|
They are usually created and configured using
|
|
<directive module="mod_proxy">ProxyPass</directive> or
|
|
<directive module="mod_proxy">ProxyPassMatch</directive> when used
|
|
for a reverse proxy:</p>
|
|
|
|
<highlight language="config">
|
|
ProxyPass "/example" "http://backend.example.com" connectiontimeout=5 timeout=30
|
|
</highlight>
|
|
|
|
<p>This will create a worker associated with the origin server URL
|
|
<code>http://backend.example.com</code> that will use the given timeout
|
|
values. All timeouts use the <a href="directive-dict.html#Syntax">time-interval</a>
|
|
directive syntax. When used in a forward proxy, workers are usually defined
|
|
via the <directive module="mod_proxy">ProxySet</directive> directive:</p>
|
|
|
|
<highlight language="config">
|
|
ProxySet http://backend.example.com connectiontimeout=5 timeout=30
|
|
</highlight>
|
|
|
|
<p>or alternatively using <directive module="mod_proxy">Proxy</directive>
|
|
and <directive module="mod_proxy">ProxySet</directive>:</p>
|
|
|
|
<highlight language="config">
|
|
<Proxy http://backend.example.com>
|
|
ProxySet connectiontimeout=5 timeout=30
|
|
</Proxy>
|
|
</highlight>
|
|
|
|
<p>Using explicitly configured workers in the forward mode is
|
|
not very common, because forward proxies usually communicate with many
|
|
different origin servers. Creating explicit workers for some of the
|
|
origin servers can still be useful if they are used very often.
|
|
Explicitly configured workers have no concept of forward or reverse
|
|
proxying by themselves. They encapsulate a common concept of
|
|
communication with origin servers. A worker created by
|
|
<directive module="mod_proxy">ProxyPass</directive> for use in a
|
|
reverse proxy will also be used for forward proxy requests whenever
|
|
the URL to the origin server matches the worker URL, and vice versa.</p>
|
|
|
|
<p>The URL identifying a direct worker is the URL of its
|
|
origin server including any path components given:</p>
|
|
|
|
<highlight language="config">
|
|
ProxyPass "/examples" "http://backend.example.com/examples"
|
|
ProxyPass "/docs" "http://backend.example.com/docs"
|
|
</highlight>
|
|
|
|
<p>This example defines two different workers, each using a separate
|
|
connection pool and configuration.</p>
|
|
|
|
<note type="warning"><title>Worker Sharing</title>
|
|
<p>Worker sharing happens if the worker URLs overlap, which occurs when
|
|
the URL of some worker is a leading substring of the URL of another
|
|
worker defined later in the configuration file. In the following example</p>
|
|
|
|
<highlight language="config">
|
|
ProxyPass "/apps" "http://backend.example.com/" timeout=60
|
|
ProxyPass "/examples" "http://backend.example.com/examples" timeout=10
|
|
</highlight>
|
|
|
|
<p>the second worker isn't actually created. Instead the first
|
|
worker is used. The benefit is, that there is only one connection pool,
|
|
so connections are more often reused. Note that all configuration attributes
|
|
given explicitly for the later worker will be ignored. This will be logged
|
|
as a warning. In the above example, the resulting timeout value
|
|
for the URL <code>/examples</code> will be <code>60</code> instead
|
|
of <code>10</code>!</p>
|
|
|
|
<p>If you want to avoid worker sharing, sort your worker definitions
|
|
by URL length, starting with the longest worker URLs. If you want to maximize
|
|
worker sharing, use the reverse sort order. See also the related warning about
|
|
ordering <directive module="mod_proxy">ProxyPass</directive> directives.</p>
|
|
|
|
</note> <!-- /worker_sharing -->
|
|
|
|
<note type="warning"><title>Host part in the URL</title>
|
|
<p>The host part needs to start with a letter [a-z]. For example:</p>
|
|
<highlight language="config">
|
|
ProxyPass "/apps" "http://127"
|
|
</highlight>
|
|
<p>is not valid and will cause an error while processing a request that
|
|
maps the path.</p>
|
|
</note>
|
|
|
|
<p>Explicitly configured workers come in two flavors:
|
|
<dfn>direct workers</dfn> and <dfn>(load) balancer workers</dfn>.
|
|
They support many important configuration attributes which are
|
|
described below in the <directive module="mod_proxy">ProxyPass</directive>
|
|
directive. The same attributes can also be set using
|
|
<directive module="mod_proxy">ProxySet</directive>.</p>
|
|
|
|
<p>The set of options available for a direct worker
|
|
depends on the protocol which is specified in the origin server URL.
|
|
Available protocols include <code>ajp</code>, <code>fcgi</code>,
|
|
<code>ftp</code>, <code>http</code> and <code>scgi</code>.</p>
|
|
|
|
<p>Balancer workers are virtual workers that use direct workers known
|
|
as their members to actually handle the requests. Each balancer can
|
|
have multiple members. When it handles a request, it chooses a member
|
|
based on the configured load balancing algorithm.</p>
|
|
|
|
<p>A balancer worker is created if its worker URL uses
|
|
<code>balancer</code> as the protocol scheme.
|
|
The balancer URL uniquely identifies the balancer worker.
|
|
Members are added to a balancer using
|
|
<directive module="mod_proxy">BalancerMember</directive>.</p>
|
|
|
|
<note><title>DNS resolution for origin domains</title>
|
|
<p>DNS resolution happens when the socket to
|
|
the origin domain is created for the first time.
|
|
When connection reuse is enabled, each backend domain is resolved
|
|
only once per child process, and cached for all further connections
|
|
until the child is recycled. This information should to be considered
|
|
while planning DNS maintenance tasks involving backend domains.
|
|
Please also check <directive module="mod_proxy">ProxyPass</directive>
|
|
parameters for more details about connection reuse.
|
|
</p>
|
|
</note>
|
|
|
|
</section> <!-- /workers -->
|
|
|
|
<section id="access"><title>Controlling Access to Your Proxy</title>
|
|
<p>You can control who can access your proxy via the <directive
|
|
module="mod_proxy" type="section">Proxy</directive> control block as in
|
|
the following example:</p>
|
|
|
|
<highlight language="config">
|
|
<Proxy *>
|
|
Require ip 192.168.0
|
|
</Proxy>
|
|
</highlight>
|
|
|
|
<p>For more information on access control directives, see
|
|
<module>mod_authz_host</module>.</p>
|
|
|
|
<p>Strictly limiting access is essential if you are using a
|
|
forward proxy (using the <directive
|
|
module="mod_proxy">ProxyRequests</directive> 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 <directive
|
|
module="mod_proxy">ProxyPass</directive> directive with
|
|
<code>ProxyRequests Off</code>), access control is less
|
|
critical because clients can only contact the hosts that you
|
|
have specifically configured.</p>
|
|
|
|
<p><strong>See Also</strong> the <a href="mod_proxy_http.html#env"
|
|
>Proxy-Chain-Auth</a> environment variable.</p>
|
|
|
|
</section> <!-- /access -->
|
|
|
|
<section id="startup"><title>Slow Startup</title>
|
|
<p>If you're using the <directive module="mod_proxy"
|
|
>ProxyBlock</directive> 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>
|
|
</section> <!-- /startup -->
|
|
|
|
<section id="intranet"><title>Intranet Proxy</title>
|
|
<p>An Apache httpd proxy server situated in an intranet needs to forward
|
|
external requests through the company's firewall (for this, configure
|
|
the <directive module="mod_proxy">ProxyRemote</directive> 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 <directive module="mod_proxy">NoProxy</directive>
|
|
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 <directive module="mod_proxy"
|
|
>ProxyDomain</directive> directive is used and the server is <a
|
|
href="#proxyrequests">configured for proxy service</a>, Apache httpd can return
|
|
a redirect response and send the client to the correct, fully qualified,
|
|
server address. This is the preferred method since the user's bookmark
|
|
files will then contain fully qualified hosts.</p>
|
|
</section> <!-- /intranet -->
|
|
|
|
<section id="envsettings"><title>Protocol Adjustments</title>
|
|
<p>For circumstances where <module>mod_proxy</module> 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
|
|
<directive module="mod_env">SetEnv</directive> directive.</p>
|
|
|
|
<p>These are the <code>force-proxy-request-1.0</code> and
|
|
<code>proxy-nokeepalive</code> notes.</p>
|
|
|
|
<highlight language="config">
|
|
<Location "/buggyappserver/">
|
|
ProxyPass "http://buggyappserver:7001/foo/"
|
|
SetEnv force-proxy-request-1.0 1
|
|
SetEnv proxy-nokeepalive 1
|
|
</Location>
|
|
</highlight>
|
|
|
|
<p> In 2.4.26 and later, the "no-proxy" environment variable can be set to disable
|
|
<module>mod_proxy</module> processing the current request.
|
|
This variable should be set with <directive module="mod_setenvif"
|
|
>SetEnvIf</directive>, as <directive module="mod_env">SetEnv</directive>
|
|
is not evaluated early enough.</p>
|
|
|
|
</section> <!-- /envsettings -->
|
|
|
|
<section id="request-bodies"><title>Request Bodies</title>
|
|
|
|
<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, <module>mod_proxy_http</module>
|
|
will always attempt to send the <code>Content-Length</code>. But
|
|
if the body is large and the original request used chunked
|
|
encoding, then chunked encoding may also be used in the upstream
|
|
request. You can control this selection using <a
|
|
href="../env.html">environment variables</a>. Setting
|
|
<code>proxy-sendcl</code> ensures maximum compatibility with
|
|
upstream servers by always sending the
|
|
<code>Content-Length</code>, while setting
|
|
<code>proxy-sendchunked</code> minimizes resource usage by using
|
|
chunked encoding.</p>
|
|
|
|
<p>Under some circumstances, the server must spool request bodies
|
|
to disk to satisfy the requested handling of request bodies. For
|
|
example, this spooling will occur if the original body was sent with
|
|
chunked encoding (and is large), but the administrator has
|
|
asked for backend requests to be sent with Content-Length or as HTTP/1.0.
|
|
This spooling can also occur if the request body already has a
|
|
Content-Length header, but the server is configured to filter incoming
|
|
request bodies.</p>
|
|
|
|
<p><directive module="core">LimitRequestBody</directive> only applies to
|
|
request bodies that the server will spool to disk</p>
|
|
|
|
</section> <!-- /request-bodies -->
|
|
|
|
<section id="x-headers"><title>Reverse Proxy Request Headers</title>
|
|
|
|
<p>When acting in a reverse-proxy mode (using the <directive
|
|
module="mod_proxy">ProxyPass</directive> directive, for example),
|
|
<module>mod_proxy_http</module> adds several request headers in
|
|
order to pass information to the origin server. These headers
|
|
are:</p>
|
|
|
|
<dl>
|
|
<dt><code>X-Forwarded-For</code></dt>
|
|
<dd>The IP address of the client.</dd>
|
|
<dt><code>X-Forwarded-Host</code></dt>
|
|
<dd>The original host requested by the client in the <code>Host</code>
|
|
HTTP request header.</dd>
|
|
<dt><code>X-Forwarded-Server</code></dt>
|
|
<dd>The hostname of the proxy server.</dd>
|
|
</dl>
|
|
|
|
<p>Be careful when using these headers on the origin server, since
|
|
they will contain more than one (comma-separated) value if the
|
|
original request already contained one of these headers. For
|
|
example, you can use <code>%{X-Forwarded-For}i</code> in the log
|
|
format string of the origin server to log the original clients IP
|
|
address, but you may get more than one address if the request
|
|
passes through several proxies.</p>
|
|
|
|
<p>See also the <directive
|
|
module="mod_proxy">ProxyPreserveHost</directive> and <directive
|
|
module="mod_proxy">ProxyVia</directive> directives, which control
|
|
other request headers.</p>
|
|
|
|
<p>Note: If you need to specify custom request headers to be
|
|
added to the forwarded request, use the
|
|
<directive module="mod_headers">RequestHeader</directive>
|
|
directive.</p>
|
|
|
|
</section> <!--/x-headers -->
|
|
|
|
|
|
<directivesynopsis type="section">
|
|
<name>Proxy</name>
|
|
<description>Container for directives applied to proxied resources</description>
|
|
<syntax><Proxy <var>wildcard-url</var>> ...</Proxy></syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>Directives placed in <directive type="section">Proxy</directive>
|
|
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>
|
|
|
|
<highlight language="config">
|
|
<Proxy *>
|
|
Require host yournetwork.example.com
|
|
</Proxy>
|
|
</highlight>
|
|
|
|
<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>
|
|
|
|
<highlight language="config">
|
|
<Proxy http://example.com/foo/*>
|
|
SetOutputFilter INCLUDES
|
|
</Proxy>
|
|
</highlight>
|
|
|
|
<p>The next example will allow web clients from the specified IP
|
|
addresses to issue <code>CONNECT</code> requests to access the
|
|
<code>https://www.example.com/</code> SSL server if
|
|
<module>mod_proxy_connect</module> is enabled.
|
|
</p>
|
|
|
|
<highlight language="config">
|
|
<Proxy www.example.com:443>
|
|
Require ip 192.168.0.0/16
|
|
</Proxy>
|
|
</highlight>
|
|
|
|
<note><title>Differences from the Location configuration section</title>
|
|
<p>A backend URL matches the configuration section if it begins with the
|
|
the <var>wildcard-url</var> string, even if the last path segment in the
|
|
directive only matches a prefix of the backend URL. For example,
|
|
<Proxy http://example.com/foo> matches all of
|
|
http://example.com/foo, http://example.com/foo/bar, and
|
|
http://example.com/foobar. The matching of the final URL differs
|
|
from the behavior of the <directive type="section" module="core"
|
|
>Location</directive> section, which for purposes of this note
|
|
treats the final path component as if it ended in a slash.</p>
|
|
<p>For more control over the matching, see <directive type="section"
|
|
>ProxyMatch</directive>.</p>
|
|
</note>
|
|
|
|
</usage>
|
|
<seealso><directive type="section" module="mod_proxy">ProxyMatch</directive></seealso>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyBadHeader</name>
|
|
<description>Determines how to handle bad header lines in a
|
|
response</description>
|
|
<syntax>ProxyBadHeader IsError|Ignore|StartBody</syntax>
|
|
<default>ProxyBadHeader IsError</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive>ProxyBadHeader</directive> directive determines the
|
|
behavior of <module>mod_proxy</module> if it receives syntactically invalid
|
|
response header lines (<em>i.e.</em> containing no colon) from the origin
|
|
server. The following arguments are possible:</p>
|
|
|
|
<dl>
|
|
<dt><code>IsError</code></dt>
|
|
<dd>Abort the request and end up with a 502 (Bad Gateway) response. This is
|
|
the default behavior.</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>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis type="section">
|
|
<name>ProxyMatch</name>
|
|
<description>Container for directives applied to regular-expression-matched
|
|
proxied resources</description>
|
|
<syntax><ProxyMatch <var>regex</var>> ...</ProxyMatch></syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive type="section">ProxyMatch</directive> directive is
|
|
identical to the <directive module="mod_proxy"
|
|
type="section">Proxy</directive> directive, except that it matches URLs
|
|
using <glossary ref="regex">regular expressions</glossary>.</p>
|
|
|
|
<p>From 2.4.8 onwards, named groups and backreferences are captured and
|
|
written to the environment with the corresponding name prefixed with
|
|
"MATCH_" and in upper case. This allows elements of URLs to be referenced
|
|
from within <a href="../expr.html">expressions</a> and modules like
|
|
<module>mod_rewrite</module>. In order to prevent confusion, numbered
|
|
(unnamed) backreferences are ignored. Use named groups instead.</p>
|
|
|
|
<highlight language="config">
|
|
<ProxyMatch ^http://(?<sitename>[^/]+)>
|
|
require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example
|
|
</ProxyMatch>
|
|
</highlight>
|
|
</usage>
|
|
<seealso><directive type="section" module="mod_proxy">Proxy</directive></seealso>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyPreserveHost</name>
|
|
<description>Use incoming Host HTTP request header for proxy
|
|
request</description>
|
|
<syntax>ProxyPreserveHost On|Off</syntax>
|
|
<default>ProxyPreserveHost Off</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context>
|
|
</contextlist>
|
|
<compatibility>Usable in directory
|
|
context in 2.3.3 and later.</compatibility>
|
|
|
|
<usage>
|
|
<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
|
|
<directive module="mod_proxy">ProxyPass</directive> 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>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyRequests</name>
|
|
<description>Enables forward (standard) proxy requests</description>
|
|
<syntax>ProxyRequests On|Off</syntax>
|
|
<default>ProxyRequests Off</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>This allows or prevents Apache httpd from functioning as a forward proxy
|
|
server. (Setting ProxyRequests to <code>Off</code> does not disable use of
|
|
the <directive module="mod_proxy">ProxyPass</directive> directive.)</p>
|
|
|
|
<p>In a typical reverse proxy or gateway configuration, this
|
|
option should be set to
|
|
<code>Off</code>.</p>
|
|
|
|
<p>In order to get the functionality of proxying HTTP or FTP sites, you
|
|
need also <module>mod_proxy_http</module> or <module>mod_proxy_ftp</module>
|
|
(or both) present in the server.</p>
|
|
|
|
<p>In order to get the functionality of (forward) proxying HTTPS sites, you
|
|
need <module>mod_proxy_connect</module> enabled in the server.</p>
|
|
|
|
<note type="warning"><title>Warning</title>
|
|
<p>Do not enable proxying with <directive
|
|
module="mod_proxy">ProxyRequests</directive> 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>
|
|
</note>
|
|
</usage>
|
|
<seealso><a href="#forwardreverse">Forward and Reverse Proxies/Gateways</a></seealso>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyRemote</name>
|
|
<description>Remote proxy used to handle certain requests</description>
|
|
<syntax>ProxyRemote <var>match</var> <var>remote-server</var></syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<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>
|
|
|
|
<example>
|
|
<dfn>remote-server</dfn> =
|
|
<var>scheme</var>://<var>hostname</var>[:<var>port</var>]
|
|
</example>
|
|
|
|
<p><var>scheme</var> is effectively the protocol that should be used to
|
|
communicate with the remote server; only <code>http</code> and <code>https</code>
|
|
are supported by this module. When using <code>https</code>, the requests
|
|
are forwarded through the remote proxy using the HTTP CONNECT method.</p>
|
|
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
ProxyRemote http://goodguys.example.com/ http://mirrorguys.example.com:8000
|
|
ProxyRemote * http://cleverproxy.localdomain
|
|
ProxyRemote ftp http://ftpproxy.mydomain:8080
|
|
</highlight>
|
|
</example>
|
|
|
|
<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>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyRemoteMatch</name>
|
|
<description>Remote proxy used to handle requests matched by regular
|
|
expressions</description>
|
|
<syntax>ProxyRemoteMatch <var>regex</var> <var>remote-server</var></syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive>ProxyRemoteMatch</directive> is identical to the
|
|
<directive module="mod_proxy">ProxyRemote</directive> directive, except that
|
|
the first argument is a <glossary ref="regex">regular expression</glossary>
|
|
match against the requested URL.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>BalancerGrowth</name>
|
|
<description>Number of additional Balancers that can be added Post-configuration</description>
|
|
<syntax>BalancerGrowth <var>#</var></syntax>
|
|
<default>BalancerGrowth 5</default>
|
|
<contextlist><context>server config</context><context>virtual host</context></contextlist>
|
|
<compatibility>BalancerGrowth is only available in Apache HTTP Server 2.3.13
|
|
and later.</compatibility>
|
|
<usage>
|
|
<p>This directive allows for growth potential in the number of
|
|
Balancers available for a virtualhost in addition to the
|
|
number pre-configured. It only takes effect if there is at
|
|
least one pre-configured Balancer.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>BalancerPersist</name>
|
|
<description>Attempt to persist changes made by the Balancer Manager across restarts.</description>
|
|
<syntax>BalancerPersist On|Off</syntax>
|
|
<default>BalancerPersist Off</default>
|
|
<contextlist><context>server config</context><context>virtual host</context></contextlist>
|
|
<compatibility>BalancerPersist is only available in Apache HTTP Server 2.4.4 and later.</compatibility>
|
|
<usage>
|
|
<p>This directive will cause the shared memory storage associated
|
|
with the balancers and balancer members to be persisted across
|
|
restarts. This allows these local changes to not be lost during the
|
|
normal restart/graceful state transitions.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyPassInherit</name>
|
|
<description>Inherit ProxyPass directives defined from the main server</description>
|
|
<syntax>ProxyPassInherit On|Off</syntax>
|
|
<default>ProxyPassInherit On</default>
|
|
<contextlist><context>server config</context><context>virtual host</context></contextlist>
|
|
<compatibility>ProxyPassInherit is only available in Apache HTTP Server 2.4.5 and later.
|
|
</compatibility>
|
|
<usage>
|
|
<p>This directive will cause the current server/vhost to "inherit"
|
|
<directive module="mod_proxy">ProxyPass</directive>
|
|
directives defined in the main server. This can cause issues and
|
|
inconsistent behavior if using the Balancer Manager for dynamic changes
|
|
and so should be disabled if using that feature.</p>
|
|
<p>The setting in the global server defines the default for all vhosts.</p>
|
|
<p>Disabling ProxyPassInherit also disables <directive module="mod_proxy">BalancerInherit</directive>.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>BalancerInherit</name>
|
|
<description>Inherit proxy Balancers/Workers defined from the main server</description>
|
|
<syntax>BalancerInherit On|Off</syntax>
|
|
<default>BalancerInherit On</default>
|
|
<contextlist><context>server config</context><context>virtual host</context></contextlist>
|
|
<compatibility>BalancerInherit is only available in Apache HTTP Server 2.4.5 and later.</compatibility>
|
|
<usage>
|
|
<p>This directive will cause the current server/vhost to "inherit"
|
|
Balancers and Workers defined in the main server. This can cause issues and
|
|
inconsistent behavior if using the Balancer Manager for dynamic changes
|
|
and so should be disabled if using that feature.</p>
|
|
<p>The setting in the global server defines the default for all vhosts.</p>
|
|
<p>Disabling <directive module="mod_proxy">ProxyPassInherit</directive> also disables BalancerInherit.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>BalancerMember</name>
|
|
<description>Add a member to a load balancing group</description>
|
|
<syntax>BalancerMember [<var>balancerurl</var>] <var>url</var> [<var
|
|
>key=value [key=value ...]]</var></syntax>
|
|
<contextlist><context>directory</context>
|
|
</contextlist>
|
|
<usage>
|
|
<p>This directive adds a member to a load balancing group. It can be used
|
|
within a <code><Proxy <var>balancer://</var>...></code> container
|
|
directive and can take any of the key value pair parameters available to
|
|
<directive module="mod_proxy">ProxyPass</directive> directives.</p>
|
|
<p>One additional parameter is available only to <directive>BalancerMember</directive> directives:
|
|
<var>loadfactor</var>. This is the member load factor - a decimal between 1.0
|
|
(default) and 100.0, which defines the weighted load to be applied to the
|
|
member in question.</p>
|
|
<p>The <var>balancerurl</var> is only needed when not within a
|
|
<code><Proxy <var>balancer://</var>...></code>
|
|
container directive. It corresponds to the url of a balancer defined in
|
|
<directive module="mod_proxy">ProxyPass</directive> directive.</p>
|
|
<p>The path component of the balancer URL in any
|
|
<code><Proxy <var>balancer://</var>...></code> container directive
|
|
is ignored.</p>
|
|
<p>Trailing slashes should typically be removed from the URL of a
|
|
<directive>BalancerMember</directive>.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxySet</name>
|
|
<description>Set various Proxy balancer or member parameters</description>
|
|
<syntax>ProxySet <var>url</var> <var>key=value [key=value ...]</var></syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context>
|
|
</contextlist>
|
|
<usage>
|
|
<p>This directive is used as an alternate method of setting any of the
|
|
parameters available to Proxy balancers and workers normally done via the
|
|
<directive module="mod_proxy">ProxyPass</directive> directive. If used
|
|
within a <code><Proxy <var>balancer url|worker url</var>></code>
|
|
container directive, the <var>url</var> argument is not required. As a side
|
|
effect the respective balancer or worker gets created. This can be useful
|
|
when doing reverse proxying via a
|
|
<directive module="mod_rewrite">RewriteRule</directive> instead of a
|
|
<directive module="mod_proxy">ProxyPass</directive> directive.</p>
|
|
|
|
<example>
|
|
<highlight language="config">
|
|
<Proxy balancer://hotcluster>
|
|
BalancerMember http://www2.example.com:8080 loadfactor=1
|
|
BalancerMember http://www3.example.com:8080 loadfactor=2
|
|
ProxySet lbmethod=bytraffic
|
|
</Proxy>
|
|
</highlight>
|
|
</example>
|
|
|
|
<highlight language="config">
|
|
<Proxy http://backend>
|
|
ProxySet keepalive=On
|
|
</Proxy>
|
|
</highlight>
|
|
|
|
<highlight language="config">
|
|
ProxySet balancer://foo lbmethod=bytraffic timeout=15
|
|
</highlight>
|
|
|
|
<highlight language="config">
|
|
ProxySet ajp://backend:7001 timeout=15
|
|
</highlight>
|
|
|
|
<note type="warning"><title>Warning</title>
|
|
<p>Keep in mind that the same parameter key can have a different meaning
|
|
depending whether it is applied to a balancer or a worker, as shown by
|
|
the two examples above regarding timeout.</p>
|
|
</note>
|
|
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyPass</name>
|
|
<description>Maps remote servers into the local server URL-space</description>
|
|
<syntax>ProxyPass [<var>path</var>] !|<var>url</var> [<var>key=value</var>
|
|
<var>[key=value</var> ...]] [nocanon] [interpolate] [noquery]</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context>
|
|
</contextlist>
|
|
<compatibility>Unix Domain Socket (UDS) support added in 2.4.7</compatibility>
|
|
|
|
<usage>
|
|
<p>This directive allows remote servers to be mapped into the
|
|
space of the local server. The local server does not act as a
|
|
proxy in the conventional sense but appears to be a mirror of the
|
|
remote server. The local server is often called a <dfn>reverse
|
|
proxy</dfn> or <dfn>gateway</dfn>. The <var>path</var> is the name of
|
|
a local virtual path; <var>url</var> is a partial URL for the
|
|
remote server and cannot include a query string.</p>
|
|
|
|
<note>It is strongly suggested to review the concept of a
|
|
<a href="#workers">Worker</a> before proceeding any further
|
|
with this section.</note>
|
|
|
|
<note>This directive is not supported within
|
|
<directive type="section" module="core">Directory</directive>,
|
|
<directive type="section" module="core">If</directive> and
|
|
<directive type="section" module="core">Files</directive> containers.
|
|
</note>
|
|
|
|
<note type="warning">The <directive
|
|
module="mod_proxy">ProxyRequests</directive> directive should
|
|
usually be set <strong>off</strong> when using
|
|
<directive>ProxyPass</directive>.</note>
|
|
|
|
<p>In 2.4.7 and later, support for using a Unix Domain Socket is available by using a target
|
|
which prepends <code>unix:/path/lis.sock|</code>. For example, to proxy
|
|
HTTP and target the UDS at /home/www.socket, you would use
|
|
<code>unix:/home/www.socket|http://localhost/whatever/</code>. Since
|
|
the socket is local, the hostname used (in this case <code>localhost</code>)
|
|
is moot, but it is passed as the Host: header value of the request.</p>
|
|
|
|
<note><strong>Note:</strong> The path associated with the <code>unix:</code>
|
|
URL is <directive>DefaultRuntimeDir</directive> aware.</note>
|
|
|
|
<note><strong>Note:</strong> <directive>RewriteRule</directive> requires
|
|
the <code>[P,NE]</code> option to prevent the <code>'|'</code> character
|
|
from being escaped.</note>
|
|
|
|
<p>When used inside a <directive type="section" module="core"
|
|
>Location</directive> section, the first argument is omitted and the local
|
|
directory is obtained from the <directive type="section" module="core"
|
|
>Location</directive>. The same will occur inside a
|
|
<directive type="section" module="core">LocationMatch</directive> section;
|
|
however, ProxyPass does not interpret the regexp as such, so it is necessary
|
|
to use <directive>ProxyPassMatch</directive> in this situation instead.</p>
|
|
|
|
<p>Suppose the local server has address <code>http://example.com/</code>;
|
|
then</p>
|
|
|
|
<highlight language="config">
|
|
<Location "/mirror/foo/">
|
|
ProxyPass "http://backend.example.com/"
|
|
</Location>
|
|
</highlight>
|
|
|
|
<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>If you require a more flexible reverse-proxy configuration, see the
|
|
<directive module="mod_rewrite">RewriteRule</directive> directive with the
|
|
<code>[P]</code> flag.</p>
|
|
|
|
<p>The following alternative syntax is possible; however, it can carry a
|
|
performance penalty when present in very large numbers. The advantage of
|
|
the below syntax is that it allows for dynamic control via the
|
|
<a href="mod_proxy_balancer.html#balancer_manager">Balancer Manager</a> interface:</p>
|
|
|
|
<highlight language="config">
|
|
ProxyPass "/mirror/foo/" "http://backend.example.com/"
|
|
</highlight>
|
|
|
|
<note type="warning">
|
|
<p>If the first argument ends with a trailing <strong>/</strong>, the second
|
|
argument should also end with a trailing <strong>/</strong>, and vice
|
|
versa. Otherwise, the resulting requests to the backend may miss some
|
|
needed slashes and do not deliver the expected results.
|
|
</p>
|
|
</note>
|
|
|
|
<p>The <code>!</code> directive is useful in situations where you don't want
|
|
to reverse-proxy a subdirectory, <em>e.g.</em></p>
|
|
|
|
<highlight language="config">
|
|
<Location "/mirror/foo/">
|
|
ProxyPass "http://backend.example.com/"
|
|
</Location>
|
|
<Location "/mirror/foo/i">
|
|
ProxyPass "!"
|
|
</Location>
|
|
</highlight>
|
|
|
|
<highlight language="config">
|
|
ProxyPass "/mirror/foo/i" "!"
|
|
ProxyPass "/mirror/foo" "http://backend.example.com"
|
|
</highlight>
|
|
|
|
<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>
|
|
|
|
<p>Mixing ProxyPass settings in different contexts does not work:</p>
|
|
<highlight language="config">
|
|
ProxyPass "/mirror/foo/i" "!"
|
|
<Location "/mirror/foo/">
|
|
ProxyPass "http://backend.example.com/"
|
|
</Location>
|
|
</highlight>
|
|
<p>In this case, a request to <code>/mirror/foo/i</code> will get proxied,
|
|
because the <directive>ProxyPass</directive> directive in the Location block will be evaluated
|
|
first. The fact that <directive>ProxyPass</directive> supports both server and directory contexts
|
|
does not mean that their scope and position in the configuration file will
|
|
guarantee any ordering or override.</p>
|
|
|
|
<note type="warning"><title>Ordering ProxyPass Directives</title>
|
|
<p>The configured <directive module="mod_proxy">ProxyPass</directive>
|
|
and <directive module="mod_proxy">ProxyPassMatch</directive>
|
|
rules are checked in the order of configuration. The first rule that
|
|
matches wins. So usually you should sort conflicting
|
|
<directive module="mod_proxy">ProxyPass</directive> rules starting with the
|
|
longest URLs first. Otherwise, later rules for longer URLS will be hidden
|
|
by any earlier rule which uses a leading substring of the URL. Note that
|
|
there is some relation with worker sharing.</p>
|
|
</note>
|
|
<note type="warning"><title>Ordering ProxyPass Directives in Locations</title>
|
|
<p>Only one <directive module="mod_proxy">ProxyPass</directive> directive
|
|
can be placed in a <directive module="core">Location</directive> block,
|
|
and the most specific location will take precedence.</p>
|
|
</note>
|
|
<note type="warning"><title>Exclusions and the no-proxy environment variable</title>
|
|
<p>Exclusions must come <em>before</em> the
|
|
general <directive>ProxyPass</directive> directives. In 2.4.26 and later, the "no-proxy"
|
|
environment variable is an alternative to exclusions, and is the only
|
|
way to configure an exclusion of a <directive>ProxyPass</directive>
|
|
directive in <directive module="core">Location</directive> context.
|
|
This variable should be set with <directive module="mod_setenvif"
|
|
>SetEnvIf</directive>, as <directive module="mod_env">SetEnv</directive>
|
|
is not evaluated early enough.
|
|
</p>
|
|
|
|
</note> <!-- /ordering_proxypass -->
|
|
|
|
<p><strong>ProxyPass <code>key=value</code> Parameters</strong></p>
|
|
|
|
<p>In Apache HTTP Server 2.1 and later, mod_proxy supports pooled
|
|
connections to a backend server. Connections created on demand
|
|
can be retained in a pool for future use. Limits on the pool size
|
|
and other settings can be coded on
|
|
the <directive>ProxyPass</directive> directive
|
|
using <code>key=value</code> parameters, described in the tables
|
|
below.</p>
|
|
|
|
<note type="warning"><title>Maximum connections to the backend</title>
|
|
<p>By default, mod_proxy will allow and retain the maximum number of
|
|
connections that could be used simultaneously by that web server child
|
|
process. Use the <code>max</code> parameter to reduce the number from
|
|
the default. The pool of connections is maintained per web server child
|
|
process, and <code>max</code> and other settings are not coordinated
|
|
among all child processes, except when only one child process is allowed
|
|
by configuration or MPM design.</p>
|
|
</note>
|
|
|
|
<p>Use the <code>ttl</code> parameter to set an optional
|
|
time to live; connections which have been unused for at least
|
|
<code>ttl</code> seconds will be closed. <code>ttl</code> can be used
|
|
to avoid using a connection which is subject to closing because of the
|
|
backend server's keep-alive timeout.</p>
|
|
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
ProxyPass "/example" "http://backend.example.com" max=20 ttl=120 retry=300
|
|
</highlight>
|
|
</example>
|
|
|
|
<table border="2"><tr><th>Worker|BalancerMember parameters</th></tr></table>
|
|
<table>
|
|
<tr><th>Parameter</th>
|
|
<th>Default</th>
|
|
<th>Description</th></tr>
|
|
<tr><td>min</td>
|
|
<td>0</td>
|
|
<td>Minimum number of connection pool entries, unrelated to the
|
|
actual number of connections. This only needs to be modified from the
|
|
default for special circumstances where heap memory associated with the
|
|
backend connections should be preallocated or retained.</td></tr>
|
|
<tr><td>max</td>
|
|
<td>1...n</td>
|
|
<td>Maximum number of connections that will be allowed to the
|
|
backend server. The default for this limit is the number of threads
|
|
per process in the active MPM. In the Prefork MPM, this is always 1;
|
|
while with other MPMs, it is controlled by the
|
|
<directive>ThreadsPerChild</directive> directive.</td></tr>
|
|
<tr><td>smax</td>
|
|
<td>max</td>
|
|
<td>Retained connection pool entries above this limit are freed
|
|
during certain operations if they have been unused for longer than
|
|
the time to live, controlled by the <code>ttl</code> parameter. If
|
|
the connection pool entry has an associated connection, it will be
|
|
closed. This only needs to be modified from the default for special
|
|
circumstances where connection pool entries and any associated
|
|
connections which have exceeded the time to live need to be freed or
|
|
closed more aggressively.</td></tr>
|
|
<tr><td>acquire</td>
|
|
<td>-</td>
|
|
<td>If set, this will be the maximum time to wait for a free
|
|
connection in the connection pool, in milliseconds. If there are no free
|
|
connections in the pool, the Apache httpd will return <code>SERVER_BUSY</code>
|
|
status to the client.
|
|
</td></tr>
|
|
<tr><td>connectiontimeout</td>
|
|
<td>timeout</td>
|
|
<td>Connect timeout in seconds.
|
|
The number of seconds Apache httpd waits for the creation of a connection to
|
|
the backend to complete. By adding a postfix of ms, the timeout can be
|
|
also set in milliseconds. Uses the <a href="directive-dict.html#Syntax">time-interval</a> directive syntax
|
|
</td></tr>
|
|
<tr><td>disablereuse</td>
|
|
<td>Off</td>
|
|
<td>This parameter should be used when you want to force mod_proxy
|
|
to immediately close a connection to the backend after being used, and
|
|
thus, disable its persistent connection and pool for that backend.
|
|
This helps in various situations where a firewall between Apache
|
|
httpd and
|
|
the backend server (regardless of protocol) tends to silently
|
|
drop connections or when backends themselves may be under round-
|
|
robin DNS.
|
|
When connection reuse is enabled each backend domain is resolved
|
|
(with a DNS query) only once per child process and cached for all further
|
|
connections until the child is recycled. To disable connection reuse,
|
|
set this property value to <code>On</code>.
|
|
</td></tr>
|
|
<tr><td>enablereuse</td>
|
|
<td>On</td>
|
|
<td>This is the inverse of 'disablereuse' above, provided as a
|
|
convenience for scheme handlers that require opt-in for connection
|
|
reuse (such as <module>mod_proxy_fcgi</module>).
|
|
</td></tr>
|
|
<tr><td>flushpackets</td>
|
|
<td>off</td>
|
|
<td>Determines whether the proxy module will auto-flush the output
|
|
brigade after each "chunk" of data. 'off' means that it will flush
|
|
only when needed; 'on' means after each chunk is sent; and
|
|
'auto' means poll/wait for a period of time and flush if
|
|
no input has been received for 'flushwait' milliseconds.
|
|
Currently, this is in effect only for mod_proxy_ajp and mod_proxy_fcgi.
|
|
</td></tr>
|
|
<tr><td>flushwait</td>
|
|
<td>10</td>
|
|
<td>The time to wait for additional input, in milliseconds, before
|
|
flushing the output brigade if 'flushpackets' is 'auto'.
|
|
Uses <a href="directive-dict.html#Syntax">time-interval</a> directive syntax.
|
|
</td></tr>
|
|
<tr><td>iobuffersize</td>
|
|
<td>8192</td>
|
|
<td>Adjusts the size of the internal scratchpad IO buffer. This allows you
|
|
to override the <directive>ProxyIOBufferSize</directive> for a specific worker.
|
|
This must be at least 512 or set to 0 for the system default of 8192.
|
|
</td></tr>
|
|
<tr><td>responsefieldsize</td>
|
|
<td>8192</td>
|
|
<td>Adjust the size of the proxy response field buffer. The buffer size
|
|
should be at least the size of the largest expected header size from
|
|
a proxied response. Setting the value to 0 will use the system
|
|
default of 8192 bytes.<br />
|
|
Available in Apache HTTP Server 2.4.34 and later.
|
|
</td></tr>
|
|
<tr><td>keepalive</td>
|
|
<td>Off</td>
|
|
<td><p>This parameter should be used when you have a firewall between your
|
|
Apache httpd and the backend server, which tends to drop inactive connections.
|
|
This flag will tell the Operating System to send <code>KEEP_ALIVE</code>
|
|
messages on inactive connections and thus prevent the firewall
|
|
from dropping the connection.
|
|
To enable keepalive, set this property value to <code>On</code>. </p>
|
|
<p>The frequency of initial and subsequent TCP keepalive probes
|
|
depends on global OS settings, and may be as high as 2 hours. To be useful,
|
|
the frequency configured in the OS must be smaller than the threshold used
|
|
by the firewall. Uses the <a href="directive-dict.html#Syntax">time-interval</a> directive syntax.</p>
|
|
</td></tr>
|
|
<tr><td>lbset</td>
|
|
<td>0</td>
|
|
<td>Sets the load balancer cluster set that the worker is a member
|
|
of. The load balancer will try all members of a lower numbered
|
|
lbset before trying higher numbered ones.
|
|
</td></tr>
|
|
<tr><td>ping</td>
|
|
<td>0</td>
|
|
<td>Ping property tells the webserver to "test" the connection to
|
|
the backend before forwarding the request. For negative values,
|
|
the test is a simple socket check; for positive values, it's
|
|
a more functional check, dependent upon the protocol. For AJP, it causes
|
|
<module>mod_proxy_ajp</module> to send a <code>CPING</code>
|
|
request on the ajp13 connection (implemented on Tomcat 3.3.2+, 4.1.28+
|
|
and 5.0.13+). For HTTP, it causes <module>mod_proxy_http</module>
|
|
to send a <code>100-Continue</code> to the backend (only valid for
|
|
HTTP/1.1 - for non HTTP/1.1 backends, this property has no
|
|
effect). In both cases, the parameter is the delay in seconds to wait
|
|
for the reply.
|
|
This feature has been added to avoid problems with hung and
|
|
busy backends.
|
|
This will increase the network traffic during the normal operation
|
|
which could be an issue, but it will lower the
|
|
traffic in case some of the cluster nodes are down or busy.
|
|
By adding a postfix of ms, the delay can be also set in
|
|
milliseconds. Uses the <a href="directive-dict.html#Syntax">time-interval</a> directive syntax.
|
|
</td></tr>
|
|
<tr><td>receivebuffersize</td>
|
|
<td>0</td>
|
|
<td>Adjusts the size of the explicit (TCP/IP) network buffer size for
|
|
proxied connections. This allows you to override the
|
|
<directive>ProxyReceiveBufferSize</directive> for a specific worker.
|
|
This must be at least 512 or set to 0 for the system default.
|
|
</td></tr>
|
|
<tr><td>redirect</td>
|
|
<td>-</td>
|
|
<td>Redirection Route of the worker. This value is usually
|
|
set dynamically to enable safe removal of the node from
|
|
the cluster. If set, all requests without session id will be
|
|
redirected to the BalancerMember that has route parameter
|
|
equal to this value.
|
|
</td></tr>
|
|
<tr><td>retry</td>
|
|
<td>60</td>
|
|
<td>Connection pool worker retry timeout in seconds.
|
|
If the connection pool worker to the backend server is in the error state,
|
|
Apache httpd will not forward any requests to that server until the timeout
|
|
expires. This enables to shut down the backend server for maintenance
|
|
and bring it back online later. A value of 0 means always retry workers
|
|
in an error state with no timeout.
|
|
Uses the <a href="directive-dict.html#Syntax">time-interval</a> directive syntax.
|
|
</td></tr>
|
|
<tr><td>route</td>
|
|
<td>-</td>
|
|
<td>Route of the worker when used inside load balancer.
|
|
The route is a value appended to session id.
|
|
</td></tr>
|
|
<tr><td><a name="status_table">status</a></td>
|
|
<td>-</td>
|
|
<td>Single letter value defining the initial status of
|
|
this worker.
|
|
<table border="1">
|
|
<tr><td><code>D</code></td><td>Worker is disabled and will not accept any requests; will be
|
|
automatically retried.</td></tr>
|
|
<tr><td><code>S</code></td><td>Worker is administratively stopped; will not accept requests
|
|
and will not be automatically retried.</td></tr>
|
|
<tr><td><code>I</code></td><td>Worker is in ignore-errors mode and will always be considered available.</td></tr>
|
|
<tr><td><code>R</code></td><td>Worker is a hot spare. For each worker in a given lbset that is unusable
|
|
(draining, stopped, in error, etc.), a usable hot spare with the same lbset will be used in
|
|
its place. Hot spares can help ensure that a specific number of workers are always available
|
|
for use by a balancer.</td></tr>
|
|
<tr><td><code>H</code></td><td>Worker is in hot-standby mode and will only be used if no other
|
|
viable workers or spares are available in the balancer set.</td></tr>
|
|
<tr><td><code>E</code></td><td>Worker is in an error state.</td></tr>
|
|
<tr><td><code>N</code></td><td>Worker is in drain mode and will only accept existing sticky sessions
|
|
destined for itself and ignore all other requests.</td></tr>
|
|
</table>
|
|
Status can be set (which is the default) by prepending with '+' or
|
|
cleared by prepending with '-'.
|
|
Thus, a setting of 'S-E' sets this worker to Stopped and
|
|
clears the in-error flag.
|
|
</td></tr>
|
|
<tr><td>timeout</td>
|
|
<td><directive module="mod_proxy">ProxyTimeout</directive></td>
|
|
<td>Connection timeout in seconds.
|
|
The number of seconds Apache httpd waits for data sent by / to the backend.
|
|
Uses the <a href="directive-dict.html#Syntax">time-interval</a> directive syntax.
|
|
</td></tr>
|
|
<tr><td>ttl</td>
|
|
<td>-</td>
|
|
<td>Time to live for inactive connections and associated connection
|
|
pool entries, in seconds. Once reaching this limit, a
|
|
connection will not be used again; it will be closed at some
|
|
later time. Uses the <a href="directive-dict.html#Syntax">time-interval</a> directive syntax.
|
|
</td></tr>
|
|
<tr><td>flusher</td>
|
|
<td>flush</td>
|
|
<td><p>Name of the provider used by <module>mod_proxy_fdpass</module>.
|
|
See the documentation of this module for more details.</p>
|
|
</td></tr>
|
|
<tr><td>secret</td>
|
|
<td>-</td>
|
|
<td><p>Value of secret used by <module>mod_proxy_ajp</module>.
|
|
See the documentation of this module for more details.</p>
|
|
</td></tr>
|
|
<tr><td>upgrade</td>
|
|
<td>WebSocket</td>
|
|
<td><p>Protocol accepted in the Upgrade header by <module>mod_proxy_wstunnel</module>.
|
|
See the documentation of this module for more details.</p>
|
|
</td></tr>
|
|
|
|
</table>
|
|
|
|
<p>If the Proxy directive scheme starts with the
|
|
<code>balancer://</code> (eg: <code>balancer://cluster</code>,
|
|
any path information is ignored), then a virtual worker that does not really
|
|
communicate with the backend server will be created. Instead, it is responsible
|
|
for the management of several "real" workers. In that case, the special set of
|
|
parameters can be added to this virtual worker. See <module>mod_proxy_balancer</module>
|
|
for more information about how the balancer works.
|
|
</p>
|
|
<table border="2"><tr><th>Balancer parameters</th></tr></table>
|
|
<table>
|
|
<tr><th>Parameter</th>
|
|
<th>Default</th>
|
|
<th>Description</th></tr>
|
|
<tr><td>lbmethod</td>
|
|
<td>byrequests</td>
|
|
<td>Balancer load-balance method. Select the load-balancing scheduler
|
|
method to use. Either <code>byrequests</code>, to perform weighted
|
|
request counting; <code>bytraffic</code>, to perform weighted
|
|
traffic byte count balancing; or <code>bybusyness</code>, to perform
|
|
pending request balancing. The default is <code>byrequests</code>.
|
|
</td></tr>
|
|
<tr><td>maxattempts</td>
|
|
<td>One less than the number of workers, or 1 with a single worker.</td>
|
|
<td>Maximum number of failover attempts before giving up.
|
|
</td></tr>
|
|
<tr><td>nofailover</td>
|
|
<td>Off</td>
|
|
<td>If set to <code>On</code>, the session will break if the worker is in
|
|
error state or disabled. Set this value to <code>On</code> if backend
|
|
servers do not support session replication.
|
|
</td></tr>
|
|
<tr><td>stickysession</td>
|
|
<td>-</td>
|
|
<td>Balancer sticky session name. The value is usually set to something
|
|
like <code>JSESSIONID</code> or <code>PHPSESSIONID</code>,
|
|
and it depends on the backend application server that support sessions.
|
|
If the backend application server uses different names for cookies
|
|
and url encoded id (like servlet containers), use | to separate them.
|
|
The first part is for the cookie; the second is for the path.<br />
|
|
Available in Apache HTTP Server 2.4.4 and later.
|
|
</td></tr>
|
|
<tr><td>stickysessionsep</td>
|
|
<td>"."</td>
|
|
<td>Sets the separation symbol in the session cookie. Some backend application servers
|
|
do not use the '.' as the symbol. For example, the Oracle Weblogic server uses
|
|
'!'. The correct symbol can be set using this option. The setting of 'Off'
|
|
signifies that no symbol is used.
|
|
</td></tr>
|
|
<tr><td>scolonpathdelim</td>
|
|
<td>Off</td>
|
|
<td>If set to <code>On</code>, the semi-colon character ';' will be
|
|
used as an additional sticky session path delimiter/separator. This
|
|
is mainly used to emulate mod_jk's behavior when dealing with paths such
|
|
as <code>JSESSIONID=6736bcf34;foo=aabfa</code>
|
|
</td></tr>
|
|
<tr><td>timeout</td>
|
|
<td>0</td>
|
|
<td>Balancer timeout in seconds. If set, this will be the maximum time
|
|
to wait for a free worker. The default is to not wait.
|
|
Uses the <a href="directive-dict.html#Syntax">time-interval</a> directive syntax.
|
|
</td></tr>
|
|
<tr><td>failonstatus</td>
|
|
<td>-</td>
|
|
<td>A single or comma-separated list of HTTP status codes. If set, this will
|
|
force the worker into error state when the backend returns any status code
|
|
in the list. Worker recovery behaves the same as other worker errors.
|
|
</td></tr>
|
|
<tr><td>failontimeout</td>
|
|
<td>Off</td>
|
|
<td>If set, an IO read timeout after a request is sent to the backend will
|
|
force the worker into error state. Worker recovery behaves the same as other
|
|
worker errors.<br />
|
|
Available in Apache HTTP Server 2.4.5 and later.
|
|
</td></tr>
|
|
<tr><td>nonce</td>
|
|
<td><auto></td>
|
|
<td>The protective nonce used in the <code>balancer-manager</code> application page.
|
|
The default is to use an automatically determined UUID-based
|
|
nonce, to provide for further protection for the page. If set,
|
|
then the nonce is set to that value. A setting of <code>None</code>
|
|
disables all nonce checking.
|
|
<note><title>Note</title>
|
|
<p>In addition to the nonce, the <code>balancer-manager</code> page
|
|
should be protected via an ACL.</p>
|
|
</note>
|
|
</td></tr>
|
|
<tr><td>growth</td>
|
|
<td>0</td>
|
|
<td>Number of additional BalancerMembers to allow to be added
|
|
to this balancer in addition to those defined at configuration.
|
|
</td></tr>
|
|
<tr><td>forcerecovery</td>
|
|
<td>On</td>
|
|
<td>Force the immediate recovery of all workers without considering the
|
|
retry parameter of the workers if all workers of a balancer are
|
|
in error state. There might be cases where an already overloaded backend
|
|
can get into deeper trouble if the recovery of all workers is enforced
|
|
without considering the retry parameter of each worker. In this case,
|
|
set to <code>Off</code>.<br />
|
|
Available in Apache HTTP Server 2.4.2 and later.
|
|
</td></tr>
|
|
|
|
</table>
|
|
<p>A sample balancer setup:</p>
|
|
<highlight language="config">
|
|
ProxyPass "/special-area" "http://special.example.com" smax=5 max=10
|
|
ProxyPass "/" "balancer://mycluster/" stickysession=JSESSIONID|jsessionid nofailover=On
|
|
<Proxy balancer://mycluster>
|
|
BalancerMember ajp://1.2.3.4:8009
|
|
BalancerMember ajp://1.2.3.5:8009 loadfactor=20
|
|
# Less powerful server, don't send as many requests there,
|
|
BalancerMember ajp://1.2.3.6:8009 loadfactor=5
|
|
</Proxy>
|
|
</highlight>
|
|
|
|
<p>Configuring hot spares can help ensure that a certain number of
|
|
workers are always available for use per load balancer set:</p>
|
|
<highlight language="config">
|
|
ProxyPass "/" "balancer://sparecluster/"
|
|
<Proxy balancer://sparecluster>
|
|
BalancerMember ajp://1.2.3.4:8009
|
|
BalancerMember ajp://1.2.3.5:8009
|
|
# The servers below are hot spares. For each server above that is unusable
|
|
# (draining, stopped, unreachable, in error state, etc.), one of these spares
|
|
# will be used in its place. Two servers will always be available for a request
|
|
# unless one or more of the spares is also unusable.
|
|
BalancerMember ajp://1.2.3.6:8009 status=+R
|
|
BalancerMember ajp://1.2.3.7:8009 status=+R
|
|
</Proxy>
|
|
</highlight>
|
|
|
|
<p>Setting up a hot-standby that will only be used if no other
|
|
members (or spares) are available in the load balancer set:</p>
|
|
<highlight language="config">
|
|
ProxyPass "/" "balancer://hotcluster/"
|
|
<Proxy balancer://hotcluster>
|
|
BalancerMember ajp://1.2.3.4:8009 loadfactor=1
|
|
BalancerMember ajp://1.2.3.5:8009 loadfactor=2.25
|
|
# The server below is on hot standby
|
|
BalancerMember ajp://1.2.3.6:8009 status=+H
|
|
ProxySet lbmethod=bytraffic
|
|
</Proxy>
|
|
</highlight>
|
|
|
|
<p><strong>Additional ProxyPass Keywords</strong></p>
|
|
|
|
<p>Normally, mod_proxy will canonicalise ProxyPassed URLs.
|
|
But this may be incompatible with some backends, particularly those
|
|
that make use of <var>PATH_INFO</var>. The optional <var>nocanon</var>
|
|
keyword suppresses this and passes the URL path "raw" to the
|
|
backend. Note that this keyword may affect the security of your backend,
|
|
as it removes the normal limited protection against URL-based attacks
|
|
provided by the proxy.</p>
|
|
|
|
<p>Normally, mod_proxy will include the query string when
|
|
generating the <var>SCRIPT_FILENAME</var> environment variable.
|
|
The optional <var>noquery</var> keyword (available in
|
|
httpd 2.4.1 and later) prevents this.</p>
|
|
|
|
<p>The optional <var>interpolate</var> keyword, in combination with
|
|
<directive module="mod_proxy">ProxyPassInterpolateEnv</directive>, causes the ProxyPass
|
|
to interpolate environment variables, using the syntax
|
|
<var>${VARNAME}</var>. Note that many of the standard CGI-derived
|
|
environment variables will not exist when this interpolation happens,
|
|
so you may still have to resort to <module>mod_rewrite</module>
|
|
for complex rules. Also note that interpolation is supported
|
|
within the scheme/hostname/port portion of a URL only for variables that
|
|
are available when the directive is parsed
|
|
(like <directive module="core">Define</directive>). Dynamic determination of
|
|
those fields can be accomplished with <module>mod_rewrite</module>.
|
|
The following example describes how to use <module>mod_rewrite</module>
|
|
to dynamically set the scheme to http or https:</p>
|
|
|
|
<highlight language="config">
|
|
RewriteEngine On
|
|
|
|
RewriteCond %{HTTPS} =off
|
|
RewriteRule . - [E=protocol:http]
|
|
RewriteCond %{HTTPS} =on
|
|
RewriteRule . - [E=protocol:https]
|
|
|
|
RewriteRule ^/mirror/foo/(.*) %{ENV:protocol}://backend.example.com/$1 [P]
|
|
ProxyPassReverse "/mirror/foo/" "http://backend.example.com/"
|
|
ProxyPassReverse "/mirror/foo/" "https://backend.example.com/"
|
|
</highlight>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyPassMatch</name>
|
|
<description>Maps remote servers into the local server URL-space using regular expressions</description>
|
|
<syntax>ProxyPassMatch [<var>regex</var>] !|<var>url</var> [<var>key=value</var>
|
|
<var>[key=value</var> ...]]</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>This directive is equivalent to <directive module="mod_proxy">ProxyPass</directive>
|
|
but makes use of regular expressions instead of simple prefix matching. The
|
|
supplied regular expression is matched against the <var>url</var>, and if it
|
|
matches, the server will substitute any parenthesized matches into the given
|
|
string and use it as a new <var>url</var>.</p>
|
|
|
|
<note><strong>Note: </strong>This directive cannot be used within a
|
|
<code><Directory></code> context.</note>
|
|
|
|
<p>Suppose the local server has address <code>http://example.com/</code>;
|
|
then</p>
|
|
|
|
<highlight language="config">
|
|
ProxyPassMatch "^/(.*\.gif)$" "http://backend.example.com/$1"
|
|
</highlight>
|
|
|
|
<p>will cause a local request for
|
|
<code>http://example.com/foo/bar.gif</code> to be internally converted
|
|
into a proxy request to <code>http://backend.example.com/foo/bar.gif</code>.</p>
|
|
<note><title>Note</title>
|
|
<p>The URL argument must be parsable as a URL <em>before</em> regexp
|
|
substitutions (as well as after). This limits the matches you can use.
|
|
For instance, if we had used</p>
|
|
<highlight language="config">
|
|
ProxyPassMatch "^(/.*\.gif)$" "http://backend.example.com:8000$1"
|
|
</highlight>
|
|
<p>in our previous example, it would fail with a syntax error
|
|
at server startup. This is a bug (PR 46665 in the ASF bugzilla),
|
|
and the workaround is to reformulate the match:</p>
|
|
<highlight language="config">
|
|
ProxyPassMatch "^/(.*\.gif)$" "http://backend.example.com:8000/$1"
|
|
</highlight>
|
|
</note>
|
|
<p>The <code>!</code> directive is useful in situations where you don't want
|
|
to reverse-proxy a subdirectory.</p>
|
|
|
|
<p>When used inside a <directive type="section" module="core"
|
|
>LocationMatch</directive> section, the first argument is omitted and the
|
|
regexp is obtained from the <directive type="section" module="core"
|
|
>LocationMatch</directive>.</p>
|
|
|
|
<p>If you require a more flexible reverse-proxy configuration, see the
|
|
<directive module="mod_rewrite">RewriteRule</directive> directive with the
|
|
<code>[P]</code> flag.</p>
|
|
|
|
<note>
|
|
<title>Default Substitution</title>
|
|
<p>When the URL parameter doesn't use any backreferences into the regular
|
|
expression, the original URL will be appended to the URL parameter.
|
|
</p>
|
|
</note>
|
|
|
|
<note type="warning">
|
|
<title>Security Warning</title>
|
|
<p>Take care when constructing the target URL of the rule, considering
|
|
the security impact from allowing the client influence over the set of
|
|
URLs to which your server will act as a proxy. Ensure that the scheme
|
|
and hostname part of the URL is either fixed or does not allow the
|
|
client undue influence.</p>
|
|
</note>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyPassReverse</name>
|
|
<description>Adjusts the URL in HTTP response headers sent from a reverse
|
|
proxied server</description>
|
|
<syntax>ProxyPassReverse [<var>path</var>] <var>url</var>
|
|
[<var>interpolate</var>]</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>This directive lets Apache httpd 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 httpd is used as a
|
|
reverse proxy (or gateway) to avoid bypassing 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 httpd will not rewrite other response
|
|
headers, nor will it by default rewrite URL references inside HTML pages.
|
|
This means that if the proxied content contains absolute URL
|
|
references, they will bypass the proxy. To rewrite HTML content to
|
|
match the proxy, you must load and enable <module>mod_proxy_html</module>.
|
|
</p>
|
|
|
|
<p><var>path</var> is the name of a local virtual path. It is combined
|
|
with the requests scheme, host, and port to form the replacement
|
|
prefix of the affected response header.
|
|
This parameter is usually the same as the first parameter of the
|
|
<directive module="mod_proxy">ProxyPass</directive> directive.
|
|
</p>
|
|
|
|
<p><var>url</var> is a partial URL for the remote server. When the remote
|
|
server sends the specifically mentioned headers beginning with this partial
|
|
URL, the prefix from the remote server is replaced with a prefix that
|
|
points to the reverse proxy.
|
|
This parameter is usually the same as the second parameter of the
|
|
<directive module="mod_proxy">ProxyPass</directive> directive, but it may
|
|
differ if the remote server uses a different scheme, host, port, or path
|
|
in the affected headers. In configurations with
|
|
<directive module="mod_proxy">ProxyPreserveHost</directive>, the hostname
|
|
in the partial URL may already be the hostname of the reverse proxy, which
|
|
will prevent the matching and replacement done by this directive.
|
|
</p>
|
|
|
|
<p>For example, suppose the local server has address
|
|
<code>http://example.com/</code>; then</p>
|
|
|
|
<highlight language="config">
|
|
ProxyPass "/mirror/foo/" "http://backend.example.com/"
|
|
ProxyPassReverse "/mirror/foo/" "http://backend.example.com/"
|
|
ProxyPassReverseCookieDomain backend.example.com public.example.com
|
|
ProxyPassReverseCookiePath "/" "/mirror/foo/"
|
|
</highlight>
|
|
|
|
<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 which <code>ProxyPass</code> provides here).
|
|
It also takes care of redirects which the server <code>backend.example.com</code> sends
|
|
when redirecting <code>http://backend.example.com/bar</code> to
|
|
<code>http://backend.example.com/quux</code> . Apache httpd 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 <directive
|
|
module="core">UseCanonicalName</directive> directive.</p>
|
|
|
|
<p>Note that this <directive>ProxyPassReverse</directive> directive can
|
|
also be used in conjunction with the proxy feature
|
|
(<code>RewriteRule ... [P]</code>) from <module>mod_rewrite</module>
|
|
because it doesn't depend on a corresponding <directive module="mod_proxy"
|
|
>ProxyPass</directive> directive.</p>
|
|
|
|
<p>The optional <var>interpolate</var> keyword, used together with
|
|
<directive>ProxyPassInterpolateEnv</directive>, enables interpolation
|
|
of environment variables specified using the format <var>${VARNAME}</var>.
|
|
Note that interpolation is not supported within the scheme portion of a
|
|
URL.</p>
|
|
|
|
<p>When used inside a <directive type="section" module="core"
|
|
>Location</directive> section, the first argument is omitted and the local
|
|
directory is obtained from the <directive type="section" module="core"
|
|
>Location</directive>. The same occurs inside a <directive type="section"
|
|
module="core">LocationMatch</directive> section, but will probably not work as
|
|
intended, as ProxyPassReverse will interpret the regexp literally as a
|
|
path; if needed in this situation, specify the ProxyPassReverse outside
|
|
the section or in a separate <directive type="section" module="core"
|
|
>Location</directive> section.</p>
|
|
|
|
<p>This directive is not supported in <directive type="section" module="core"
|
|
>Directory</directive> or <directive type="section" module="core"
|
|
>Files</directive> sections.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyPassReverseCookieDomain</name>
|
|
<description>Adjusts the Domain string in Set-Cookie headers from a reverse-
|
|
proxied server</description>
|
|
<syntax>ProxyPassReverseCookieDomain <var>internal-domain</var>
|
|
<var>public-domain</var> [<var>interpolate</var>]</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context>
|
|
</contextlist>
|
|
<usage>
|
|
<p>Usage is basically similar to
|
|
<directive module="mod_proxy">ProxyPassReverse</directive>, but instead of
|
|
rewriting headers that are a URL, this rewrites the <code>domain</code>
|
|
string in <code>Set-Cookie</code> headers.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyPassReverseCookiePath</name>
|
|
<description>Adjusts the Path string in Set-Cookie headers from a reverse-
|
|
proxied server</description>
|
|
<syntax>ProxyPassReverseCookiePath <var>internal-path</var>
|
|
<var>public-path</var> [<var>interpolate</var>]</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context>
|
|
</contextlist>
|
|
<usage>
|
|
<p>
|
|
Useful in conjunction with
|
|
<directive module="mod_proxy">ProxyPassReverse</directive>
|
|
in situations where backend URL paths are mapped to public paths on the
|
|
reverse proxy. This directive rewrites the <code>path</code> string in
|
|
<code>Set-Cookie</code> headers. If the beginning of the cookie path matches
|
|
<var>internal-path</var>, the cookie path will be replaced with
|
|
<var>public-path</var>.
|
|
</p><p>
|
|
In the example given with
|
|
<directive module="mod_proxy">ProxyPassReverse</directive>, the directive:
|
|
</p>
|
|
<highlight language="config">
|
|
ProxyPassReverseCookiePath "/" "/mirror/foo/"
|
|
</highlight>
|
|
<p>
|
|
will rewrite a cookie with backend path <code>/</code> (or
|
|
<code>/example</code> or, in fact, anything) to <code>/mirror/foo/</code>.
|
|
</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyBlock</name>
|
|
<description>Disallow proxy requests to certain hosts</description>
|
|
<syntax>ProxyBlock *|<var>hostname</var>|<var>partial-hostname</var> [<var>hostname</var>|<var>partial-hostname</var>]...</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive>ProxyBlock</directive> directive can be used to
|
|
block FTP or HTTP access to certain hosts via the proxy, based on
|
|
a full or partial hostname match, or, if applicable, an IP address
|
|
comparison.</p>
|
|
|
|
<p>Each of the arguments to the <directive>ProxyBlock</directive>
|
|
directive can be either <code>*</code> or a alphanumeric string.
|
|
At startup, the module will attempt to resolve every alphanumeric
|
|
string from a DNS name to a set of IP addresses, but any DNS errors
|
|
are ignored.</p>
|
|
|
|
<p>If an asterisk "<code>*</code>" argument is specified,
|
|
<module>mod_proxy</module> will deny access to all FTP or HTTP
|
|
sites.</p>
|
|
|
|
<p>Otherwise, for any request for an HTTP or FTP resource via the
|
|
proxy, <module>mod_proxy</module> will check the hostname of the
|
|
request URI against each specified string. If a partial string
|
|
match is found, access is denied. If no matches against hostnames
|
|
are found, and a remote (forward) proxy is configured using
|
|
<directive>ProxyRemote</directive> or
|
|
<directive>ProxyRemoteMatch</directive>, access is allowed. If no
|
|
remote (forward) proxy is configured, the IP address of the
|
|
hostname from the URI is compared against all resolved IP
|
|
addresses determined at startup. Access is denied if any match is
|
|
found.</p>
|
|
|
|
<p>Note that the DNS lookups may slow down the startup time of the
|
|
server.</p>
|
|
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
ProxyBlock news.example.com auctions.example.com friends.example.com
|
|
</highlight>
|
|
</example>
|
|
|
|
<p>Note that <code>example</code> would also be sufficient to match any
|
|
of these sites.</p>
|
|
|
|
<p>Hosts would also be matched if referenced by IP address.</p>
|
|
|
|
<p>Note also that</p>
|
|
|
|
<highlight language="config">
|
|
ProxyBlock *
|
|
</highlight>
|
|
|
|
<p>blocks connections to all sites.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyReceiveBufferSize</name>
|
|
<description>Network buffer size for proxied HTTP and FTP
|
|
connections</description>
|
|
<syntax>ProxyReceiveBufferSize <var>bytes</var></syntax>
|
|
<default>ProxyReceiveBufferSize 0</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive>ProxyReceiveBufferSize</directive> 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>
|
|
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
ProxyReceiveBufferSize 2048
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyIOBufferSize</name>
|
|
<description>Determine size of internal data throughput buffer</description>
|
|
<syntax>ProxyIOBufferSize <var>bytes</var></syntax>
|
|
<default>ProxyIOBufferSize 8192</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive>ProxyIOBufferSize</directive> directive adjusts the size
|
|
of the internal buffer which is used as a scratchpad for the data between
|
|
input and output. The size must be at least <code>512</code>.</p>
|
|
|
|
<p>In almost every case, there's no reason to change that value.</p>
|
|
|
|
<p>If used with AJP, this directive sets the maximum AJP packet size in
|
|
bytes. Values larger than 65536 are set to 65536. If you change it from
|
|
the default, you must also change the <code>packetSize</code> attribute of
|
|
your AJP connector on the Tomcat side! The attribute
|
|
<code>packetSize</code> is only available in Tomcat <code>5.5.20+</code>
|
|
and <code>6.0.2+</code></p>
|
|
|
|
<p>Normally it is not necessary to change the maximum packet size.
|
|
Problems with the default value have been reported when sending
|
|
certificates or certificate chains.</p>
|
|
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyMaxForwards</name>
|
|
<description>Maximium number of proxies that a request can be forwarded
|
|
through</description>
|
|
<syntax>ProxyMaxForwards <var>number</var></syntax>
|
|
<default>ProxyMaxForwards -1</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive>ProxyMaxForwards</directive> directive specifies the
|
|
maximum number of proxies through which a request may pass if there's no
|
|
<code>Max-Forwards</code> header supplied with the request. This may
|
|
be set to prevent infinite proxy loops or a DoS attack.</p>
|
|
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
ProxyMaxForwards 15
|
|
</highlight>
|
|
</example>
|
|
|
|
<p>Note that setting <directive>ProxyMaxForwards</directive> is a
|
|
violation of the HTTP/1.1 protocol (RFC2616), which forbids a Proxy
|
|
setting <code>Max-Forwards</code> if the Client didn't set it.
|
|
Earlier Apache httpd versions would always set it. A negative
|
|
<directive>ProxyMaxForwards</directive> value, including the
|
|
default -1, gives you protocol-compliant behavior but may
|
|
leave you open to loops.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>NoProxy</name>
|
|
<description>Hosts, domains, or networks that will be connected to
|
|
directly</description>
|
|
<syntax>NoProxy <var>host</var> [<var>host</var>] ...</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>This directive is only useful for Apache httpd proxy servers within
|
|
intranets. The <directive>NoProxy</directive> 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
|
|
<directive module="mod_proxy">ProxyRemote</directive> proxy server(s).</p>
|
|
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
ProxyRemote * http://firewall.example.com:81
|
|
NoProxy .example.com 192.168.112.0/21
|
|
</highlight>
|
|
</example>
|
|
|
|
<p>The <var>host</var> arguments to the <directive>NoProxy</directive>
|
|
directive are one of the following type list:</p>
|
|
|
|
<dl>
|
|
<!-- ===================== Domain ======================= -->
|
|
<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>
|
|
|
|
<example><title>Examples</title>
|
|
.com .example.org.
|
|
</example>
|
|
|
|
<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>
|
|
|
|
<note><title>Note</title>
|
|
<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, the two domains <code>.ExAmple.com</code> and
|
|
<code>.example.com.</code> (note the trailing period) are considered
|
|
equal. Since a domain comparison does not involve a DNS lookup, it is much
|
|
more efficient than subnet comparison.</p>
|
|
</note></dd>
|
|
|
|
<!-- ===================== SubNet ======================= -->
|
|
<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="#ipaddr">IPAddr</a></var>, while a <var>SubNet</var> with zero
|
|
valid bits (<em>e.g.</em>, 0.0.0.0/0) is the same as the constant
|
|
<var>_Default_</var>, matching any IP address.</p></dd>
|
|
|
|
<!-- ===================== IPAddr ======================= -->
|
|
<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>
|
|
<example><title>Example</title>
|
|
192.168.123.7
|
|
</example>
|
|
|
|
<note><title>Note</title>
|
|
<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>
|
|
</note></dd>
|
|
|
|
<!-- ===================== Hostname ======================= -->
|
|
<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>
|
|
|
|
<example><title>Examples</title>
|
|
prep.ai.example.edu<br />
|
|
www.example.org
|
|
</example>
|
|
|
|
<note><title>Note</title>
|
|
<p>In many situations, it is more effective to specify an <var><a
|
|
href="#ipaddr">IPAddr</a></var> in place of a <var>Hostname</var> since a
|
|
DNS lookup can be avoided. Name resolution in Apache httpd can take a remarkable
|
|
deal of time when the connection to the name server uses a slow PPP
|
|
link.</p>
|
|
<p><var>Hostname</var> comparisons are done without regard to the case,
|
|
and <var>Hostname</var>s are always assumed to be anchored in the root
|
|
of the DNS tree; therefore, the two hosts <code>WWW.ExAmple.com</code>
|
|
and <code>www.example.com.</code> (note the trailing period) are
|
|
considered equal.</p>
|
|
</note></dd>
|
|
</dl>
|
|
</usage>
|
|
<seealso><a href="../dns-caveats.html">DNS Issues</a></seealso>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyTimeout</name>
|
|
<description>Network timeout for proxied requests</description>
|
|
<syntax>ProxyTimeout <var>time-interval</var>[s]</syntax>
|
|
<default>Value of <directive module="core">Timeout</directive></default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<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>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyDomain</name>
|
|
<description>Default domain name for proxied requests</description>
|
|
<syntax>ProxyDomain <var>Domain</var></syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>This directive is only useful for Apache httpd proxy servers within
|
|
intranets. The <directive>ProxyDomain</directive> 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>
|
|
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
ProxyRemote "*" "http://firewall.example.com:81"
|
|
NoProxy ".example.com" "192.168.112.0/21"
|
|
ProxyDomain ".example.com"
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyVia</name>
|
|
<description>Information provided in the <code>Via</code> HTTP response
|
|
header for proxied requests</description>
|
|
<syntax>ProxyVia On|Off|Full|Block</syntax>
|
|
<default>ProxyVia Off</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<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 httpd 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>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyErrorOverride</name>
|
|
<description>Override error pages for proxied content</description>
|
|
<syntax>ProxyErrorOverride On|Off</syntax>
|
|
<default>ProxyErrorOverride Off</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<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
|
|
<module>mod_include</module>'s SSI) to get
|
|
the error code and act accordingly. (Default behavior would display
|
|
the error page of the proxied server. Turning this on shows the SSI
|
|
Error message.)</p>
|
|
|
|
<p>This directive does not affect the processing of informational (1xx),
|
|
normal success (2xx), or redirect (3xx) responses.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyPassInterpolateEnv</name>
|
|
<description>Enable Environment Variable interpolation in Reverse Proxy configurations</description>
|
|
<syntax>ProxyPassInterpolateEnv On|Off</syntax>
|
|
<default>ProxyPassInterpolateEnv Off</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context>
|
|
<context>directory</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>This directive, together with the <var>interpolate</var> argument to
|
|
<directive>ProxyPass</directive>, <directive>ProxyPassReverse</directive>,
|
|
<directive>ProxyPassReverseCookieDomain</directive>, and
|
|
<directive>ProxyPassReverseCookiePath</directive>,
|
|
enables reverse proxies to be dynamically
|
|
configured using environment variables which may be set by
|
|
another module such as <module>mod_rewrite</module>.
|
|
It affects the <directive>ProxyPass</directive>,
|
|
<directive>ProxyPassReverse</directive>,
|
|
<directive>ProxyPassReverseCookieDomain</directive>, and
|
|
<directive>ProxyPassReverseCookiePath</directive> directives
|
|
and causes them to substitute the value of an environment
|
|
variable <code>varname</code> for the string <code>${varname}</code>
|
|
in configuration directives if the <var>interpolate</var> option is set.</p>
|
|
<p>The scheme/hostname/port portion of <directive>ProxyPass</directive> may
|
|
contain variables, but only the ones available when the directive is parsed
|
|
(for example, using <directive module="core">Define</directive>).
|
|
For all the other use cases, please consider using
|
|
<module>mod_rewrite</module> instead.</p>
|
|
<note type="warning"><title>Performance warning</title>
|
|
<p>Keep this turned off unless you need it!
|
|
Adding variables to <directive>ProxyPass</directive> for example may lead to
|
|
the use of the default mod_proxy's workers configured (that don't allow any fine
|
|
tuning like connections reuse, etc..).</p>
|
|
</note>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyStatus</name>
|
|
<description>Show Proxy LoadBalancer status in mod_status</description>
|
|
<syntax>ProxyStatus Off|On|Full</syntax>
|
|
<default>ProxyStatus Off</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>This directive determines whether or not proxy
|
|
loadbalancer status data is displayed via the <module>mod_status</module>
|
|
server-status page.</p>
|
|
<note><title>Note</title>
|
|
<p><strong>Full</strong> is synonymous with <strong>On</strong></p>
|
|
</note>
|
|
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyAddHeaders</name>
|
|
<description>Add proxy information in X-Forwarded-* headers</description>
|
|
<syntax>ProxyAddHeaders Off|On</syntax>
|
|
<default>ProxyAddHeaders On</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context>
|
|
<context>directory</context>
|
|
</contextlist>
|
|
<compatibility>Available in version 2.3.10 and later</compatibility>
|
|
|
|
<usage>
|
|
<p>This directive determines whether or not proxy related information should be passed to the
|
|
backend server through X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Server HTTP headers.</p>
|
|
<note><title>Effectiveness</title>
|
|
<p>This option is of use only for HTTP proxying, as handled by <module>mod_proxy_http</module>.</p>
|
|
</note>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>Proxy100Continue</name>
|
|
<description>Forward 100-continue expectation to the origin server</description>
|
|
<syntax>Proxy100Continue Off|On</syntax>
|
|
<default>Proxy100Continue On</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context>
|
|
<context>directory</context>
|
|
</contextlist>
|
|
<compatibility>Available in version 2.4.39 and later</compatibility>
|
|
|
|
<usage>
|
|
<p>This directive determines whether the proxy should forward 100-continue
|
|
<em>Expect:</em>ation to the origin server and thus let it decide when/if
|
|
the HTTP request body should be read, or when <code>Off</code> the proxy
|
|
should generate <em>100 Continue</em> intermediate response by itself before
|
|
forwarding the request body.</p>
|
|
<note><title>Effectiveness</title>
|
|
<p>This option is of use only for HTTP proxying, as handled by <module>mod_proxy_http</module>.</p>
|
|
</note>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxySourceAddress</name>
|
|
<description>Set local IP address for outgoing proxy connections</description>
|
|
<syntax>ProxySourceAddress <var>address</var></syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context>
|
|
</contextlist>
|
|
<compatibility>Available in version 2.3.9 and later</compatibility>
|
|
|
|
<usage>
|
|
<p>This directive allows to set a specific local address to bind to when connecting
|
|
to a backend server.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
</modulesynopsis>
|