Module mod_proxy

The AllowCONNECT directive specifies a list of port numbers the server allows clients to specify when using the CONNECT method. Clients use the CONNECT method when HTTPS connections are 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 this directive to override the default and only allow connections that use one of the listed ports.

Parameter: port_list

• The port_list parameter can consist of a string of port numbers separated by spaces (see example).

Example

AllowCONNECT 443 563 1070 8088

• ProxyBlock may be used to block incoming requests prior to this directive's consideration.
• Setting ProxyRequests to off negates this directive.

This directive may be configured multiple times in a container. The directives are processed from the first to the last occurrence.

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

The NoProxy directive specifies a list of domains, subnets, IP addresses, and/or hosts (in any combination) separated by spaces. Multiple NoProxy directives are allowed. Items in each list are used to match requests for which the server should attempt to handle directly rather than going through a remote proxy server (specified using the ProxyRemote directive). When a client sends a request that matches one or more listed items, the server attempts to connect directly to the server specified in the URL rather than to a remote proxy (specified by ProxyRemote) to chain the request.

Parameter: domain | subnet | ipaddr | hostname

• A domain is a partially qualified DNS domain name, preceded by a period. It represents a group of hosts that logically belong to the same DNS domain or zone (that is, the suffixes of the hostnames are all ending in Domain).
• A subnet is a partially qualified Internet address in a 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 that can be reached over a common network interface. In the absence of the explicit netmask 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. For example, the subnet '192.168.0.0' with an implied netmask of '16' valid bits (sometimes used in the netmask form 255.255.0.0.).
• An 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. For example: 192.168.123.7
• A hostname is a fully qualified DNS domain name that can be resolved to one or more IP addresses via the DNS domain name service. It represents a logical host (in contrast to domain, see above) and must be resolvable to at least one ipaddr (or often to a list of hosts with different IP addresses).

Example

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

• ProxyBlock may be used to block incoming requests prior to consideration for this directive.
• This directive is commonly used in conjunction with the ProxyRemote and ProxyDomain directives for directing proxy requests within intranets.
• Setting ProxyNoConnect to on negates this directive.

This directive may be configured multiple times in a container. The directives are processed from the first to the last occurrence.

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

<Proxy http://www.ibm.com/>
 Allow from All
 Order Allow,Deny
</Proxy>

<Proxy /docs/>
 Allow from All
 Order Allow,Deny
</Proxy>

The <Proxy> and </Proxy> directives are used to enclose (or contain) a group of directives that apply only to proxy requests that match the specified criteria. Multiple proxy containers are allowed, however they may not be nested. Requests that do not match container criteria are outside the context of the enclosed directives. Any directive allowed within a directory context is also allowed within a proxy context (see <Directory> for details on directory containers).

Parameter: criteria

• The criteria parameter accepts a partial URL or virtual directory path used to identify requests to which the enclosed directives apply. Partial URLs are used to identify both forward and reverse proxy requests. A match is considered by comparing request URL strings to the specified criteria string, starting with the first character. A match is made if the two strings are identical, up to the length of the criteria string.

  Refer to <ProxyMatch> for details regarding the use of regular expression criteria for proxy containers.

  Directives within proxy containers apply only to matched requests handled by the proxy function (including both forward and reverse proxy). Requests not handled by the proxy function are not affected by directives within proxy containers.

Example One

<Proxy /user/local/httpd/htdocs>
 Allow from All
 Order Allow,Deny
</Proxy>

Note: Previously, directory containers were used to enclose groups of directives that applied to proxy requests by appending the prefix "proxy:" to the beginning of the directory name criteria specified for <Directory> or <DirectoryMatch> directives. This is no longer supported. The proxy function now ignores directives enclosed in <Directory> (or <File>) containers.

Directives within <Location> containers (if matched) take precedence over directives within <Proxy> containers. See <Location> or <LocationMatch> for more information on <Location> containers.

When request URLs match criteria strings of multiple proxy containers, directives within all matched containers are combined and applied. <Proxy> sections are processed in the order they appear in the configuration file. The following is an example of how directives are combined and applied according to order.

Example Two: Forward Proxy

ProxyRequest on
<Proxy http://>
 Deny from All
 ServerSignature on
</Proxy>
<Proxy http://www.ibm.com/>
 Allow from All
</Proxy>

For this example, a request for http://www.ibm.com/docs/whitepaper.pdf matches criteria specified for both proxy containers, therefore the server applies the directives within both containers. Since the criteria specified for the second container (<Proxy http://www.ibm.com/>) is more specific (a better match) than the criteria specified for the first container (<Proxy http://>) directives enclosed within the second container take precedence. The request is therefore allowed since the second container has an "Allow from All" directive. The ServerSignature directive would be applied to this request as well (if needed). A request for http://web.samples.org/welcome.htm, however, only matches the criteria for the first container, and is therefore denied since this container has a "Deny from All" directive.

