From dc1817cb14a6736075a5dbd8a69ce73b454f82fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Malo?= Date: Mon, 5 May 2003 23:27:56 +0000 Subject: [PATCH] general mod_proxy docs cleanup: - add documentation for ProxyIOBufferSize (review desired) - fix context lists of ProxyPass and ProxyPassReverse - add more notes about the accompanying modules (_http, _ftp, _connect) - markup & reformatting (sorry for the big diff) -> update transformation git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@99725 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/mod_proxy.html.en | 1149 +++++++++--------- docs/manual/mod/mod_proxy.xml | 1262 ++++++++++---------- docs/manual/mod/quickreference.html.de | 49 +- docs/manual/mod/quickreference.html.en | 49 +- docs/manual/mod/quickreference.html.ja.jis | 49 +- 5 files changed, 1305 insertions(+), 1253 deletions(-) diff --git a/docs/manual/mod/mod_proxy.html.en b/docs/manual/mod/mod_proxy.html.en index dbac5cf62f..e0152cb4fb 100644 --- a/docs/manual/mod/mod_proxy.html.en +++ b/docs/manual/mod/mod_proxy.html.en @@ -29,44 +29,40 @@ Source File:mod_proxy.c

Summary

-

Warning

-This document has been updated to take into account changes -made in the 2.0 version of the Apache HTTP Server. Some of the -information may still be inaccurate, please use it -with care. -
+

Warning

+

Do not enable proxying with ProxyRequests until you have secured your server. Open proxy servers are dangerous both to your + network and to the Internet at large.

+
-

This module implements a proxy/gateway for Apache. It implements -proxying capability for -FTP, -CONNECT (for SSL), -HTTP/0.9, -HTTP/1.0, and -HTTP/1.1. -The module can be configured to connect to other proxy modules for these -and other protocols.

+

This module implements a proxy/gateway for Apache. It implements + proxying capability for FTP, CONNECT (for SSL), + HTTP/0.9, HTTP/1.0, and HTTP/1.1. + The module can be configured to connect to other proxy modules for these + and other protocols.

-

This module was experimental in Apache 1.1.x. Improvements and bugfixes -were made in Apache v1.2.x and Apache v1.3.x, then the module underwent a major -overhaul for Apache v2.0. The protocol support was upgraded to HTTP/1.1, -and filter support was enabled.

+

This module was experimental in Apache 1.1.x. Improvements and bugfixes + were made in Apache v1.2.x and Apache v1.3.x, then the module underwent a + major overhaul for Apache v2.0. The protocol support was upgraded to + HTTP/1.1, and filter support was enabled.

-

Please note that the caching function present in -mod_proxy up to Apache v1.3.x has been removed from -mod_proxy and will be incorporated into a new module, mod_cache. In other words: -the Apache 2.0.x-Proxy doesn't -cache at all - all caching functionality has been moved into mod_cache, -which is capable of caching any content, not only content from proxy. -

- -

If you need to use SSL when contacting remote servers, have a look at the -SSLProxy* directives in mod_ssl.

- -

Do not enable proxying with ProxyRequests until you have -secured your server. Open proxy servers are -dangerous both to your network and to the Internet at large.

+

During the overhaul process the mod_proxy has been + splitted into several module files. The accompanying modules distributed + with the httpd are mod_proxy_http, + mod_proxy_ftp and mod_proxy_connect. + Thus if you want to use one or more of the particular proxy functions you + have to load mod_proxy and the appropriate + module(s) into the server (either statically or dynamically via the + LoadModule directive).

+

Please note that the caching function present in mod_proxy up to Apache v1.3.x has been removed + from mod_proxy and will be incorporated into a new module, + mod_cache. In other words: the Apache 2.0.x-Proxy doesn't + cache at all - all caching functionality has been moved into + mod_cache, which is capable of caching any content, not + only content from proxy.

+

If you need to use SSL when contacting remote servers, have a look at the + SSLProxy* directives in mod_ssl.

Directives

Topics

See also

+
top

Common configuration topics

+ - +

A forward proxy is an intermediate system that enables a + browser to connect to a remote network to which it normally does not have + access. A forward proxy can also be used to cache data, reducing load on + the networks between the forward proxy and the remote webserver.

-

Forward and Reverse Proxies

+

Apache's mod_proxy can be figured to behave like a + forward proxy using the ProxyRemote directive. In addition, caching of data can be + achieved by configuring mod_cache. Other dedicated + forward proxy packages include Squid.

-

Apache can be configured in both a forward and reverse -proxy configuration.

+

A reverse proxy is a webserver system that is capable of + serving webpages sourced from other webservers - in addition to webpages + on disk or generated dynamically by CGI - making these pages look like + they originated at the reverse proxy.

-

A forward proxy is an intermediate system that enables a browser to connect to a -remote network to which it normally does not have access. A forward proxy -can also be used to cache data, reducing load on the networks between the -forward proxy and the remote webserver.

+

When configured with the mod_cache module the reverse proxy can act as + a cache for slower backend webservers. The reverse proxy can also enable + advanced URL strategies and management techniques, allowing webpages + served using different webserver systems or architectures to coexist + inside the same URL space. Reverse proxy systems are also ideal for + implementing centralised logging websites with many or diverse website + backends. Complex multi-tier webserver systems can be constructed using an + mod_proxy frontend and any number of backend + webservers.

-

Apache's mod_proxy can be figured to behave like a forward proxy -using the ProxyRemote -directive. In addition, caching of data can be achieved by configuring -Apache mod_cache. Other dedicated forward proxy -packages include Squid.

+

The reverse proxy is configured using the ProxyPass and ProxyPassReverse directives. Caching can be + enabled using mod_cache as with the forward proxy.

+ -

A reverse proxy is a webserver system that is capable of serving webpages -sourced from other webservers - in addition to webpages on disk or generated -dynamically by CGI - making these pages look like they originated at the -reverse proxy.

+

Controlling access to your proxy

+

You can control who can access your proxy via the <Proxy> control block using + the following example:

-

When configured with the mod_cache module the reverse -proxy can act as a cache for slower backend webservers. The reverse proxy -can also enable advanced URL strategies and management techniques, allowing -webpages served using different webserver systems or architectures to -coexist inside the same URL space. Reverse proxy systems are also ideal for -implementing centralised logging websites with many or diverse website -backends. Complex multi-tier webserver systems can be constructed using an -Apache mod_proxy frontend and any number of backend webservers.

+

+ <Proxy *>
+ + Order Deny,Allow
+ Deny from all
+ Allow from 192.168.0
+ + </Proxy> +

-

The reverse proxy is configured using the -ProxyPass and ProxyPassReverse directives. Caching can be -enabled using mod_cache as with the forward proxy.

+

When configuring a reverse proxy, access control takes on the + attributes of the normal server <Directory> configuration.

+ +

Why doesn't file type xxx + download via FTP?

+

You probably don't have that particular file type defined as + application/octet-stream in your proxy's mime.types + configuration file. A useful line can be

+ 
application/octet-stream   bin dms lha lzh exe class tgz taz
+ -

Controlling access to your proxy

+

How can I force an FTP ASCII download of + File xxx?

+

In the rare situation where you must download a specific file using the + FTP ASCII transfer method (while the default transfer is in + binary mode), you can override mod_proxy's + default by suffixing the request with ;type=a to force an + ASCII transfer. (FTP Directory listings are always executed in ASCII mode, + however.)

+ -

You can control who can access your proxy via the -<Proxy> -control block using the following example:

+

How can I access FTP files outside + of my home directory?

+

An FTP URI is interpreted relative to the home directory of the user + who is logging in. Alas, to reach higher directory levels you cannot + use /../, as the dots are interpreted by the browser and not actually + sent to the FTP server. To address this problem, the so called Squid + %2f hack was implemented in the Apache FTP proxy; it is a + solution which is also used by other popular proxy servers like the Squid Proxy Cache. By + prepending /%2f to the path of your request, you can make + such a proxy change the FTP starting directory to / (instead + of the home directory). For example, to retrieve the file + /etc/motd, you would use the URL:

-

-<Proxy *>
-Order Deny,Allow
-Deny from all
-Allow from 192.168.0
-</Proxy> -

+

+ ftp://user@host/%2f/etc/motd +

+ -

When configuring a reverse proxy, access control takes on the -attributes of the normal server <directory> configuration.

+

How can I hide the FTP cleartext password + in my browser's URL line?

+

To log in to an FTP server by username and password, Apache uses + different strategies. In absense of a user name and password in the URL + altogether, Apache sends an anomymous login to the FTP server, + i.e.,

+

+ user: anonymous
+ password: apache_proxy@ +

-

Why doesn't file type xxx -download via FTP?

+

This works for all popular FTP servers which are configured for + anonymous access.

-

You probably don't have that particular file type defined as -application/octet-stream in your proxy's mime.types configuration -file. A useful line can be

+

For a personal login with a specific username, you can embed the user + name into the URL, like in:

-

-application/octet-stream bin dms lha lzh exe class tgz taz -

+

+ ftp://username@host/myfile +

+

If the FTP server asks for a password when given this username (which + it should), then Apache will reply with a 401 (Authorization + required) response, which causes the Browser to pop up the + username/password dialog. Upon entering the password, the connection + attempt is retried, and if successful, the requested resource is + presented. The advantage of this procedure is that your browser does not + display the password in cleartext (which it would if you had used

-

How can I force an FTP ASCII download of -File xxx?

+

+ ftp://username:password@host/myfile +

-

In the rare situation where you must download a specific file using the FTP -ASCII transfer method (while the default transfer is in -binary mode), you can override mod_proxy's default by -suffixing the request with ;type=a to force an ASCII transfer. -(FTP Directory listings are always executed in ASCII mode, however.)

+

in the first place).

+

Note

+

The password which is transmitted in such a way is not encrypted on + its way. It travels between your browser and the Apache proxy server in + a base64-encoded cleartext string, and between the Apache proxy and the + FTP server as plaintext. You should therefore think twice before + accessing your FTP server via HTTP (or before accessing your personal + files via FTP at all!) When using unsecure channels, an eavesdropper + might intercept your password on its way.

+
+ -

How can I access FTP files outside -of my home directory?

+

Why does Apache start more slowly when using + the proxy module?

+

If you're using the ProxyBlock directive, hostnames' IP addresses are looked up + and cached during startup for later match test. This may take a few + seconds (or more) depending on the speed with which the hostname lookups + occur.

+ -

-An FTP URI is interpreted relative to the home directory of the user -who is logging in. Alas, to reach higher directory levels you cannot -use /../, as the dots are interpreted by the browser and not actually -sent to the FTP server. To address this problem, the so called "Squid -%2f hack" was implemented in the Apache FTP proxy; it is is a solution -which is also used by other popular proxy servers like the Squid Proxy Cache. By -prepending /%2f to the path of your request, you can make such a proxy -change the FTP starting directory to / (instead of the home -directory).

+

What other functions are useful for an + intranet proxy server?

+

An Apache proxy server situated in an intranet needs to forward + external requests through the company's firewall. However, when it has to + access resources within the intranet, it can bypass the firewall when + accessing hosts. The NoProxy + directive is useful for specifying which hosts belong to the intranet and + should be accessed directly.

-

Example: To retrieve the file -/etc/motd, you would use the URL

-

ftp://user@host/%2f/etc/motd

- - -

How can I hide the FTP cleartext password -in my browser's URL line?

- -

-To log in to an FTP server by username and password, Apache -uses different strategies. -In absense of a user name and password in the URL altogether, -Apache sends an anomymous login to the FTP server, i.e.,

-

-user: anonymous
-password: apache_proxy@ -

-

This works for all popular FTP servers which are configured for -anonymous access.

- -

For a personal login with a specific username, you can embed -the user name into the URL, like in: -ftp://username@host/myfile. If the FTP server -asks for a password when given this username (which it should), -then Apache will reply with a [401 Authorization required] response, -which causes the Browser to pop up the username/password dialog. -Upon entering the password, the connection attempt is retried, -and if successful, the requested resource is presented. -The advantage of this procedure is that your browser does not -display the password in cleartext (which it would if you had used -ftp://username:password@host/myfile in -the first place).

