manual/mod/mod_proxy.html

	mod_proxy.html revision 35f745d0d98970c673c5ef89cd48bbd2beeb2efe
1N/A<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
1N/A<HTML>
1N/A<HEAD>
1N/A<TITLE>Apache module mod_proxy</TITLE>
1N/A</HEAD>
1N/A
1N/A<BODY>
1N/A<!--#include virtual="header.html" -->
1N/A<H1>Apache module mod_proxy</h1>
1N/A
1N/AThis module is contained in the <code>mod_proxy.c</code> file for Apache 1.1.x,
1N/Aor the <code>modules/proxy</code> subdirectory for Apache 1.2, and
1N/Ais not compiled in by default. It provides for an <b>HTTP 1.0</b> caching proxy
1N/Aserver. It is only available in Apache 1.1 and later. Common configuration
1N/Aquestions are addressed <a href="#configs">here</a>.
1N/A
1N/A<h3>Note:</h3>
1N/A<p>This module was experimental in Apache 1.1.x. As of Apache 1.2, mod_proxy
1N/Astability is <i>greatly</i> improved.<p>
1N/A
1N/A<h2>Summary</h2>
1N/A
1N/AThis module implements a proxy/cache for Apache. It implements
1N/Aproxying capability for
1N/A<code>FTP</code>,
1N/A<code>CONNECT</code> (for SSL),
1N/A<code>HTTP/0.9</code>, and
1N/A<code>HTTP/1.0</code>.
1N/AThe module can be configured to connect to other proxy modules for these
1N/Aand other protocols.
1N/A
1N/A<h2>Directives</h2>
1N/A<ul>
1N/A<li><a href="#proxyrequests">ProxyRequests</a>
1N/A<li><a href="#proxyremote">ProxyRemote</a>
1N/A<li><a href="#proxypass">ProxyPass</a>
1N/A<li><a href="#proxyblock">ProxyBlock</a>
1N/A<li><a href="#cacheroot">CacheRoot</a>
1N/A<li><a href="#cachesize">CacheSize</a>
1N/A<li><a href="#cachemaxexpire">CacheMaxExpire</a>
1N/A<li><a href="#cachedefaultexpire">CacheDefaultExpire</a>
1N/A<li><a href="#cachelastmodifiedfactor">CacheLastModifiedFactor</a>
1N/A<li><a href="#cachegcinterval">CacheGcInterval</a>
1N/A<li><a href="#cachedirlevels">CacheDirLevels</a>
1N/A<li><a href="#cachedirlength">CacheDirLength</a>
1N/A<li><a href="#nocache">NoCache</a>
1N/A</ul>
1N/A
1N/A<hr>
1N/A
1N/A<A name="proxyrequests"><h2>ProxyRequests</h2></A>
1N/A<strong>Syntax:</strong> ProxyRequests <em>on/off</em><br>
1N/A<strong>Default:</strong> <code>ProxyRequests Off</code><br>
1N/A<strong>Context:</strong> server config<br>
1N/A<strong>Status:</strong> Base<br>
1N/A<strong>Module:</strong> mod_proxy<br>
1N/A<strong>Compatibility:</strong> ProxyRequest is only available in
1N/AApache 1.1 and later.<p>
1N/A
1N/AThis allows or prevents Apache from functioning as a proxy
1N/Aserver. Setting ProxyRequests to 'off' does not disable use of the <a
1N/Ahref="#proxypass">ProxyPass</a> directive.
1N/A
1N/A<A name="proxyremote"><h2>ProxyRemote</h2></A>
1N/A<strong>Syntax:</strong> ProxyRemote <em>&lt;match&gt; &lt;remote-server&gt;</em><br>
1N/A<strong>Context:</strong> server config<br>
1N/A<strong>Status:</strong> Base<br>
1N/A<strong>Module:</strong> mod_proxy<br>
1N/A<strong>Compatibility:</strong> ProxyRemote is only available in
1N/AApache 1.1 and later.<p>
1N/A
1N/AThis defines remote proxies to this proxy. &lt;match&gt; is either the
1N/Aname of a URL-scheme that the remote server supports, or a partial URL
1N/Afor which the remote server should be used, or '*' to indicate the
1N/Aserver should be contacted for all requests. &lt;remote-server&gt; is a
1N/Apartial URL for the remote server. Syntax:
1N/A
1N/A<pre>
1N/A  &lt;remote-server&gt; = &lt;protocol&gt;://&lt;hostname&gt;[:port]
1N/A</pre>
1N/A
1N/A&lt;protocol&gt; is the protocol that should be used to communicate
1N/Awith the remote server; only "http" is supported by this module.
1N/A
1N/AExample:
1N/A<pre>
1N/A  ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000
1N/A  ProxyRemote * http://cleversite.com
1N/A  ProxyRemote ftp http://ftpproxy.mydomain.com:8080
1N/A</pre>
1N/A
1N/AIn the last example, the proxy will forward FTP requests, encapsulated
1N/Aas yet another HTTP proxy request, to another proxy which can handle
1N/Athem.
1N/A
1N/A<A name="proxypass"><h2>ProxyPass</h2></A>
1N/A<strong>Syntax:</strong> ProxyPass <em>&lt;path&gt; &lt;url&gt;</em><br>
1N/A<strong>Context:</strong> server config<br>
1N/A<strong>Status:</strong> Base<br>
1N/A<strong>Module:</strong> mod_proxy<br>
1N/A<strong>Compatibility:</strong> ProxyPass is only available in
1N/AApache 1.1 and later.<p>
1N/A
1N/AThis directive allows remote servers to be mapped into the space of the local
1N/Aserver; the local server does not act as a proxy in the conventional sense,
1N/Abut appears to be a mirror of the remote server. &lt;path&gt; is the name of
1N/Aa local virtual path; &lt;url&gt; is a partial URL for the remote server.
1N/A
1N/ASuppose the local server has address http://wibble.org; then
1N/A<pre>
1N/A   ProxyPass /mirror/foo http://foo.com
1N/A</pre>
1N/AWill cause a local request for the http://wibble.org/mirror/foo/bar to be
1N/Ainternally converted into a proxy request to http://foo.com/bar
1N/A
1N/A<A name="proxyblock"><h2>ProxyBlock</h2></A>
1N/A<strong>Syntax:</strong> ProxyBlock <em>&lt;word/host/domain list&gt;</em><br>
1N/A<strong>Context:</strong> server config<br>
1N/A<strong>Status:</strong> Base<br>
1N/A<strong>Module:</strong> mod_proxy<br>
1N/A<strong>Compatibility:</strong> ProxyBlock is only available in
1N/AApache 1.2 and later.<p>
1N/A
1N/AThe ProxyBlock directive specifies a list of words, hosts and/or domains,
1N/Aseparated by spaces. HTTP, HTTPS, and FTP document requests to matched words,
1N/Ahosts or domains are <em>blocked</em> by the proxy server. The proxy module
1N/Awill also attempt to determine IP addresses of list items which may be
1N/Ahostnames during startup, and cache them for match test as well. Example:
1N/A
1N/A<pre>
1N/A  ProxyBlock joes_garage.com some_host.co.uk rocky.wotsamattau.edu
1N/A</pre>
1N/A
1N/A'rocky.wotsamattau.edu' would also be matched if referenced by IP address.<p>
1N/A
1N/ANote that 'wotsamattau' would also be sufficient to match 'wotsamattau.edu'.<p>
1N/A
1N/ANote also that
1N/A
1N/A<pre>
1N/AProxyBlock *
1N/A</pre>
1N/A
1N/Ablocks connections to all sites.
1N/A
1N/A<A name="cacheroot"><h2>CacheRoot</h2></A>
1N/A<strong>Syntax:</strong> CacheRoot <em>&lt;directory&gt;</em><br>
1N/A<strong>Context:</strong> server config<br>
1N/A<strong>Status:</strong> Base<br>
1N/A<strong>Module:</strong> mod_proxy<br>
1N/A<strong>Compatibility:</strong> CacheRoot is only available in
1N/AApache 1.1 and later.<p>
1N/A
1N/ASets the name of the directory to contain cache files; this must be
1N/Awritable
1N/Aby the httpd server.
1N/A
1N/A<A name="cachesize"><h2>CacheSize</h2></A>
1N/A<strong>Syntax:</strong> CacheSize <em>&lt;size&gt;</em><br>
1N/A<strong>Default:</strong> <code>CacheSize 5</code><br>
1N/A<strong>Context:</strong> server config<br>
1N/A<strong>Status:</strong> Base<br>
1N/A<strong>Module:</strong> mod_proxy<br>
1N/A<strong>Compatibility:</strong> CacheSize is only available in
1N/AApache 1.1 and later.<p>
1N/A
1N/ASets the desired space usage of the cache, in Kb (1024 byte units). Although
1N/Ausage may grow above this setting, the garbage collection will delete files
1N/Auntil the usage is at or below this setting.
1N/A
1N/A<A name="cachegcinterval"><h2>CacheGcInterval</h2></A>
1N/A<strong>Syntax:</strong> CacheGcInterval <em>&lt;time&gt;</em><br>
1N/A<strong>Context:</strong> server config<br>
1N/A<strong>Status:</strong> Base<br>
1N/A<strong>Module:</strong> mod_proxy<br>
1N/A<strong>Compatibility:</strong> CacheGcinterval is only available in
1N/AApache 1.1 and later.<p>
1N/A
1N/ACheck the cache every &lt;time&gt; hours, and delete files if the space
1N/Ausage is greater than that set by CacheSize.
1N/A
1N/A<A name="cachemaxexpire"><h2>CacheMaxExpire</h2></A>
1N/A<strong>Syntax:</strong> CacheMaxExpire <em>&lt;time&gt;</em><br>
1N/A<strong>Default:</strong> <code>CacheMaxExpire 24</code><br>
1N/A<strong>Context:</strong> server config<br>
1N/A<strong>Status:</strong> Base<br>
1N/A<strong>Module:</strong> mod_proxy<br>
1N/A<strong>Compatibility:</strong> CacheMaxExpire is only available in
1N/AApache 1.1 and later.<p>
1N/A
1N/ACachable HTTP documents will be retained for at most &lt;time&gt; hours without
1N/Achecking the origin server. Thus documents can be at most &lt;time&gt;
1N/Ahours out of date. This restriction is enforced even if an expiry date
1N/Awas supplied with the document.
1N/A
1N/A<A name="cachelastmodifiedfactor"><h2>CacheLastModifiedFactor</h2></A>
1N/A<strong>Syntax:</strong> CacheLastModifiedFactor <em>&lt;factor&gt;</em><br>
1N/A<strong>Default:</strong> <code>CacheLastModifiedFactor 0.1</code><br>
1N/A<strong>Context:</strong> server config<br>
1N/A<strong>Status:</strong> Base<br>
1N/A<strong>Module:</strong> mod_proxy<br>
1N/A<strong>Compatibility:</strong> CacheLastModifiedFactor is only available in
1N/AApache 1.1 and later.<p>
1N/A
1N/AIf the origin HTTP server did not supply an expiry date for the
1N/Adocument, then estimate one using the formula
1N/A<pre>
1N/A  expiry-period = time-since-last-modification * &lt;factor&gt;
1N/A</pre>
1N/AFor example, if the document was last modified 10 hours ago, and
1N/A&lt;factor&gt; is 0.1, then the expiry period will be set to 10*0.1 = 1 hour.
1N/A
1N/A<p>If the expiry-period would be longer than that set by CacheMaxExpire,
1N/Athen the latter takes precedence.
1N/A
1N/A<A name="cachedirlevels"><h2>CacheDirLevels</h2></A>
1N/A<strong>Syntax:</strong> CacheDirLevels <em>&lt;levels&gt;</em><br>
1N/A<strong>Default:</strong> <code>CacheDirLevels 3</code><br>
1N/A<strong>Context:</strong> server config<br>
1N/A<strong>Status:</strong> Base<br>
1N/A<strong>Module:</strong> mod_proxy<br>
1N/A<strong>Compatibility:</strong> CacheDirLevels is only available in
1N/AApache 1.1 and later.<p>
1N/A
1N/ACacheDirLevels sets the number of levels of subdirectories in the cache.
1N/ACached data will be saved this many directory levels below CacheRoot.
1N/A
1N/A<A name="cachedirlength"><h2>CacheDirLength</h2></A>
1N/A<strong>Syntax:</strong> CacheDirLength <em>&lt;length&gt;</em><br>
1N/A<strong>Default:</strong> <code>CacheDirLength 1</code><br>
1N/A<strong>Context:</strong> server config<br>
1N/A<strong>Status:</strong> Base<br>
1N/A<strong>Module:</strong> mod_proxy<br>
1N/A<strong>Compatibility:</strong> CacheDirLength is only available in
1N/AApache 1.1 and later.<p>
1N/A
1N/ACacheDirLength sets the number of characters in proxy cache subdirectory names.
1N/A
1N/A<A name="cachedefaultexpire"><h2>CacheDefaultExpire</h2></A>
1N/A<strong>Syntax:</strong> CacheDefaultExpire <em>&lt;time&gt;</em><br>
1N/A<strong>Default:</strong> <code>CacheDefaultExpire 1</code><br>
1N/A<strong>Context:</strong> server config<br>
1N/A<strong>Status:</strong> Base<br>
1N/A<strong>Module:</strong> mod_proxy<br>
1N/A<strong>Compatibility:</strong> CacheDefaultExpire is only available in
1N/AApache 1.1 and later.<p>
1N/A
1N/AIf the document is fetched via a protocol that does not support expiry times,
1N/Athen use &lt;time&gt; hours as the expiry time.
1N/A<a href="#cachemaxexpire">CacheMaxExpire</a> does <strong>not</strong>
1N/Aoverride.
1N/A
1N/A<A name="nocache"><h2>NoCache</h2></A>
1N/A<strong>Syntax:</strong> NoCache <em>&lt;word/host/domain list&gt;</em><br>
1N/A<strong>Context:</strong> server config<br>
1N/A<strong>Status:</strong> Base<br>
1N/A<strong>Module:</strong> mod_proxy<br>
1N/A<strong>Compatibility:</strong> NoCache is only available in
1N/AApache 1.1 and later.<p>
1N/A
1N/AThe NoCache directive specifies a list of words, hosts and/or domains, separated
1N/Aby spaces. HTTP and non-passworded FTP documents from matched words, hosts or
1N/Adomains are <em>not</em> cached by the proxy server. The proxy module will
1N/Aalso attempt to determine IP addresses of list items which may be hostnames
1N/Aduring startup, and cache them for match test as well. Example:
1N/A
1N/A<pre>
1N/A  NoCache joes_garage.com some_host.co.uk bullwinkle.wotsamattau.edu
1N/A</pre>
1N/A
1N/A'bullwinkle.wotsamattau.edu' would also be matched if referenced by IP
1N/Aaddress.<p>
1N/A
1N/ANote that 'wotsamattau' would also be sufficient to match 'wotsamattau.edu'.<p>
1N/A
1N/ANote also that
1N/A
1N/A<pre>
1N/ANoCache *
1N/A</pre>
1N/A
1N/Adisables caching completely.<p>
1N/A
1N/A<hr>
1N/A
1N/A<a name="configs"><h2>Common configuration topics</h2></a>
1N/A
1N/A<ul>
1N/A<li><a href="#access">Controlling access to your proxy</a>
1N/A<li><a href="#shortname">Using Netscape hostname shortcuts</a>
1N/A<li><a href="#mimetypes">Why doesn't file type <i>xxx</i> download via FTP?</a>
1N/A<li><a href="#startup">Why does Apache start more slowly when using the
1N/A    proxy module?</a>
1N/A<li><a href="#socks">Can I use the Apache proxy module with my SOCKS proxy?</a>
1N/A</ul>
1N/A
1N/A<h2><a name="access">Controlling access to your proxy</a></h2>
1N/A
1N/AYou can control who can access your proxy via the normal &lt;Directory&gt;
1N/Acontrol block using the following example:<p>
1N/A
1N/A<pre>
1N/A&lt;Directory proxy:*&gt;
1N/A&lt;Limit GET&gt;
1N/Aorder deny,allow
1N/Adeny from [machines you'd like *not* to allow by IP address or name]
1N/Aallow from [machines you'd like to allow by IP address or name]
1N/A&lt;/Limit&gt;
1N/A&lt;/Directory&gt;
1N/A</pre><p>
1N/A
1N/A<h2><a name="shortname">Using Netscape hostname shortcuts</a></h2>
1N/A
1N/AThere is an optional patch to the proxy module to allow Netscape-like
1N/Ahostname shortcuts to be used. It's available
1N/A<a href="http://www.apache.org/dist/contrib/patches/1.2/netscapehost.patch">
1N/Ahere</a>.<p>
1N/A
1N/A<h2><a name="mimetypes">Why doesn't file type <i>xxx</i> download via FTP?</a></h2>
1N/A
1N/AYou probably don't have that particular file type defined as
1N/A<i>application/octet-stream</i> in your proxy's mime.types configuration
1N/Afile. A useful line can be<p>
1N/A
1N/A<pre>
1N/Aapplication/octet-stream        bin dms lha lzh exe class tgz taz
1N/A</pre>
1N/A
1N/A<h2><a name="startup">Why does Apache start more slowly when using the
1N/A    proxy module?</a></h2>
1N/A
1N/AIf you're using the <code>ProxyBlock</code> or <code>NoCache</code>
1N/Adirectives, hostnames' IP addresses are looked up and cached during
1N/Astartup for later match test. This may take a few seconds (or more)
1N/Adepending on the speed with which the hostname lookups occur.<p>
1N/A
1N/A<h2><a name="socks">Can I use the Apache proxy module with my SOCKS proxy?</a></h2>
1N/A
1N/AYes. Just build Apache with the rule <code>SOCKS4=yes</code> in your
1N/A<i>Configuration</i> file, and follow the instructions there. SOCKS5
1N/Acapability can be added in a similar way (there's no <code>SOCKS5</code>
1N/Arule yet), so use the <code>EXTRA_LFLAGS</code> definition, or build Apache
1N/Anormally and run it with the <i>runsocks</i> wrapper provided with SOCKS5,
1N/Aif your OS supports dynamically linked libraries.<p>
1N/A
1N/ASome users have reported problems when using SOCKS version 4.2 on Solaris.
1N/AThe problem was solved by upgrading to SOCKS 4.3.<p>
1N/A
1N/ARemember that you'll also have to grant access to your Apache proxy machine by
1N/Apermitting connections on the appropriate ports in your SOCKS daemon's
1N/Aconfiguration.<p>
1N/A
1N/A<!--#include virtual="footer.html" -->
1N/A</BODY>
1N/A</HTML>
1N/A
1N/A