2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <modulesynopsis metafile="mod_proxy.xml.meta">
7 <description>HTTP/1.1 proxy/gateway server</description>
8 <status>Extension</status>
9 <sourcefile>mod_proxy.c</sourcefile>
10 <identifier>proxy_module</identifier>
13 <note type="warning"><title>Warning</title>
14 <p>Do not enable proxying with <directive module="mod_proxy"
15 >ProxyRequests</directive> until you have <a href="#access"
16 >secured your server</a>. Open proxy servers are dangerous both to your
17 network and to the Internet at large.</p>
20 <p>This module implements a proxy/gateway for Apache. It implements
21 proxying capability for <code>FTP</code>, <code>CONNECT</code> (for SSL),
22 <code>HTTP/0.9</code>, <code>HTTP/1.0</code>, and <code>HTTP/1.1</code>.
23 The module can be configured to connect to other proxy modules for these
24 and other protocols.</p>
26 <p>This module was experimental in Apache 1.1.x. Improvements and bugfixes
27 were made in Apache v1.2.x and Apache v1.3.x, then the module underwent a
28 major overhaul for Apache v2.0. The protocol support was upgraded to
29 <code>HTTP/1.1</code>, and filter support was enabled.</p>
31 <p>During the overhaul process, <module>mod_proxy</module> features
32 have been split into several module files: <module>mod_proxy_http</module>,
33 <module>mod_proxy_ftp</module> and <module>mod_proxy_connect</module>.
34 Thus, if you want to use one or more of the particular proxy functions,
35 load <module>mod_proxy</module> <em>and</em> the appropriate
36 module(s) into the server (either statically or dynamically via the
37 <directive module="mod_so">LoadModule</directive> directive).</p>
39 <p>Please note that the <strong>caching</strong> function present in <module
40 >mod_proxy</module> up to Apache v1.3.x has been <strong>removed</strong>
41 from <module>mod_proxy</module> and incorporated into a new module,
42 <module>mod_cache</module>. In other words, the Apache 2.0.x proxy doesn't
43 cache - all caching functionality has been moved into
44 <module>mod_cache</module>, which is capable of caching any content, not
45 just content from the proxy.</p>
47 <p>If you need to use SSL when contacting remote servers, have a look at the
48 <code>SSLProxy*</code> directives in <module>mod_ssl</module>.</p>
50 <seealso><module>mod_proxy_http</module></seealso>
51 <seealso><module>mod_proxy_ftp</module></seealso>
52 <seealso><module>mod_proxy_connect</module></seealso>
53 <seealso><module>mod_ssl</module></seealso>
55 <section id="configs"><title>Common configuration topics</title>
57 <li><a href="#forwardreverse">Forward and Reverse Proxies</a></li>
58 <li><a href="#access">Controlling access to your proxy</a></li>
59 <li><a href="#mimetypes">Why doesn't file type <var>xxx</var> download via
61 <li><a href="#type">How can I force an FTP ASCII download of File
62 <var>xxx</var>?</a></li>
63 <li><a href="#percent2fhack">How can I access FTP files outside of my home
65 <li><a href="#ftppass">How can I hide the FTP cleartext password in my
66 browser's URL line?</a></li>
67 <li><a href="#startup">Why does Apache start more slowly when using the
68 proxy module?</a></li>
69 <li><a href="#intranet">What other functions are useful for an intranet
70 proxy server?</a></li>
71 <li><a href="#envsettings">How can I make the proxy talk HTTP/1.0 and
72 disable keepalives?</a></li>
75 <section id="forwardreverse"><title>Forward and Reverse Proxies</title>
76 <p>Apache can be configured in both a <dfn>forward</dfn> and
77 <dfn>reverse</dfn> proxy configuration.</p>
79 <p>A <dfn>forward proxy</dfn> is an intermediate system that enables a
80 browser to connect to a remote network to which it normally does not have
81 access. A forward proxy can also be used to cache data, reducing load on
82 the networks between the forward proxy and the remote webserver.</p>
84 <p>Apache's <module>mod_proxy</module> can be figured to behave like a
85 forward proxy using the <directive module="mod_proxy"
86 >ProxyRemote</directive> directive. In addition, caching of data can be
87 achieved by configuring <module>mod_cache</module>. Other dedicated
88 forward proxy packages include <a href="http://www.squid-cache.org/"
91 <p>A <dfn>reverse proxy</dfn> is a webserver system that is capable of
92 serving webpages sourced from other webservers - in addition to webpages
93 on disk or generated dynamically by CGI - making these pages look like
94 they originated at the reverse proxy.</p>
96 <p>When configured with the mod_cache module the reverse proxy can act as
97 a cache for slower backend webservers. The reverse proxy can also enable
98 advanced URL strategies and management techniques, allowing webpages
99 served using different webserver systems or architectures to coexist
100 inside the same URL space. Reverse proxy systems are also ideal for
101 implementing centralised logging websites with many or diverse website
102 backends. Complex multi-tier webserver systems can be constructed using an
103 <module>mod_proxy</module> frontend and any number of backend
106 <p>The reverse proxy is configured using the <directive
107 module="mod_proxy">ProxyPass</directive> and <directive
108 module="mod_proxy">ProxyPassReverse</directive> directives. Caching can be
109 enabled using mod_cache as with the forward proxy.</p>
110 </section> <!-- /forwardreverse -->
112 <section id="access"><title>Controlling access to your proxy</title>
113 <p>You can control who can access your proxy via the <directive
114 module="mod_proxy" type="section">Proxy</directive> control block using
115 the following example:</p>
118 <Proxy *><br />
120 Order Deny,Allow<br />
122 Allow from 192.168.0<br />
127 <p>When configuring a reverse proxy, access control takes on the
128 attributes of the normal server <directive module="core" type="section"
129 >Directory</directive> configuration.</p>
130 </section> <!-- /access -->
132 <section id="mimetypes"><title>Why doesn't file type <var>xxx</var>
133 download via FTP?</title>
134 <p>You probably don't have that particular file type defined as
135 <code>application/octet-stream</code> in your proxy's mime.types
136 configuration file. A useful line can be</p>
139 <pre>application/octet-stream bin dms lha lzh exe class tgz taz</pre>
141 </section> <!-- /mimetypes -->
143 <section id="type"><title>How can I force an FTP ASCII download of
144 File <var>xxx</var>?</title>
145 <p>In the rare situation where you must download a specific file using the
146 FTP <code>ASCII</code> transfer method (while the default transfer is in
147 <code>binary</code> mode), you can override <module>mod_proxy</module>'s
148 default by suffixing the request with <code>;type=a</code> to force an
149 ASCII transfer. (FTP Directory listings are always executed in ASCII mode,
151 </section> <!-- /type -->
153 <section id="percent2fhck"><title>How can I access FTP files outside
154 of my home directory?</title>
155 <p>An FTP URI is interpreted relative to the home directory of the user
156 who is logging in. Alas, to reach higher directory levels you cannot
157 use /../, as the dots are interpreted by the browser and not actually
158 sent to the FTP server. To address this problem, the so called <dfn>Squid
159 %2f hack</dfn> was implemented in the Apache FTP proxy; it is a
160 solution which is also used by other popular proxy servers like the <a
161 href="http://www.squid-cache.org/">Squid Proxy Cache</a>. By
162 prepending <code>/%2f</code> to the path of your request, you can make
163 such a proxy change the FTP starting directory to <code>/</code> (instead
164 of the home directory). For example, to retrieve the file
165 <code>/etc/motd</code>, you would use the URL:</p>
168 ftp://<var>user</var>@<var>host</var>/%2f/etc/motd
170 </section> <!-- /percent2fhck -->
172 <section id="ftppass"><title>How can I hide the FTP cleartext password
173 in my browser's URL line?</title>
174 <p>To log in to an FTP server by username and password, Apache uses
175 different strategies. In absense of a user name and password in the URL
176 altogether, Apache sends an anomymous login to the FTP server,
180 user: anonymous<br />
181 password: apache_proxy@
184 <p>This works for all popular FTP servers which are configured for
185 anonymous access.</p>
187 <p>For a personal login with a specific username, you can embed the user
188 name into the URL, like in:</p>
191 ftp://<var>username</var>@<var>host</var>/myfile
194 <p>If the FTP server asks for a password when given this username (which
195 it should), then Apache will reply with a <code>401</code> (Authorization
196 required) response, which causes the Browser to pop up the
197 username/password dialog. Upon entering the password, the connection
198 attempt is retried, and if successful, the requested resource is
199 presented. The advantage of this procedure is that your browser does not
200 display the password in cleartext (which it would if you had used</p>
203 ftp://<var>username</var>:<var>password</var>@<var>host</var>/myfile
206 <p>in the first place).</p>
208 <note><title>Note</title>
209 <p>The password which is transmitted in such a way is not encrypted on
210 its way. It travels between your browser and the Apache proxy server in
211 a base64-encoded cleartext string, and between the Apache proxy and the
212 FTP server as plaintext. You should therefore think twice before
213 accessing your FTP server via HTTP (or before accessing your personal
214 files via FTP at all!) When using unsecure channels, an eavesdropper
215 might intercept your password on its way.</p>
217 </section> <!-- /ftppass -->
219 <section id="startup"><title>Why does Apache start more slowly when using
220 the proxy module?</title>
221 <p>If you're using the <directive module="mod_proxy"
222 >ProxyBlock</directive> directive, hostnames' IP addresses are looked up
223 and cached during startup for later match test. This may take a few
224 seconds (or more) depending on the speed with which the hostname lookups
226 </section> <!-- /startup -->
228 <section id="intranet"><title>What other functions are useful for an
229 intranet proxy server?</title>
230 <p>An Apache proxy server situated in an intranet needs to forward
231 external requests through the company's firewall. However, when it has to
232 access resources within the intranet, it can bypass the firewall when
233 accessing hosts. The <directive module="mod_proxy">NoProxy</directive>
234 directive is useful for specifying which hosts belong to the intranet and
235 should be accessed directly.</p>
237 <p>Users within an intranet tend to omit the local domain name from their
238 WWW requests, thus requesting "http://somehost/" instead of
239 <code>http://somehost.example.com/</code>. Some commercial proxy servers
240 let them get away with this and simply serve the request, implying a
241 configured local domain. When the <directive module="mod_proxy"
242 >ProxyDomain</directive> directive is used and the server is <a
243 href="#proxyrequests">configured for proxy service</a>, Apache can return
244 a redirect response and send the client to the correct, fully qualified,
245 server address. This is the preferred method since the user's bookmark
246 files will then contain fully qualified hosts.</p>
247 </section> <!-- /intranet -->
249 <section id="envsettings"><title>How can I make the proxy talk HTTP/1.0 and
250 disable keepalives?</title>
251 <p>For circumstances where you have a application server which doesn't
252 implement keepalives or HTTP/1.1 properly, there are 2 environment
253 variables which when set send a HTTP/1.0 with no keepalive. These are set
254 via the <directive module="mod_env">SetEnv</directive> directive.</p>
256 <p>These are the <code>force-proxy-request-1.0</code> and
257 <code>proxy-nokeepalive</code> notes.</p>
260 <Location /buggyappserver/><br />
262 ProxyPass http://buggyappserver:7001/foo/<br />
263 SetEnv force-proxy-request-1.0 1<br />
264 SetEnv proxy-nokeepalive 1<br />
268 </section> <!-- /envsettings -->
271 <directivesynopsis type="section">
273 <description>Container for directives applied to proxied resources</description>
274 <syntax><Proxy <var>wildcard-url</var>> ...</Proxy></syntax>
275 <contextlist><context>server config</context><context>virtual host</context>
279 <p>Directives placed in <directive type="section">Proxy</directive>
280 sections apply only to matching proxied content. Shell-style wildcards are
283 <p>For example, the following will allow only hosts in
284 <code>yournetwork.example.com</code> to access content via your proxy
288 <Proxy *><br />
290 Order Deny,Allow<br />
292 Allow from yournetwork.example.com<br />
297 <p>The following example will process all files in the <code>foo</code>
298 directory of <code>example.com</code> through the <code>INCLUDES</code>
299 filter when they are sent through the proxy server:</p>
302 <Proxy http://example.com/foo/*><br />
304 SetOutputFilter INCLUDES<br />
312 <name>ProxyBadHeader</name>
313 <description>Determines how to handle bad header lines in a
314 response</description>
315 <syntax>ProxyBadHeader IsError|Ignore|StartBody</syntax>
316 <default>ProxyBadHeader IsError</default>
317 <contextlist><context>server config</context><context>virtual host</context>
319 <compatibility>available in Apache 2.0.44 and later</compatibility>
322 <p>The <directive>ProxyBadHeader</directive> directive determines the
323 behaviour of <module>mod_proxy</module> if it receives syntactically invalid
324 header lines (<em>i.e.</em> containing no colon). The following arguments
328 <dt><code>IsError</code></dt>
329 <dd>Abort the request and end up with a 502 (Bad Gateway) response. This is
330 the default behaviour.</dd>
332 <dt><code>Ignore</code></dt>
333 <dd>Treat bad header lines as if they weren't sent.</dd>
335 <dt><code>StartBody</code></dt>
336 <dd>When receiving the first bad header line, finish reading the headers and
337 treat the remainder as body. This helps to work around buggy backend servers
338 which forget to insert an empty line between the headers and the body.</dd>
343 <directivesynopsis type="section">
344 <name>ProxyMatch</name>
345 <description>Container for directives applied to regular-expression-matched
346 proxied resources</description>
347 <syntax><ProxyMatch <var>regex</var>> ...</ProxyMatch></syntax>
348 <contextlist><context>server config</context><context>virtual host</context>
352 <p>The <directive type="section">ProxyMatch</directive> directive is
353 identical to the <directive module="mod_proxy"
354 type="section">Proxy</directive> directive, except it matches URLs
355 using regular expressions.</p>
360 <name>ProxyPreserveHost</name>
361 <description>Use incoming Host HTTP request header for proxy
362 request</description>
363 <syntax>ProxyPreserveHost On|Off</syntax>
364 <default>ProxyPreserveHost Off</default>
365 <contextlist><context>server config</context><context>virtual host</context>
367 <compatibility>Available in Apache 2.0.31 and later.</compatibility>
370 <p>When enabled, this option will pass the Host: line from the incoming
371 request to the proxied host, instead of the hostname specified in the
374 <p>This option should normally be turned <code>Off</code>. It is mostly
375 useful in special configurations like proxied mass name-based virtual
376 hosting, where the original Host header needs to be evaluated by the
382 <name>ProxyRequests</name>
383 <description>Enables forward (standard) proxy requests</description>
384 <syntax>ProxyRequests On|Off</syntax>
385 <default>ProxyRequests Off</default>
386 <contextlist><context>server config</context><context>virtual host</context>
390 <p>This allows or prevents Apache from functioning as a forward proxy
391 server. (Setting ProxyRequests to <code>Off</code> does not disable use of
392 the <directive module="mod_proxy">ProxyPass</directive> directive.)</p>
394 <p>In a typical reverse proxy configuration, this option should be set to
395 <code>Off</code>.</p>
397 <p>In order to get the functionality of proxying HTTP or FTP sites, you
398 need also <module>mod_proxy_http</module> or <module>mod_proxy_ftp</module>
399 (or both) present in the server.</p>
401 <note type="warning"><title>Warning</title>
402 <p>Do not enable proxying with <directive
403 module="mod_proxy">ProxyRequests</directive> until you have <a
404 href="#access">secured your server</a>. Open proxy servers are dangerous
405 both to your network and to the Internet at large.</p>
411 <name>ProxyRemote</name>
412 <description>Remote proxy used to handle certain requests</description>
413 <syntax>ProxyRemote <var>match</var> <var>remote-server</var></syntax>
414 <contextlist><context>server config</context><context>virtual host</context>
418 <p>This defines remote proxies to this proxy. <var>match</var> is either the
419 name of a URL-scheme that the remote server supports, or a partial URL
420 for which the remote server should be used, or <code>*</code> to indicate
421 the server should be contacted for all requests. <var>remote-server</var> is
422 a partial URL for the remote server. Syntax:</p>
425 <dfn>remote-server</dfn> =
426 <var>scheme</var>://<var>hostname</var>[:<var>port</var>]
429 <p><var>scheme</var> is effectively the protocol that should be used to
430 communicate with the remote server; only <code>http</code> is supported by
433 <example><title>Example</title>
434 ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000<br />
435 ProxyRemote * http://cleversite.com<br />
436 ProxyRemote ftp http://ftpproxy.mydomain.com:8080
439 <p>In the last example, the proxy will forward FTP requests, encapsulated
440 as yet another HTTP proxy request, to another proxy which can handle
443 <p>This option also supports reverse proxy configuration - a backend
444 webserver can be embedded within a virtualhost URL space even if that
445 server is hidden by another forward proxy.</p>
450 <name>ProxyRemoteMatch</name>
451 <description>Remote proxy used to handle requests matched by regular
452 expressions</description>
453 <syntax>ProxyRemoteMatch <var>regex</var> <var>remote-server</var></syntax>
454 <contextlist><context>server config</context><context>virtual host</context>
458 <p>The <directive>ProxyRemoteMatch</directive> is identical to the
459 <directive module="mod_proxy">ProxyRemote</directive> directive, except the
460 first argument is a regular expression match against the requested URL.</p>
465 <name>ProxyPass</name>
466 <description>Maps remote servers into the local server URL-space</description>
467 <syntax>ProxyPass [<var>path</var>] !|<var>url</var></syntax>
468 <contextlist><context>server config</context><context>virtual host</context>
469 <context>directory</context>
473 <p>This directive allows remote servers to be mapped into the space of
474 the local server; the local server does not act as a proxy in the
475 conventional sense, but appears to be a mirror of the remote
476 server. <var>path</var> is the name of a local virtual path; <var>url</var>
477 is a partial URL for the remote server and cannot include a query
480 <p>Suppose the local server has address <code>http://example.com/</code>;
484 ProxyPass /mirror/foo/ http://backend.example.com/
487 <p>will cause a local request for
488 <code>http://example.com/mirror/foo/bar</code> to be internally converted
489 into a proxy request to <code>http://backend.example.com/bar</code>.</p>
491 <p>The <code>!</code> directive is useful in situations where you don't want
492 to reverse-proxy a subdirectory, <em>e.g.</em></p>
495 ProxyPass /mirror/foo/i !<br />
496 ProxyPass /mirror/foo http://backend.example.com
499 <p>will proxy all requests to <code>/mirror/foo</code> to
500 <code>backend.example.com</code> <em>except</em> requests made to
501 <code>/mirror/foo/i</code>.</p>
503 <note><title>Note</title>
504 <p>Order is important. you need to put the exclusions <em>before</em> the
505 general proxypass directive.</p>
508 <p>When used inside a <directive type="section" module="core"
509 >Location</directive> section, the first argument is ommitted and the local
510 directory is obtained from the <directive type="section" module="core"
511 >Location</directive>.</p>
513 <p>If you require a more flexible reverse-proxy configuration, see the
514 <directive module="mod_rewrite">RewriteRule</directive> directive with the
515 <code>[P]</code> flag.</p>
520 <name>ProxyPassReverse</name>
521 <description>Adjusts the URL in HTTP response headers sent from a reverse
522 proxied server</description>
523 <syntax>ProxyPassReverse [<var>path</var>] <var>url</var></syntax>
524 <contextlist><context>server config</context><context>virtual host</context>
525 <context>directory</context>
529 <p>This directive lets Apache adjust the URL in the <code>Location</code>,
530 <code>Content-Location</code> and <code>URI</code> headers on HTTP redirect
531 responses. This is essential when Apache is used as a reverse proxy to avoid
532 by-passing the reverse proxy because of HTTP redirects on the backend
533 servers which stay behind the reverse proxy.</p>
535 <p><var>path</var> is the name of a local virtual path. <var>url</var> is a
536 partial URL for the remote server - the same way they are used for the
537 <directive module="mod_proxy">ProxyPass</directive> directive.</p>
539 <p>For example, suppose the local server has address
540 <code>http://example.com/</code>; then</p>
543 ProxyPass /mirror/foo/ http://backend.example.com/<br />
544 ProxyPassReverse /mirror/foo/ http://backend.example.com/
547 <p>will not only cause a local request for the
548 <code>http://example.com/mirror/foo/bar</code> to be internally converted
549 into a proxy request to <code>http://backend.example.com/bar</code>
550 (the functionality <code>ProxyPass</code> provides here). It also takes care
551 of redirects the server <code>backend.example.com</code> sends: when
552 <code>http://backend.example.com/bar</code> is redirected by him to
553 <code>http://backend.example.com/quux</code> Apache adjusts this to
554 <code>http://example.com/mirror/foo/quux</code> before forwarding the HTTP
555 redirect response to the client. Note that the hostname used for
556 constructing the URL is chosen in respect to the setting of the <directive
557 module="core">UseCanonicalName</directive> directive.</p>
559 <p>Note that this <directive>ProxyPassReverse</directive> directive can
560 also be used in conjunction with the proxy pass-through feature
561 (<code>RewriteRule ... [P]</code>) from <module>mod_rewrite</module>
562 because its doesn't depend on a corresponding <directive module="mod_proxy"
563 >ProxyPass</directive> directive.</p>
565 <p>When used inside a <directive type="section" module="core"
566 >Location</directive> section, the first argument is ommitted and the local
567 directory is obtained from the <directive type="section" module="core"
568 >Location</directive>.</p>
573 <name>AllowCONNECT</name>
574 <description>Ports that are allowed to <code>CONNECT</code> through the
576 <syntax>AllowCONNECT <var>port</var> [<var>port</var>] ...</syntax>
577 <default>AllowCONNECT 443 563</default>
578 <contextlist><context>server config</context><context>virtual host</context>
582 <p>The <directive>AllowCONNECT</directive> directive specifies a list
583 of port numbers to which the proxy <code>CONNECT</code> method may
584 connect. Today's browsers use this method when a <code>https</code>
585 connection is requested and proxy tunneling over HTTP is in effect.</p>
587 <p>By default, only the default https port (<code>443</code>) and the
588 default snews port (<code>563</code>) are enabled. Use the
589 <directive>AllowCONNECT</directive> directive to override this default and
590 allow connections to the listed ports only.</p>
592 <p>Note that you'll need to have <module>mod_proxy_connect</module> present
593 in the server in order to get the support for the <code>CONNECT</code> at
599 <name>ProxyBlock</name>
600 <description>Words, hosts, or domains that are banned from being
601 proxied</description>
602 <syntax>ProxyBlock *|<var>word</var>|<var>host</var>|<var>domain</var>
603 [<var>word</var>|<var>host</var>|<var>domain</var>] ...</syntax>
604 <contextlist><context>server config</context><context>virtual host</context>
608 <p>The <directive>ProxyBlock</directive> directive specifies a list of
609 words, hosts and/or domains, separated by spaces. HTTP, HTTPS, and
610 FTP document requests to sites whose names contain matched words,
611 hosts or domains are <em>blocked</em> by the proxy server. The proxy
612 module will also attempt to determine IP addresses of list items which
613 may be hostnames during startup, and cache them for match test as
614 well. That may slow down the startup time of the server.</p>
616 <example><title>Example</title>
617 ProxyBlock joes-garage.com some-host.co.uk rocky.wotsamattau.edu
620 <p><code>rocky.wotsamattau.edu</code> would also be matched if referenced by
623 <p>Note that <code>wotsamattau</code> would also be sufficient to match
624 <code>wotsamattau.edu</code>.</p>
626 <p>Note also that</p>
632 <p>blocks connections to all sites.</p>
637 <name>ProxyReceiveBufferSize</name>
638 <description>Network buffer size for proxied HTTP and FTP
639 connections</description>
640 <syntax>ProxyReceiveBufferSize <var>bytes</var></syntax>
641 <default>ProxyReceiveBufferSize 0</default>
642 <contextlist><context>server config</context><context>virtual host</context>
646 <p>The <directive>ProxyReceiveBufferSize</directive> directive specifies an
647 explicit (TCP/IP) network buffer size for proxied HTTP and FTP connections,
648 for increased throughput. It has to be greater than <code>512</code> or set
649 to <code>0</code> to indicate that the system's default buffer size should
652 <example><title>Example</title>
653 ProxyReceiveBufferSize 2048
659 <name>ProxyIOBufferSize</name>
660 <description>Determine size of internal data throughput buffer</description>
661 <syntax>ProxyIOBufferSize <var>bytes</var></syntax>
662 <default>ProxyIOBufferSize 8192</default>
663 <contextlist><context>server config</context><context>virtual host</context>
667 <p>The <directive>ProxyIOBufferSize</directive> directive adjusts the size
668 of the internal buffer, which is used as a scratchpad for the data between
669 input and output. The size must be less or equal <code>8192</code>.</p>
671 <p>In almost every case there's no reason to change that value.</p>
676 <name>ProxyMaxForwards</name>
677 <description>Maximium number of proxies that a request can be forwarded
678 through</description>
679 <syntax>ProxyMaxForwards <var>number</var></syntax>
680 <default>ProxyMaxForwards 10</default>
681 <contextlist><context>server config</context><context>virtual host</context>
683 <compatibility>Available in Apache 2.0 and later</compatibility>
686 <p>The <directive>ProxyMaxForwards</directive> directive specifies the
687 maximum number of proxies through which a request may pass, if there's no
688 <code>Max-Forwards</code> header supplied with the request. This is
689 set to prevent infinite proxy loops, or a DoS attack.</p>
691 <example><title>Example</title>
699 <description>Hosts, domains, or networks that will be connected to
700 directly</description>
701 <syntax>NoProxy <var>host</var> [<var>host</var>] ...</syntax>
702 <contextlist><context>server config</context><context>virtual host</context>
706 <p>This directive is only useful for Apache proxy servers within
707 intranets. The <directive>NoProxy</directive> directive specifies a
708 list of subnets, IP addresses, hosts and/or domains, separated by
709 spaces. A request to a host which matches one or more of these is
710 always served directly, without forwarding to the configured
711 <directive module="mod_proxy">ProxyRemote</directive> proxy server(s).</p>
713 <example><title>Example</title>
714 ProxyRemote * http://firewall.mycompany.com:81<br />
715 NoProxy .mycompany.com 192.168.112.0/21
718 <p>The <var>host</var> arguments to the <directive>NoProxy</directive>
719 directive are one of the following type list:</p>
722 <!-- ===================== Domain ======================= -->
723 <dt><var><a name="domain" id="domain">Domain</a></var></dt>
725 <p>A <dfn>Domain</dfn> is a partially qualified DNS domain name, preceded
726 by a period. It represents a list of hosts which logically belong to the
727 same DNS domain or zone (<em>i.e.</em>, the suffixes of the hostnames are
728 all ending in <var>Domain</var>).</p>
730 <example><title>Examples</title>
734 <p>To distinguish <var>Domain</var>s from <var><a href="#hostname"
735 >Hostname</a></var>s (both syntactically and semantically; a DNS domain can
736 have a DNS A record, too!), <var>Domain</var>s are always written with a
739 <note><title>Note</title>
740 <p>Domain name comparisons are done without regard to the case, and
741 <var>Domain</var>s are always assumed to be anchored in the root of the
742 DNS tree, therefore two domains <code>.MyDomain.com</code> and
743 <code>.mydomain.com.</code> (note the trailing period) are considered
744 equal. Since a domain comparison does not involve a DNS lookup, it is much
745 more efficient than subnet comparison.</p>
748 <!-- ===================== SubNet ======================= -->
749 <dt><var><a name="subnet" id="subnet">SubNet</a></var></dt>
751 <p>A <dfn>SubNet</dfn> is a partially qualified internet address in
752 numeric (dotted quad) form, optionally followed by a slash and the netmask,
753 specified as the number of significant bits in the <var>SubNet</var>. It is
754 used to represent a subnet of hosts which can be reached over a common
755 network interface. In the absence of the explicit net mask it is assumed
756 that omitted (or zero valued) trailing digits specify the mask. (In this
757 case, the netmask can only be multiples of 8 bits wide.) Examples:</p>
760 <dt><code>192.168</code> or <code>192.168.0.0</code></dt>
761 <dd>the subnet 192.168.0.0 with an implied netmask of 16 valid bits
762 (sometimes used in the netmask form <code>255.255.0.0</code>)</dd>
763 <dt><code>192.168.112.0/21</code></dt>
764 <dd>the subnet <code>192.168.112.0/21</code> with a netmask of 21
765 valid bits (also used in the form 255.255.248.0)</dd>
768 <p>As a degenerate case, a <em>SubNet</em> with 32 valid bits is the
769 equivalent to an <var><a href="#ipadr">IPAddr</a></var>, while a <var>SubNet</var> with zero
770 valid bits (<em>e.g.</em>, 0.0.0.0/0) is the same as the constant
771 <var>_Default_</var>, matching any IP address.</p></dd>
773 <!-- ===================== IPAddr ======================= -->
774 <dt><var><a name="ipaddr" id="ipaddr">IPAddr</a></var></dt>
776 <p>A <dfn>IPAddr</dfn> represents a fully qualified internet address in
777 numeric (dotted quad) form. Usually, this address represents a host, but
778 there need not necessarily be a DNS domain name connected with the
780 <example><title>Example</title>
784 <note><title>Note</title>
785 <p>An <var>IPAddr</var> does not need to be resolved by the DNS system, so
786 it can result in more effective apache performance.</p>
789 <!-- ===================== Hostname ======================= -->
790 <dt><var><a name="hostname" id="hostname">Hostname</a></var></dt>
792 <p>A <dfn>Hostname</dfn> is a fully qualified DNS domain name which can
793 be resolved to one or more <var><a href="#ipaddr">IPAddrs</a></var> via the
794 DNS domain name service. It represents a logical host (in contrast to
795 <var><a href="#domain">Domain</a></var>s, see above) and must be resolvable
796 to at least one <var><a href="#ipaddr">IPAddr</a></var> (or often to a list
797 of hosts with different <var><a href="#ipaddr">IPAddr</a></var>s).</p>
799 <example><title>Examples</title>
800 prep.ai.mit.edu<br />
804 <note><title>Note</title>
805 <p>In many situations, it is more effective to specify an <var><a
806 href="#ipaddr">IPAddr</a></var> in place of a <var>Hostname</var> since a
807 DNS lookup can be avoided. Name resolution in Apache can take a remarkable
808 deal of time when the connection to the name server uses a slow PPP
810 <p><var>Hostname</var> comparisons are done without regard to the case,
811 and <var>Hostname</var>s are always assumed to be anchored in the root
812 of the DNS tree, therefore two hosts <code>WWW.MyDomain.com</code>
813 and <code>www.mydomain.com.</code> (note the trailing period) are
814 considered equal.</p>
818 <seealso><a href="../dns-caveats.html">DNS Issues</a></seealso>
822 <name>ProxyTimeout</name>
823 <description>Network timeout for proxied requests</description>
824 <syntax>ProxyTimeout <var>seconds</var></syntax>
825 <default>ProxyTimeout 300</default>
826 <contextlist><context>server config</context><context>virtual host</context>
828 <compatibility>Available in Apache 2.0.31 and later</compatibility>
831 <p>This directive allows a user to specifiy a timeout on proxy requests.
832 This is useful when you have a slow/buggy appserver which hangs, and you
833 would rather just return a timeout and fail gracefully instead of waiting
834 however long it takes the server to return.</p>
839 <name>ProxyDomain</name>
840 <description>Default domain name for proxied requests</description>
841 <syntax>ProxyDomain <var>Domain</var></syntax>
842 <contextlist><context>server config</context><context>virtual host</context>
846 <p>This directive is only useful for Apache proxy servers within
847 intranets. The <directive>ProxyDomain</directive> directive specifies
848 the default domain which the apache proxy server will belong to. If a
849 request to a host without a domain name is encountered, a redirection
850 response to the same host with the configured <var>Domain</var> appended
851 will be generated.</p>
853 <example><title>Example</title>
854 ProxyRemote * http://firewall.mycompany.com:81<br />
855 NoProxy .mycompany.com 192.168.112.0/21<br />
856 ProxyDomain .mycompany.com
862 <name>ProxyVia</name>
863 <description>Information provided in the <code>Via</code> HTTP response
864 header for proxied requests</description>
865 <syntax>ProxyVia On|Off|Full|Block</syntax>
866 <default>ProxyVia Off</default>
867 <contextlist><context>server config</context><context>virtual host</context>
871 <p>This directive controls the use of the <code>Via:</code> HTTP
872 header by the proxy. Its intended use is to control the flow of of
873 proxy requests along a chain of proxy servers. See <a
874 href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a> (HTTP/1.1), section
875 14.45 for an explanation of <code>Via:</code> header lines.</p>
878 <li>If set to <code>Off</code>, which is the default, no special processing
879 is performed. If a request or reply contains a <code>Via:</code> header,
880 it is passed through unchanged.</li>
882 <li>If set to <code>On</code>, each request and reply will get a
883 <code>Via:</code> header line added for the current host.</li>
885 <li>If set to <code>Full</code>, each generated <code>Via:</code> header
886 line will additionally have the Apache server version shown as a
887 <code>Via:</code> comment field.</li>
889 <li>If set to <code>Block</code>, every proxy request will have all its
890 <code>Via:</code> header lines removed. No new <code>Via:</code> header will
897 <name>ProxyErrorOverride</name>
898 <description>Override error pages for proxied content</description>
899 <syntax>ProxyErrorOverride On|Off</syntax>
900 <default>ProxyErrorOverride Off</default>
901 <contextlist><context>server config</context><context>virtual host</context>
903 <compatibility>Available in version 2.0 and later</compatibility>
906 <p>This directive is useful for reverse-proxy setups, where you want to
907 have a common look and feel on the error pages seen by the end user.
908 This also allows for included files (via mod_include's SSI) to get
909 the error code and act accordingly (default behavior would display
910 the error page of the proxied server, turning this on shows the SSI