Reverse Proxy Guide

Reverse Proxy ¶

Simple reverse proxying ¶

The ProxyPass directive specifies the mapping of incoming requests to the backend server (or a cluster of servers known as a Balancer group). The simplest example proxies all requests ("/") to a single backend:

ProxyPass "/"  "http://www.example.com/"

To ensure that Location: headers generated from the backend are modified to point to the reverse proxy, instead of back to itself, the ProxyPassReverse directive is most often required:

ProxyPass "/"  "http://www.example.com/"
ProxyPassReverse "/"  "http://www.example.com/"

Only specific URIs can be proxied, as shown in this example:

ProxyPass "/images"  "http://www.example.com/"
ProxyPassReverse "/images"  "http://www.example.com/"

In the above, any requests which start with the /images path will be proxied to the specified backend, otherwise it will be handled locally.

Clusters and Balancers ¶

The single-backend setup above has an obvious weakness: if that node goes down or becomes overloaded, the proxied content is unavailable. What you need is a group of backend servers that the reverse proxy can load-balance and failover among. This group is sometimes called a cluster; Apache httpd's term is a balancer. You define a balancer using the <Proxy> and BalancerMember directives:

<Proxy balancer://myset>
BalancerMember http://www2.example.com:8080
BalancerMember http://www3.example.com:8080
ProxySet lbmethod=bytraffic
</Proxy>

ProxyPass "/images/"  "balancer://myset/"
ProxyPassReverse "/images/"  "balancer://myset/"

The balancer:// scheme is what tells httpd that we are creating a balancer set, with the name myset. It includes 2 backend servers, which httpd calls BalancerMembers. In this case, any requests for /images will be proxied to one of the 2 backends. The ProxySet directive specifies that the myset Balancer use a load balancing algorithm that balances based on I/O bytes.

Balancer and BalancerMember configuration ¶

You can tune balancers and workers through parameters on ProxyPass. For example, to have http://www3.example.com:8080 handle 3× the traffic with a 1-second timeout:

<Proxy balancer://myset>
BalancerMember http://www2.example.com:8080
BalancerMember http://www3.example.com:8080 loadfactor=3 timeout=1
ProxySet lbmethod=bytraffic
</Proxy>

ProxyPass "/images"  "balancer://myset/"
ProxyPassReverse "/images"  "balancer://myset/"

Failover ¶

You can fine-tune failover scenarios, specifying which workers and balancers handle traffic when others fail. The setup below implements three failover cases:

1. http://spare1.example.com:8080 and http://spare2.example.com:8080 are only sent traffic if one or both of http://www2.example.com:8080 or http://www3.example.com:8080 is unavailable. (One spare will be used to replace one unusable member of the same balancer set.)
2. http://hstandby.example.com:8080 is only sent traffic if all other workers in balancer set 0 are not available.
3. If all load balancer set 0 workers, spares, and the standby are unavailable, only then will the http://bkup1.example.com:8080 and http://bkup2.example.com:8080 workers from balancer set 1 be brought into rotation.

You can have one or more hot spares and hot standbys for each load balancer set.

<Proxy balancer://myset>
BalancerMember http://www2.example.com:8080
BalancerMember http://www3.example.com:8080 loadfactor=3 timeout=1
BalancerMember http://spare1.example.com:8080 status=+R
BalancerMember http://spare2.example.com:8080 status=+R
BalancerMember http://hstandby.example.com:8080 status=+H
BalancerMember http://bkup1.example.com:8080 lbset=1
BalancerMember http://bkup2.example.com:8080 lbset=1
ProxySet lbmethod=byrequests
</Proxy>

ProxyPass "/images/"  "balancer://myset/"
ProxyPassReverse "/images/"  "balancer://myset/"

Hot spares replace unusable workers (draining, stopped, or in an error state) within the same load balancer set. Hot standbys activate only when all workers and spares in a set are unavailable. Sets are tried in order from lowest to highest.

Balancer Manager ¶

Apache httpd includes an embedded balancer-manager application. Like mod_status, it displays the current configuration and status of your balancers and workers. It also lets you reconfigure them at runtime—including adding new BalancerMembers to an existing balancer. To enable it, add the following to your configuration:

<Location "/balancer-manager">
SetHandler balancer-manager
Require host localhost
</Location>

When you access that URL (e.g. http://rproxy.example.com/balancer-manager/), you will see a page like this:

From here you can adjust parameters, take workers offline, change load balancing methods, and add new workers. Clicking on the balancer itself shows:

Whereas clicking on a worker, displays this page:

To persist these changes across restarts, enable BalancerPersist.

Dynamic Health Checks ¶

Before proxying a request, httpd can test whether a worker is available using the ping parameter in ProxyPass. Often it is more useful to check worker health out of band. mod_proxy_hcheck provides this capability.

BalancerMember status flags ¶

In the balancer-manager the current state, or status, of a worker is displayed and can be set/reset. The meanings of these statuses are as follows: