Httpd ProxyPass

External

• https://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypass

Internal

• mod_proxy Configuration
• mod_proxy Concepts

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:

ProxyPass Concepts

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>

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:

Worker Sharing

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:

ProxyPass Connection Pool Concepts

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

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.

This ProxyPass (worker) timeout and balancer timeout have different meanings.

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:

Keep-Alive

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.

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:

Worker Status

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.

ProxyPass (worker) timeout and balancer timeout have different meanings.

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.