| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| <HTML> |
| <HEAD> |
| <TITLE>Apache module mod_proxy</TITLE> |
| </HEAD> |
| |
| <!-- Background white, links blue (unvisited), navy (visited), red (active) --> |
| <BODY |
| BGCOLOR="#FFFFFF" |
| TEXT="#000000" |
| LINK="#0000FF" |
| VLINK="#000080" |
| ALINK="#FF0000" |
| > |
| <!--#include virtual="header.html" --> |
| <H1 ALIGN="CENTER">Module mod_proxy</H1> |
| |
| This module is contained in the <code>mod_proxy.c</code> file for Apache 1.1.x, |
| or the <code>modules/proxy</code> subdirectory for Apache 1.2, and |
| is not compiled in by default. It provides for an <b>HTTP 1.0</b> caching proxy |
| server. It is only available in Apache 1.1 and later. Common configuration |
| questions are addressed <a href="#configs">here</a>. |
| |
| <h3>Note:</h3> |
| <p>This module was experimental in Apache 1.1.x. As of Apache 1.2, mod_proxy |
| stability is <i>greatly</i> improved.<p> |
| |
| <h2>Summary</h2> |
| |
| This module implements a proxy/cache for Apache. It implements |
| proxying capability for |
| <code>FTP</code>, |
| <code>CONNECT</code> (for SSL), |
| <code>HTTP/0.9</code>, and |
| <code>HTTP/1.0</code>. |
| The module can be configured to connect to other proxy modules for these |
| and other protocols. |
| |
| <h2>Directives</h2> |
| <ul> |
| <li><a href="#proxyrequests">ProxyRequests</a> |
| <li><a href="#proxyremote">ProxyRemote</a> |
| <li><a href="#proxypass">ProxyPass</a> |
| <li><a href="#proxyblock">ProxyBlock</a> |
| <li><a href="#cacheroot">CacheRoot</a> |
| <li><a href="#cachesize">CacheSize</a> |
| <li><a href="#cachemaxexpire">CacheMaxExpire</a> |
| <li><a href="#cachedefaultexpire">CacheDefaultExpire</a> |
| <li><a href="#cachelastmodifiedfactor">CacheLastModifiedFactor</a> |
| <li><a href="#cachegcinterval">CacheGcInterval</a> |
| <li><a href="#cachedirlevels">CacheDirLevels</a> |
| <li><a href="#cachedirlength">CacheDirLength</a> |
| <li><a href="#nocache">NoCache</a> |
| </ul> |
| |
| <hr> |
| |
| <A name="proxyrequests"><h2>ProxyRequests</h2></A> |
| <strong>Syntax:</strong> ProxyRequests <em>on/off</em><br> |
| <strong>Default:</strong> <code>ProxyRequests Off</code><br> |
| <strong>Context:</strong> server config, virtual host<br> |
| <strong>Status:</strong> Base<br> |
| <strong>Module:</strong> mod_proxy<br> |
| <strong>Compatibility:</strong> ProxyRequest is only available in |
| Apache 1.1 and later.<p> |
| |
| This allows or prevents Apache from functioning as a proxy |
| server. Setting ProxyRequests to 'off' does not disable use of the <a |
| href="#proxypass">ProxyPass</a> directive. |
| |
| <A name="proxyremote"><h2>ProxyRemote</h2></A> |
| <strong>Syntax:</strong> ProxyRemote <em><match> <remote-server></em><br> |
| <strong>Context:</strong> server config, virtual host<br> |
| <strong>Status:</strong> Base<br> |
| <strong>Module:</strong> mod_proxy<br> |
| <strong>Compatibility:</strong> ProxyRemote is only available in |
| Apache 1.1 and later.<p> |
| |
| This defines remote proxies to this proxy. <match> 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 '*' to indicate the |
| server should be contacted for all requests. <remote-server> is a |
| partial URL for the remote server. Syntax: |
| |
| <pre> |
| <remote-server> = <protocol>://<hostname>[:port] |
| </pre> |
| |
| <protocol> is the protocol that should be used to communicate |
| with the remote server; only "http" is supported by this module. |
| |
| Example: |
| <pre> |
| ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000 |
| ProxyRemote * http://cleversite.com |
| ProxyRemote ftp http://ftpproxy.mydomain.com:8080 |
| </pre> |
| |
| In the last example, the proxy will forward FTP requests, encapsulated |
| as yet another HTTP proxy request, to another proxy which can handle |
| them. |
| |
| <A name="proxypass"><h2>ProxyPass</h2></A> |
| <strong>Syntax:</strong> ProxyPass <em><path> <url></em><br> |
| <strong>Context:</strong> server config, virtual host<br> |
| <strong>Status:</strong> Base<br> |
| <strong>Module:</strong> mod_proxy<br> |
| <strong>Compatibility:</strong> ProxyPass is only available in |
| Apache 1.1 and later.<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. <path> is the name of |
| a local virtual path; <url> is a partial URL for the remote server. |
| |
| Suppose the local server has address http://wibble.org; then |
| <pre> |
| ProxyPass /mirror/foo http://foo.com |
| </pre> |
| Will cause a local request for the http://wibble.org/mirror/foo/bar to be |
| internally converted into a proxy request to http://foo.com/bar |
| |
| <A name="proxyblock"><h2>ProxyBlock</h2></A> |
| <strong>Syntax:</strong> ProxyBlock <em><word/host/domain list></em><br> |
| <strong>Context:</strong> server config, virtual host<br> |
| <strong>Status:</strong> Base<br> |
| <strong>Module:</strong> mod_proxy<br> |
| <strong>Compatibility:</strong> ProxyBlock is only available in |
| Apache 1.2 and later.<p> |
| |
| The ProxyBlock directive specifies a list of words, hosts and/or domains, |
| separated by spaces. HTTP, HTTPS, and FTP document requests to 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. Example: |
| |
| <pre> |
| ProxyBlock joes_garage.com some_host.co.uk rocky.wotsamattau.edu |
| </pre> |
| |
| 'rocky.wotsamattau.edu' would also be matched if referenced by IP address.<p> |
| |
| Note that 'wotsamattau' would also be sufficient to match 'wotsamattau.edu'.<p> |
| |
| Note also that |
| |
| <pre> |
| ProxyBlock * |
| </pre> |
| |
| blocks connections to all sites. |
| |
| <A name="cacheroot"><h2>CacheRoot</h2></A> |
| <strong>Syntax:</strong> CacheRoot <em><directory></em><br> |
| <strong>Context:</strong> server config, virtual host<br> |
| <strong>Status:</strong> Base<br> |
| <strong>Module:</strong> mod_proxy<br> |
| <strong>Compatibility:</strong> CacheRoot is only available in |
| Apache 1.1 and later.<p> |
| |
| Sets the name of the directory to contain cache files; this must be |
| writable |
| by the httpd server. |
| |
| <A name="cachesize"><h2>CacheSize</h2></A> |
| <strong>Syntax:</strong> CacheSize <em><size></em><br> |
| <strong>Default:</strong> <code>CacheSize 5</code><br> |
| <strong>Context:</strong> server config, virtual host<br> |
| <strong>Status:</strong> Base<br> |
| <strong>Module:</strong> mod_proxy<br> |
| <strong>Compatibility:</strong> CacheSize is only available in |
| Apache 1.1 and later.<p> |
| |
| Sets the desired space usage of the cache, in Kb (1024 byte units). Although |
| usage may grow above this setting, the garbage collection will delete files |
| until the usage is at or below this setting. |
| |
| <A name="cachegcinterval"><h2>CacheGcInterval</h2></A> |
| <strong>Syntax:</strong> CacheGcInterval <em><time></em><br> |
| <strong>Context:</strong> server config, virtual host<br> |
| <strong>Status:</strong> Base<br> |
| <strong>Module:</strong> mod_proxy<br> |
| <strong>Compatibility:</strong> CacheGcinterval is only available in |
| Apache 1.1 and later.<p> |
| |
| Check the cache every <time> hours, and delete files if the space |
| usage is greater than that set by CacheSize. |
| |
| <A name="cachemaxexpire"><h2>CacheMaxExpire</h2></A> |
| <strong>Syntax:</strong> CacheMaxExpire <em><time></em><br> |
| <strong>Default:</strong> <code>CacheMaxExpire 24</code><br> |
| <strong>Context:</strong> server config, virtual host<br> |
| <strong>Status:</strong> Base<br> |
| <strong>Module:</strong> mod_proxy<br> |
| <strong>Compatibility:</strong> CacheMaxExpire is only available in |
| Apache 1.1 and later.<p> |
| |
| Cachable HTTP documents will be retained for at most <time> hours without |
| checking the origin server. Thus documents can be at most <time> |
| hours out of date. This restriction is enforced even if an expiry date |
| was supplied with the document. |
| |
| <A name="cachelastmodifiedfactor"><h2>CacheLastModifiedFactor</h2></A> |
| <strong>Syntax:</strong> CacheLastModifiedFactor <em><factor></em><br> |
| <strong>Default:</strong> <code>CacheLastModifiedFactor 0.1</code><br> |
| <strong>Context:</strong> server config, virtual host<br> |
| <strong>Status:</strong> Base<br> |
| <strong>Module:</strong> mod_proxy<br> |
| <strong>Compatibility:</strong> CacheLastModifiedFactor is only available in |
| Apache 1.1 and later.<p> |
| |
| If the origin HTTP server did not supply an expiry date for the |
| document, then estimate one using the formula |
| <pre> |
| expiry-period = time-since-last-modification * <factor> |
| </pre> |
| For example, if the document was last modified 10 hours ago, and |
| <factor> is 0.1, then the expiry period will be set to 10*0.1 = 1 hour. |
| |
| <p>If the expiry-period would be longer than that set by CacheMaxExpire, |
| then the latter takes precedence. |
| |
| <A name="cachedirlevels"><h2>CacheDirLevels</h2></A> |
| <strong>Syntax:</strong> CacheDirLevels <em><levels></em><br> |
| <strong>Default:</strong> <code>CacheDirLevels 3</code><br> |
| <strong>Context:</strong> server config, virtual host<br> |
| <strong>Status:</strong> Base<br> |
| <strong>Module:</strong> mod_proxy<br> |
| <strong>Compatibility:</strong> CacheDirLevels is only available in |
| Apache 1.1 and later.<p> |
| |
| CacheDirLevels sets the number of levels of subdirectories in the cache. |
| Cached data will be saved this many directory levels below CacheRoot. |
| |
| <A name="cachedirlength"><h2>CacheDirLength</h2></A> |
| <strong>Syntax:</strong> CacheDirLength <em><length></em><br> |
| <strong>Default:</strong> <code>CacheDirLength 1</code><br> |
| <strong>Context:</strong> server config, virtual host<br> |
| <strong>Status:</strong> Base<br> |
| <strong>Module:</strong> mod_proxy<br> |
| <strong>Compatibility:</strong> CacheDirLength is only available in |
| Apache 1.1 and later.<p> |
| |
| CacheDirLength sets the number of characters in proxy cache subdirectory names. |
| |
| <A name="cachedefaultexpire"><h2>CacheDefaultExpire</h2></A> |
| <strong>Syntax:</strong> CacheDefaultExpire <em><time></em><br> |
| <strong>Default:</strong> <code>CacheDefaultExpire 1</code><br> |
| <strong>Context:</strong> server config, virtual host<br> |
| <strong>Status:</strong> Base<br> |
| <strong>Module:</strong> mod_proxy<br> |
| <strong>Compatibility:</strong> CacheDefaultExpire is only available in |
| Apache 1.1 and later.<p> |
| |
| If the document is fetched via a protocol that does not support expiry times, |
| then use <time> hours as the expiry time. |
| <a href="#cachemaxexpire">CacheMaxExpire</a> does <strong>not</strong> |
| override. |
| |
| <A name="nocache"><h2>NoCache</h2></A> |
| <strong>Syntax:</strong> NoCache <em><word/host/domain list></em><br> |
| <strong>Context:</strong> server config, virtual host<br> |
| <strong>Status:</strong> Base<br> |
| <strong>Module:</strong> mod_proxy<br> |
| <strong>Compatibility:</strong> NoCache is only available in |
| Apache 1.1 and later.<p> |
| |
| The NoCache directive specifies a list of words, hosts and/or domains, separated |
| by spaces. HTTP and non-passworded FTP documents from matched words, hosts or |
| domains are <em>not</em> cached 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. Example: |
| |
| <pre> |
| NoCache joes_garage.com some_host.co.uk bullwinkle.wotsamattau.edu |
| </pre> |
| |
| 'bullwinkle.wotsamattau.edu' would also be matched if referenced by IP |
| address.<p> |
| |
| Note that 'wotsamattau' would also be sufficient to match 'wotsamattau.edu'.<p> |
| |
| Note also that |
| |
| <pre> |
| NoCache * |
| </pre> |
| |
| disables caching completely.<p> |
| |
| <hr> |
| |
| <a name="configs"><h2>Common configuration topics</h2></a> |
| |
| <ul> |
| <li><a href="#access">Controlling access to your proxy</a> |
| <li><a href="#shortname">Using Netscape hostname shortcuts</a> |
| <li><a href="#mimetypes">Why doesn't file type <i>xxx</i> download via FTP?</a> |
| <li><a href="#startup">Why does Apache start more slowly when using the |
| proxy module?</a> |
| <li><a href="#socks">Can I use the Apache proxy module with my SOCKS proxy?</a> |
| </ul> |
| |
| <h2><a name="access">Controlling access to your proxy</a></h2> |
| |
| You can control who can access your proxy via the normal <Directory> |
| control block using the following example:<p> |
| |
| <pre> |
| <Directory proxy:*> |
| <Limit GET PUT POST DELETE CONNECT OPTIONS> |
| order deny,allow |
| deny from [machines you'd like *not* to allow by IP address or name] |
| allow from [machines you'd like to allow by IP address or name] |
| </Limit> |
| </Directory> |
| </pre><p> |
| |
| A <Files> block will also work, and is the only method known to work |
| for all possible URLs in Apache versions earlier than 1.2b10.<p> |
| |
| <h2><a name="shortname">Using Netscape hostname shortcuts</a></h2> |
| |
| There is an optional patch to the proxy module to allow Netscape-like |
| hostname shortcuts to be used. It's available |
| <a href="http://www.apache.org/dist/contrib/patches/1.2/netscapehost.patch"> |
| here</a>.<p> |
| |
| <h2><a name="mimetypes">Why doesn't file type <i>xxx</i> download via FTP?</a></h2> |
| |
| You probably don't have that particular file type defined as |
| <i>application/octet-stream</i> in your proxy's mime.types configuration |
| file. A useful line can be<p> |
| |
| <pre> |
| application/octet-stream bin dms lha lzh exe class tgz taz |
| </pre> |
| |
| <h2><a name="startup">Why does Apache start more slowly when using the |
| proxy module?</a></h2> |
| |
| If you're using the <code>ProxyBlock</code> or <code>NoCache</code> |
| directives, 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> |
| |
| <h2><a name="socks">Can I use the Apache proxy module with my SOCKS proxy?</a></h2> |
| |
| Yes. Just build Apache with the rule <code>SOCKS4=yes</code> in your |
| <i>Configuration</i> file, and follow the instructions there. SOCKS5 |
| capability can be added in a similar way (there's no <code>SOCKS5</code> |
| rule yet), so use the <code>EXTRA_LFLAGS</code> definition, or build Apache |
| normally and run it with the <i>runsocks</i> wrapper provided with SOCKS5, |
| if your OS supports dynamically linked libraries.<p> |
| |
| Some users have reported problems when using SOCKS version 4.2 on Solaris. |
| The problem was solved by upgrading to SOCKS 4.3.<p> |
| |
| Remember that you'll also have to grant access to your Apache proxy machine by |
| permitting connections on the appropriate ports in your SOCKS daemon's |
| configuration.<p> |
| |
| <!--#include virtual="footer.html" --> |
| </BODY> |
| </HTML> |
| |