- -

Note

-The password which is transmitted in such a way -is not encrypted on its way. It travels between your browser and -the Apache proxy server in a base64-encoded cleartext string, and -between the Apache proxy and the FTP server as plaintext. You should -therefore think twice before accessing your FTP server via HTTP -(or before accessing your personal files via FTP at all!) When -using unsecure channels, an eavesdropper might intercept your -password on its way. -
- - -

Why does Apache start more slowly when -using the proxy module?

- -

If you're using the ProxyBlock -directive, hostnames' IP addresses are looked up and cached during -startup for later match test. This may take a few seconds (or more) -depending on the speed with which the hostname lookups occur.

- - - - -

What other functions are useful for an -intranet proxy server?

- -

An Apache proxy server situated in an intranet needs to forward -external requests through the company's firewall. However, when it has -to access resources within the intranet, it can bypass the firewall -when accessing hosts. The NoProxy directive is useful for -specifying which hosts belong to the intranet and should be accessed -directly.

- -

Users within an intranet tend to omit the local domain name from their -WWW requests, thus requesting "http://somehost/" instead of -"http://somehost.my.dom.ain/". Some commercial proxy servers let them get -away with this and simply serve the request, implying a configured -local domain. When the ProxyDomain directive -is used and the server is configured for -proxy service, Apache can return a redirect response and send the client -to the correct, fully qualified, server address. This is the preferred method -since the user's bookmark files will then contain fully qualified hosts.

- -

How can I make the proxy talk HTTP/1.0 and -disable keepalives?

- -

For circumstances where you have a application server which doesn't implement -keepalives or HTTP/1.1 properly, there are 2 environment variables which when -set send a HTTP/1.0 with no keepalive. These are set via the SetEnv directive.

-

These are the 'force-proxy-request-1.0' and 'proxy-nokeepalive' notes.

- -

-<location /buggyappserver/ >
-ProxyPass http://buggyappserver:7001/foo/
-SetEnv force-proxy-request-1.0 1
-SetEnv proxy-nokeepalive 1
-</location> -

+

Users within an intranet tend to omit the local domain name from their + WWW requests, thus requesting "http://somehost/" instead of + http://somehost.example.com/. Some commercial proxy servers + let them get away with this and simply serve the request, implying a + configured local domain. When the ProxyDomain directive is used and the server is configured for proxy service, Apache can return + a redirect response and send the client to the correct, fully qualified, + server address. This is the preferred method since the user's bookmark + files will then contain fully qualified hosts.

+ +

How can I make the proxy talk HTTP/1.0 and + disable keepalives?

+

For circumstances where you have a application server which doesn't + implement keepalives or HTTP/1.1 properly, there are 2 environment + variables which when set send a HTTP/1.0 with no keepalive. These are set + via the SetEnv directive.

+

These are the force-proxy-request-1.0 and + proxy-nokeepalive notes.

+

+ <Location /buggyappserver/>
+ + ProxyPass http://buggyappserver:7001/foo/
+ SetEnv force-proxy-request-1.0 1
+ SetEnv proxy-nokeepalive 1
+ + </Location> +

+
top

AllowCONNECT Directive

- - + +
Description:Ports that are allowed to CONNECT through -the proxy
Syntax:AllowCONNECT port [port] ...
Description:Ports that are allowed to CONNECT through the +proxy
Syntax:AllowCONNECT port [port] ...
Default:AllowCONNECT 443 563
Context:server config, virtual host
Status:Extension
Module:mod_proxy
-

The AllowCONNECT directive specifies a list -of port numbers to which the proxy CONNECT method may -connect. Today's browsers use this method when a https -connection is requested and proxy tunneling over http is in -effect.
By default, only the default https port (443) and the -default snews port (563) are enabled. Use the -AllowCONNECT directive to overrride this default and -allow connections to the listed ports only.

+

The AllowCONNECT directive specifies a list + of port numbers to which the proxy CONNECT method may + connect. Today's browsers use this method when a https + connection is requested and proxy tunneling over HTTP is in effect.

+ +

By default, only the default https port (443) and the + default snews port (563) are enabled. Use the + AllowCONNECT directive to override this default and + allow connections to the listed ports only.

+ +

Note that you'll need to have mod_proxy_connect present + in the server in order to get the support for the CONNECT at + all.

top

NoProxy Directive

- - + +
Description:Hosts, domains, or networks that will be connected -to directly
Syntax:NoProxy host [host] ...
Description:Hosts, domains, or networks that will be connected to +directly
Syntax:NoProxy host [host] ...
Context:server config, virtual host
Status:Extension
Module:mod_proxy
-

This directive is only useful for Apache proxy servers within -intranets. The NoProxy directive specifies a -list of subnets, IP addresses, hosts and/or domains, separated by -spaces. A request to a host which matches one or more of these is -always served directly, without forwarding to the configured -ProxyRemote proxy server(s).

+

This directive is only useful for Apache proxy servers within + intranets. The NoProxy directive specifies a + list of subnets, IP addresses, hosts and/or domains, separated by + spaces. A request to a host which matches one or more of these is + always served directly, without forwarding to the configured + ProxyRemote proxy server(s).

-

Example

- ProxyRemote * http://firewall.mycompany.com:81
- NoProxy .mycompany.com 192.168.112.0/21 -

+

Example

+ ProxyRemote * http://firewall.mycompany.com:81
+ NoProxy .mycompany.com 192.168.112.0/21 +

-

The host arguments to the NoProxy directive are one of the -following type list:

-
+

The host arguments to the NoProxy + directive are one of the following type list:

+ +
-
- Domain
-
A Domain is a partially qualified DNS domain name, preceded - by a period. - It represents a list of hosts which logically belong to the same DNS - domain or zone (i.e., the suffixes of the hostnames are all ending in - Domain).
- Examples: .com .apache.org.
- To distinguish Domains from Hostnames (both - syntactically and semantically; a DNS domain can have a DNS A record, - too!), Domains are always written - with a leading period.
- Note: Domain name comparisons are done without regard to the case, - and Domains are always assumed to be anchored in the root - of the DNS tree, therefore two domains .MyDomain.com and - .mydomain.com. (note the trailing period) are - considered equal. Since a domain comparison does not involve a DNS - lookup, it is much more efficient than subnet comparison.
+
Domain
+
+

A Domain is a partially qualified DNS domain name, preceded + by a period. It represents a list of hosts which logically belong to the + same DNS domain or zone (i.e., the suffixes of the hostnames are + all ending in Domain).

+ +

Examples

+ .com .apache.org. +

+ +

To distinguish Domains from Hostnames (both syntactically and semantically; a DNS domain can + have a DNS A record, too!), Domains are always written with a + leading period.

+ +

Note

+

Domain name comparisons are done without regard to the case, and + Domains are always assumed to be anchored in the root of the + DNS tree, therefore two domains .MyDomain.com and + .mydomain.com. (note the trailing period) are considered + equal. Since a domain comparison does not involve a DNS lookup, it is much + more efficient than subnet comparison.

+
-
- SubNet
-
A SubNet is a partially qualified internet address in - numeric (dotted quad) form, optionally followed by a slash and the - netmask, specified as the number of significant bits in the - SubNet. It is used to represent a subnet of hosts which can - be reached over a common network interface. In the absence of the - explicit net mask it is assumed that omitted (or zero valued) - trailing digits specify the mask. (In this case, the netmask can - only be multiples of 8 bits wide.)
- Examples: -
-
192.168 or 192.168.0.0
-
the subnet 192.168.0.0 with an implied netmask of 16 valid bits - (sometimes used in the netmask form 255.255.0.0)
-
192.168.112.0/21
-
the subnet 192.168.112.0/21 with a netmask of 21 - valid bits (also used in the form 255.255.248.0)
-
- As a degenerate case, a SubNet with 32 valid bits is the - equivalent to an IPAddr, while a SubNet with zero - valid bits (e.g., 0.0.0.0/0) is the same as the constant - _Default_, matching any IP address.
+
SubNet
+
+

A SubNet is a partially qualified internet address in + numeric (dotted quad) form, optionally followed by a slash and the netmask, + specified as the number of significant bits in the SubNet. It is + used to represent a subnet of hosts which can be reached over a common + network interface. In the absence of the explicit net mask it is assumed + that omitted (or zero valued) trailing digits specify the mask. (In this + case, the netmask can only be multiples of 8 bits wide.) Examples:

+ +
+
192.168 or 192.168.0.0
+
the subnet 192.168.0.0 with an implied netmask of 16 valid bits + (sometimes used in the netmask form 255.255.0.0)
+
192.168.112.0/21
+
the subnet 192.168.112.0/21 with a netmask of 21 + valid bits (also used in the form 255.255.248.0)
+
+ +

As a degenerate case, a SubNet with 32 valid bits is the + equivalent to an IPAddr, while a SubNet with zero + valid bits (e.g., 0.0.0.0/0) is the same as the constant + _Default_, matching any IP address.

-
- IPAddr
-
A IPAddr represents a fully qualified internet address in - numeric (dotted quad) form. Usually, this address represents a - host, but there need not necessarily be a DNS domain name - connected with the address.
- Example: 192.168.123.7
- Note: An IPAddr does not need to be resolved by the DNS - system, so it can result in more effective apache performance.
+
IPAddr
+
+

A IPAddr represents a fully qualified internet address in + numeric (dotted quad) form. Usually, this address represents a host, but + there need not necessarily be a DNS domain name connected with the + address.

+

Example

+ 192.168.123.7 +

+ +

Note

+

An IPAddr does not need to be resolved by the DNS system, so + it can result in more effective apache performance.

