Httpd ProxyPass

External

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

Internal

• httpd Directives
• mod_proxy Concepts
• ProxyPassMatch
• ProxyPassReverse

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". mod_proxy connection pool dynamics is explained here: mod_proxy Concepts - Connection Pooling

max

Reduces the maximum number of connections in the pool, to the specified value, as described in 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.

timeout

The number of seconds httpd waits for data to be sent by the backend 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

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. mod_proxy connection pool dynamics is explained here: mod_proxy Concepts - Connection Pooling.

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.

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

All parameters described below also apply to <Proxy> element load balancing configuration as well.

Configuration elements:

lbmethod

Defines the load balancing scheduler method to use. Available options:

• byrequests
• bytraffic
• bybusyness

The default value is "byrequests".

The load balancing dynamics is 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.

stickysession

The name of the cookie that maintains the sticky session ID. The value 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.

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.