If request URLs match criteria strings for one or more <Proxy> directives as well as regular expression criteria for one or more <ProxyMatch> directives, the server applies matched <Proxy> and <ProxyMatch> container directives in the order they appear in the configuration file.

Example:

ProxyRequest on
<Proxy http://www.ibm.com/>
 Allow from All
</Proxy>
<ProxyMatch ^(.*)>
 Deny from All
</ProxyMatch>

A request for http://www.ibm.com/welcome.html matches criteria specified for both proxy containers, therefore the server applies the directives within both containers. Directives for the <Proxy> container are applied first, then directives for the <ProxyMatch> container. Due to the order that directives are applied, the request is denied since the "Deny from All" directive (from the <ProxyMatch> container) is applied last, eveh though the <Proxy> container is a more exact match.

This directive tells the server how to handle a bad header line in a response. The value ignore means the proxy ignores the bad header and continues. The value IsError means that the proxy fails out on the request. The value StartBody means that proxy (if it has seen other headers before this bad one) starts sending the rest of the headers as body and hopes that the server can handle it.

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

The ProxyBlock directive specifies a list of words, hosts, and/or domains (in any combination), separated by spaces. Multiple ProxyBlock directives are allowed. Requests to sites whose URLs contain matched words, hosts, or domains are blocked by the server. At startup the server attempts to determine list item IP addresses, that may be host names, and records them for a match test.

Parameter: word | host | domain

• A word can be any keyword (for example, ProxyBlock hello server good-bye).
• A host is a fully qualified DNS domain name that can be resolved to one or more IP addresses via the DNS domain name service. It represents a logical host (in contrast to domain, see below) and must be resolvable to at least one IP address (or often to a list of hosts with different IP addresses), otherwise it is simply treated as a word (see above).
• A domain is a partially qualified DNS domain name, preceded by a period. It represents a group of hosts that logically belong to the same DNS domain or zone (that is, the suffixes of the hostnames are all ending in Domain).

Example

ProxyBlock ibm.com www-1.ibm.com www-2.ibm.com server hello

The 'www-2.ibm.com' would also be matched if referenced by IP address since the server records addresses at startup for a match test. Note that either 'ibm.com' or 'ibm' is sufficient to match both 'www-1.ibm.com' and 'www-2.ibm.com' by word. However, their corresponding IP addresses would not be blocked since the server could not determine their addresses without having their hostnames specifically listed.

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

The ProxyCacheOnly directive specifies a list of words, hosts, and domains (in any combination), separated by spaces. Multiple ProxyCacheOnly directives are allowed. Listed items are used to match requests for which the server should cache documents if caching is enabled. The server may then serve cached documents for subsequent requests. The server will also attempt to determine list item IP addresses and records them for a match test.

If this directive is absent, all documents satisfying all other caching directives (for example, ProxyNoCache, CacheMaxFileSize, CacheMinFileSize, etc.) are cached. If this directive is present, only documents from matched words, hosts, or domains are cached (as long as they also satisfy all other caching directives).

Parameter: word | host | domain

• A word can be any keyword (for example, ProxyCacheOnly hello server good-bye).
• A host is a fully qualified DNS domain name that can be resolved to one or more IP addresses via the DNS domain name service. It represents a logical host (in contrast to domain, see below) and must be resolvable to at least one IP address (or often to a list of hosts with different IP addresses), otherwise it is simply treated as a word (see above).
• A domain is a partially qualified DNS domain name, preceded by a period. It represents a group of hosts that logically belong to the same DNS domain or zone (that is, the suffixes of the hostnames are all ending in Domain).

Example

ProxyCacheOnly ibm.com www-1.ibm.com sample.server.edu

For this example, 'sample.server.edu' would also be matched if referenced by IP address since the server records addresses at startup for a match test. Note that 'sample', 'server', 'edu', 'sample.server', or 'server.edu' is sufficient to match 'sample.server.edu' by word, however documents for requests using IP addresses corresponding to 'sample.server.edu' would not be cached since the server could not determine the addresses unless the hostname is specifically listed.

• CacheMinFileSize, CacheMaxFileSize, and CacheTimeMargin may make documents ineligible for cache prior to consideration for this directive.
• ProxyNoCache provides counter function. Documents matching a previous ProxyNoCache template in the configuration will not be cached, regardless of whether they match a subsequent ProxyCacheOnly template. In other words, a ProxyNoCache directive may override a ProxyCacheOnly directive if configured prior to the ProxyCacheOnly directive.
• This directive is used only if CacheRoot is set.
• Setting ProxyNoConnect to off negates this directive.

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

The ProxyDomain directive specifies the default domain to which the server belongs when acting as a forward proxy server. If a request specifies a host without a domain name, the server sends a response that redirects the client to the host with the configured domain appended. Possible values include all domain names starting with a dot (or period) and consisting only of the characters AZ, AZ, '.' (dot), '-' (dash), and 0-9.

Parameter: domain

