Httpd ProxyPass
External
Internal
Overview
The ProxyPass directive maps remote servers into the local server URL-space, by creating a worker that handles the request associated with the declared remote URL. A more flexible alternative is the use of RewriteRule with the [P] flag.
For ProxyPass-related mod_proxy concepts see:
It can be used inside a <Location> or <LocationMatch> directive, see Example below. <ProxyPass> is not supported within <Directory> and <Files> containers.
Syntax
ProxyPass [path] !|url [key=value ...]
The path is the name of a local virtual path.
The url is a partial URL for the origin server. It cannot include a query string.
If path ends with a trailing "/", the url should also end with a trailing "/", and vice-versa, otherwise the resulting requests to the backend may miss some of the needed slashes and produce unwanted results.
Example
ProxyPass "/something" "http://example.com/something-else
Alternative using <Location>:
<Location "/something">
ProxyPass "http://example.com/something-else"
</Location>
Prevent a URL from Being Proxied
Order
ProxyPass and ProxyPassMatch rules are checked in the order in which they were specified in the configuration file, and the first rule match wins. For the same reason, exclusions must come before the general ProxyPass directives.
Also see:
Preventing a Sub-Directory to Be Proxied
ProxyPass "/something/do-not-proxy" "!" ProxyPass "/something" "http://example.com"
Connection Pool Configuration
Configuration example:
ProxyPass "/something" "httpd://backend.example.com" max=20 ttl=120 retry=300
For concepts, see:
All the parameters described below apply to BalancerMember configuration as well.
lbset
Sets the load balancer cluster set the worker is member of. The load balancer will try all members with a lower numbered lbset before trying the higher numbered ones. The default value is 0.
disablereuse
Explicitly turns off persistent connections. By default is "Off".
ProxyPass /something http://backend.example.com disablereuse=On
mod_proxy connection pool dynamics is explained here mod_proxy Concepts - Connection Pooling
enablereuse
max
Specifies the maximum number of connections per httpd child process that will be allowed to the backend server, for this ProxyPass. It defaults to the number of threads per httpd child process for the MPM, ThreadsPerChild. max can only reduce the maximum number of connections in the pool, to the specified value, never increase it over the number_of_processes * number_of_threads_per_process. More details are available in mod_proxy Concepts - Connection Pooling.
smax
If set to a lower value than max, connections above this limit are shut down if they have been unused for longer than ttl. The default is given by max value. mod_proxy connection pool dynamics is explained here mod_proxy Concepts - Connection Pooling.
connectiontimeout
The number of seconds httpd waits for the creation of the connection to complete. By adding "ms", the timeout can be also be set in milliseconds. The default value is given by timeout. mod_proxy connection pool dynamics is explained here mod_proxy Concepts - Connection Pooling.
ttl
The time to live in seconds after which an inactive connection in the pool is closed. mod_proxy connection pool dynamics is explained here: mod_proxy Concepts - Connection Pooling. There is no default, which means that by default connections won't expire. ttl can be used to avoid using a connection which is subject to closing because of the backend server's keep-alive timeout.
For a load balanced proxy, "ttl" must be specified individually for each BalancerMember. An attempt to declare it on the ProxyPass directive will be rejected with: "ProxyPass unknown Balancer parameter".
timeout
The number of seconds the httpd proxy waits for data to be sent by the backend node before it timeouts. If not specified, the default is given by ProxyTimeout.
mod_proxy connection pool dynamics is explained here: mod_proxy Concepts - Connection Pooling
Note: when used on a balancer ProxyPass declaration ("ProxyPass / balancer://mycluster/ timeout=30"), "timeout" did not override the ProxyTimeout value, so it was probably interpreted as the value of the balancer timeout. In this situation, it is probably best to use ProxyTimeout for clarity.
acquire
The number of milliseconds to wait for a connection to become free in the pool. There is no default. mod_proxy connection pool dynamics is explained here: mod_proxy Concepts - Connection Pooling.
keepalive
This parameter should be used when there is a firewall between httpd and the backend server, which tends to drop inactive connections. This flag will tell the OS to send KEEP_ALIVE messages on inactive connections and thus prevent the firewall from dropping the connection. To enable keepalive, set this property value to "On". The frequency of initial and subsequent TCP keepalive probes depends on global OS settings, and may be as high as 2 hours. To be useful, the frequency configured in the OS must be smaller than the threshold used by the firewall. mod_proxy connection pool dynamics is explained here mod_proxy Concepts - Connection Pooling
Also see:
iobuffersize
Allows overriding of ProxyIOBufferSize for a specific worker. Set to 0 to use the default ProxyIOBufferSize value.
retry
The amount of time in seconds to avoid a connection in error state. Zero means always retry workers in error state with no timeout.
If the configuration applies to a balancer worker member, it must be declared with the BalancerMember directive, an attempt to declare it on the shared ProxyPass will cause a configuration error:
<Proxy balancer://mycluster>
BalancerMember http://localhost:10000 ... retry=30
BalancerMember http://localhost:10001 ... retry=30
...
</Proxy>
mod_proxy connection pool dynamics is explained here mod_proxy Concepts - Connection Pooling. Also see Balancer Members in Error State.
ping
The number of seconds to wait for the backend reply after sending a PING request. "ms" suffix allows configuration in milliseconds. The default is 0 (no pinging). mod_proxy connection pool dynamics is explained here mod_proxy Concepts - Connection Pooling.
flushpackets
flushwait
receivebuffesize
Overrides ProxyReceiveBufferSize on a woker basis. Default is 0 - no override.
route
The route of the worker when used inside a load balancer. The route is a value appended to the session ID. No default. The load balancing and session stickiness dynamics is explained here mod_proxy Concepts - Load_Balancing.
redirect
Represents the redirection route of the worker. This value is usually set dynamically to enable safe removal of the node from the cluster. If set, all requests without session ID will be redirected to the BalancerMember that has the route parameter equals to this value. No default.
status
The initial status of the worker:
Status can be set by prepending it with "+" or cleared by prepending it with "-".
Load Balancing Configuration
The following configuration elements are load-balancing specific and should be applied to ProxyPass only when it defines a balancer worker.
All parameters described below also apply to <Proxy> element load balancing configuration as well, where they can be set with ProxySet, when <Proxy> defines a balancer worker.
lbmethod
Defines the load balancing scheduler method to use. Available options: "byrequests", "bytraffic", "bybusyness". The default value is "byrequests".
ProxyPass / balancer://cluster/ lbmethod=byrequests
ProxyPass / balancer://cluster/
<Proxy balancer://cluster>
BalancerMember ...
ProxySet lbmethod=byrequests
</Proxy>
mod_proxy load balancing concepts are explained here mod_proxy Concepts - Load_Balancing.
maxattempts
The maximum number of failover attempts before giving up. The default is equal with the number of members minus 1, or 1 if there is a single member. The load balancing dynamics is explained here: mod_proxy Concepts - Load_Balancing.
nofailover
By default is "Off": failover is enabled. If set to "On", the session will break if the worker is in error state or disabled. This should be set to "On" if the backend servers do not support session replication. The load balancing dynamics is explained here: mod_proxy Concepts - Load_Balancing.
failonstatus
A comma-separated list of HTTP status codes, which, once received from the backend, will make the balancer to mark the worker to be in error state.
ProxyPass / balancer://mycluster/ failonstatus=500,501,502 ...
There is no default value, the worker will not marked to be in error state on any response code. If enabled, the balancer react as follows:
[error] [client ::1] proxy: BALANCER: (balancer://mycluster). Forcing worker (http://localhost:10000) into error state due to status code 500 matching 'failonstatus' balancer parameter
Member recovery is described here. mod_proxy load balancing concepts are explained here mod_proxy Concepts - Load_Balancing.
failontimeout
By default is "Off", which means a balancer worker won't be marked to be in error state if there is a timeout on receiving the answer from the backend. If set ("On"), a response timeout will determine the balancer to mark the corresponding worker to be in error state. Member recovery is described here. mod_proxy load balancing concepts are explained here mod_proxy Concepts - Load Balancing.
forcerecovery
Force the immediate recovery of all members without considering the retry parameter of the members if all members of a balancer are in error state.
Default is "On", which means requests will be sent to the members in error state immediately.
There might be cases where an already overloaded backend can get into deeper trouble if the recovery of all workers is enforced without considering the retry parameter of each worker. In this case, set to Off.
For more details on member recovery see mod_proxy Concepts.
stickysession
The name of the cookie that maintains the sticky session ID. The value case sensitive, and it is usually something like "JSESSIONID". If the backend container uses different name for cookies and URL encoded ID, use "|" to separate them. The load balancing dynamics is explained here: mod_proxy Concepts - Load_Balancing.
stickysessionsep
Defines the separation symbol in the session cookie. The default is ".". The setting of "Off" signifies that no symbol is used. The load balancing dynamics is explained here: mod_proxy Concepts - Load_Balancing.
scolonpathdelim
Define the sticky session path delimiter. If set to "On", the default of ";" will be used. The load balancing dynamics is explained here: mod_proxy Concepts - Load_Balancing.
timeout
The maximum time in seconds to wait for a free balancer worker. If not set (the default) the balancer will not wait.
The load balancing dynamics is explained here: mod_proxy Concepts - Load_Balancing.
nonce
The protective nonce used in the balancer-manager application page. The default is to use an automatically determined UUID-based nonce, to provide for further protection for the page. If set, then the nonce is set to that value. A setting of None disables all nonce checking. In addition to the nonce, the balancer-manager page should be protected via an ACL.
growth
Number of additional BalancerMembers to allow to be added to this balancer in addition to those defined at configuration.
Additional ProxyPass Keywords
nocannon
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.
noquery
Normally, mod_proxy will include the query string when generating the SCRIPT_FILENAME environment variable. The optional no query prevents this.
interpolate
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.