+
-
- Hostname
-
A Hostname is a fully qualified DNS domain name which can - be resolved to one or more IPAddrs via the DNS domain name service. - It represents a logical host (in contrast to - Domains, see - above) and must be resolvable to at least one IPAddr (or often to a list of hosts - with different IPAddr's).
- Examples: prep.ai.mit.edu - www.apache.org.
- Note: In many situations, it is more effective to specify an - IPAddr in place of a - Hostname since a DNS lookup - can be avoided. Name resolution in Apache can take a remarkable deal - of time when the connection to the name server uses a slow PPP - link.
- Note: Hostname comparisons are done without regard to the case, - and Hostnames are always assumed to be anchored in the root - of the DNS tree, therefore two hosts WWW.MyDomain.com - and www.mydomain.com. (note the trailing period) are - considered equal.
-
+
Hostname
+
+

A Hostname is a fully qualified DNS domain name which can + be resolved to one or more IPAddrs via the + DNS domain name service. It represents a logical host (in contrast to + Domains, see above) and must be resolvable + to at least one IPAddr (or often to a list + of hosts with different IPAddrs).

+ +

Examples

+ prep.ai.mit.edu
+ www.apache.org +

+ +

Note

+

In many situations, it is more effective to specify an IPAddr in place of a Hostname since a + DNS lookup can be avoided. Name resolution in Apache can take a remarkable + deal of time when the connection to the name server uses a slow PPP + link.

+

Hostname comparisons are done without regard to the case, + and Hostnames are always assumed to be anchored in the root + of the DNS tree, therefore two hosts WWW.MyDomain.com + and www.mydomain.com. (note the trailing period) are + considered equal.

+
+

See also

top
@@ -500,61 +529,60 @@ which forget to insert an empty line between the headers and the body. - +
Description:Words, hosts, or domains that are banned from being proxied
Syntax:ProxyBlock *|word|host|domain -[word|host|domain] ...
Syntax:ProxyBlock *|word|host|domain +[word|host|domain] ...
Context:server config, virtual host
Status:Extension
Module:mod_proxy
-

The ProxyBlock directive specifies a list of -words, hosts and/or domains, separated by spaces. HTTP, HTTPS, and -FTP document requests to sites whose names contain matched words, -hosts or domains are blocked 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:

+

The ProxyBlock directive specifies a list of + words, hosts and/or domains, separated by spaces. HTTP, HTTPS, and + FTP document requests to sites whose names contain matched words, + hosts or domains are blocked by the proxy server. The proxy + module will also attempt to determine IP addresses of list items which + may be hostnames during startup, and cache them for match test as + well. That may slow down the startup time of the server.

-

- ProxyBlock joes-garage.com some-host.co.uk rocky.wotsamattau.edu -

+

Example

+ ProxyBlock joes-garage.com some-host.co.uk rocky.wotsamattau.edu +

-

'rocky.wotsamattau.edu' would also be matched if referenced by IP -address.

+

rocky.wotsamattau.edu would also be matched if referenced by + IP address.

-

Note that 'wotsamattau' would also be sufficient to match -'wotsamattau.edu'.

+

Note that wotsamattau would also be sufficient to match + wotsamattau.edu.

-

Note also that

+

Note also that

-

-ProxyBlock * -

- -

blocks connections to all sites.

+

+ ProxyBlock * +

+

blocks connections to all sites.

top

ProxyDomain Directive

- +
Description:Default domain name for proxied requests
Syntax:ProxyDomain Domain
Syntax:ProxyDomain Domain
Context:server config, virtual host
Status:Extension
Module:mod_proxy
-

This directive is only useful for Apache proxy servers within -intranets. The ProxyDomain directive specifies -the default domain which the apache proxy server will belong to. If a -request to a host without a domain name is encountered, a redirection -response to the same host with the configured Domain appended -will be generated.

+

This directive is only useful for Apache proxy servers within + intranets. The ProxyDomain directive specifies + the default domain which the apache proxy server will belong to. If a + request to a host without a domain name is encountered, a redirection + response to the same host with the configured Domain appended + will be generated.

-

Example

- ProxyRemote * http://firewall.mycompany.com:81
- NoProxy .mycompany.com 192.168.112.0/21
- ProxyDomain .mycompany.com -

+

Example

+ ProxyRemote * http://firewall.mycompany.com:81
+ NoProxy .mycompany.com 192.168.112.0/21
+ ProxyDomain .mycompany.com +

top
@@ -568,25 +596,29 @@ will be generated.

Module:mod_proxy Compatibility:Available in version 2.0 and later -

This directive is useful for reverse-proxy setups, where you want to -have a common look and feel on the error pages seen by the end user. -This also allows for included files (via mod_include's SSI) to get -the error code and act accordingly (default behavior would display -the error page of the proxied server, turning this on shows the SSI -Error message).

+

This directive is useful for reverse-proxy setups, where you want to + have a common look and feel on the error pages seen by the end user. + This also allows for included files (via mod_include's SSI) to get + the error code and act accordingly (default behavior would display + the error page of the proxied server, turning this on shows the SSI + Error message).

top

ProxyIOBufferSize Directive

- - + + +
Description:IO buffer size for outgoing HTTP and FTP -connections
Syntax:ProxyIOBufferSize bytes
Description:Determine size of internal data throughput buffer
Syntax:ProxyIOBufferSize bytes
Default:ProxyIOBufferSize 8192
Context:server config, virtual host
Status:Extension
Module:mod_proxy
+

The ProxyIOBufferSize directive adjusts the size + of the internal buffer, which is used as a scratchpad for the data between + input and output. The size must be less or equal 8192.

+

In almost every case there's no reason to change that value.

top
@@ -594,14 +626,14 @@ connections - +
Description:Container for directives applied to regular-expression-matched proxied resources
Syntax:<ProxyMatch regex> ...</ProxyMatch>
Syntax:<ProxyMatch regex> ...</ProxyMatch>
Context:server config, virtual host
Status:Extension
Module:mod_proxy
-

The <ProxyMatch> directive is -identical to the <Proxy> directive, except it matches URLs -using regular expressions.

+

The <ProxyMatch> directive is + identical to the <Proxy> directive, except it matches URLs + using regular expressions.

top
@@ -609,253 +641,263 @@ using regular expressions.

- +
Description:Maximium number of proxies that a request can be forwarded through
Syntax:ProxyMaxForwards number
Syntax:ProxyMaxForwards number
Default:ProxyMaxForwards 10
Context:server config, virtual host
Status:Extension
Module:mod_proxy
Compatibility:Available in Apache 2.0 and later
-

The ProxyMaxForwards directive specifies the -maximum number of proxies through which a request may pass. This is -set to prevent infinite proxy loops, or a DoS attack.

+

The ProxyMaxForwards directive specifies the + maximum number of proxies through which a request may pass, if there's no + Max-Forwards header supplied with the request. This is + set to prevent infinite proxy loops, or a DoS attack.

-

Example

- ProxyMaxForwards 10 -

+

Example

+ ProxyMaxForwards 15 +

top

ProxyPass Directive

- - - + + +
Description:Maps remote servers into the local server -URL-space
Syntax:ProxyPass [path] !|url
Context:server config, virtual host
Description:Maps remote servers into the local server URL-space
Syntax:ProxyPass [path] !|url
Context:server config, virtual host, directory
Status:Extension
Module:mod_proxy
-

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 and cannot -include a query string.

+

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 and cannot include a query + string.

-

Suppose the local server has address http://wibble.org/; -then

-

- ProxyPass /mirror/foo/ http://foo.com/ -

-

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>.

-

-The ! directive is useful in situations where you don't want to reverse-proxy -a subdirectory. eg.

-

- ProxyPass /mirror/foo/i !
- ProxyPass /mirror/foo http://foo.com -

-

will proxy all requests to /mirror/foo to foo.com EXCEPT requests made to /mirror/foo/i

+

Suppose the local server has address http://example.com/; + then

-
NB: order is important. you need to put the exclusions BEFORE the general proxypass directive
+

+ ProxyPass /mirror/foo/ http://backend.example.com/ +

-

When used inside a <Location> section, the first argument is -ommitted and the local directory is obtained from the <Location>.

+

will cause a local request for + http://example.com/mirror/foo/bar to be internally converted + into a proxy request to http://backend.example.com/bar.

-

If you require a more flexible reverse-proxy configuration, see -the RewriteRule directive -with the [P] flag.

+

The ! directive is useful in situations where you don't want + to reverse-proxy a subdirectory, e.g.

+

+ ProxyPass /mirror/foo/i !
+ ProxyPass /mirror/foo http://backend.example.com +

+ +

will proxy all requests to /mirror/foo to + backend.example.com except requests made to + /mirror/foo/i.

+ +

Note

+

Order is important. you need to put the exclusions before the + general proxypass directive.

+
+ +

When used inside a <Location> section, the first argument is ommitted and the local + directory is obtained from the <Location>.

+ +

If you require a more flexible reverse-proxy configuration, see the + RewriteRule directive with the + [P] flag.

top

ProxyPassReverse Directive

- - - + + +
Description:Adjusts the URL in HTTP response headers sent from -a reverse proxied server
Syntax:ProxyPassReverse [path] url
Context:server config, virtual host
Description:Adjusts the URL in HTTP response headers sent from a reverse +proxied server
Syntax:ProxyPassReverse [path] url
Context:server config, virtual host, directory
Status:Extension
Module:mod_proxy
-

This directive lets Apache adjust the URL in the Location, -Content-Location and URI headers on -HTTP redirect responses. This is essential when Apache is used as -a reverse proxy to avoid by-passing the reverse proxy because of HTTP -redirects on the backend servers which stay behind the reverse proxy.

+

This directive lets Apache adjust the URL in the Location, + Content-Location and URI headers on HTTP redirect + responses. This is essential when Apache is used as a reverse proxy to avoid + by-passing the reverse proxy because of HTTP redirects on the backend + servers which stay behind the reverse proxy.

-

path is the name of a local virtual path.
-url is a partial URL for the remote server - the same way they are -used for the ProxyPass directive.

+

path is the name of a local virtual path. url is a + partial URL for the remote server - the same way they are used for the + ProxyPass directive.

-

-Example:
-Suppose the local server has address http://wibble.org/; then

-

- ProxyPass /mirror/foo/ http://foo.com/
- ProxyPassReverse /mirror/foo/ http://foo.com/ -

-

will not only 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> (the -functionality ProxyPass provides here). It also takes care of -redirects the server foo.com sends: when http://foo.com/bar is -redirected by him to http://foo.com/quux Apache adjusts this to -http://wibble.org/mirror/foo/quux before forwarding the HTTP -redirect response to the client. Note that the hostname used for -constructing the URL is chosen in respect to the setting of the -UseCanonicalName directive.

-

-Note that this ProxyPassReverse directive can -also be used in conjunction with the proxy pass-through feature -("RewriteRule ... [P]") from -mod_rewrite because its doesn't depend on a -corresponding ProxyPass -directive.

+

For example, suppose the local server has address + http://example.com/; then

-

When used inside a <Location> section, the first argument is -ommitted and the local directory is obtained from the <Location>.

+

+ ProxyPass /mirror/foo/ http://backend.example.com/
+ ProxyPassReverse /mirror/foo/ http://backend.example.com/ +

+

will not only cause a local request for the + http://example.com/mirror/foo/bar to be internally converted + into a proxy request to http://backend.example.com/bar + (the functionality ProxyPass provides here). It also takes care + of redirects the server backend.example.com sends: when + http://backend.example.com/bar is redirected by him to + http://backend.example.com/quux Apache adjusts this to + http://example.com/mirror/foo/quux before forwarding the HTTP + redirect response to the client. Note that the hostname used for + constructing the URL is chosen in respect to the setting of the UseCanonicalName directive.

+ +

Note that this ProxyPassReverse directive can + also be used in conjunction with the proxy pass-through feature + (RewriteRule ... [P]) from mod_rewrite + because its doesn't depend on a corresponding ProxyPass directive.

+ +

When used inside a <Location> section, the first argument is ommitted and the local + directory is obtained from the <Location>.

top

ProxyPreserveHost Directive

- - + + - +
Description:Use incoming Host HTTP request header for -proxy request
Syntax:ProxyPreserveHost on|off
Description:Use incoming Host HTTP request header for proxy +request
Syntax:ProxyPreserveHost On|Off
Default:ProxyPreserveHost Off
Context:server config, virtual host
Status:Extension
Module:mod_proxy
Compatibility:Available in -Apache 2.0.31 and later.
Compatibility:Available in Apache 2.0.31 and later.
-

When enabled, this option will pass the Host: line from the -incoming request to the proxied host, instead of the hostname -specified in the proxypass line. -

-

This option should normally be turned 'off'.

+

When enabled, this option will pass the Host: line from the incoming + request to the proxied host, instead of the hostname specified in the + proxypass line.

+ +

This option should normally be turned Off. It is mostly + useful in special configurations like proxied mass name-based virtual + hosting, where the original Host header needs to be evaluated by the + backend server.

top

ProxyReceiveBufferSize Directive

- - + +
Description:Network buffer size for outgoing HTTP and FTP +
Description:Network buffer size for proxied HTTP and FTP connections
Syntax:ProxyReceiveBufferSize bytes
Syntax:ProxyReceiveBufferSize bytes
Default:ProxyReceiveBufferSize 0
Context:server config, virtual host
Status:Extension
Module:mod_proxy
-

The ProxyReceiveBufferSize directive -specifies an explicit network buffer size for outgoing HTTP and FTP -connections, for increased throughput. It has to be greater than 512 -or set to 0 to indicate that the system's default buffer size should -be used.

-

Example

- ProxyReceiveBufferSize 2048 -

+

The ProxyReceiveBufferSize directive specifies an + explicit (TCP/IP) network buffer size for proxied HTTP and FTP connections, + for increased throughput. It has to be greater than 512 or set + to 0 to indicate that the system's default buffer size should + be used.

+ +

Example

+ ProxyReceiveBufferSize 2048 +

top

ProxyRemote Directive

- +
Description:Remote proxy used to handle certain requests
Syntax:ProxyRemote match remote-server
Syntax:ProxyRemote match remote-server
Context:server config, virtual host
Status:Extension
Module:mod_proxy
-

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:

+

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:

-
-  remote-server = protocol://hostname[:port]
-
+

+ remote-server = + scheme://hostname[:port] +

-

protocol is the protocol that should be used to communicate -with the remote server; only "http" is supported by this module.

+

scheme is effectively the protocol that should be used to + communicate with the remote server; only http is supported by + this module.

-

-Example:

-

- ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000
- ProxyRemote * http://cleversite.com
- ProxyRemote ftp http://ftpproxy.mydomain.com:8080 -

+

Example

+ ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000
+ ProxyRemote * http://cleversite.com
+ ProxyRemote ftp http://ftpproxy.mydomain.com:8080 +

-

In the last example, the proxy will forward FTP requests, encapsulated -as yet another HTTP proxy request, to another proxy which can handle -them.

+

In the last example, the proxy will forward FTP requests, encapsulated + as yet another HTTP proxy request, to another proxy which can handle + them.

-

This option also supports reverse proxy configuration - a backend -webserver can be embedded within a virtualhost URL space even if that -server is hidden by another forward proxy.

+

This option also supports reverse proxy configuration - a backend + webserver can be embedded within a virtualhost URL space even if that + server is hidden by another forward proxy.

top

ProxyRemoteMatch Directive

- - + +
Description:Remote proxy used to handle requests -matched by regular expressions
Syntax:ProxyRemoteMatch regex remote-server
Description:Remote proxy used to handle requests matched by regular +expressions
Syntax:ProxyRemoteMatch regex remote-server
Context:server config, virtual host
Status:Extension
Module:mod_proxy
-

The ProxyRemoteMatch is identical -to the ProxyRemote -directive, except the first argument is a regular expression -match against the requested URL.

+

The ProxyRemoteMatch is identical to the + ProxyRemote directive, except the + first argument is a regular expression match against the requested URL.

top

ProxyRequests Directive

- +
Description:Enables forward (standard) proxy requests
Syntax:ProxyRequests on|off
Syntax:ProxyRequests On|Off
Default:ProxyRequests Off
Context:server config, virtual host
Status:Extension
Module:mod_proxy
-

This allows or prevents Apache from functioning as a forward proxy -server. (Setting ProxyRequests to 'off' does not disable use of the -ProxyPass directive.)

+

This allows or prevents Apache from functioning as a forward proxy + server. (Setting ProxyRequests to Off does not disable use of + the ProxyPass directive.)

-

In a typical reverse proxy configuration, this option should be set to -'off'.

+

In a typical reverse proxy configuration, this option should be set to + Off.

-

Do not enable proxying with ProxyRequests until you have -secured your server. Open proxy servers are -dangerous both to your network and to the Internet at large.

+

In order to get the functionality of proxying HTTP or FTP sites, you + need also mod_proxy_http or mod_proxy_ftp + (or both) present in the server.

+

Warning

+

Do not enable proxying with ProxyRequests until you have secured your server. Open proxy servers are dangerous + both to your network and to the Internet at large.

+
top

ProxyTimeout Directive

- + - +
Description:Network timeout for proxied requests
Syntax:ProxyTimeout seconds
Syntax:ProxyTimeout seconds
Default:ProxyTimeout 300
Context:server config, virtual host
Status:Extension
Module:mod_proxy
Compatibility:Available in -Apache 2.0.31 and later
Compatibility:Available in Apache 2.0.31 and later
-

This directive allows a user to specifiy a timeout on proxy requests. -This is usefull when you have a slow/buggy appserver which hangs, -and you would rather just return a timeout and fail gracefully instead -of waiting however long it takes the server to return -

+

This directive allows a user to specifiy a timeout on proxy requests. + This is useful when you have a slow/buggy appserver which hangs, and you + would rather just return a timeout and fail gracefully instead of waiting + however long it takes the server to return.

top
@@ -863,34 +905,33 @@ of waiting however long it takes the server to return - - + +
Description:Information provided in the Via HTTP response header for proxied requests
Syntax:ProxyVia on|off|full|block
Default:ProxyVia off
Syntax:ProxyVia On|Off|Full|Block
Default:ProxyVia Off
Context:server config, virtual host
Status:Extension
Module:mod_proxy
-

This directive controls the use of the Via: HTTP -header by the proxy. Its intended use is to control the flow of of -proxy requests along a chain of proxy servers. See RFC2068 (HTTP/1.1) -for an explanation of Via: header lines.

+

This directive controls the use of the Via: HTTP + header by the proxy. Its intended use is to control the flow of of + proxy requests along a chain of proxy servers. See RFC 2616 (HTTP/1.1), section + 14.45 for an explanation of Via: header lines.

- diff --git a/docs/manual/mod/mod_proxy.xml b/docs/manual/mod/mod_proxy.xml index 3734da0a82..e09f953eb5 100644 --- a/docs/manual/mod/mod_proxy.xml +++ b/docs/manual/mod/mod_proxy.xml @@ -10,303 +10,302 @@ proxy_module -Warning -This document has been updated to take into account changes -made in the 2.0 version of the Apache HTTP Server. Some of the -information may still be inaccurate, please use it -with care. - + Warning +

Do not enable proxying with ProxyRequests until you have secured your server. Open proxy servers are dangerous both to your + network and to the Internet at large.

+ -

This module implements a proxy/gateway for Apache. It implements -proxying capability for -FTP, -CONNECT (for SSL), -HTTP/0.9, -HTTP/1.0, and -HTTP/1.1. -The module can be configured to connect to other proxy modules for these -and other protocols.

+

This module implements a proxy/gateway for Apache. It implements + proxying capability for FTP, CONNECT (for SSL), + HTTP/0.9, HTTP/1.0, and HTTP/1.1. + The module can be configured to connect to other proxy modules for these + and other protocols.

-

This module was experimental in Apache 1.1.x. Improvements and bugfixes -were made in Apache v1.2.x and Apache v1.3.x, then the module underwent a major -overhaul for Apache v2.0. The protocol support was upgraded to HTTP/1.1, -and filter support was enabled.

+

This module was experimental in Apache 1.1.x. Improvements and bugfixes + were made in Apache v1.2.x and Apache v1.3.x, then the module underwent a + major overhaul for Apache v2.0. The protocol support was upgraded to + HTTP/1.1, and filter support was enabled.

-

Please note that the caching function present in -mod_proxy up to Apache v1.3.x has been removed from -mod_proxy and will be incorporated into a new module, mod_cache. In other words: -the Apache 2.0.x-Proxy doesn't -cache at all - all caching functionality has been moved into mod_cache, -which is capable of caching any content, not only content from proxy. -

- -

If you need to use SSL when contacting remote servers, have a look at the -SSLProxy* directives in mod_ssl.

- -

Do not enable proxying with ProxyRequests until you have -secured your server. Open proxy servers are -dangerous both to your network and to the Internet at large.

 +

During the overhaul process the mod_proxy has been + splitted into several module files. The accompanying modules distributed + with the httpd are mod_proxy_http, + mod_proxy_ftp and mod_proxy_connect. + Thus if you want to use one or more of the particular proxy functions you + have to load mod_proxy and the appropriate + module(s) into the server (either statically or dynamically via the + LoadModule directive).

+

Please note that the caching function present in mod_proxy up to Apache v1.3.x has been removed + from mod_proxy and will be incorporated into a new module, + mod_cache. In other words: the Apache 2.0.x-Proxy doesn't + cache at all - all caching functionality has been moved into + mod_cache, which is capable of caching any content, not + only content from proxy.

+

If you need to use SSL when contacting remote servers, have a look at the + SSLProxy* directives in mod_ssl.

 +mod_proxy_http +mod_proxy_ftp +mod_proxy_connect +mod_ssl
Common configuration topics + - +
Forward and Reverse Proxies +

Apache can be configured in both a forward and + reverse proxy configuration.

-
Forward and Reverse Proxies +

A forward proxy is an intermediate system that enables a + browser to connect to a remote network to which it normally does not have + access. A forward proxy can also be used to cache data, reducing load on + the networks between the forward proxy and the remote webserver.

-

Apache can be configured in both a forward and reverse -proxy configuration.

+

Apache's mod_proxy can be figured to behave like a + forward proxy using the ProxyRemote directive. In addition, caching of data can be + achieved by configuring mod_cache. Other dedicated + forward proxy packages include Squid.

-

A forward proxy is an intermediate system that enables a browser to connect to a -remote network to which it normally does not have access. A forward proxy -can also be used to cache data, reducing load on the networks between the -forward proxy and the remote webserver.

+

A reverse proxy is a webserver system that is capable of + serving webpages sourced from other webservers - in addition to webpages + on disk or generated dynamically by CGI - making these pages look like + they originated at the reverse proxy.

-

Apache's mod_proxy can be figured to behave like a forward proxy -using the ProxyRemote -directive. In addition, caching of data can be achieved by configuring -Apache mod_cache. Other dedicated forward proxy -packages include Squid.

+

When configured with the mod_cache module the reverse proxy can act as + a cache for slower backend webservers. The reverse proxy can also enable + advanced URL strategies and management techniques, allowing webpages + served using different webserver systems or architectures to coexist + inside the same URL space. Reverse proxy systems are also ideal for + implementing centralised logging websites with many or diverse website + backends. Complex multi-tier webserver systems can be constructed using an + mod_proxy frontend and any number of backend + webservers.

-

A reverse proxy is a webserver system that is capable of serving webpages -sourced from other webservers - in addition to webpages on disk or generated -dynamically by CGI - making these pages look like they originated at the -reverse proxy.

+

The reverse proxy is configured using the ProxyPass and ProxyPassReverse directives. Caching can be + enabled using mod_cache as with the forward proxy.

+
-

When configured with the mod_cache module the reverse -proxy can act as a cache for slower backend webservers. The reverse proxy -can also enable advanced URL strategies and management techniques, allowing -webpages served using different webserver systems or architectures to -coexist inside the same URL space. Reverse proxy systems are also ideal for -implementing centralised logging websites with many or diverse website -backends. Complex multi-tier webserver systems can be constructed using an -Apache mod_proxy frontend and any number of backend webservers.

+
Controlling access to your proxy +

You can control who can access your proxy via the Proxy control block using + the following example:

-

The reverse proxy is configured using the -ProxyPass and ProxyPassReverse directives. Caching can be -enabled using mod_cache as with the forward proxy.

+ + <Proxy *>
+ + Order Deny,Allow
+ Deny from all
+ Allow from 192.168.0
+ + </Proxy> + -
+

When configuring a reverse proxy, access control takes on the + attributes of the normal server Directory configuration.

+
-
Controlling access to your proxy +
Why doesn't file type <var>xxx</var> + download via FTP? +

You probably don't have that particular file type defined as + application/octet-stream in your proxy's mime.types + configuration file. A useful line can be

-

You can control who can access your proxy via the -Proxy -control block using the following example:

+ +
application/octet-stream   bin dms lha lzh exe class tgz taz
+ +
- -<Proxy *>
-Order Deny,Allow
-Deny from all
-Allow from 192.168.0
-</Proxy> - +
How can I force an FTP ASCII download of + File <var>xxx</var>? +

In the rare situation where you must download a specific file using the + FTP ASCII transfer method (while the default transfer is in + binary mode), you can override mod_proxy's + default by suffixing the request with ;type=a to force an + ASCII transfer. (FTP Directory listings are always executed in ASCII mode, + however.)

+
-

When configuring a reverse proxy, access control takes on the -attributes of the normal server directory configuration.

-
+
How can I access FTP files outside + of my home directory? +

An FTP URI is interpreted relative to the home directory of the user + who is logging in. Alas, to reach higher directory levels you cannot + use /../, as the dots are interpreted by the browser and not actually + sent to the FTP server. To address this problem, the so called Squid + %2f hack was implemented in the Apache FTP proxy; it is a + solution which is also used by other popular proxy servers like the Squid Proxy Cache. By + prepending /%2f to the path of your request, you can make + such a proxy change the FTP starting directory to / (instead + of the home directory). For example, to retrieve the file + /etc/motd, you would use the URL:

-
Why doesn't file type <em>xxx</em> -download via FTP? + + ftp://user@host/%2f/etc/motd + +
-

You probably don't have that particular file type defined as -application/octet-stream in your proxy's mime.types configuration -file. A useful line can be

+
How can I hide the FTP cleartext password + in my browser's URL line? +

To log in to an FTP server by username and password, Apache uses + different strategies. In absense of a user name and password in the URL + altogether, Apache sends an anomymous login to the FTP server, + i.e.,

- -application/octet-stream bin dms lha lzh exe class tgz taz - -
+ + user: anonymous
+ password: apache_proxy@ + -
How can I force an FTP ASCII download of -File <em>xxx</em>? +

This works for all popular FTP servers which are configured for + anonymous access.

-

In the rare situation where you must download a specific file using the FTP -ASCII transfer method (while the default transfer is in -binary mode), you can override mod_proxy's default by -suffixing the request with ;type=a to force an ASCII transfer. -(FTP Directory listings are always executed in ASCII mode, however.)

-
+

For a personal login with a specific username, you can embed the user + name into the URL, like in:

-
How can I access FTP files outside -of my home directory? + + ftp://username@host/myfile + -

-An FTP URI is interpreted relative to the home directory of the user -who is logging in. Alas, to reach higher directory levels you cannot -use /../, as the dots are interpreted by the browser and not actually -sent to the FTP server. To address this problem, the so called "Squid -%2f hack" was implemented in the Apache FTP proxy; it is is a solution -which is also used by other popular proxy servers like the Squid Proxy Cache. By -prepending /%2f to the path of your request, you can make such a proxy -change the FTP starting directory to / (instead of the home -directory).

+

If the FTP server asks for a password when given this username (which + it should), then Apache will reply with a 401 (Authorization + required) response, which causes the Browser to pop up the + username/password dialog. Upon entering the password, the connection + attempt is retried, and if successful, the requested resource is + presented. The advantage of this procedure is that your browser does not + display the password in cleartext (which it would if you had used

-

Example: To retrieve the file -/etc/motd, you would use the URL

-ftp://user@host/%2f/etc/motd -
+ + ftp://username:password@host/myfile + -
How can I hide the FTP cleartext password -in my browser's URL line? +

in the first place).

-

-To log in to an FTP server by username and password, Apache -uses different strategies. -In absense of a user name and password in the URL altogether, -Apache sends an anomymous login to the FTP server, i.e.,

- -user: anonymous
-password: apache_proxy@ - -

This works for all popular FTP servers which are configured for -anonymous access.

+ Note +

The password which is transmitted in such a way is not encrypted on + its way. It travels between your browser and the Apache proxy server in + a base64-encoded cleartext string, and between the Apache proxy and the + FTP server as plaintext. You should therefore think twice before + accessing your FTP server via HTTP (or before accessing your personal + files via FTP at all!) When using unsecure channels, an eavesdropper + might intercept your password on its way.

+ +
-

For a personal login with a specific username, you can embed -the user name into the URL, like in: -ftp://username@host/myfile. If the FTP server -asks for a password when given this username (which it should), -then Apache will reply with a [401 Authorization required] response, -which causes the Browser to pop up the username/password dialog. -Upon entering the password, the connection attempt is retried, -and if successful, the requested resource is presented. -The advantage of this procedure is that your browser does not -display the password in cleartext (which it would if you had used -ftp://username:password@host/myfile in -the first place).

+
Why does Apache start more slowly when using + the proxy module? +

If you're using the ProxyBlock directive, hostnames' IP addresses are looked up + and cached during startup for later match test. This may take a few + seconds (or more) depending on the speed with which the hostname lookups + occur.

+
-Note -The password which is transmitted in such a way -is not encrypted on its way. It travels between your browser and -the Apache proxy server in a base64-encoded cleartext string, and -between the Apache proxy and the FTP server as plaintext. You should -therefore think twice before accessing your FTP server via HTTP -(or before accessing your personal files via FTP at all!) When -using unsecure channels, an eavesdropper might intercept your -password on its way. - -
+
What other functions are useful for an + intranet proxy server? +

An Apache proxy server situated in an intranet needs to forward + external requests through the company's firewall. However, when it has to + access resources within the intranet, it can bypass the firewall when + accessing hosts. The NoProxy + directive is useful for specifying which hosts belong to the intranet and + should be accessed directly.

-
Why does Apache start more slowly when -using the proxy module? +

Users within an intranet tend to omit the local domain name from their + WWW requests, thus requesting "http://somehost/" instead of + http://somehost.example.com/. Some commercial proxy servers + let them get away with this and simply serve the request, implying a + configured local domain. When the ProxyDomain directive is used and the server is configured for proxy service, Apache can return + a redirect response and send the client to the correct, fully qualified, + server address. This is the preferred method since the user's bookmark + files will then contain fully qualified hosts.

+
-

If you're using the ProxyBlock -directive, hostnames' IP addresses are looked up and cached during -startup for later match test. This may take a few seconds (or more) -depending on the speed with which the hostname lookups occur.

-
+
How can I make the proxy talk HTTP/1.0 and + disable keepalives? +

For circumstances where you have a application server which doesn't + implement keepalives or HTTP/1.1 properly, there are 2 environment + variables which when set send a HTTP/1.0 with no keepalive. These are set + via the SetEnv directive.

- - -
What other functions are useful for an -intranet proxy server? - -

An Apache proxy server situated in an intranet needs to forward -external requests through the company's firewall. However, when it has -to access resources within the intranet, it can bypass the firewall -when accessing hosts. The NoProxy directive is useful for -specifying which hosts belong to the intranet and should be accessed -directly.

- -

Users within an intranet tend to omit the local domain name from their -WWW requests, thus requesting "http://somehost/" instead of -"http://somehost.my.dom.ain/". Some commercial proxy servers let them get -away with this and simply serve the request, implying a configured -local domain. When the ProxyDomain directive -is used and the server is configured for -proxy service, Apache can return a redirect response and send the client -to the correct, fully qualified, server address. This is the preferred method -since the user's bookmark files will then contain fully qualified hosts.

-
-
How can I make the proxy talk HTTP/1.0 and -disable keepalives? - -

For circumstances where you have a application server which doesn't implement -keepalives or HTTP/1.1 properly, there are 2 environment variables which when -set send a HTTP/1.0 with no keepalive. These are set via the SetEnv directive.

-

These are the 'force-proxy-request-1.0' and 'proxy-nokeepalive' notes.

- - -<location /buggyappserver/ >
-ProxyPass http://buggyappserver:7001/foo/
-SetEnv force-proxy-request-1.0 1
-SetEnv proxy-nokeepalive 1
-</location> - - -
+

These are the force-proxy-request-1.0 and + proxy-nokeepalive notes.

+ + <Location /buggyappserver/>
+ + ProxyPass http://buggyappserver:7001/foo/
+ SetEnv force-proxy-request-1.0 1
+ SetEnv proxy-nokeepalive 1
+ + </Location> + +
Proxy -Container for directives applied to proxied -resources -<Proxy wildcard-url> ...</Proxy> -server config -virtual host +Container for directives applied to proxied resources +<Proxy wildcard-url> ...</Proxy> +server configvirtual host + -

Directives placed in Proxy -sections apply only to matching proxied content. Shell-style -wildcards are allowed.

+

Directives placed in Proxy + sections apply only to matching proxied content. Shell-style wildcards are + allowed.

-

For example, the following will allow only hosts in -yournetwork.example.com to access content via your -proxy server:

+

For example, the following will allow only hosts in + yournetwork.example.com to access content via your proxy + server:

- -<Proxy *>
-  Order Deny,Allow
-  Deny from all
-  Allow from yournetwork.example.com
-</Proxy> - + + <Proxy *>
+ + Order Deny,Allow
+ Deny from all
+ Allow from yournetwork.example.com
+ + </Proxy> + -

The following example will process all files in the -foo directory of example.com through the -INCLUDES filter when they are sent through the proxy -server:

- -<Proxy http://example.com/foo/*>
-  SetOutputFilter INCLUDES
-</Proxy> - +

The following example will process all files in the foo + directory of example.com through the INCLUDES + filter when they are sent through the proxy server:

+ + + <Proxy http://example.com/foo/*>
+ + SetOutputFilter INCLUDES
+ + </Proxy> + @@ -321,22 +320,24 @@ response available in Apache 2.0.44 and later -

The ProxyBadHeader directive determines the behaviour -of mod_proxy if it receives syntactically invalid header lines -(i.e. containing no colon). The following arguments are possible:

-
-
IsError
-
Abort the request and end up with a 502 (Bad Gateway) response. This is the -default behaviour.
+

The ProxyBadHeader directive determines the + behaviour of mod_proxy if it receives syntactically invalid + header lines (i.e. containing no colon). The following arguments + are possible:

-
Ignore
-
Treat bad header lines as if they weren't sent.
+
+
IsError
+
Abort the request and end up with a 502 (Bad Gateway) response. This is + the default behaviour.
-
StartBody
-
When receiving the first bad header line, finish reading the headers and -treat the remainder as body. This helps to work around buggy backend servers -which forget to insert an empty line between the headers and the body.
-
+
Ignore
+
Treat bad header lines as if they weren't sent.
+ +
StartBody
+
When receiving the first bad header line, finish reading the headers and + treat the remainder as body. This helps to work around buggy backend servers + which forget to insert an empty line between the headers and the body.
+
@@ -344,244 +345,254 @@ which forget to insert an empty line between the headers and the body. ProxyMatch Container for directives applied to regular-expression-matched proxied resources -<ProxyMatch regex> ...</ProxyMatch> -server config -virtual host +<ProxyMatch regex> ...</ProxyMatch> +server configvirtual host + -

The ProxyMatch directive is -identical to the Proxy directive, except it matches URLs -using regular expressions.

+

The ProxyMatch directive is + identical to the Proxy directive, except it matches URLs + using regular expressions.

 - ProxyPreserveHost -Use incoming Host HTTP request header for -proxy request -ProxyPreserveHost on|off +Use incoming Host HTTP request header for proxy +request +ProxyPreserveHost On|Off ProxyPreserveHost Off -server config -virtual host +server configvirtual host -Available in -Apache 2.0.31 and later. +Available in Apache 2.0.31 and later. -

When enabled, this option will pass the Host: line from the -incoming request to the proxied host, instead of the hostname -specified in the proxypass line. -

-

This option should normally be turned 'off'.

+

When enabled, this option will pass the Host: line from the incoming + request to the proxied host, instead of the hostname specified in the + proxypass line.

+ +

This option should normally be turned Off. It is mostly + useful in special configurations like proxied mass name-based virtual + hosting, where the original Host header needs to be evaluated by the + backend server.

 ProxyRequests Enables forward (standard) proxy requests -ProxyRequests on|off +ProxyRequests On|Off ProxyRequests Off -server config -virtual host +server configvirtual host -

This allows or prevents Apache from functioning as a forward proxy -server. (Setting ProxyRequests to 'off' does not disable use of the -ProxyPass directive.)

+

This allows or prevents Apache from functioning as a forward proxy + server. (Setting ProxyRequests to Off does not disable use of + the ProxyPass directive.)

-

In a typical reverse proxy configuration, this option should be set to -'off'.

+

In a typical reverse proxy configuration, this option should be set to + Off.

-

Do not enable proxying with ProxyRequests until you have -secured your server. Open proxy servers are -dangerous both to your network and to the Internet at large.

 +

In order to get the functionality of proxying HTTP or FTP sites, you + need also mod_proxy_http or mod_proxy_ftp + (or both) present in the server.

+ Warning +

Do not enable proxying with ProxyRequests until you have secured your server. Open proxy servers are dangerous + both to your network and to the Internet at large.

+ ProxyRemote Remote proxy used to handle certain requests -ProxyRemote match remote-server -server config -virtual host +ProxyRemote match remote-server +server configvirtual host -

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:

+

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:

-
-  remote-server = protocol://hostname[:port]
-
+ + remote-server = + scheme://hostname[:port] + -

protocol is the protocol that should be used to communicate -with the remote server; only "http" is supported by this module.

+

scheme is effectively the protocol that should be used to + communicate with the remote server; only http is supported by + this module.

-

-Example:

- - ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000
- ProxyRemote * http://cleversite.com
- ProxyRemote ftp http://ftpproxy.mydomain.com:8080 - + Example + ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000
+ ProxyRemote * http://cleversite.com
+ ProxyRemote ftp http://ftpproxy.mydomain.com:8080 + -

In the last example, the proxy will forward FTP requests, encapsulated -as yet another HTTP proxy request, to another proxy which can handle -them.

+

In the last example, the proxy will forward FTP requests, encapsulated + as yet another HTTP proxy request, to another proxy which can handle + them.

-

This option also supports reverse proxy configuration - a backend -webserver can be embedded within a virtualhost URL space even if that -server is hidden by another forward proxy.

+

This option also supports reverse proxy configuration - a backend + webserver can be embedded within a virtualhost URL space even if that + server is hidden by another forward proxy.

 ProxyRemoteMatch -Remote proxy used to handle requests -matched by regular expressions -ProxyRemoteMatch regex remote-server -server config -virtual host +Remote proxy used to handle requests matched by regular +expressions +ProxyRemoteMatch regex remote-server +server configvirtual host -

The ProxyRemoteMatch is identical -to the ProxyRemote -directive, except the first argument is a regular expression -match against the requested URL.

+

The ProxyRemoteMatch is identical to the + ProxyRemote directive, except the + first argument is a regular expression match against the requested URL.

 ProxyPass -Maps remote servers into the local server -URL-space -ProxyPass [path] !|url -server config -virtual host +Maps remote servers into the local server URL-space +ProxyPass [path] !|url +server configvirtual host +directory -

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 and cannot -include a query string.

+

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 and cannot include a query + string.

-

Suppose the local server has address http://wibble.org/; -then

- - ProxyPass /mirror/foo/ http://foo.com/ - -

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>.

-

-The ! directive is useful in situations where you don't want to reverse-proxy -a subdirectory. eg.

- - ProxyPass /mirror/foo/i !
- ProxyPass /mirror/foo http://foo.com - -

will proxy all requests to /mirror/foo to foo.com EXCEPT requests made to /mirror/foo/i

+

Suppose the local server has address http://example.com/; + then

-NB: order is important. you need to put the exclusions BEFORE the general proxypass directive + + ProxyPass /mirror/foo/ http://backend.example.com/ + -

When used inside a Location section, the first argument is -ommitted and the local directory is obtained from the Location.

+

will cause a local request for + http://example.com/mirror/foo/bar to be internally converted + into a proxy request to http://backend.example.com/bar.

-

If you require a more flexible reverse-proxy configuration, see -the RewriteRule directive -with the [P] flag.

+

The ! directive is useful in situations where you don't want + to reverse-proxy a subdirectory, e.g.

+ + ProxyPass /mirror/foo/i !
+ ProxyPass /mirror/foo http://backend.example.com + + +

will proxy all requests to /mirror/foo to + backend.example.com except requests made to + /mirror/foo/i.

+ + Note +

Order is important. you need to put the exclusions before the + general proxypass directive.

+ + +

When used inside a Location section, the first argument is ommitted and the local + directory is obtained from the Location.

+ +

If you require a more flexible reverse-proxy configuration, see the + RewriteRule directive with the + [P] flag.

 - ProxyPassReverse -Adjusts the URL in HTTP response headers sent from -a reverse proxied server -ProxyPassReverse [path] url -server config -virtual host +Adjusts the URL in HTTP response headers sent from a reverse +proxied server +ProxyPassReverse [path] url +server configvirtual host +directory -

This directive lets Apache adjust the URL in the Location, -Content-Location and URI headers on -HTTP redirect responses. This is essential when Apache is used as -a reverse proxy to avoid by-passing the reverse proxy because of HTTP -redirects on the backend servers which stay behind the reverse proxy.

+

This directive lets Apache adjust the URL in the Location, + Content-Location and URI headers on HTTP redirect + responses. This is essential when Apache is used as a reverse proxy to avoid + by-passing the reverse proxy because of HTTP redirects on the backend + servers which stay behind the reverse proxy.

-

path is the name of a local virtual path.
-url is a partial URL for the remote server - the same way they are -used for the ProxyPass directive.

+

path is the name of a local virtual path. url is a + partial URL for the remote server - the same way they are used for the + ProxyPass directive.

-

-Example:
-Suppose the local server has address http://wibble.org/; then

- - ProxyPass /mirror/foo/ http://foo.com/
- ProxyPassReverse /mirror/foo/ http://foo.com/ - -

will not only 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> (the -functionality ProxyPass provides here). It also takes care of -redirects the server foo.com sends: when http://foo.com/bar is -redirected by him to http://foo.com/quux Apache adjusts this to -http://wibble.org/mirror/foo/quux before forwarding the HTTP -redirect response to the client. Note that the hostname used for -constructing the URL is chosen in respect to the setting of the -UseCanonicalName directive.

-

-Note that this ProxyPassReverse directive can -also be used in conjunction with the proxy pass-through feature -("RewriteRule ... [P]") from -mod_rewrite because its doesn't depend on a -corresponding ProxyPass -directive.

+

For example, suppose the local server has address + http://example.com/; then

-

When used inside a Location section, the first argument is -ommitted and the local directory is obtained from the Location.

+ + ProxyPass /mirror/foo/ http://backend.example.com/
+ ProxyPassReverse /mirror/foo/ http://backend.example.com/ + +

will not only cause a local request for the + http://example.com/mirror/foo/bar to be internally converted + into a proxy request to http://backend.example.com/bar + (the functionality ProxyPass provides here). It also takes care + of redirects the server backend.example.com sends: when + http://backend.example.com/bar is redirected by him to + http://backend.example.com/quux Apache adjusts this to + http://example.com/mirror/foo/quux before forwarding the HTTP + redirect response to the client. Note that the hostname used for + constructing the URL is chosen in respect to the setting of the UseCanonicalName directive.

+ +

Note that this ProxyPassReverse directive can + also be used in conjunction with the proxy pass-through feature + (RewriteRule ... [P]) from mod_rewrite + because its doesn't depend on a corresponding ProxyPass directive.

+ +

When used inside a Location section, the first argument is ommitted and the local + directory is obtained from the Location.

 AllowCONNECT -Ports that are allowed to CONNECT through -the proxy -AllowCONNECT port [port] ... +Ports that are allowed to CONNECT through the +proxy +AllowCONNECT port [port] ... AllowCONNECT 443 563 -server config -virtual host +server configvirtual host -

The AllowCONNECT directive specifies a list -of port numbers to which the proxy CONNECT method may -connect. Today's browsers use this method when a https -connection is requested and proxy tunneling over http is in -effect.
By default, only the default https port (443) and the -default snews port (563) are enabled. Use the -AllowCONNECT directive to overrride this default and -allow connections to the listed ports only.

+

The AllowCONNECT directive specifies a list + of port numbers to which the proxy CONNECT method may + connect. Today's browsers use this method when a https + connection is requested and proxy tunneling over HTTP is in effect.

+ +

By default, only the default https port (443) and the + default snews port (563) are enabled. Use the + AllowCONNECT directive to override this default and + allow connections to the listed ports only.

+ +

Note that you'll need to have mod_proxy_connect present + in the server in order to get the support for the CONNECT at + all.

 @@ -589,74 +600,76 @@ allow connections to the listed ports only.

ProxyBlock Words, hosts, or domains that are banned from being proxied -ProxyBlock *|word|host|domain -[word|host|domain] ... -server config -virtual host +ProxyBlock *|word|host|domain +[word|host|domain] ... +server configvirtual host -

The ProxyBlock directive specifies a list of -words, hosts and/or domains, separated by spaces. HTTP, HTTPS, and -FTP document requests to sites whose names contain matched words, -hosts or domains are blocked 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:

+

The ProxyBlock directive specifies a list of + words, hosts and/or domains, separated by spaces. HTTP, HTTPS, and + FTP document requests to sites whose names contain matched words, + hosts or domains are blocked by the proxy server. The proxy + module will also attempt to determine IP addresses of list items which + may be hostnames during startup, and cache them for match test as + well. That may slow down the startup time of the server.

- - ProxyBlock joes-garage.com some-host.co.uk rocky.wotsamattau.edu - + Example + ProxyBlock joes-garage.com some-host.co.uk rocky.wotsamattau.edu + -

'rocky.wotsamattau.edu' would also be matched if referenced by IP -address.

+

rocky.wotsamattau.edu would also be matched if referenced by + IP address.

-

Note that 'wotsamattau' would also be sufficient to match -'wotsamattau.edu'.

+

Note that wotsamattau would also be sufficient to match + wotsamattau.edu.

-

Note also that

+

Note also that

- -ProxyBlock * - - -

blocks connections to all sites.

+ + ProxyBlock * + +

blocks connections to all sites.

 ProxyReceiveBufferSize -Network buffer size for outgoing HTTP and FTP +Network buffer size for proxied HTTP and FTP connections -ProxyReceiveBufferSize bytes -server config -virtual host +ProxyReceiveBufferSize bytes +ProxyReceiveBufferSize 0 +server configvirtual host -

The ProxyReceiveBufferSize directive -specifies an explicit network buffer size for outgoing HTTP and FTP -connections, for increased throughput. It has to be greater than 512 -or set to 0 to indicate that the system's default buffer size should -be used.

-Example - ProxyReceiveBufferSize 2048 - +

The ProxyReceiveBufferSize directive specifies an + explicit (TCP/IP) network buffer size for proxied HTTP and FTP connections, + for increased throughput. It has to be greater than 512 or set + to 0 to indicate that the system's default buffer size should + be used.

+ + Example + ProxyReceiveBufferSize 2048 + ProxyIOBufferSize -IO buffer size for outgoing HTTP and FTP -connections -ProxyIOBufferSize bytes -server config -virtual host +Determine size of internal data throughput buffer +ProxyIOBufferSize bytes +ProxyIOBufferSize 8192 +server configvirtual host - +

The ProxyIOBufferSize directive adjusts the size + of the internal buffer, which is used as a scratchpad for the data between + input and output. The size must be less or equal 8192.

+ +

In almost every case there's no reason to change that value.

 @@ -664,130 +677,144 @@ connections ProxyMaxForwards Maximium number of proxies that a request can be forwarded through -ProxyMaxForwards number +ProxyMaxForwards number ProxyMaxForwards 10 -server config -virtual host +server configvirtual host Available in Apache 2.0 and later -

The ProxyMaxForwards directive specifies the -maximum number of proxies through which a request may pass. This is -set to prevent infinite proxy loops, or a DoS attack.

+

The ProxyMaxForwards directive specifies the + maximum number of proxies through which a request may pass, if there's no + Max-Forwards header supplied with the request. This is + set to prevent infinite proxy loops, or a DoS attack.

-Example - ProxyMaxForwards 10 - + Example + ProxyMaxForwards 15 + NoProxy -Hosts, domains, or networks that will be connected -to directly -NoProxy host [host] ... -server config -virtual host +Hosts, domains, or networks that will be connected to +directly +NoProxy host [host] ... +server configvirtual host -

This directive is only useful for Apache proxy servers within -intranets. The NoProxy directive specifies a -list of subnets, IP addresses, hosts and/or domains, separated by -spaces. A request to a host which matches one or more of these is -always served directly, without forwarding to the configured -ProxyRemote proxy server(s).

+

This directive is only useful for Apache proxy servers within + intranets. The NoProxy directive specifies a + list of subnets, IP addresses, hosts and/or domains, separated by + spaces. A request to a host which matches one or more of these is + always served directly, without forwarding to the configured + ProxyRemote proxy server(s).

-Example - ProxyRemote * http://firewall.mycompany.com:81
- NoProxy .mycompany.com 192.168.112.0/21 - + Example + ProxyRemote * http://firewall.mycompany.com:81
+ NoProxy .mycompany.com 192.168.112.0/21 + -

The host arguments to the NoProxy directive are one of the -following type list:

-
+

The host arguments to the NoProxy + directive are one of the following type list:

+ +
-
- Domain
-
A Domain is a partially qualified DNS domain name, preceded - by a period. - It represents a list of hosts which logically belong to the same DNS - domain or zone (i.e., the suffixes of the hostnames are all ending in - Domain).
- Examples: .com .apache.org.
- To distinguish Domains from Hostnames (both - syntactically and semantically; a DNS domain can have a DNS A record, - too!), Domains are always written - with a leading period.
- Note: Domain name comparisons are done without regard to the case, - and Domains are always assumed to be anchored in the root - of the DNS tree, therefore two domains .MyDomain.com and - .mydomain.com. (note the trailing period) are - considered equal. Since a domain comparison does not involve a DNS - lookup, it is much more efficient than subnet comparison.
+
Domain
+
+

A Domain is a partially qualified DNS domain name, preceded + by a period. It represents a list of hosts which logically belong to the + same DNS domain or zone (i.e., the suffixes of the hostnames are + all ending in Domain).

+ + Examples + .com .apache.org. + + +

To distinguish Domains from Hostnames (both syntactically and semantically; a DNS domain can + have a DNS A record, too!), Domains are always written with a + leading period.

+ + Note +

Domain name comparisons are done without regard to the case, and + Domains are always assumed to be anchored in the root of the + DNS tree, therefore two domains .MyDomain.com and + .mydomain.com. (note the trailing period) are considered + equal. Since a domain comparison does not involve a DNS lookup, it is much + more efficient than subnet comparison.

+
-
- SubNet
-
A SubNet is a partially qualified internet address in - numeric (dotted quad) form, optionally followed by a slash and the - netmask, specified as the number of significant bits in the - SubNet. It is used to represent a subnet of hosts which can - be reached over a common network interface. In the absence of the - explicit net mask it is assumed that omitted (or zero valued) - trailing digits specify the mask. (In this case, the netmask can - only be multiples of 8 bits wide.)
- Examples: -
-
192.168 or 192.168.0.0
-
the subnet 192.168.0.0 with an implied netmask of 16 valid bits - (sometimes used in the netmask form 255.255.0.0)
-
192.168.112.0/21
-
the subnet 192.168.112.0/21 with a netmask of 21 - valid bits (also used in the form 255.255.248.0)
-
- As a degenerate case, a SubNet with 32 valid bits is the - equivalent to an IPAddr, while a SubNet with zero - valid bits (e.g., 0.0.0.0/0) is the same as the constant - _Default_, matching any IP address.
+
SubNet
+
+

A SubNet is a partially qualified internet address in + numeric (dotted quad) form, optionally followed by a slash and the netmask, + specified as the number of significant bits in the SubNet. It is + used to represent a subnet of hosts which can be reached over a common + network interface. In the absence of the explicit net mask it is assumed + that omitted (or zero valued) trailing digits specify the mask. (In this + case, the netmask can only be multiples of 8 bits wide.) Examples:

+ +
+
192.168 or 192.168.0.0
+
the subnet 192.168.0.0 with an implied netmask of 16 valid bits + (sometimes used in the netmask form 255.255.0.0)
+
192.168.112.0/21
+
the subnet 192.168.112.0/21 with a netmask of 21 + valid bits (also used in the form 255.255.248.0)
+
+ +

As a degenerate case, a SubNet with 32 valid bits is the + equivalent to an IPAddr, while a SubNet with zero + valid bits (e.g., 0.0.0.0/0) is the same as the constant + _Default_, matching any IP address.

-
- IPAddr
-
A IPAddr represents a fully qualified internet address in - numeric (dotted quad) form. Usually, this address represents a - host, but there need not necessarily be a DNS domain name - connected with the address.
- Example: 192.168.123.7
- Note: An IPAddr does not need to be resolved by the DNS - system, so it can result in more effective apache performance.
+
IPAddr
+
+

A IPAddr represents a fully qualified internet address in + numeric (dotted quad) form. Usually, this address represents a host, but + there need not necessarily be a DNS domain name connected with the + address.

+ Example + 192.168.123.7 + + + Note +

An IPAddr does not need to be resolved by the DNS system, so + it can result in more effective apache performance.

+
-
- Hostname
-
A Hostname is a fully qualified DNS domain name which can - be resolved to one or more IPAddrs via the DNS domain name service. - It represents a logical host (in contrast to - Domains, see - above) and must be resolvable to at least one IPAddr (or often to a list of hosts - with different IPAddr's).
- Examples: prep.ai.mit.edu - www.apache.org.
- Note: In many situations, it is more effective to specify an - IPAddr in place of a - Hostname since a DNS lookup - can be avoided. Name resolution in Apache can take a remarkable deal - of time when the connection to the name server uses a slow PPP - link.
- Note: Hostname comparisons are done without regard to the case, - and Hostnames are always assumed to be anchored in the root - of the DNS tree, therefore two hosts WWW.MyDomain.com - and www.mydomain.com. (note the trailing period) are - considered equal.
-
+
Hostname
+
+

A Hostname is a fully qualified DNS domain name which can + be resolved to one or more IPAddrs via the + DNS domain name service. It represents a logical host (in contrast to + Domains, see above) and must be resolvable + to at least one IPAddr (or often to a list + of hosts with different IPAddrs).

+ + Examples + prep.ai.mit.edu
+ www.apache.org + + + Note +

In many situations, it is more effective to specify an IPAddr in place of a Hostname since a + DNS lookup can be avoided. Name resolution in Apache can take a remarkable + deal of time when the connection to the name server uses a slow PPP + link.

+

Hostname comparisons are done without regard to the case, + and Hostnames are always assumed to be anchored in the root + of the DNS tree, therefore two hosts WWW.MyDomain.com + and www.mydomain.com. (note the trailing period) are + considered equal.

+
+
DNS Issues @@ -795,44 +822,40 @@ following type list:

ProxyTimeout Network timeout for proxied requests -ProxyTimeout seconds +ProxyTimeout seconds ProxyTimeout 300 -server config -virtual host +server configvirtual host -Available in -Apache 2.0.31 and later +Available in Apache 2.0.31 and later -

This directive allows a user to specifiy a timeout on proxy requests. -This is usefull when you have a slow/buggy appserver which hangs, -and you would rather just return a timeout and fail gracefully instead -of waiting however long it takes the server to return -

+

This directive allows a user to specifiy a timeout on proxy requests. + This is useful when you have a slow/buggy appserver which hangs, and you + would rather just return a timeout and fail gracefully instead of waiting + however long it takes the server to return.

 ProxyDomain Default domain name for proxied requests -ProxyDomain Domain -server config -virtual host +ProxyDomain Domain +server configvirtual host -

This directive is only useful for Apache proxy servers within -intranets. The ProxyDomain directive specifies -the default domain which the apache proxy server will belong to. If a -request to a host without a domain name is encountered, a redirection -response to the same host with the configured Domain appended -will be generated.

+

This directive is only useful for Apache proxy servers within + intranets. The ProxyDomain directive specifies + the default domain which the apache proxy server will belong to. If a + request to a host without a domain name is encountered, a redirection + response to the same host with the configured Domain appended + will be generated.

-Example - ProxyRemote * http://firewall.mycompany.com:81
- NoProxy .mycompany.com 192.168.112.0/21
- ProxyDomain .mycompany.com - + Example + ProxyRemote * http://firewall.mycompany.com:81
+ NoProxy .mycompany.com 192.168.112.0/21
+ ProxyDomain .mycompany.com + @@ -840,35 +863,34 @@ will be generated.

ProxyVia Information provided in the Via HTTP response header for proxied requests -ProxyVia on|off|full|block -ProxyVia off -server config -virtual host +ProxyVia On|Off|Full|Block +ProxyVia Off +server configvirtual host -

This directive controls the use of the Via: HTTP -header by the proxy. Its intended use is to control the flow of of -proxy requests along a chain of proxy servers. See RFC2068 (HTTP/1.1) -for an explanation of Via: header lines.

+

This directive controls the use of the Via: HTTP + header by the proxy. Its intended use is to control the flow of of + proxy requests along a chain of proxy servers. See RFC 2616 (HTTP/1.1), section + 14.45 for an explanation of Via: header lines.

-
  • If set -to off, which is the default, no special processing is -performed. If a request or reply contains a Via: header, -it is passed through unchanged.
    • +
      +
    • If set to Off, which is the default, no special processing + is performed. If a request or reply contains a Via: header, + it is passed through unchanged.
      • -
    • If set to on, each -request and reply will get a Via: header line added for -the current host.
      • +
    • If set to On, each request and reply will get a + Via: header line added for the current host.
      • -
    • If set to full, each generated Via: header -line will additionally have the Apache server version shown as a -Via: comment field.
      • +
    • If set to Full, each generated Via: header + line will additionally have the Apache server version shown as a + Via: comment field.
      • -
    • If set to block, every -proxy request will have all its Via: header lines -removed. No new Via: header will be generated.
      • -
    +
  • If set to Block, every proxy request will have all its + Via: header lines removed. No new Via: header will + be generated.
    • +
@@ -877,20 +899,18 @@ removed. No new Via: header will be generated. Override error pages for proxied content ProxyErrorOverride On|Off ProxyErrorOverride Off -server config -virtual host +server configvirtual host Available in version 2.0 and later -

This directive is useful for reverse-proxy setups, where you want to -have a common look and feel on the error pages seen by the end user. -This also allows for included files (via mod_include's SSI) to get -the error code and act accordingly (default behavior would display -the error page of the proxied server, turning this on shows the SSI -Error message).

+

This directive is useful for reverse-proxy setups, where you want to + have a common look and feel on the error pages seen by the end user. + This also allows for included files (via mod_include's SSI) to get + the error code and act accordingly (default behavior would display + the error page of the proxied server, turning this on shows the SSI + Error message).

 - diff --git a/docs/manual/mod/quickreference.html.de b/docs/manual/mod/quickreference.html.de index 988d2b8ae4..dc9c146eed 100644 --- a/docs/manual/mod/quickreference.html.de +++ b/docs/manual/mod/quickreference.html.de @@ -115,8 +115,8 @@ expressions Allow from all|host|env=env-variable [host|env=env-variable] ...dhBControls which hosts can access an area of the server -AllowCONNECT port [port] ... 443 563 svEPorts that are allowed to CONNECT through -the proxy +AllowCONNECT port [port] ... 443 563 svEPorts that are allowed to CONNECT through the +proxy AllowOverride All|None|Direktiven-Typ [Direktiven-Typ] ... All dCDirektiven-Typen, die in .htaccess-Dateien erlaubt sind. @@ -458,8 +458,8 @@ components as part of the filename a matching file with MultiViews NameVirtualHost Adresse[:Port]sCBestimmt eine IP-Adresse für den Betrieb namensbasierter virtueller Hosts -NoProxy host [host] ...svEHosts, domains, or networks that will be connected -to directly +NoProxy host [host] ...svEHosts, domains, or networks that will be connected to +directly NumServers number 2 sMTotal number of children alive at the same time NWSSLTrustedCerts filename [filename] ...sBList of additional client certificates Options @@ -473,35 +473,32 @@ evaluated. PidFile Dateiname logs/httpd.pid sMDatei, in welcher der Server die Prozess-ID des Daemons ablegt ProtocolEcho On|OffsvXTurn the echo server on or off -<Proxy wildcard-url> ...</Proxy>svEContainer for directives applied to proxied -resources +<Proxy wildcard-url> ...</Proxy>svEContainer for directives applied to proxied resources ProxyBadHeader IsError|Ignore|StartBody IsError svEDetermines how to handle bad header lines in a response -ProxyBlock *|word|host|domain -[word|host|domain] ...svEWords, hosts, or domains that are banned from being +ProxyBlock *|word|host|domain +[word|host|domain] ...svEWords, hosts, or domains that are banned from being proxied -ProxyDomain DomainsvEDefault domain name for proxied requests +ProxyDomain DomainsvEDefault domain name for proxied requests ProxyErrorOverride On|Off Off svEOverride error pages for proxied content -ProxyIOBufferSize bytessvEIO buffer size for outgoing HTTP and FTP -connections -<ProxyMatch regex> ...</ProxyMatch>svEContainer for directives applied to regular-expression-matched +ProxyIOBufferSize bytes 8192 svEDetermine size of internal data throughput buffer +<ProxyMatch regex> ...</ProxyMatch>svEContainer for directives applied to regular-expression-matched proxied resources -ProxyMaxForwards number 10 svEMaximium number of proxies that a request can be forwarded +ProxyMaxForwards number 10 svEMaximium number of proxies that a request can be forwarded through -ProxyPass [path] !|urlsvEMaps remote servers into the local server -URL-space -ProxyPassReverse [path] urlsvEAdjusts the URL in HTTP response headers sent from -a reverse proxied server -ProxyPreserveHost on|off Off svEUse incoming Host HTTP request header for -proxy request -ProxyReceiveBufferSize bytessvENetwork buffer size for outgoing HTTP and FTP +ProxyPass [path] !|urlsvdEMaps remote servers into the local server URL-space +ProxyPassReverse [path] urlsvdEAdjusts the URL in HTTP response headers sent from a reverse +proxied server +ProxyPreserveHost On|Off Off svEUse incoming Host HTTP request header for proxy +request +ProxyReceiveBufferSize bytes 0 svENetwork buffer size for proxied HTTP and FTP connections -ProxyRemote match remote-serversvERemote proxy used to handle certain requests -ProxyRemoteMatch regex remote-serversvERemote proxy used to handle requests -matched by regular expressions -ProxyRequests on|off Off svEEnables forward (standard) proxy requests -ProxyTimeout seconds 300 svENetwork timeout for proxied requests -ProxyVia on|off|full|block off svEInformation provided in the Via HTTP response +ProxyRemote match remote-serversvERemote proxy used to handle certain requests +ProxyRemoteMatch regex remote-serversvERemote proxy used to handle requests matched by regular +expressions +ProxyRequests On|Off Off svEEnables forward (standard) proxy requests +ProxyTimeout seconds 300 svENetwork timeout for proxied requests +ProxyVia On|Off|Full|Block Off svEInformation provided in the Via HTTP response header for proxied requests ReadmeName filenamesvdhBName of the file that will be inserted at the end of the index listing diff --git a/docs/manual/mod/quickreference.html.en b/docs/manual/mod/quickreference.html.en index a95f430cff..7e2f88d56c 100644 --- a/docs/manual/mod/quickreference.html.en +++ b/docs/manual/mod/quickreference.html.en @@ -111,8 +111,8 @@ expressions Allow from all|host|env=env-variable [host|env=env-variable] ...dhBControls which hosts can access an area of the server -AllowCONNECT port [port] ... 443 563 svEPorts that are allowed to CONNECT through -the proxy +AllowCONNECT port [port] ... 443 563 svEPorts that are allowed to CONNECT through the +proxy AllowOverride All|None|directive-type [directive-type] ... All dCTypes of directives that are allowed in .htaccess files @@ -445,8 +445,8 @@ components as part of the filename a matching file with MultiViews NameVirtualHost addr[:port]sCDesignates an IP address for name-virtual hosting -NoProxy host [host] ...svEHosts, domains, or networks that will be connected -to directly +NoProxy host [host] ...svEHosts, domains, or networks that will be connected to +directly NumServers number 2 sMTotal number of children alive at the same time NWSSLTrustedCerts filename [filename] ...sBList of additional client certificates Options @@ -460,35 +460,32 @@ evaluated. PidFile filename logs/httpd.pid sMFile where the server records the process ID of the daemon ProtocolEcho On|OffsvXTurn the echo server on or off -<Proxy wildcard-url> ...</Proxy>svEContainer for directives applied to proxied -resources +<Proxy wildcard-url> ...</Proxy>svEContainer for directives applied to proxied resources ProxyBadHeader IsError|Ignore|StartBody IsError svEDetermines how to handle bad header lines in a response -ProxyBlock *|word|host|domain -[word|host|domain] ...svEWords, hosts, or domains that are banned from being +ProxyBlock *|word|host|domain +[word|host|domain] ...svEWords, hosts, or domains that are banned from being proxied -ProxyDomain DomainsvEDefault domain name for proxied requests +ProxyDomain DomainsvEDefault domain name for proxied requests ProxyErrorOverride On|Off Off svEOverride error pages for proxied content -ProxyIOBufferSize bytessvEIO buffer size for outgoing HTTP and FTP -connections -<ProxyMatch regex> ...</ProxyMatch>svEContainer for directives applied to regular-expression-matched +ProxyIOBufferSize bytes 8192 svEDetermine size of internal data throughput buffer +<ProxyMatch regex> ...</ProxyMatch>svEContainer for directives applied to regular-expression-matched proxied resources -ProxyMaxForwards number 10 svEMaximium number of proxies that a request can be forwarded +ProxyMaxForwards number 10 svEMaximium number of proxies that a request can be forwarded through -ProxyPass [path] !|urlsvEMaps remote servers into the local server -URL-space -ProxyPassReverse [path] urlsvEAdjusts the URL in HTTP response headers sent from -a reverse proxied server -ProxyPreserveHost on|off Off svEUse incoming Host HTTP request header for -proxy request -ProxyReceiveBufferSize bytessvENetwork buffer size for outgoing HTTP and FTP +ProxyPass [path] !|urlsvdEMaps remote servers into the local server URL-space +ProxyPassReverse [path] urlsvdEAdjusts the URL in HTTP response headers sent from a reverse +proxied server +ProxyPreserveHost On|Off Off svEUse incoming Host HTTP request header for proxy +request +ProxyReceiveBufferSize bytes 0 svENetwork buffer size for proxied HTTP and FTP connections -ProxyRemote match remote-serversvERemote proxy used to handle certain requests -ProxyRemoteMatch regex remote-serversvERemote proxy used to handle requests -matched by regular expressions -ProxyRequests on|off Off svEEnables forward (standard) proxy requests -ProxyTimeout seconds 300 svENetwork timeout for proxied requests -ProxyVia on|off|full|block off svEInformation provided in the Via HTTP response +ProxyRemote match remote-serversvERemote proxy used to handle certain requests +ProxyRemoteMatch regex remote-serversvERemote proxy used to handle requests matched by regular +expressions +ProxyRequests On|Off Off svEEnables forward (standard) proxy requests +ProxyTimeout seconds 300 svENetwork timeout for proxied requests +ProxyVia On|Off|Full|Block Off svEInformation provided in the Via HTTP response header for proxied requests ReadmeName filenamesvdhBName of the file that will be inserted at the end of the index listing diff --git a/docs/manual/mod/quickreference.html.ja.jis b/docs/manual/mod/quickreference.html.ja.jis index a2bba8e69d..e047b6691d 100644 --- a/docs/manual/mod/quickreference.html.ja.jis +++ b/docs/manual/mod/quickreference.html.ja.jis @@ -110,8 +110,8 @@ MIME $B%?%$%W$K$h$C$FA*Br(B file-path|directory-pathsvB$B@55,I=8=$r;H$C$F(B URL $B$r%U%!%$%k%7%9%F%`$N0LCV$K%^%C%W$9$k(B Allow from all|host|env=env-variable [host|env=env-variable] ...dhB$B%5!<%P$N$"$kNN0h$K%"%/%;%9$G$-$k%[%9%H$r@)8f$9$k(B -AllowCONNECT port [port] ... 443 563 svEPorts that are allowed to CONNECT through -the proxy +AllowCONNECT port [port] ... 443 563 svEPorts that are allowed to CONNECT through the +proxy AllowOverride All|None|directive-type [directive-type] ... All dCTypes of directives that are allowed in .htaccess files @@ -439,8 +439,8 @@ using the specified magic file $B%U%!%$%k$N%?%$%W$r;XDj$9$k(B NameVirtualHost addr[:port]sCDesignates an IP address for name-virtual hosting -NoProxy host [host] ...svEHosts, domains, or networks that will be connected -to directly +NoProxy host [host] ...svEHosts, domains, or networks that will be connected to +directly NumServers number 2 sM$BF1;~$K5/F0$7$F$$$k;R%W%m%;%9$NAm?t(B NumServers number 2 sMTotal number of children alive at the same time NWSSLTrustedCerts filename [filename] ...sBList of additional client certificates @@ -454,35 +454,32 @@ directory PidFile filename logs/httpd.pid sM$B%G!<%b%s$N%W%m%;%9(B ID $B$r%5!<%P$,5-O?$9$k$?$a$N%U%!%$%k(B ProtocolEcho On|OffsvX$B%(%3!<%5!<%P$NM-8zL58z$r@_Dj$7$^$9!#(B -<Proxy wildcard-url> ...</Proxy>svEContainer for directives applied to proxied -resources +<Proxy wildcard-url> ...</Proxy>svEContainer for directives applied to proxied resources ProxyBadHeader IsError|Ignore|StartBody IsError svEDetermines how to handle bad header lines in a response -ProxyBlock *|word|host|domain -[word|host|domain] ...svEWords, hosts, or domains that are banned from being +ProxyBlock *|word|host|domain +[word|host|domain] ...svEWords, hosts, or domains that are banned from being proxied -ProxyDomain DomainsvEDefault domain name for proxied requests +ProxyDomain DomainsvEDefault domain name for proxied requests ProxyErrorOverride On|Off Off svEOverride error pages for proxied content -ProxyIOBufferSize bytessvEIO buffer size for outgoing HTTP and FTP -connections -<ProxyMatch regex> ...</ProxyMatch>svEContainer for directives applied to regular-expression-matched +ProxyIOBufferSize bytes 8192 svEDetermine size of internal data throughput buffer +<ProxyMatch regex> ...</ProxyMatch>svEContainer for directives applied to regular-expression-matched proxied resources -ProxyMaxForwards number 10 svEMaximium number of proxies that a request can be forwarded +ProxyMaxForwards number 10 svEMaximium number of proxies that a request can be forwarded through -ProxyPass [path] !|urlsvEMaps remote servers into the local server -URL-space -ProxyPassReverse [path] urlsvEAdjusts the URL in HTTP response headers sent from -a reverse proxied server -ProxyPreserveHost on|off Off svEUse incoming Host HTTP request header for -proxy request -ProxyReceiveBufferSize bytessvENetwork buffer size for outgoing HTTP and FTP +ProxyPass [path] !|urlsvdEMaps remote servers into the local server URL-space +ProxyPassReverse [path] urlsvdEAdjusts the URL in HTTP response headers sent from a reverse +proxied server +ProxyPreserveHost On|Off Off svEUse incoming Host HTTP request header for proxy +request +ProxyReceiveBufferSize bytes 0 svENetwork buffer size for proxied HTTP and FTP connections -ProxyRemote match remote-serversvERemote proxy used to handle certain requests -ProxyRemoteMatch regex remote-serversvERemote proxy used to handle requests -matched by regular expressions -ProxyRequests on|off Off svEEnables forward (standard) proxy requests -ProxyTimeout seconds 300 svENetwork timeout for proxied requests -ProxyVia on|off|full|block off svEInformation provided in the Via HTTP response +ProxyRemote match remote-serversvERemote proxy used to handle certain requests +ProxyRemoteMatch regex remote-serversvERemote proxy used to handle requests matched by regular +expressions +ProxyRequests On|Off Off svEEnables forward (standard) proxy requests +ProxyTimeout seconds 300 svENetwork timeout for proxied requests +ProxyVia On|Off|Full|Block Off svEInformation provided in the Via HTTP response header for proxied requests ReadmeName filenamesvdhB$B%$%s%G%C%/%90lMw$N:G8e$KA^F~$5$l$k%U%!%$%k$NL>A0(B Redirect [status] URL-path