mirror of
https://github.com/apache/httpd.git
synced 2025-06-03 10:42:03 +03:00
b68721ed3a
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@102617 13f79535-47bb-0310-9956-ffa450edef68
986 lines
41 KiB
XML
986 lines
41 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
|
|
|
|
<!--
|
|
Copyright 2002-2004 The Apache Software Foundation
|
|
|
|
Licensed 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>HTTP/1.1 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>This module implements a proxy/gateway for Apache. It implements
|
|
proxying capability for <code>FTP</code>, <code>CONNECT</code> (for SSL),
|
|
<code>HTTP/0.9</code>, <code>HTTP/1.0</code>, and <code>HTTP/1.1</code>.
|
|
The module can be configured to connect to other proxy modules for these
|
|
and other protocols.</p>
|
|
|
|
<p>Apache's proxy features are divided into several modules in
|
|
addition to <module>mod_proxy</module>:
|
|
<module>mod_proxy_http</module>, <module>mod_proxy_ftp</module>
|
|
and <module>mod_proxy_connect</module>. Thus, if you want to use
|
|
one or more of the particular proxy functions, load
|
|
<module>mod_proxy</module> <em>and</em> the appropriate module(s)
|
|
into the server (either statically at compile-time or dynamically
|
|
via the <directive module="mod_so">LoadModule</directive>
|
|
directive).</p>
|
|
|
|
<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_http</module></seealso>
|
|
<seealso><module>mod_proxy_ftp</module></seealso>
|
|
<seealso><module>mod_proxy_connect</module></seealso>
|
|
<seealso><module>mod_ssl</module></seealso>
|
|
|
|
<section id="forwardreverse"><title>Forward and Reverse Proxies</title>
|
|
<p>Apache can be configured in both a <dfn>forward</dfn> and
|
|
<dfn>reverse</dfn> proxy mode.</p>
|
|
|
|
<p>An ordinary <dfn>forward proxy</dfn> is an intermediate
|
|
server that sits between the client and the <em>origin
|
|
server</em>. In order to get content from the origin server,
|
|
the client sends a request to the proxy naming the origin server
|
|
as the target and the proxy then requests the content from the
|
|
origin server and returns it to the client. The client must be
|
|
specially configured to use the forward proxy to access other
|
|
sites.</p>
|
|
|
|
<p>A typical usage of a forward proxy is to provide Internet
|
|
access to internal clients that are otherwise restricted by a
|
|
firewall. The forward proxy can also use caching (as provided
|
|
by <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 proxys allow clients to access arbitrary sites through
|
|
your server and to hide their true origin, it is essential that
|
|
you <a href="#access">secure your server</a> so that only
|
|
authorized clients can access the proxy before activating a
|
|
forward proxy.</p>
|
|
|
|
<p>A <dfn>reverse proxy</dfn>, by contrast, appears to the
|
|
client just like an ordinary web server. No special
|
|
configuration on the client is necessary. The client makes
|
|
ordinary requests for content in the name-space of the reverse
|
|
proxy. The reverse proxy then decides where to send those
|
|
requests, and returns the content as if it was itself the
|
|
origin.</p>
|
|
|
|
<p>A typical usage of a reverse proxy is to provide Internet
|
|
users access to a server that is behind a firewall. Reverse
|
|
proxies can also be used to balance load among several back-end
|
|
servers, or to provide caching for a slower back-end server.
|
|
In addition, reverse proxies can be used simply to bring
|
|
several servers into the same URL space.</p>
|
|
|
|
<p>A reverse proxy is activated using the <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>Forward Proxy</title>
|
|
ProxyRequests On<br />
|
|
ProxyVia On<br />
|
|
<br />
|
|
<Proxy *><br />
|
|
<indent>
|
|
Order deny,allow<br />
|
|
Deny from all<br />
|
|
Allow from internal.example.com<br />
|
|
</indent>
|
|
</Proxy>
|
|
</example>
|
|
|
|
<example><title>Reverse Proxy</title>
|
|
ProxyRequests Off<br />
|
|
<br />
|
|
<Proxy *><br />
|
|
<indent>
|
|
Order deny,allow<br />
|
|
Allow from all<br />
|
|
</indent>
|
|
</Proxy><br />
|
|
<br />
|
|
ProxyPass /foo http://foo.example.com/bar<br />
|
|
ProxyPassReverse /foo http://foo.example.com/bar
|
|
</example>
|
|
</section> <!-- /examples -->
|
|
|
|
|
|
<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>
|
|
|
|
<example>
|
|
<Proxy *><br />
|
|
<indent>
|
|
Order Deny,Allow<br />
|
|
Deny from all<br />
|
|
Allow from 192.168.0<br />
|
|
</indent>
|
|
</Proxy>
|
|
</example>
|
|
|
|
<p>For more information on access control directives, see
|
|
<module>mod_access</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>
|
|
|
|
</section> <!-- /access -->
|
|
|
|
<section id="ftp-proxy"><title>FTP Proxy</title>
|
|
|
|
|
|
<section id="mimetypes"><title>Why doesn't file type <var>xxx</var>
|
|
download via FTP?</title>
|
|
<p>You probably don't have that particular file type defined as
|
|
<code>application/octet-stream</code> in your proxy's mime.types
|
|
configuration file. A useful line can be</p>
|
|
|
|
<example>
|
|
<pre>application/octet-stream bin dms lha lzh exe class tgz taz</pre>
|
|
</example>
|
|
</section> <!-- /mimetypes -->
|
|
|
|
<section id="type"><title>How can I force an FTP ASCII download of
|
|
File <var>xxx</var>?</title>
|
|
<p>In the rare situation where you must download a specific file using the
|
|
FTP <code>ASCII</code> transfer method (while the default transfer is in
|
|
<code>binary</code> mode), you can override <module>mod_proxy</module>'s
|
|
default by suffixing the request with <code>;type=a</code> to force an
|
|
ASCII transfer. (FTP Directory listings are always executed in ASCII mode,
|
|
however.)</p>
|
|
</section> <!-- /type -->
|
|
|
|
<section id="percent2fhck"><title>How can I access FTP files outside
|
|
of my home directory?</title>
|
|
<p>An FTP URI is interpreted relative to the home directory of the user
|
|
who is logging in. Alas, to reach higher directory levels you cannot
|
|
use /../, as the dots are interpreted by the browser and not actually
|
|
sent to the FTP server. To address this problem, the so called <dfn>Squid
|
|
%2f hack</dfn> was implemented in the Apache FTP proxy; it is a
|
|
solution which is also used by other popular proxy servers like the <a
|
|
href="http://www.squid-cache.org/">Squid Proxy Cache</a>. By
|
|
prepending <code>/%2f</code> to the path of your request, you can make
|
|
such a proxy change the FTP starting directory to <code>/</code> (instead
|
|
of the home directory). For example, to retrieve the file
|
|
<code>/etc/motd</code>, you would use the URL:</p>
|
|
|
|
<example>
|
|
ftp://<var>user</var>@<var>host</var>/%2f/etc/motd
|
|
</example>
|
|
</section> <!-- /percent2fhck -->
|
|
|
|
<section id="ftppass"><title>How can I hide the FTP cleartext password
|
|
in my browser's URL line?</title>
|
|
<p>To log in to an FTP server by username and password, Apache uses
|
|
different strategies. In absense of a user name and password in the URL
|
|
altogether, Apache sends an anonymous login to the FTP server,
|
|
<em>i.e.</em>,</p>
|
|
|
|
<example>
|
|
user: anonymous<br />
|
|
password: apache_proxy@
|
|
</example>
|
|
|
|
<p>This works for all popular FTP servers which are configured for
|
|
anonymous access.</p>
|
|
|
|
<p>For a personal login with a specific username, you can embed the user
|
|
name into the URL, like in:</p>
|
|
|
|
<example>
|
|
ftp://<var>username</var>@<var>host</var>/myfile
|
|
</example>
|
|
|
|
<p>If the FTP server asks for a password when given this username (which
|
|
it should), then Apache will reply with a <code>401</code> (Authorization
|
|
required) response, which causes the Browser to pop up the
|
|
username/password dialog. Upon entering the password, the connection
|
|
attempt is retried, and if successful, the requested resource is
|
|
presented. The advantage of this procedure is that your browser does not
|
|
display the password in cleartext (which it would if you had used</p>
|
|
|
|
<example>
|
|
ftp://<var>username</var>:<var>password</var>@<var>host</var>/myfile
|
|
</example>
|
|
|
|
<p>in the first place).</p>
|
|
|
|
<note><title>Note</title>
|
|
<p>The password which is transmitted in such a way is not encrypted on
|
|
its way. It travels between your browser and the Apache proxy server in
|
|
a base64-encoded cleartext string, and between the Apache proxy and the
|
|
FTP server as plaintext. You should therefore think twice before
|
|
accessing your FTP server via HTTP (or before accessing your personal
|
|
files via FTP at all!) When using unsecure channels, an eavesdropper
|
|
might intercept your password on its way.</p>
|
|
</note>
|
|
</section> <!-- /ftppass -->
|
|
</section> <!-- /ftpproxy -->
|
|
<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 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 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 you have a application server which doesn't
|
|
implement keepalives or HTTP/1.1 properly, there are 2 environment
|
|
variables which when set send a HTTP/1.0 with no keepalive. These are set
|
|
via the <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>
|
|
|
|
<example>
|
|
<Location /buggyappserver/><br />
|
|
<indent>
|
|
ProxyPass http://buggyappserver:7001/foo/<br />
|
|
SetEnv force-proxy-request-1.0 1<br />
|
|
SetEnv proxy-nokeepalive 1<br />
|
|
</indent>
|
|
</Location>
|
|
</example>
|
|
</section> <!-- /envsettings -->
|
|
|
|
<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>
|
|
|
|
<example>
|
|
<Proxy *><br />
|
|
<indent>
|
|
Order Deny,Allow<br />
|
|
Deny from all<br />
|
|
Allow from yournetwork.example.com<br />
|
|
</indent>
|
|
</Proxy>
|
|
</example>
|
|
|
|
<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>
|
|
|
|
<example>
|
|
<Proxy http://example.com/foo/*><br />
|
|
<indent>
|
|
SetOutputFilter INCLUDES<br />
|
|
</indent>
|
|
</Proxy>
|
|
</example>
|
|
</usage>
|
|
</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>
|
|
<compatibility>available in Apache 2.0.44 and later</compatibility>
|
|
|
|
<usage>
|
|
<p>The <directive>ProxyBadHeader</directive> directive determines the
|
|
behaviour of <module>mod_proxy</module> if it receives syntactically invalid
|
|
header lines (<em>i.e.</em> containing no colon). The following arguments
|
|
are possible:</p>
|
|
|
|
<dl>
|
|
<dt><code>IsError</code></dt>
|
|
<dd>Abort the request and end up with a 502 (Bad Gateway) response. This is
|
|
the default behaviour.</dd>
|
|
|
|
<dt><code>Ignore</code></dt>
|
|
<dd>Treat bad header lines as if they weren't sent.</dd>
|
|
|
|
<dt><code>StartBody</code></dt>
|
|
<dd>When receiving the first bad header line, finish reading the headers and
|
|
treat the remainder as body. This helps to work around buggy backend servers
|
|
which forget to insert an empty line between the headers and the body.</dd>
|
|
</dl>
|
|
</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 it matches URLs
|
|
using regular expressions.</p>
|
|
</usage>
|
|
</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>
|
|
</contextlist>
|
|
<compatibility>Available in Apache 2.0.31 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
|
|
proxypass 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 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 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>
|
|
|
|
<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>
|
|
</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> is supported by
|
|
this module.</p>
|
|
|
|
<example><title>Example</title>
|
|
ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000<br />
|
|
ProxyRemote * http://cleversite.com<br />
|
|
ProxyRemote ftp http://ftpproxy.mydomain.com:8080
|
|
</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 the
|
|
first argument is a regular expression match against the requested URL.</p>
|
|
</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></syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context>
|
|
</contextlist>
|
|
|
|
<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. <var>path</var> is the name of a local virtual path; <var>url</var>
|
|
is a partial URL for the remote server and cannot include a query
|
|
string.</p>
|
|
|
|
<p>Suppose the local server has address <code>http://example.com/</code>;
|
|
then</p>
|
|
|
|
<example>
|
|
ProxyPass /mirror/foo/ http://backend.example.com/
|
|
</example>
|
|
|
|
<p>will cause a local request for
|
|
<code>http://example.com/mirror/foo/bar</code> to be internally converted
|
|
into a proxy request to <code>http://backend.example.com/bar</code>.</p>
|
|
|
|
<p>The <code>!</code> directive is useful in situations where you don't want
|
|
to reverse-proxy a subdirectory, <em>e.g.</em></p>
|
|
|
|
<example>
|
|
ProxyPass /mirror/foo/i !<br />
|
|
ProxyPass /mirror/foo http://backend.example.com
|
|
</example>
|
|
|
|
<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>
|
|
|
|
<note><title>Note</title>
|
|
<p>Order is important. you need to put the exclusions <em>before</em> the
|
|
general proxypass directive.</p>
|
|
</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>.</p>
|
|
|
|
<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>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>
|
|
</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></syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>This directive lets Apache adjust the URL in the <code>Location</code>,
|
|
<code>Content-Location</code> and <code>URI</code> headers on HTTP redirect
|
|
responses. This is essential when Apache is used as a reverse proxy to avoid
|
|
by-passing the reverse proxy because of HTTP redirects on the backend
|
|
servers which stay behind the reverse proxy.</p>
|
|
|
|
<p>Only the HTTP response headers specifically mentioned above
|
|
will be rewritten. Apache will not rewrite other response
|
|
headers, nor will it rewrite URL references inside HTML pages.
|
|
This means that if the proxied content contains absolute URL
|
|
references, they will by-pass the proxy. A third-party module
|
|
that will look inside the HTML and rewrite URL references is Nick
|
|
Kew's <a href="http://www.webthing.com/software/mod_proxy_html/"
|
|
>mod_proxy_html</a>.</p>
|
|
|
|
<p><var>path</var> is the name of a local virtual path. <var>url</var> is a
|
|
partial URL for the remote server - the same way they are used for the
|
|
<directive module="mod_proxy">ProxyPass</directive> directive.</p>
|
|
|
|
<p>For example, suppose the local server has address
|
|
<code>http://example.com/</code>; then</p>
|
|
|
|
<example>
|
|
ProxyPass /mirror/foo/ http://backend.example.com/<br />
|
|
ProxyPassReverse /mirror/foo/ http://backend.example.com/
|
|
</example>
|
|
|
|
<p>will not only cause a local request for the
|
|
<code>http://example.com/mirror/foo/bar</code> to be internally converted
|
|
into a proxy request to <code>http://backend.example.com/bar</code>
|
|
(the functionality <code>ProxyPass</code> provides here). It also takes care
|
|
of redirects the server <code>backend.example.com</code> sends: when
|
|
<code>http://backend.example.com/bar</code> is redirected by him to
|
|
<code>http://backend.example.com/quux</code> Apache adjusts this to
|
|
<code>http://example.com/mirror/foo/quux</code> before forwarding the HTTP
|
|
redirect response to the client. Note that the hostname used for
|
|
constructing the URL is chosen in respect to the setting of the <directive
|
|
module="core">UseCanonicalName</directive> directive.</p>
|
|
|
|
<p>Note that this <directive>ProxyPassReverse</directive> directive can
|
|
also be used in conjunction with the proxy pass-through feature
|
|
(<code>RewriteRule ... [P]</code>) from <module>mod_rewrite</module>
|
|
because its doesn't depend on a corresponding <directive module="mod_proxy"
|
|
>ProxyPass</directive> directive.</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>.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>AllowCONNECT</name>
|
|
<description>Ports that are allowed to <code>CONNECT</code> through the
|
|
proxy</description>
|
|
<syntax>AllowCONNECT <var>port</var> [<var>port</var>] ...</syntax>
|
|
<default>AllowCONNECT 443 563</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive>AllowCONNECT</directive> directive specifies a list
|
|
of port numbers to which the proxy <code>CONNECT</code> method may
|
|
connect. Today's browsers use this method when a <code>https</code>
|
|
connection is requested and proxy tunneling over HTTP is in effect.</p>
|
|
|
|
<p>By default, only the default https port (<code>443</code>) and the
|
|
default snews port (<code>563</code>) are enabled. Use the
|
|
<directive>AllowCONNECT</directive> directive to override this default and
|
|
allow connections to the listed ports only.</p>
|
|
|
|
<p>Note that you'll need to have <module>mod_proxy_connect</module> present
|
|
in the server in order to get the support for the <code>CONNECT</code> at
|
|
all.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyBlock</name>
|
|
<description>Words, hosts, or domains that are banned from being
|
|
proxied</description>
|
|
<syntax>ProxyBlock *|<var>word</var>|<var>host</var>|<var>domain</var>
|
|
[<var>word</var>|<var>host</var>|<var>domain</var>] ...</syntax>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>The <directive>ProxyBlock</directive> directive specifies a list of
|
|
words, hosts and/or domains, separated by spaces. HTTP, HTTPS, and
|
|
FTP document requests to sites whose names contain matched words,
|
|
hosts or domains are <em>blocked</em> by the proxy server. The proxy
|
|
module will also attempt to determine IP addresses of list items which
|
|
may be hostnames during startup, and cache them for match test as
|
|
well. That may slow down the startup time of the server.</p>
|
|
|
|
<example><title>Example</title>
|
|
ProxyBlock joes-garage.com some-host.co.uk rocky.wotsamattau.edu
|
|
</example>
|
|
|
|
<p><code>rocky.wotsamattau.edu</code> would also be matched if referenced by
|
|
IP address.</p>
|
|
|
|
<p>Note that <code>wotsamattau</code> would also be sufficient to match
|
|
<code>wotsamattau.edu</code>.</p>
|
|
|
|
<p>Note also that</p>
|
|
|
|
<example>
|
|
ProxyBlock *
|
|
</example>
|
|
|
|
<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>
|
|
ProxyReceiveBufferSize 2048
|
|
</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 less or equal <code>8192</code>.</p>
|
|
|
|
<p>In almost every case there's no reason to change that value.</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 10</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
<compatibility>Available in Apache 2.0 and later</compatibility>
|
|
|
|
<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 is
|
|
set to prevent infinite proxy loops, or a DoS attack.</p>
|
|
|
|
<example><title>Example</title>
|
|
ProxyMaxForwards 15
|
|
</example>
|
|
</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 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>
|
|
ProxyRemote * http://firewall.mycompany.com:81<br />
|
|
NoProxy .mycompany.com 192.168.112.0/21
|
|
</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 .apache.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 two domains <code>.MyDomain.com</code> and
|
|
<code>.mydomain.com.</code> (note the trailing period) are considered
|
|
equal. Since a domain comparison does not involve a DNS lookup, it is much
|
|
more efficient than subnet comparison.</p>
|
|
</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 255.255.248.0)</dd>
|
|
</dl>
|
|
|
|
<p>As a degenerate case, a <em>SubNet</em> with 32 valid bits is the
|
|
equivalent to an <var><a href="#ipadr">IPAddr</a></var>, while a <var>SubNet</var> with zero
|
|
valid bits (<em>e.g.</em>, 0.0.0.0/0) is the same as the constant
|
|
<var>_Default_</var>, matching any IP address.</p></dd>
|
|
|
|
<!-- ===================== 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.mit.edu<br />
|
|
www.apache.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 can take a remarkable
|
|
deal of time when the connection to the name server uses a slow PPP
|
|
link.</p>
|
|
<p><var>Hostname</var> comparisons are done without regard to the case,
|
|
and <var>Hostname</var>s are always assumed to be anchored in the root
|
|
of the DNS tree, therefore two hosts <code>WWW.MyDomain.com</code>
|
|
and <code>www.mydomain.com.</code> (note the trailing period) are
|
|
considered equal.</p>
|
|
</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>seconds</var></syntax>
|
|
<default>ProxyTimeout 300</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
<compatibility>Available in Apache 2.0.31 and later</compatibility>
|
|
|
|
<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 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>
|
|
ProxyRemote * http://firewall.mycompany.com:81<br />
|
|
NoProxy .mycompany.com 192.168.112.0/21<br />
|
|
ProxyDomain .mycompany.com
|
|
</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 of
|
|
proxy requests along a chain of proxy servers. See <a
|
|
href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a> (HTTP/1.1), section
|
|
14.45 for an explanation of <code>Via:</code> header lines.</p>
|
|
|
|
<ul>
|
|
<li>If set to <code>Off</code>, which is the default, no special processing
|
|
is performed. If a request or reply contains a <code>Via:</code> header,
|
|
it is passed through unchanged.</li>
|
|
|
|
<li>If set to <code>On</code>, each request and reply will get a
|
|
<code>Via:</code> header line added for the current host.</li>
|
|
|
|
<li>If set to <code>Full</code>, each generated <code>Via:</code> header
|
|
line will additionally have the Apache server version shown as a
|
|
<code>Via:</code> comment field.</li>
|
|
|
|
<li>If set to <code>Block</code>, every proxy request will have all its
|
|
<code>Via:</code> header lines removed. No new <code>Via:</code> header will
|
|
be generated.</li>
|
|
</ul>
|
|
</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>
|
|
</contextlist>
|
|
<compatibility>Available in version 2.0 and later</compatibility>
|
|
|
|
<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 mod_include'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>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
</modulesynopsis>
|