• The domain is a partially qualified DNS domain name, preceded by a period. It represents a group of hosts that logically belong to the same DNS domain or zone (that is, the suffixes of the hostnames are all ending in Domain).

Example

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

For this example, if an unqualified request for http://myserver/ comes in, the server will redirect the client to a fully qualified host name using the default domain. That is, the client will be redirected to http://myserver.mycompany.com/.

• ProxyBlock may be used to block incoming requests prior to consideration for this directive.
• This directive is commonly used in conjunction with the NoProxy and ProxyRemote directives for directing proxy requests within intranets.
• Setting ProxyRequests to off negates this directive

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

The ProxyErrorOverride directive specifies if the server is to override error response codes and message text sent by remote servers to enable local error messaging for remote server problems. If disabled (the default), all responses sent by remote servers (including errors) are relayed to clients (local error messaging is not used). If enabled, server related error codes and messages sent by remote servers (codes greater than or equal to 400) are overridden and local error messaging is used to send responses that pertain to the local server, rather than the remote server. Non-server related error codes (codes less than 400) are not affected by this directive and are always relayed to clients.

Parameter: on | off

• If off, is specified (the default), all response codes and messages sent by remote servers are relayed to clients (unaltered).
• If on is specified, error response codes and messages sent by remote servers relating to server problems are overridden and local error messaging is used to send responses to clients.

By default, local error messaging will send hardcoded messages to clients. However, it may be configured to send custom web pages as well, or to redirect certain errors to local CGI programs (or servlets) or remote servers to handle. When ProxyErrorOverride is used in conjunction with ErrorDocument support, custom responses may be sent to clients when proxy requests fail due to remote server problems. This is useful for reverse proxy setups where remote server problems need to be concealed from clients or when web sites must have a common error reporting appearance. It may be used, however, for any proxy setup where remote server errors need to be handled in a certain (customized) manner.

For example, suppose the local server has address http://www.ibm.com/ and the following directives are setup for reverse proxy:

ProxyPass /docs/ http://pubserver.ibm.com/public/documentation/
ProxyErrorOverride on
ErrorDocument proxyrmterror /cgi-bin/proxyerr.pgm

Now further suppose the local server was sent the request http://www.ibm.com/docs/whitepaper.html. The ProxyPass directive will cause the request to be internally converted into a request for http://pubserver.ibm.com/public/documentation/whitepaper.html. The proxy function will then be invoked to retrieve /public/documentation/whitepaper.html from pubserver.ibm.com. The remote server (pubserver.ibm.com) then has an error that causes it to return response code 500 (internal error) to the local server (www.ibm.com). Since ProxyErrorOverride is enabled, the local server overrides the response code (along with any message text) and enables local error messaging to handle the response. Furthermore, since ErrorDocument is setup for such a response (proxyrmterror), the error is passed to the cgi program /cgi-bin/proxyerr.pgm which handles the problem by sending a customized error page to the client.

In this example of a reverse proxy request process, internal server errors from a remote server (pubserver.ibm.com) are concealed from the client since local error messaging is enabled for proxy requests on www.ibm.com. Similar handling may be setup for forward proxy scenarios as well.

• If custom error messages are not defined (not enabled via ErrorDocument), local error messaging may still be used to send hardcoded messages pertaining to the local server.
• Setting ProxyRequests to off does not negate this directive. It is available regardless of the forward proxy state.

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

ProxyReverse on
ProxyPass /docs/v4r4m0/ http://pubserver.ibm.com/public/v4r4m0/
<ProxyMatch "^http://pubserver.ibm.com/public/v[0-9]r[0-9]m[0-9]/(.*)"> 
 Allow from All
 Order Allow,Deny
</ProxyMatch>

<ProxyMatch "^http://server[0-9]r[0-9]m[0-9]/docs/*">
 Allow from All
 Order Allow,Deny
</ProxyMatch>

The <ProxyMatch> directive is used to enclose a group of directives that apply only to proxy requests that match the specified criteria. Multiple proxy containers are allowed, however they may not be nested. Requests that do not match container criteria are outside the context of the enclosed directives. Any directive allowed within a directory context is also allowed within a proxy context.

Parameter: criteria

• The criteria parameter accepts a UNIX-style extended regular expression used to identify requests to which the enclosed directives apply. Expressions are used to identify both forward and reverse proxy requests. A match is considered by comparing request URL strings to the specified expression. Subexpressions are grouped within parentheses. Then, parenthetically enclosed regular expressions are substituted in a subsequent $n statement. A match is made if the URL string matches the expression using regular expression logic. For reverse proxy, the specified expression must match the new outgoing URL.

Proxy containers defined by <ProxyMatch> directives (including the directives enclosed by them) are handled in the same way as those defined by <Proxy> directives. The only difference is in how the criteria is specified and handled using regular expressions (for <ProxyMatch>) rather than string literals (for <Proxy>). Refer to <Proxy> for further details regarding proxy containers.

For example, suppose the local server has address http://as400.ibm.com/ and the following directives are setup for reverse proxy:

Example

ProxyPass /v4r3m0/docs/ http://pubserver.ibm.com/public/vrm430/
ProxyPass /v4r4m0/docs/ http://pubserver.ibm.com/public/vrm440/
ProxyPass /v4r5m0/docs/ http://pubserver.ibm.com/public/vrm450/
ProxyPass /v5r1m0/docs/ http://pubserver.ibm.com/public/vrm510/
<ProxyMatch "^http://pubserver.ibm.com/public/v[0-9]r[0-9]m[0-9]/(.*)">
 AuthName "iSeries Document Server"
 AuthType Basic
 Require group admin
 PasswdFile QUSRSYS/DOC_USERS
 GroupFile /groups/doc_readers
</ProxyMatch>

For this example, a request for /v4r5m0/docs/manual.html is identified as a proxy request since it matches the third ProxyPass statement (ProxyPass /v4r5m0/docs/ http://pubserver.ibm.com/public/vrm450/). Once identified as a proxy request, it is compared against criteria specified for the proxy container (ProxyMatch "^http://pubserver.ibm.com/public/v[0-9]r[0-9]m[0-9]/(.*)") using regular expression logic. A match is made and the server applies the directives within the container that requires the client to provide basic authentication credentials (AuthType Basic). If the client is authenticated (PasswdFile QUSRSYS/DOC_USERS) and authorized (GroupFile /groups/doc_readers, or Require group admin) the request will be internally converted into a request for http://publicserver.ibm.com/public/vrm450/manual.html and further handled by the proxy function (see ProxyPass for more information on reverse proxy). If the client is not authenticated or authorized, the request fails.

• The client is authenticated if a valid userid and password is provided, according to the PasswdFile directive.
• The client is authorized if the userid (or group) is allowed access, according to the GroupFile or Require directives.

Notice that in the above example the directives enclosed in the proxy container will apply to requests matching any of the ProxyPass directives since the regular expression criteria (specified for <ProxyMatch>) matches all four virtual directory path names specified for ProxyPass.

• Setting ProxyRequests to off does not negate this directive. It is available regardless of the forward proxy state.

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

The ProxyMaxForwards directive specifies the value the server is to use when adding Max-Forwards request headers to requests that do not contain a Max-Forwards header. When the server receives requests that do not contain a Max-Forwards header, it automatically adds one using the specified value. This setting is not used for requests that already contain a Max-Forwards header.

Parameter: maximum

• The maximum parameter accepts an integer value between 1 and 2,147,483,648 to specify the value the server is to use when it adds Max-Forwards request headers to proxy requests.

The server uses Max-Forwards headers to prevent infinite proxy loops, and possibly certain types of denial of service attacks. This is accomplished by ensuring that a Max-Forwards header is set for all requests to control the maximum number of times it can be forwarded (or passed to subsequent servers).

When the server receives requests containing a Max-Forwards header, it will continue to process the requests only if the value for the header is greater than 0 (zero). If the value is greater than zero, the server decrements it and continues to process the request. If the request subsequently needs to be forwarded to another server, the Max-Forwards header is sent with the decremented value. This process is repeated until the request is fulfilled (or rejected) by a server, or until the value for the Max-Forwards header reaches zero. Once the value reaches zero (or less), the server will not forward the request and will respond immediately (see example, request 3) with the following response codes:

• If TRACE method is used, 200 (OK) is returned as well as any trace data.
• If OPTIONS method is used, 200 (OK) is returned as well as any options data.
• If any other method is used, 502 (BAD_GATEWAY) is returned as well as the server's customized error page for "proxyfail" (if enabled, see ErrorDocument).

This setting is used for both forward and reverse proxy requests.

Example: Forward Proxy

ProxyRequests on
ProxyMaxForwards 8

For this example, consider the following three requests:

Request 1

GET http://docserver.ibm.com/manual.pdf HTTP/1.0

For this request, the server will use the value specified for ProxyMaxForwards (8) to add the new header "Max-Forwards : 8" to the request (since it is not already present), and then forward it to docserver.ibm.com as:

GET /manual.pdf HTTP/1.0
Max-Forwards : 8

Request 2

GET http://docserver.ibm.com/manual.pdf HTTP/1.0
Max-Forwards : 3

For this request, the server will decrement the value for the Max-Forwards header to 2, and then forward the request to docserver.ibm.com as:

GET /manual.pdf HTTP/1.0
Max-Forwards : 2

In this case, the value specified for ProxyMaxForwards is not used since the request already contained a Max-Forwards header.

Request 3

GET http://docserver.ibm.com/manual.pdf HTTP/1.0
Max-Forwards : 0

For this request, the server will immediately return response code 502 (BAD_GATEWAY) since the request cannot be forwarded any further due to the Max-Forwards header value. In this case, docserver.ibm.com is never contacted.

• Setting ProxyRequests to off does not negate this directive. It is available regardless of the forward proxy state.

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

The ProxyNoCache directive specifies a list of words, hosts, and domains (in any combination), separated by spaces. HTTP and non-passworded FTP documents from matched words, hosts or domains are not cached by the proxy server. The proxy module will also attempt to determine IP addresses of list items, that may be hostnames during startup, and cache them for a match test. If this directive is absent, all documents satisfying all other caching directives (for example: ProxyCacheOnly, CacheMaxFileSize, CacheMinFileSize, etc.) are cached. If this directive is present, documents from matched words, hosts or domains are not cached.

Parameter: word | host | domain

• A word can consist of any combination of keywords (for example, ProxyNoCache hello server good-bye).
• The host is a fully qualified DNS domain name that can be resolved to one or more IP address via the DNS domain name service. It represents a logical host (in contrast to domain, see above) and must be resolvable to at least one IP address (or often to a list of hosts with different IP addresses).
• The domain is a partially qualified DNS domain name, preceded by a period. It represents a list of hosts that logically belong to the same DNS domain or zone (that is, the suffixes of the hostnames are all ending in Domain).

Example

ProxyNoCache ibm.com www-1.ibm.com sample.example.edu

The 'sample.example.edu' would also be matched if referenced by IP address. Note that 'example ' is sufficient to match 'example.edu'.

• ProxyCacheOnly provides counter function. Documents matching a previous ProxyCacheOnly template in the configuration will be cached, regardless of whether they match a subsequent ProxyNoCache template. In other words, a ProxyCacheOnly directive may override a ProxyNoCache directive if configured prior to the ProxyNoCache directive.
• This directive is used only if CacheRoot is set.
• Setting ProxyRequests to off negates this directive.

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

The ProxyNoConnect directive specifies if the proxy is to connect to remote content servers to retrieve documents. If the server is not allowed to connect to remote content servers, it can only serve documents from cache.

Parameter: on | off

• If off is specified, the server may serve documents from cache (if enabled) as well as issue outgoing requests to remote servers to retrieve servable documents (see Example 1, below).
• If set to on is specified, the proxy may only serve documents from cache (if enabled). It will not establish outgoing connections with remote servers. CacheRoot is required if on is specified (see Example 2, below).

Example 1

ProxyRequests on
ProxyNoConnect off
CacheRoot /QOpenSys/UserData/HTTPA/CacheRoot/myproxy

In this example, the proxy may serve documents from cache as well as issue outgoing requests to remote servers.

Example 2

ProxyRequests on
ProxyNoConnect on
CacheRoot /QOpenSys/UserData/HTTPA/CacheRoot

In this example, the proxy may only serve documents from cache. Documents will not be retrieved from remote servers since outgoing connections are not permitted. Since the server is not permitted to retrieve documents, items in cache must be managed by another application or process other than the server itself.

• CacheRoot is required if this directive is set to on.
• The ProxyNoConnect directive causes the AllowCONNECT directive to be ineffective. If ProxyNoConnect is present, and AllowCONNECT is also specified, then even if the AllowCONNECT allows a SSL connection to be made on a specific port, the ProxyNoConnect directive dictates that no connections are allowed.

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

ProxyPass /docs/confidential/ !
ProxyPass /docs/ http://pubserver.ibm.com/public/documentation/

The ProxyPass directive specifies information used either to identify and map requests into the space of remote servers, or to prevent requests from being mapped into the space of remote servers, when the reverse proxy function is enabled. Multiple ProxyPass directives are allowed. When enabled, the server does not act as a proxy in the conventional sense, but appears to be a mirror of remote servers by transforming requests that match specified (virtual) directory paths into proxy requests using a corresponding partial URL. If the reverse proxy function is not enabled, this directive has no affect (see ProxyReverse).

Parameter One: path | url

• The path parameter is the name of a local virtual path. When the directive is placed outside a location container, the first parameter accepts a directory name used to identify requests to be handled by the proxy function. The directory name does not need to specify an existing directory, it may be a name used only as a virtual directory for the server.
• The url parameter is a partial URL for the remote server. When the directive is placed inside a location container, the first parameter accepts a partial URL used to transform matched requests (for the location container) into proxy requests. When matched, the portion of the original request URL that matches the location container criteria is replaced with the specified partial URL. Mapped requests are then handled by the proxy function (see example two).

Parameter Two: url | !

• The url | ! parameter is used when the directive is placed outside a location container, the second parameter accepts a partial URL or the negation operator (!). Partial URLs are used to transform matched requests into proxy requests by replacing the portion of the original request URL that matches the path parameter (parameter one) with the specified partial URL (parameter two). Mapped requests are then handled by the proxy function. The negation operator is used to prevent requests that match the path parameter (parameter one) from being mapped and handled by the proxy function, even though they may match a succeeding ProxyPass directive. Example one, below, shows both partial URLs and the negation operator being used for multiple ProxyPass directives.
• When the directive is placed inside a location container a second parameter cannot be specified.

The server functions as a reverse proxy by mapping requests for documents inside virtual directories (specified by the path parameter or location container criteria) into the space of remote servers (specified by the url parameter). It then retrieves the documents (via proxy), and serves them while making it appear to the client as if they originated from the local server.

The negation operator (!) is used to prevent specific virtual subdirectories to be mapped into the space of remote servers, while allowing higher level (parent) directories to be mapped. Order is important in these situations. ProxyPass directives using the negation operator to prevent specific virtual subdirectories from being mapped must be placed before those mapping higher level (parent) directories (see example one).

Suppose the local server has address http://iseries.ibm.com/:

Example 1

ProxyReverse on
ProxyPass /docs/v4r5m0/ http://pubserver.ibm.com/public/v4r5m0/
ProxyPass /docs/archives/confidential/ !
ProxyPass /docs/archives/private/ !
ProxyPass /docs/archives/ http://pubserver.ibm.com/archives/documents/example

For this example, since the reverse proxy function is enabled (ProxyReverse on), the first ProxyPass directive will cause a local request for /docs/v4r5m0/manual.html to be internally transformed into a request for http://pubserver.ibm.com/public/v4r5m0/manual.html. The proxy function will then be used to retrieve /public/v4r5m0/manual.html from pubserver.ibm.com and return the document to the requesting client. In this way, a virtual /docs/v4r5m0/ directory on the local server (as400.ibm.com) appears as a mirror of the /public/v4r5m0/ directory of the remote server (pubserver.ibm.com). A request for /docs/archives/20020101.log will be handled in a similar way, using the last ProxyPass directive (ProxyPass /docs/archives/ http://pubserver.ibm.com/archives/documents/). However, a request for /docs/archives/confidential/secrets.txt will not be handled by the proxy function since the second ProxyPass directive prohibits any request for documents within the /docs/archives/confidential/ virtual subdirectory. Likewise, the third ProxyPass directive prohibits any request for documents within the /docs/archives/private/ virtual subdirectory.

The following example shows the ProxyPass directive being used within a location container to obtain results similar to example 1.

Example Two

ProxyReverse on
<Location /docs/v4r5m0/>
 ProxyPass http://pubserver.ibm.com/public/v4r5m0/ 
</Location>
ProxyPass /docs/archives/confidential/ !
ProxyPass /docs/archives/private/ !
ProxyPass /docs/archives/ http://pubserver.ibm.com/archives/documents/

Notice the first ProxyPass directive is placed within a location container and specifies only one parameter. A local request for /docs/v4r5m0/manual.html is identified by matching the location container criteria (/docs/v4r5m0/), transformed into a request for http://pubserver.ibm.com/public/v4r5m0/manual.html by replacing the matched portion with the ProxyPass parameter, and handled by the proxy function in the same way described for example one.

• ProxyPassReverse may be used to handle HTTP redirect responses from remote servers.
• Setting ProxyReverse to off negates this directive.
• Setting ProxyRequests to off does not negate this directive. It is available regardless of the forward proxy state.

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

The ProxyPassReverse directive may specify a directory path and a partial URL used to identify and adjust URLs in response headers returned to the client (via proxy). Multiple ProxyPassReverse directives are allowed. The server adjusts the values for URI, Location, and Content-Location response headers according to the specified values.

Parameter One: path | url

• The path parameter is the name of a local virtual path. When the directive is placed outside a location container, the first parameter accepts a directory name used to adjust response header values. If URLs specified in response headers match the url parameter (parameter two), the portion that matches is replaced with the specified directory name. Adjusted headers are then returned to the client. The directory name does not need to specify an existing directory, it may be a name used only as a virtual directory for the server.
• The url parameter is a partial URL for the remote server. When the directive is placed inside a location container, the first parameter accepts a partial URL used to identify URLs in URI, Location, and Content-Location response headers returned to the server as requested by the proxy function. If any of these request headers match the specified partial URL, the portion that matches is replaced with the directory name specified for the location container. Adjust headers are then returned to the client.

Parameter Two: url

• The url parameter is a partial URL for the remote server. When the directive is placed outside a location container, the second parameter accepts a partial URL used to identify URLs in URI, Location, and Content-Location response headers returned to the server as requested by the proxy function.
• When the directive is placed inside a location container a second parameter cannot be specified.

This directive provides support to be used in applications when it is essential that clients are not directed to use URLs that bypass the proxy function. It is mainly intended to provide additional function for reverse proxy, however it may also be applied to forward proxy requests handled by the server.

Suppose the local server has address http://iseries.ibm.com:

Example

ProxyReverse on
ProxyPass /docs/v4r4m0/ http://pubserver.ibm.com/public/v4r4m0/
ProxyPass /docs/v4r5m0/ http://pubserver.ibm.com/public/v4r5m0/
ProxyPass /docs/v5r1m0/ http://pubserver.ibm.com/public/v5r1m0/
ProxyPassReverse /docs/ http://pubserver.ibm.com/public/
ProxyPass /docs/archives/ http://pubserver.ibm.com/archives/

For this example, since the reverse proxy function is enabled (ProxyReverse on), a request for /docs/v4r4m0/api_reference.htm will be internally transformed into a proxy request for http://pubserver.ibm.com/public/v4r4m0/API_reference.htm (the functionality the first ProxyPass directive provides here). The use of ProxyPassReverse adjusts URLs in URI, Location, and Content-Location response headers from pubserver.ibm.com. Therefore, when the server's request is subsequently redirected by pubserver.ibm.com with the following response:

301 "Permanently Moved"
Location: http://pubserver.ibm.com/public/archives/440/API_reference.htm
{other response headers}

{optional body text}

The server changes the matching portion of the URL in the Location header (http://pubserver.ibm.com/public/) to the virtual server path (/docs/) before sending the following (adjusted) response to the client:

301 "Permanently Moved"
Location: http://as400.ibm.com/docs/archives/440/API_reference.htm
{other response headers}

{optional body text}

In this way, any new request the client sends due to the redirect response (301 "Permanently Moved") is directed back to the proxy since the Location header is adjusted. The back end server and path name (http://pubserver.ibm.com/public/) remain hidden from the client.

• This directive is only useful when used in conjunction with the ProxyPass directive.
• Setting ProxyReverse to off negates this directive.
• Setting ProxyRequests to off does not negate this directive. It is available regardless of the proxy state.

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

The ProxyPreserveHost directive specifies whether the server is to preserve Host: headers when handling requests using the reverse proxy function.

Parameter: on | off

• If off is specified (the default), the server generates Host: headers for requests handled by the reverse proxy function, using the hostname (and optionally a port number) specified for the ProxyPass or RewriteRule directives.
• If on is specified, the server uses Host: headers sent with requests, rather than generating Host: headers, and uses the hostname (and optional port) specified for the ProxyPass or RewriteRule directives only to route the request.

Suppose, for example, the local server has the address http://as400.ibm.com/ with the following directive set up for reverse proxy:

Example

ProxyPass /docs/ http://pubserver.ibm.com:8080/public/documentation/
ProxyPreserveHost on

The server in this example is sent the following request:

GET /docs/manual.html HTTP/1.0
Host: virtual-host.ibm.com
{other request headers}

{optional body text}

The ProxyPass directive will cause the request to be internally transformed into a request for http://pubserver.ibm.com:8080/public/documentation/manual.html, and the ProxyPreserveHost directive will cause the Host: header to be preserved and passed by the proxy function, resulting in the following request sent to pubserver.ibm.com:

GET /public/documentation/manual.html HTTP/1.0
Host: virtual-host.ibm.com
{other request headers}

{optional body text}

If off were specified for ProxyPreserveHost, the Host: header would not be preserved. The server, in this case, would generate a Host: header, resulting in the following request:

GET /public/documentation/manual.html HTTP/1.0
Host: pubserver.ibm.com:8080
{other request headers}

{optional body text}

• ProxyPassReverse may be used to handle HTTP redirect responses from remote servers.
• Setting ProxyReverse to off negates this directive.
• Setting ProxyRequests to off does not negate this directive. It is available regardless of the forward proxy state.

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

Parameter: bytes

• The bytes parameter has to be greater than '512' or set to '0' to indicate that the system's default buffer size should be used.

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

The ProxyRemote directive defines remote proxies for the local server. Multiple ProxyRemote directives are allowed. When a client sends a request that matches a ProxyRemote directive, the local server connects to the remote proxy server specified in the directive, rather than to the server specified in the URL. The remote proxy server retrieves the requested document and returns it to the local server, who in turn returns it to the client. This is referred to as a "proxy chain" since more than one proxy is used.

Proxy chains are useful in cases where multiple caches are used, or when the local server doesn't support the protocol (or schema) specified in the URL and must chain the request to a proxy that does support the protocol. Proxy chains may also be useful in cases where certain requests must be chained to another proxy server in order to get through a firewall or route across a virtual private network.

Parameter One: match

• The match parameter is either the name of a URL scheme that the remote proxy server supports, a partial URL that can be used to distinguish requests that should be chained from requests that need not be chained, or '*' to indicate the remote proxy server should be contacted (or chained) for all requests.

Parameter Two: remote-server

• The remote-server parameter is a partial URL for the remote server.

  Syntax: <remote-server>=<protocol>://<hostname>[:port]

  Where <protocol> is the protocol that should be used to communicate with the remote server. Only HTTP is supported by this module.

Example 1

ProxyRemote ftp http://ftpproxy.server.com:8080

Example 2

ProxyRemote http://server.com/ http://mirrorserver.com:8000

Example 3

ProxyRemote * http://server.com

In example 1, the server will forward (or chain) all FTP requests, encapsulated as yet another HTTP proxy request, to the server named ftpproxy.server.com (port 8080), which then handles the request and returns the document to the local server.

In example 2, the server will forward all requests that match the partial URL http://server.com/ to the server named mirrorserver.com (port 8000).

In example 3, all requests will be forwarded to the server named server.com.

• ProxyBlock may be used to block incoming requests prior to consideration for this directive.
• Requests matching a NoProxy directive are not chained.
• This directive is commonly used in conjunction with NoProxy and ProxyDomain for directing proxy requests within intranets.
• Setting ProxyNoConnect to on negates this directive.

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

The ProxyRequest directive allows or prevents the server from functioning as a forward proxy.

Parameter: on | off

• If set to off , the server does not function as a forward proxy (see Example 1, below).
• If set to on, the server functions as a forward proxy and accepts proxy requests. All other directives for the mod_proxy module are in effect.

Example 1

ProxyRequests off

Example 2

    ProxyRequests on 
    CacheRoot /QOpenSys/UserData/HTTPA/CacheRoot 

Example 3

    ProxyRequests on 
    ProxyNoConnect on 
    CacheRoot /QOpenSys/UserData/HTTPA/CacheRoot 

Example 4

    ProxyRequests on 
    CacheExpiryCheck off 
    CacheRoot /QOpenSys/UserData/HTTPA/CacheRoot 

• If CacheRoot is set, the proxy also activates its caching function and may serve documents from cache (by default) as well as issue direct outgoing requests (by default) (see Example 2, above). Expiry checking for cached documents is performed (by default).
• If CacheRoot is set and ProxyNoConnect is set to on, the proxy activates its caching function but will only serve documents from cache. It will not issue outgoing requests (see Example 3, above). Expiry checking for cached documents is performed.
• If CacheRoot is set and CacheExpiryCheck is set to off, the proxy activates its caching function but will not check expiry times for cached documents. Expired documents may be served from cache (see Example 4, above).
• Setting ProxyRequests to off negates all directives for the mod_proxy module, except for the ProxyPass and ProxyPassReverse directives.

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

The ProxyReverse directive specifies whether the server may function as a reverse proxy to handle requests. The reverse proxy function is enabled by default, however other directives must specify how the server identifies and maps requests for reverse proxy. If off is specified, the reverse proxy function is disabled, and directives that apply the function (ProxyPass and RewriteRule directives using the 'proxy' flag) are ineffective. See ProxyPass and RewriteRule for more details on reverse proxy.

Parameter: on | off

• If set to off , the server does not function as a reverse proxy (see Example 1).
• If set to on, the server functions as a reverse proxy to handle requests identified and mapped for reverse proxy

Example 1

ProxyReverse off
ProxyPass /docs/ http://pubserver.ibm.com/public/documentation/

For example one, the reverse proxy function is disabled. The ProxyPass directive is ineffective.

In the following example, the reverse proxy function is enabled. The server functions as a reverse proxy to handle requests that match the path specified for the ProxyPass directive.

Example 2

ProxyReverse on
ProxyPass /docs/ http://pubserver.ibm.com/public/documentation/

See ProxyPass for more details.

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

The ProxyTimeout directive specifies the maximum number of minutes the server will wait for responses from remote servers when handling proxy requests. If not specified, the general server timeout value is used (see the TimeOut directive).

Parameter: period

• The period parameter accepts an integer value between 1 and 2,147,483,648 to specify the maximum period of time the server should wait for responses from remote servers (in seconds).

If a response is not received in the specified number of seconds, the server will cancel the request and return response code 504 (Gateway timeout).

Example

ProxyTimeout 120

For this example, the server will wait up to 120 seconds (or 2 minute) for responses from remote servers.

• ProxyPassReverse may be used to handle HTTP redirect responses from remote servers.
• Setting ProxyReverse to off negates this directive.
• Setting ProxyRequests to off does not negate this directive. It is available regardless of the forward proxy state.

LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_ftp_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM

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

Parameter: off | on | full | block

• If set to off (the default value), no special processing is performed. The proxy does not include a Via: header line, however any existing Via: headers from other proxy servers are kept intact.
• If set to on , each request and reply will get a Via: header line added for the current host. The proxy includes its own, abbreviated Via: header line. Any additional Via: header lines from other proxy servers are kept intact.
• If set to full, each generated Via: header line will additionally have HTTP Server (powered by Apache) version shown on the Via: comment field. The proxy includes its own, full Via: header (containing the proxy's version description). Any additional Via: header lines from other proxy servers are kept intact.
• If set to block, every proxy request will have all its Via: header lines removed. No new Via: header will be generated. The proxy does not include a Via: header and removes all existing Via headers from other proxy servers.

A server may be a participant in a proxy chain even though it is not specifically configured to chain its own requests. For this reason, it may be necessary to control the server's use of the Via: HTTP header even though it is not specifically configured for proxy chaining (see ProxyRemote for more details about proxy chains).