1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
4 <TITLE>Apache module mod_proxy</TITLE>
7 <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
15 <!--#include virtual="header.html" -->
16 <H1 ALIGN="CENTER">Apache module mod_proxy</H1>
18 This module is contained in the <CODE>mod_proxy.c</CODE> file for Apache 1.1.x,
19 or the <CODE>modules/proxy</CODE> subdirectory for Apache 1.2, and
20 is not compiled in by default. It provides for an <STRONG>HTTP
21 1.0</STRONG> caching proxy
22 server. It is only available in Apache 1.1 and later. Common configuration
23 questions are addressed <A HREF="#configs">after the directive
27 <P>This module was experimental in Apache 1.1.x. As of Apache 1.2, mod_proxy
28 stability is <EM>greatly</EM> improved.<P>
32 This module implements a proxy/cache for Apache. It implements
33 proxying capability for
35 <CODE>CONNECT</CODE> (for SSL),
36 <CODE>HTTP/0.9</CODE>, and
37 <CODE>HTTP/1.0</CODE>.
38 The module can be configured to connect to other proxy modules for these
43 <LI><A HREF="#proxyrequests">ProxyRequests</A>
44 <LI><A HREF="#proxyremote">ProxyRemote</A>
45 <LI><A HREF="#proxypass">ProxyPass</A>
46 <LI><A HREF="#proxypassreverse">ProxyPassReverse</A>
47 <LI><A HREF="#proxyblock">ProxyBlock</A>
48 <LI><A HREF="#allowconnect">AllowCONNECT</A>
49 <LI><A HREF="#proxyreceivebuffersize">ProxyReceiveBufferSize</A>
50 <LI><A HREF="#noproxy">NoProxy</A>
51 <LI><A HREF="#proxydomain">ProxyDomain</A>
52 <LI><A HREF="#proxyvia">ProxyVia</A>
53 <LI><A HREF="#cacheroot">CacheRoot</A>
54 <LI><A HREF="#cachesize">CacheSize</A>
55 <LI><A HREF="#cachemaxexpire">CacheMaxExpire</A>
56 <LI><A HREF="#cachedefaultexpire">CacheDefaultExpire</A>
57 <LI><A HREF="#cachelastmodifiedfactor">CacheLastModifiedFactor</A>
58 <LI><A HREF="#cachegcinterval">CacheGcInterval</A>
59 <LI><A HREF="#cachedirlevels">CacheDirLevels</A>
60 <LI><A HREF="#cachedirlength">CacheDirLength</A>
61 <LI><A HREF="#cacheforcecompletion">CacheForceCompletion</A>
62 <LI><A HREF="#nocache">NoCache</A>
67 <H2><A NAME="proxyrequests">ProxyRequests</A></H2>
69 HREF="directive-dict.html#Syntax"
71 ><STRONG>Syntax:</STRONG></A> ProxyRequests <EM>on/off</EM><BR>
73 HREF="directive-dict.html#Default"
75 ><STRONG>Default:</STRONG></A> <CODE>ProxyRequests Off</CODE><BR>
77 HREF="directive-dict.html#Context"
79 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
81 HREF="directive-dict.html#Override"
83 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
85 HREF="directive-dict.html#Status"
87 ><STRONG>Status:</STRONG></A> Base<BR>
89 HREF="directive-dict.html#Module"
91 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
93 HREF="directive-dict.html#Compatibility"
95 ><STRONG>Compatibility:</STRONG></A> ProxyRequests is only available in
96 Apache 1.1 and later.<P>
98 This allows or prevents Apache from functioning as a proxy
99 server. Setting ProxyRequests to 'off' does not disable use of the <A
100 HREF="#proxypass">ProxyPass</A> directive.
104 <H2><A NAME="proxyremote">ProxyRemote</A></H2>
106 HREF="directive-dict.html#Syntax"
108 ><STRONG>Syntax:</STRONG></A> ProxyRemote <EM><match> <remote-server></EM><BR>
110 HREF="directive-dict.html#Default"
112 ><STRONG>Default:</STRONG></A> <EM>None</EM><BR>
114 HREF="directive-dict.html#Context"
116 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
118 HREF="directive-dict.html#Override"
120 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
122 HREF="directive-dict.html#Status"
124 ><STRONG>Status:</STRONG></A> Base<BR>
126 HREF="directive-dict.html#Module"
128 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
130 HREF="directive-dict.html#Compatibility"
132 ><STRONG>Compatibility:</STRONG></A> ProxyRemote is only available in
133 Apache 1.1 and later.<P>
135 This defines remote proxies to this proxy. <match> is either the
136 name of a URL-scheme that the remote server supports, or a partial URL
137 for which the remote server should be used, or '*' to indicate the
138 server should be contacted for all requests. <remote-server> is a
139 partial URL for the remote server. Syntax:
142 <remote-server> = <protocol>://<hostname>[:port]
145 <protocol> is the protocol that should be used to communicate
146 with the remote server; only "http" is supported by this module.
150 ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000
151 ProxyRemote * http://cleversite.com
152 ProxyRemote ftp http://ftpproxy.mydomain.com:8080
155 In the last example, the proxy will forward FTP requests, encapsulated
156 as yet another HTTP proxy request, to another proxy which can handle
161 <H2><A NAME="proxypass">ProxyPass</A></H2>
163 HREF="directive-dict.html#Syntax"
165 ><STRONG>Syntax:</STRONG></A> ProxyPass <EM><path> <url></EM><BR>
167 HREF="directive-dict.html#Default"
169 ><STRONG>Default:</STRONG></A> <EM>None</EM><BR>
171 HREF="directive-dict.html#Context"
173 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
175 HREF="directive-dict.html#Override"
177 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
179 HREF="directive-dict.html#Status"
181 ><STRONG>Status:</STRONG></A> Base<BR>
183 HREF="directive-dict.html#Module"
185 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
187 HREF="directive-dict.html#Compatibility"
189 ><STRONG>Compatibility:</STRONG></A> ProxyPass is only available in
190 Apache 1.1 and later.<P>
192 This directive allows remote servers to be mapped into the space of the local
193 server; the local server does not act as a proxy in the conventional sense,
194 but appears to be a mirror of the remote server. <path> is the name of
195 a local virtual path; <url> is a partial URL for the remote server.
197 Suppose the local server has address <SAMP>http://wibble.org/</SAMP>; then
199 ProxyPass /mirror/foo/ http://foo.com/
201 will cause a local request for the
202 <<SAMP>http://wibble.org/mirror/foo/bar</SAMP>> to be
203 internally converted into a proxy request to
204 <<SAMP>http://foo.com/bar</SAMP>>.
208 <H2><A NAME="proxypassreverse">ProxyPassReverse</A></H2>
210 HREF="directive-dict.html#Syntax"
212 ><STRONG>Syntax:</STRONG></A> ProxyPassReverse <EM><path> <url></EM><BR>
214 HREF="directive-dict.html#Default"
216 ><STRONG>Default:</STRONG></A> <EM>None</EM><BR>
218 HREF="directive-dict.html#Context"
220 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
222 HREF="directive-dict.html#Override"
224 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
226 HREF="directive-dict.html#Status"
228 ><STRONG>Status:</STRONG></A> Base<BR>
230 HREF="directive-dict.html#Module"
232 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
234 HREF="directive-dict.html#Compatibility"
236 ><STRONG>Compatibility:</STRONG></A> ProxyPassReverse is only available in
237 Apache 1.3b6 and later.<P>
239 This directive lets Apache adjust the URL in the <TT>Location</TT> header on
240 HTTP redirect responses. For instance this is essential when Apache is used as
241 a reverse proxy to avoid by-passing the reverse proxy because of HTTP
242 redirects on the backend servers which stay behind the reverse proxy.
244 <path> is the name of a local virtual path.<BR>
245 <url> is a partial URL for the remote server - the same way they are
246 used for the <TT>ProxyPass</TT> directive.
249 Suppose the local server has address <SAMP>http://wibble.org/</SAMP>; then
251 ProxyPass /mirror/foo/ http://foo.com/
252 ProxyPassReverse /mirror/foo/ http://foo.com/
254 will not only cause a local request for the
255 <<SAMP>http://wibble.org/mirror/foo/bar</SAMP>> to be internally
256 converted into a proxy request to <<SAMP>http://foo.com/bar</SAMP>> (the
257 functionality <SAMP>ProxyPass</SAMP> provides here). It also takes care of
258 redirects the server foo.com sends: when <SAMP>http://foo.com/bar</SAMP> is
259 redirected by him to <SAMP>http://foo.com/quux</SAMP> Apache adjusts this to
260 <SAMP>http://wibble.org/mirror/foo/quux</SAMP> before forwarding the HTTP
261 redirect response to the client.
263 Note that this <SAMP>ProxyPassReverse</SAMP> directive can also be used in
264 conjunction with the proxy pass-through feature ("<SAMP>RewriteRule ...
267 HREF="mod_rewrite.html#RewriteRule"
268 ><TT>mod_rewrite</TT></A> because its doesn't depend on a corresponding
269 <SAMP>ProxyPass</SAMP> directive.
273 <H2><A NAME="allowconnect">AllowCONNECT</A></H2>
275 HREF="directive-dict.html#Syntax"
277 ><STRONG>Syntax:</STRONG></A> AllowCONNECT <EM><port list></EM><BR>
279 HREF="directive-dict.html#Default"
281 ><STRONG>Default:</STRONG></A> <EM><SAMP>AllowCONNECT</SAMP> 443 563</EM><BR>
283 HREF="directive-dict.html#Context"
285 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
287 HREF="directive-dict.html#Override"
289 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
291 HREF="directive-dict.html#Status"
293 ><STRONG>Status:</STRONG></A> Base<BR>
295 HREF="directive-dict.html#Module"
297 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
299 HREF="directive-dict.html#Compatibility"
301 ><STRONG>Compatibility:</STRONG></A> <SAMP>AllowCONNECT</SAMP> is only
302 available in Apache 1.3.2 and later.<P>
304 The <SAMP>AllowCONNECT</SAMP> directive specifies a list of port numbers
305 to which the proxy <SAMP>CONNECT</SAMP> method may connect.
306 Today's browsers use this method when a <EM>https</EM> connection
307 is requested and proxy tunneling over <EM>http</EM> is in effect.<BR>
308 By default, only the default https port (443) and the default
309 snews port (563) are enabled. Use the <SAMP>AllowCONNECT</SAMP>
310 directive to overrride this default and allow connections to the
315 <H2><A NAME="proxyblock">ProxyBlock</A></H2>
317 HREF="directive-dict.html#Syntax"
319 ><STRONG>Syntax:</STRONG></A> ProxyBlock <EM><word/host/domain list></EM><BR>
321 HREF="directive-dict.html#Default"
323 ><STRONG>Default:</STRONG></A> <EM>None</EM><BR>
325 HREF="directive-dict.html#Context"
327 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
329 HREF="directive-dict.html#Override"
331 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
333 HREF="directive-dict.html#Status"
335 ><STRONG>Status:</STRONG></A> Base<BR>
337 HREF="directive-dict.html#Module"
339 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
341 HREF="directive-dict.html#Compatibility"
343 ><STRONG>Compatibility:</STRONG></A> ProxyBlock is only available in
344 Apache 1.2 and later.<P>
346 The ProxyBlock directive specifies a list of words, hosts and/or domains,
347 separated by spaces. HTTP, HTTPS, and FTP document requests to matched words,
348 hosts or domains are <EM>blocked</EM> by the proxy server. The proxy module
349 will also attempt to determine IP addresses of list items which may be
350 hostnames during startup, and cache them for match test as well. Example:
353 ProxyBlock joes-garage.com some-host.co.uk rocky.wotsamattau.edu
356 'rocky.wotsamattau.edu' would also be matched if referenced by IP address.<P>
358 Note that 'wotsamattau' would also be sufficient to match 'wotsamattau.edu'.<P>
366 blocks connections to all sites.
370 <H2><A NAME="proxyreceivebuffersize">ProxyReceiveBufferSize</A></H2>
372 HREF="directive-dict.html#Syntax"
374 ><STRONG>Syntax:</STRONG></A> ProxyReceiveBufferSize <EM><bytes></EM><BR>
376 HREF="directive-dict.html#Default"
378 ><STRONG>Default:</STRONG></A> <EM>None</EM><BR>
380 HREF="directive-dict.html#Context"
382 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
384 HREF="directive-dict.html#Override"
386 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
388 HREF="directive-dict.html#Status"
390 ><STRONG>Status:</STRONG></A> Base<BR>
392 HREF="directive-dict.html#Module"
394 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
396 HREF="directive-dict.html#Compatibility"
398 ><STRONG>Compatibility:</STRONG></A> ProxyReceiveBufferSize is only available in
399 Apache 1.3 and later.<P>
401 The ProxyReceiveBufferSize directive specifies an explicit network buffer size
402 for outgoing HTTP and FTP connections, for increased throughput. It has to be
403 greater than 512 or set to 0 to indicate that the system's default buffer size
410 ProxyReceiveBufferSize 2048
415 <H2><A NAME="noproxy">NoProxy</A></H2>
417 HREF="directive-dict.html#Syntax"
419 ><STRONG>Syntax:</STRONG></A> NoProxy { <A HREF="#domain"><EM><Domain></EM></A>
420 | <A HREF="#subnet"><EM><SubNet></EM></A>
421 | <A HREF="#ipaddr"><EM><IpAddr></EM></A>
422 | <A HREF="#hostname"><EM><Hostname></EM></A>
425 HREF="directive-dict.html#Default"
427 ><STRONG>Default:</STRONG></A> <EM>None</EM><BR>
429 HREF="directive-dict.html#Context"
431 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
433 HREF="directive-dict.html#Override"
435 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
437 HREF="directive-dict.html#Status"
439 ><STRONG>Status:</STRONG></A> Base<BR>
441 HREF="directive-dict.html#Module"
443 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
445 HREF="directive-dict.html#Compatibility"
447 ><STRONG>Compatibility:</STRONG></A> NoProxy is only available in
448 Apache 1.3 and later.<P>
450 This directive is only useful for Apache proxy servers within intranets.
451 The NoProxy directive specifies a list of subnets, IP addresses, hosts
452 and/or domains, separated by spaces. A request to a host which matches
453 one or more of these is always served directly, without forwarding to
454 the configured ProxyRemote proxy server(s).
459 ProxyRemote * http://firewall.mycompany.com:81
460 NoProxy .mycompany.com 192.168.112.0/21
462 The arguments to the NoProxy directive are one of the following type list:
464 <!-- ===================== Domain ======================= -->
466 <DT><EM>Domain</EM></A>
467 <DD>A <EM>Domain</EM> is a partially qualified DNS domain name, preceded
469 It represents a list of hosts which logically belong to the same DNS
470 domain or zone (<EM>i.e.</EM>, the suffixes of the hostnames are all ending in
471 <EM>Domain</EM>).<BR>
472 Examples: <SAMP>.com</SAMP> <SAMP>.apache.org.</SAMP><BR>
473 To distinguish <EM>Domain</EM>s from <A HREF="#hostname"><EM>Hostname</EM></A>s (both
474 syntactically and semantically; a DNS domain can have a DNS A record,
475 too!), <EM>Domain</EM>s are always written
476 with a leading period.<BR>
477 Note: Domain name comparisons are done without regard to the case,
478 and <EM>Domain</EM>s are always assumed to be anchored in the root
479 of the DNS tree, therefore two domains <SAMP>.MyDomain.com</SAMP> and
480 <SAMP>.mydomain.com.</SAMP> (note the trailing period) are
481 considered equal. Since a domain comparison does not involve a DNS
482 lookup, it is much more efficient than subnet comparison.
484 <!-- ===================== SubNet ======================= -->
486 <DT><EM>SubNet</EM></A>
487 <DD>A <EM>SubNet</EM> is a partially qualified internet address in
488 numeric (dotted quad) form, optionally followed by a slash and the
489 netmask, specified as the number of significant bits in the
490 <EM>SubNet</EM>. It is used to represent a subnet of hosts which can
491 be reached over a common network interface. In the absence of the
492 explicit net mask it is assumed that omitted (or zero valued)
493 trailing digits specify the mask. (In this case, the netmask can
494 only be multiples of 8 bits wide.)<BR>
497 <DT><SAMP>192.168</SAMP> or <SAMP>192.168.0.0</SAMP>
498 <DD>the subnet 192.168.0.0 with an implied netmask of 16 valid bits
499 (sometimes used in the netmask form <SAMP>255.255.0.0</SAMP>)
500 <DT><SAMP>192.168.112.0/21</SAMP>
501 <DD>the subnet <SAMP>192.168.112.0/21</SAMP> with a netmask of 21
502 valid bits (also used in the form 255.255.248.0)
504 As a degenerate case, a <EM>SubNet</EM> with 32 valid bits is the
505 equivalent to an <EM>IPAddr</EM>, while a <EM>SubNet</EM> with zero
506 valid bits (<EM>e.g.</EM>, 0.0.0.0/0) is the same as the constant
507 <EM>_Default_</EM>, matching any IP address.
509 <!-- ===================== IPAddr ======================= -->
511 <DT><EM>IPAddr</EM></A>
512 <DD>A <EM>IPAddr</EM> represents a fully qualified internet address in
513 numeric (dotted quad) form. Usually, this address represents a
514 host, but there need not necessarily be a DNS domain name
515 connected with the address.<BR>
516 Example: 192.168.123.7<BR>
517 Note: An <EM>IPAddr</EM> does not need to be resolved by the DNS
518 system, so it can result in more effective apache performance.
519 <P><STRONG>See Also:</STRONG>
520 <A HREF="../dns-caveats.html">DNS Issues</A></P>
522 <!-- ===================== Hostname ======================= -->
524 <DT><EM>Hostname</EM></A>
525 <DD>A <EM>Hostname</EM> is a fully qualified DNS domain name which can
526 be resolved to one or more <A
527 HREF="#ipaddr"><EM>IPAddrs</EM></A> via the DNS domain name service.
528 It represents a logical host (in contrast to
529 <A HREF="#domain"><EM>Domain</EM></A>s, see
530 above) and must be resolvable to at least one <A
531 HREF="#ipaddr"><EM>IPAddr</EM></A> (or often to a list of hosts
532 with different <A HREF="#ipaddr"><EM>IPAddr</EM></A>'s).<BR>
533 Examples: <SAMP>prep.ai.mit.edu</SAMP>
534 <SAMP>www.apache.org.</SAMP><BR>
535 Note: In many situations, it is more effective to specify an
536 <A HREF="#ipaddr"><EM>IPAddr</EM></A> in place of a
537 <EM>Hostname</EM> since a DNS lookup
538 can be avoided. Name resolution in Apache can take a remarkable deal
539 of time when the connection to the name server uses a slow PPP
541 Note: <EM>Hostname</EM> comparisons are done without regard to the case,
542 and <EM>Hostname</EM>s are always assumed to be anchored in the root
543 of the DNS tree, therefore two hosts <SAMP>WWW.MyDomain.com</SAMP>
544 and <SAMP>www.mydomain.com.</SAMP> (note the trailing period) are
545 considered equal.<BR>
546 <P><STRONG>See Also:</STRONG>
547 <A HREF="../dns-caveats.html">DNS Issues</A></P>
552 <H2><A NAME="proxydomain">ProxyDomain</A></H2>
554 HREF="directive-dict.html#Syntax"
556 ><STRONG>Syntax:</STRONG></A> ProxyDomain <EM><Domain></EM><BR>
558 HREF="directive-dict.html#Default"
560 ><STRONG>Default:</STRONG></A> <EM>None</EM><BR>
562 HREF="directive-dict.html#Context"
564 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
566 HREF="directive-dict.html#Override"
568 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
570 HREF="directive-dict.html#Status"
572 ><STRONG>Status:</STRONG></A> Base<BR>
574 HREF="directive-dict.html#Module"
576 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
578 HREF="directive-dict.html#Compatibility"
580 ><STRONG>Compatibility:</STRONG></A> ProxyDomain is only available in
581 Apache 1.3 and later.<P>
583 This directive is only useful for Apache proxy servers within intranets.
584 The ProxyDomain directive specifies the default domain which the apache
585 proxy server will belong to. If a request to a host without a domain name
586 is encountered, a redirection response to the same host
587 with the configured <EM>Domain</EM> appended will be generated.
592 ProxyRemote * http://firewall.mycompany.com:81
593 NoProxy .mycompany.com 192.168.112.0/21
594 ProxyDomain .mycompany.com
599 <H2><A NAME="proxyvia">ProxyVia</A></H2>
601 HREF="directive-dict.html#Syntax"
603 ><STRONG>Syntax:</STRONG></A> ProxyVia { <EM>off</EM>
609 HREF="directive-dict.html#Default"
611 ><STRONG>Default:</STRONG></A> <EM>ProxyVia off</EM><BR>
613 HREF="directive-dict.html#Context"
615 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
617 HREF="directive-dict.html#Override"
619 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
621 HREF="directive-dict.html#Status"
623 ><STRONG>Status:</STRONG></A> Base<BR>
625 HREF="directive-dict.html#Module"
627 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
629 HREF="directive-dict.html#Compatibility"
631 ><STRONG>Compatibility:</STRONG></A> ProxyVia is only available in
632 Apache 1.3.2 and later.<P>
634 This directive controls the use of the <SAMP>Via:</SAMP> HTTP header
635 by the proxy. Its intended use is to control the flow of of proxy
636 requests along a chain of proxy servers.
637 See RFC2068 (HTTP/1.1) for an explanation of <SAMP>Via:</SAMP> header lines.<UL>
638 <LI>If set to <EM>off</EM>, which is the default, no special
639 processing is performed. If a request or reply contains a <SAMP>Via:</SAMP> header,
640 it is passed through unchanged.
641 <LI>If set to <EM>on</EM>, each request and reply will get a <SAMP>Via:</SAMP> header
642 line added for the current host.
643 <LI>If set to <EM>full</EM>, each generated <SAMP>Via:</SAMP> header line will
644 additionally have the Apache server version shown as a <SAMP>Via:</SAMP> comment field.
645 <LI>If set to <EM>block</EM>, every proxy request will have all its
646 <SAMP>Via:</SAMP> header lines removed. No new <SAMP>Via:</SAMP> header will be generated.
651 <H2><A NAME="cacheforcecompletion">CacheForceCompletion</A></H2>
653 HREF="directive-dict.html#Syntax"
655 ><STRONG>Syntax:</STRONG></A> CacheForceCompletion <EM><percentage></EM><BR>
657 HREF="directive-dict.html#Default"
659 ><STRONG>Default:</STRONG></A> <EM>90</EM><BR>
661 HREF="directive-dict.html#Context"
663 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
665 HREF="directive-dict.html#Override"
667 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
669 HREF="directive-dict.html#Status"
671 ><STRONG>Status:</STRONG></A> Base<BR>
673 HREF="directive-dict.html#Module"
675 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
677 HREF="directive-dict.html#Compatibility"
679 ><STRONG>Compatibility:</STRONG></A> CacheForceCompletion is only available in
680 Apache 1.3.1 and later.<P>
682 If an http transfer that is being cached is cancelled, the proxy module will
683 complete the transfer to cache if more than the percentage specified has
684 already been transferred.<P>
686 This is a percentage, and must be a number between 1 and 100, or 0 to use
687 the default. 100 will cause a document to be cached only if the transfer
688 was allowed to complete. A number between 60 and 90 is recommended.
692 <H2><A NAME="cacheroot">CacheRoot</A></H2>
694 HREF="directive-dict.html#Syntax"
696 ><STRONG>Syntax:</STRONG></A> CacheRoot <EM><directory></EM><BR>
698 HREF="directive-dict.html#Default"
700 ><STRONG>Default:</STRONG></A> <EM>None</EM><BR>
702 HREF="directive-dict.html#Context"
704 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
706 HREF="directive-dict.html#Override"
708 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
710 HREF="directive-dict.html#Status"
712 ><STRONG>Status:</STRONG></A> Base<BR>
714 HREF="directive-dict.html#Module"
716 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
718 HREF="directive-dict.html#Compatibility"
720 ><STRONG>Compatibility:</STRONG></A> CacheRoot is only available in
721 Apache 1.1 and later.<P>
723 Sets the name of the directory to contain cache files; this must be
724 writable by the httpd server.
725 (see the <A HREF="core.html#user"><CODE>User</CODE></A> directive).<BR>
726 Setting <CODE>CacheRoot</CODE> enables proxy cacheing; without defining
727 a <CODE>CacheRoot</CODE>, proxy functionality will be available
728 if <CODE>ProxyRequests</CODE> are set to <CODE>On</CODE>, but no
729 cacheing will be available.
733 <H2><A NAME="cachesize">CacheSize</A></H2>
735 HREF="directive-dict.html#Syntax"
737 ><STRONG>Syntax:</STRONG></A> CacheSize <EM><size></EM><BR>
739 HREF="directive-dict.html#Default"
741 ><STRONG>Default:</STRONG></A> <CODE>CacheSize 5</CODE><BR>
743 HREF="directive-dict.html#Context"
745 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
747 HREF="directive-dict.html#Override"
749 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
751 HREF="directive-dict.html#Status"
753 ><STRONG>Status:</STRONG></A> Base<BR>
755 HREF="directive-dict.html#Module"
757 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
759 HREF="directive-dict.html#Compatibility"
761 ><STRONG>Compatibility:</STRONG></A> CacheSize is only available in
762 Apache 1.1 and later.<P>
764 Sets the desired space usage of the cache, in KB (1024-byte units). Although
765 usage may grow above this setting, the garbage collection will delete files
766 until the usage is at or below this setting.<BR>
767 Depending on the expected proxy traffic volume and <CODE>CacheGcInterval</CODE>,
768 use a value which is at least 20 to 40 % lower than the available space.
772 <H2><A NAME="cachegcinterval">CacheGcInterval</A></H2>
774 HREF="directive-dict.html#Syntax"
776 ><STRONG>Syntax:</STRONG></A> CacheGcInterval <EM><time></EM><BR>
778 HREF="directive-dict.html#Default"
780 ><STRONG>Default:</STRONG></A> <EM>None</EM><BR>
782 HREF="directive-dict.html#Context"
784 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
786 HREF="directive-dict.html#Override"
788 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
790 HREF="directive-dict.html#Status"
792 ><STRONG>Status:</STRONG></A> Base<BR>
794 HREF="directive-dict.html#Module"
796 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
798 HREF="directive-dict.html#Compatibility"
800 ><STRONG>Compatibility:</STRONG></A> CacheGcinterval is only available in
801 Apache 1.1 and later.<P>
803 Check the cache every <time> hours, and delete files if the space
804 usage is greater than that set by CacheSize. Note that <time> accepts a
805 float value, you could for example use <CODE>CacheGcInterval 1.5</CODE> to
806 check the cache every 90 minutes. (If unset, no garbage collection will
807 be performed, and the cache will grow indefinitely.)
808 Note also that the larger the <CODE>CacheGcInterval</CODE>, the more
809 extra space beyond the configured <CODE>CacheSize</CODE> will be
810 needed for the cache between garbage collections.<BR> <!--
811 Note that due to a design flaw, Apache does not automatically force a
812 garbage collection when the available space on the file system where
813 the cache resides is exhausted. -->
817 <H2><A NAME="cachemaxexpire">CacheMaxExpire</A></H2>
819 HREF="directive-dict.html#Syntax"
821 ><STRONG>Syntax:</STRONG></A> CacheMaxExpire <EM><time></EM><BR>
823 HREF="directive-dict.html#Default"
825 ><STRONG>Default:</STRONG></A> <CODE>CacheMaxExpire 24</CODE><BR>
827 HREF="directive-dict.html#Context"
829 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
831 HREF="directive-dict.html#Override"
833 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
835 HREF="directive-dict.html#Status"
837 ><STRONG>Status:</STRONG></A> Base<BR>
839 HREF="directive-dict.html#Module"
841 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
843 HREF="directive-dict.html#Compatibility"
845 ><STRONG>Compatibility:</STRONG></A> CacheMaxExpire is only available in
846 Apache 1.1 and later.<P>
848 Cachable HTTP documents will be retained for at most <time> hours without
849 checking the origin server. Thus documents can be at most <time>
850 hours out of date. This restriction is enforced even if an expiry date
851 was supplied with the document.
855 <H2><A NAME="cachelastmodifiedfactor">CacheLastModifiedFactor</A></H2>
857 HREF="directive-dict.html#Syntax"
859 ><STRONG>Syntax:</STRONG></A> CacheLastModifiedFactor <EM><factor></EM><BR>
861 HREF="directive-dict.html#Default"
863 ><STRONG>Default:</STRONG></A> <CODE>CacheLastModifiedFactor 0.1</CODE><BR>
865 HREF="directive-dict.html#Context"
867 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
869 HREF="directive-dict.html#Override"
871 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
873 HREF="directive-dict.html#Status"
875 ><STRONG>Status:</STRONG></A> Base<BR>
877 HREF="directive-dict.html#Module"
879 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
881 HREF="directive-dict.html#Compatibility"
883 ><STRONG>Compatibility:</STRONG></A> CacheLastModifiedFactor is only available in
884 Apache 1.1 and later.<P>
886 If the origin HTTP server did not supply an expiry date for the
887 document, then estimate one using the formula
889 expiry-period = time-since-last-modification * <factor>
891 For example, if the document was last modified 10 hours ago, and
892 <factor> is 0.1, then the expiry period will be set to 10*0.1 = 1 hour.
894 <P>If the expiry-period would be longer than that set by CacheMaxExpire,
895 then the latter takes precedence.
899 <H2><A NAME="cachedirlevels">CacheDirLevels</A></H2>
901 HREF="directive-dict.html#Syntax"
903 ><STRONG>Syntax:</STRONG></A> CacheDirLevels <EM><levels></EM><BR>
905 HREF="directive-dict.html#Default"
907 ><STRONG>Default:</STRONG></A> <CODE>CacheDirLevels 3</CODE><BR>
909 HREF="directive-dict.html#Context"
911 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
913 HREF="directive-dict.html#Override"
915 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
917 HREF="directive-dict.html#Status"
919 ><STRONG>Status:</STRONG></A> Base<BR>
921 HREF="directive-dict.html#Module"
923 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
925 HREF="directive-dict.html#Compatibility"
927 ><STRONG>Compatibility:</STRONG></A> CacheDirLevels is only available in
928 Apache 1.1 and later.<P>
930 CacheDirLevels sets the number of levels of subdirectories in the cache.
931 Cached data will be saved this many directory levels below CacheRoot.
935 <H2><A NAME="cachedirlength">CacheDirLength</A></H2>
937 HREF="directive-dict.html#Syntax"
939 ><STRONG>Syntax:</STRONG></A> CacheDirLength <EM><length></EM><BR>
941 HREF="directive-dict.html#Default"
943 ><STRONG>Default:</STRONG></A> <CODE>CacheDirLength 1</CODE><BR>
945 HREF="directive-dict.html#Context"
947 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
949 HREF="directive-dict.html#Override"
951 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
953 HREF="directive-dict.html#Status"
955 ><STRONG>Status:</STRONG></A> Base<BR>
957 HREF="directive-dict.html#Module"
959 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
961 HREF="directive-dict.html#Compatibility"
963 ><STRONG>Compatibility:</STRONG></A> CacheDirLength is only available in
964 Apache 1.1 and later.<P>
966 CacheDirLength sets the number of characters in proxy cache subdirectory names.
970 <H2><A NAME="cachedefaultexpire">CacheDefaultExpire</A></H2>
972 HREF="directive-dict.html#Syntax"
974 ><STRONG>Syntax:</STRONG></A> CacheDefaultExpire <EM><time></EM><BR>
976 HREF="directive-dict.html#Default"
978 ><STRONG>Default:</STRONG></A> <CODE>CacheDefaultExpire 1</CODE><BR>
980 HREF="directive-dict.html#Context"
982 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
984 HREF="directive-dict.html#Override"
986 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
988 HREF="directive-dict.html#Status"
990 ><STRONG>Status:</STRONG></A> Base<BR>
992 HREF="directive-dict.html#Module"
994 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
996 HREF="directive-dict.html#Compatibility"
998 ><STRONG>Compatibility:</STRONG></A> CacheDefaultExpire is only available in
999 Apache 1.1 and later.<P>
1001 If the document is fetched via a protocol that does not support expiry times,
1002 then use <time> hours as the expiry time.
1003 <A HREF="#cachemaxexpire">CacheMaxExpire</A> does <STRONG>not</STRONG>
1004 override this setting.
1008 <H2><A NAME="nocache">NoCache</A></H2>
1010 HREF="directive-dict.html#Syntax"
1012 ><STRONG>Syntax:</STRONG></A> NoCache <EM><word/host/domain list></EM><BR>
1014 HREF="directive-dict.html#Default"
1016 ><STRONG>Default:</STRONG></A> <EM>None</EM><BR>
1018 HREF="directive-dict.html#Context"
1020 ><STRONG>Context:</STRONG></A> server config, virtual host<BR>
1022 HREF="directive-dict.html#Override"
1024 ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
1026 HREF="directive-dict.html#Status"
1028 ><STRONG>Status:</STRONG></A> Base<BR>
1030 HREF="directive-dict.html#Module"
1032 ><STRONG>Module:</STRONG></A> mod_proxy<BR>
1034 HREF="directive-dict.html#Compatibility"
1036 ><STRONG>Compatibility:</STRONG></A> NoCache is only available in
1037 Apache 1.1 and later.<P>
1039 The NoCache directive specifies a list of words, hosts and/or domains, separated
1040 by spaces. HTTP and non-passworded FTP documents from matched words, hosts or
1041 domains are <EM>not</EM> cached by the proxy server. The proxy module will
1042 also attempt to determine IP addresses of list items which may be hostnames
1043 during startup, and cache them for match test as well. Example:
1046 NoCache joes-garage.com some-host.co.uk bullwinkle.wotsamattau.edu
1049 'bullwinkle.wotsamattau.edu' would also be matched if referenced by IP
1052 Note that 'wotsamattau' would also be sufficient to match 'wotsamattau.edu'.<P>
1060 disables caching completely.<P>
1064 <H2><A NAME="configs">Common configuration topics</A></H2>
1067 <LI><A HREF="#access">Controlling access to your proxy</A>
1068 <LI><A HREF="#shortname">Using Netscape hostname shortcuts</A>
1069 <LI><A HREF="#mimetypes">Why doesn't file type <EM>xxx</EM> download via FTP?</A>
1070 <LI><A HREF="#startup">Why does Apache start more slowly when using the
1072 <LI><A HREF="#socks">Can I use the Apache proxy module with my SOCKS proxy?</A>
1073 <LI><A HREF="#intranet">What other functions are useful for an intranet proxy server?</A>
1076 <H2><A NAME="access">Controlling access to your proxy</A></H2>
1078 You can control who can access your proxy via the normal <Directory>
1079 control block using the following example:<P>
1082 <Directory proxy:*>
1084 deny from [machines you'd like *not* to allow by IP address or name]
1085 allow from [machines you'd like to allow by IP address or name]
1089 A <Files> block will also work, and is the only method known to work
1090 for all possible URLs in Apache versions earlier than 1.2b10.<P>
1092 <H2><A NAME="shortname">Using Netscape hostname shortcuts</A></H2>
1094 There is an optional patch to the proxy module to allow Netscape-like
1095 hostname shortcuts to be used. It's available from the
1096 <A HREF="http://www.apache.org/dist/contrib/patches/1.2/netscapehost.patch"
1097 ><SAMP>contrib/patches/1.2</SAMP></A> directory on the Apache Web site.<P>
1099 <H2><A NAME="mimetypes">Why doesn't file type <EM>xxx</EM> download via FTP?</A></H2>
1101 You probably don't have that particular file type defined as
1102 <EM>application/octet-stream</EM> in your proxy's mime.types configuration
1103 file. A useful line can be<P>
1106 application/octet-stream bin dms lha lzh exe class tgz taz
1109 <H2><A NAME="type">How can I force an FTP ASCII download of File <EM>xxx</EM>?</A></H2>
1111 In the rare situation where you must download a specific file using the FTP
1112 <STRONG>ASCII</STRONG> transfer method (while the default transfer is in
1113 <STRONG>binary</STRONG> mode), you can override mod_proxy's default by
1114 suffixing the request with <SAMP>;type=a</SAMP> to force an ASCII transfer.<P>
1116 <H2><A NAME="startup">Why does Apache start more slowly when using the
1117 proxy module?</A></H2>
1119 If you're using the <CODE>ProxyBlock</CODE> or <CODE>NoCache</CODE>
1120 directives, hostnames' IP addresses are looked up and cached during
1121 startup for later match test. This may take a few seconds (or more)
1122 depending on the speed with which the hostname lookups occur.<P>
1124 <H2><A NAME="socks">Can I use the Apache proxy module with my SOCKS proxy?</A></H2>
1126 Yes. Just build Apache with the rule <CODE>SOCKS4=yes</CODE> in your
1127 <EM>Configuration</EM> file, and follow the instructions there. SOCKS5
1128 capability can be added in a similar way (there's no <CODE>SOCKS5</CODE>
1129 rule yet), so use the <CODE>EXTRA_LDFLAGS</CODE> definition, or build Apache
1130 normally and run it with the <EM>runsocks</EM> wrapper provided with SOCKS5,
1131 if your OS supports dynamically linked libraries.<P>
1133 Some users have reported problems when using SOCKS version 4.2 on Solaris.
1134 The problem was solved by upgrading to SOCKS 4.3.<P>
1136 Remember that you'll also have to grant access to your Apache proxy machine by
1137 permitting connections on the appropriate ports in your SOCKS daemon's
1140 <H2><A NAME="intranet">What other functions are useful for an intranet proxy server?</A></H2>
1142 <P>An Apache proxy server situated in an intranet needs to forward external
1143 requests through the company's firewall. However, when it has to access
1144 resources within the intranet, it can bypass the firewall when accessing
1145 hosts. The <A HREF="#noproxy">NoProxy</A> directive is useful for specifying
1146 which hosts belong to the intranet and should be accessed directly.</P>
1148 <P>Users within an intranet tend to omit the local domain name from their
1149 WWW requests, thus requesting "http://somehost/" instead of
1150 "http://somehost.my.dom.ain/". Some commercial proxy servers let them get
1151 away with this and simply serve the request, implying a configured
1152 local domain. When the <A HREF="#proxydomain">ProxyDomain</A> directive
1153 is used and the server is <A HREF="#proxyrequests">configured for
1154 proxy service</A>, Apache can return a redirect response and send the client
1155 to the correct, fully qualified, server address. This is the preferred method
1156 since the user's bookmark files will then contain fully qualified hosts.</P>
1158 <!--#include virtual="footer.html" -->