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. The local server is often called a reverse proxy or gateway. The path is the name of a local virtual path; url is a partial URL for the remote server and cannot include a query string.

In 2.4.7 and later, support for using a Unix Domain Socket is available by using a target which prepends unix:/path/lis.sock| . For example, to proxy HTTP and target the UDS at /home/www/socket, you would use unix:/home/www.socket|http://localhost/whatever/ .

When used inside a <Location> section, the first argument is omitted and the local directory is obtained from the <Location> . The same will occur inside a <LocationMatch> section; however, ProxyPass does not interpret the regexp as such, so it is necessary to use ProxyPassMatch in this situation instead.

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

<Location "/mirror/foo/">
 ProxyPass "http://backend.example.com/"
</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 following alternative syntax is possible; however, it can carry a performance penalty when present in very large numbers. The advantage of the below syntax is that it allows for dynamic control via the Balancer Manager interface:

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

If the first argument ends with a trailing /, the second argument should also end with a trailing /, and vice versa. Otherwise, the resulting requests to the backend may miss some needed slashes and do not deliver the expected results.

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

<Location "/mirror/foo/">
 ProxyPass "http://backend.example.com/"
</Location>
<Location "/mirror/foo/i">
 ProxyPass "!"
</Location>

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 .

Ordering ProxyPass Directives

The configured ProxyPass and ProxyPassMatch rules are checked in the order of configuration. The first rule that matches wins. So usually you should sort conflicting ProxyPass rules starting with the longest URLs first. Otherwise, later rules for longer URLS will be hidden by any earlier rule which uses a leading substring of the URL. Note that there is some relation with worker sharing. In contrast, only one ProxyPass directive can be placed in a Location block, and the most specific location will take precedence.

For the same reasons, exclusions must come before the general ProxyPass directives. In 2.4.26 and later, the "no-proxy" environment variable is an alternative to exclusions, and is the only way to configure an exclusion of a ProxyPass directive in Location context. This variable should be set with SetEnvIf , as SetEnv is not evaluated early enough.

ProxyPass key=value Parameters

In Apache HTTP Server 2.1 and later, mod_proxy supports pooled connections to a backend server. Connections created on demand can be retained in a pool for future use. Limits on the pool size and other settings can be coded on the ProxyPass directive using key=value parameters, described in the tables below.

Maximum connections to the backend

By default, mod_proxy will allow and retain the maximum number of connections that could be used simultaneously by that web server child process. Use the max parameter to reduce the number from the default. The pool of connections is maintained per web server child process, and max and other settings are not coordinated among all child processes, except when only one child process is allowed by configuration or MPM design.

Use the ttl parameter to set an optional time to live; connections which have been unused for at least ttl seconds will be closed. ttl can be used to avoid using a connection which is subject to closing because of the backend server's keep-alive timeout.

Example

ProxyPass "/example" "http://backend.example.com" max=20 ttl=120 retry=300

If the Proxy directive scheme starts with the balancer:// (eg: balancer://cluster , any path information is ignored), then a virtual worker that does not really communicate with the backend server will be created. Instead, it is responsible for the management of several "real" workers. In that case, the special set of parameters can be added to this virtual worker. See mod_proxy_balancer for more information about how the balancer works.

A sample balancer setup:

ProxyPass "/special-area" "http://special.example.com" smax=5 max=10
ProxyPass "/" "balancer://mycluster/" stickysession=JSESSIONID|jsessionid nofailover=On
<Proxy "balancer://mycluster">
 BalancerMember "ajp://1.2.3.4:8009"
 BalancerMember "ajp://1.2.3.5:8009" loadfactor=20
 # Less powerful server, don't send as many requests there,
 BalancerMember "ajp://1.2.3.6:8009" loadfactor=5
</Proxy>

Setting up a hot-standby that will only be used if no other members are available:

ProxyPass "/" "balancer://hotcluster/"
<Proxy "balancer://hotcluster">
 BalancerMember "ajp://1.2.3.4:8009" loadfactor=1
 BalancerMember "ajp://1.2.3.5:8009" loadfactor=2.25
 # The server below is on hot standby
 BalancerMember "ajp://1.2.3.6:8009" status=+H
 ProxySet lbmethod=bytraffic
</Proxy>

Additional ProxyPass Keywords

Normally, mod_proxy will canonicalise ProxyPassed URLs. But this may be incompatible with some backends, particularly those that make use of PATH_INFO. The optional nocanon keyword suppresses this and passes the URL path "raw" to the backend. Note that this keyword may affect the security of your backend, as it removes the normal limited protection against URL-based attacks provided by the proxy.

Normally, mod_proxy will include the query string when generating the SCRIPT_FILENAME environment variable. The optional noquery keyword (available in httpd 2.4.1 and later) prevents this.

The optional interpolate keyword, in combination with ProxyPassInterpolateEnv , causes the ProxyPass to interpolate environment variables, using the syntax ${VARNAME}. Note that many of the standard CGI-derived environment variables will not exist when this interpolation happens, so you may still have to resort to mod_rewrite for complex rules. Also note that interpolation is not supported within the scheme portion of a URL. Dynamic determination of the scheme can be accomplished with mod_rewrite as in the following example.

RewriteEngine On
RewriteCond "%{HTTPS}" =off
RewriteRule "." "-" [E=protocol:http]
RewriteCond "%{HTTPS}" =on
RewriteRule "." "-" [E=protocol:https]
RewriteRule "^/mirror/foo/(.*)" "%{ENV:protocol}://backend.example.com/$1" [P]
ProxyPassReverse "/mirror/foo/" "http://backend.example.com/"
ProxyPassReverse "/mirror/foo/" "https://backend.example.com/"