How-To / Tutorials
Reverse Proxy Guide
In addition to being a "basic" web server, and providing static and
dynamic content to end-users, Apache httpd (as well as most other web
servers) can also act as a reverse proxy server, also-known-as a
"gateway" server.
In such scenarios, httpd itself does not generate or host the data,
but rather the content is obtained by one or several backend servers,
which normally have no direct connection to the external network. As
httpd receives a request from a client, the request itself is proxied
to one of these backend servers, which then handles the request, generates
the content and then sends this content back to httpd, which then
generates the actual HTTP response back to the client.
There are numerous reasons for such an implementation, but generally
the typical rationales are due to security, high-availability, load-balancing
and centralized authentication/authorization. It is critical in these
implementations that the layout, design and architecture of the backend
infrastructure (those servers which actually handle the requests) are
insulated and protected from the outside; as far as the client is concerned,
the reverse proxy server is the sole source of all content.
A typical implementation is below:
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 simpliest example proxies all requests ("/")
to a single backend:
ProxyPass "/" "http://www.example.com/"
To ensure that and 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 with be proxied to the specified backend, otherwise it will be handled
locally.
Clusters and Balancers
As useful as the above is, it still has the deficiencies that should
the (single) backend node go down, or become heavily loaded, that proxying
those requests provides no real advantage. What is needed is the ability
to define a set or group of backend servers which can handle such
requests and for the reverse proxy to load balance and failover among
them. This group is sometimes called a cluster but Apache httpd's
term is a balancer. One defines a balancer by leveraging the
Proxy and
BalancerMember directives as
shown:
<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.
Hint
BalancerMembers are also sometimes referred to as workers.
Balancer and BalancerMember configuration
You can adjust numerous configuration details of the balancers
and the workers via the various parameters defined in
ProxyPass. For example,
assuming we would want http://www3.example.com:8080 to
handle 3x the traffic with a timeout of 1 second, we would adjust the
configuration as follows:
<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 also fine-tune various failover scenarios, detailing which
workers and even which balancers should accessed in such cases. For
example, the below setup implements 2 failover cases: In the first,
http://hstandby.example.com:8080 is only sent traffic
if all other workers in the myset balancer are not available.
If that worker itself is not available, only then will the
http://bkup1.example.com:8080 and http://bkup2.example.com:8080
workers be brought into rotation:
<Proxy balancer://myset>
BalancerMember http://www2.example.com:8080
BalancerMember http://www3.example.com:8080 loadfactor=3 timeout=1
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/"
The magic of this failover setup is setting http://hstandby.example.com:8080
with the +H status flag, which puts it in hot standby mode,
and making the 2 bkup# servers part of the #1 load balancer set (the
default set is 0); for failover, hot standbys (if they exist) are used 1st, when all regular
workers are unavailable; load balancer sets are always tried lowest number first.
Balancer Manager
One of the most unique and useful features of Apache httpd's reverse proxy is
the embedded balancer-manager application. Similar to
mod_status, balancer-manager displays
the current working configuration and status of the enabled
balancers and workers currently in use. However, not only does it
display these parameters, it also allows for dynamic, runtime, on-the-fly
reconfiguration of almost all of them, including adding new BalancerMembers
(workers) to an existing balancer. To enable these capability, the following
needs to be added to your configuration:
<Location "/balancer-manager">
SetHandler balancer-manager
Require host localhost
</Location>
Warning
Do not enable the balancer-manager until you have secured your server. In
particular, ensure that access to the URL is tightly
restricted.
When the reverse proxy server is accessed at that url
(eg: http://rproxy.example.com/balancer-manager/, you will see a
page similar to the below:
This form allows the devops admin to adjust various parameters, take
workers offline, change load balancing methods and add new works. For
example, clicking on the balancer itself, you will get the following page:
Whereas clicking on a worker, displays this page:
To have these changes persist restarts of the reverse proxy, ensure that
BalancerPersist is enabled.
Dynamic Health Checks
Before httpd proxies a request to a worker, it can "test" if that worker
is available via setting the ping parameter for that worker using
ProxyPass. Oftentimes it is
more useful to check the health of the workers out of band, in a
dynamic fashion. This is achieved in Apache httpd by the
mod_proxy_hcheck module.
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:
| Flag | String | Description |
|---|
| | Ok | Worker is available |
| | Init | Worker has been initialized |
D | Dis | Worker is disabled and will not accept any requests; will be
automatically retried. |
S | Stop | Worker is administratively stopped; will not accept requests
and will not be automatically retried |
I | Ign | Worker is in ignore-errors mode and will always be considered available. |
H | Stby | Worker is in hot-standby mode and will only be used if no other
viable workers are available. |
E | Err | Worker is in an error state, usually due to failing pre-request check;
requests will not be proxied to this worker, but it will be retried depending on
the retry setting of the worker. |
N | Drn | Worker is in drain mode and will only accept existing sticky sessions
destined for itself and ignore all other requests. |
C | HcFl | Worker has failed dynamic health check and will not be used until it
passes subsequent health checks. |