From: Rich Bowen Date: Fri, 19 Jun 2026 14:24:24 +0000 (+0000) Subject: docs: howto/reverse_proxy.xml editorial cleanup X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=cbe403dc1cc342a282e81d5a2e635025571c87b1;p=thirdparty%2Fapache%2Fhttpd.git docs: howto/reverse_proxy.xml editorial cleanup - Tighten verbose prose throughout - Break long sentences for readability - Grammar and spelling fixes throughout git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1935520 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/howto/reverse_proxy.xml b/docs/manual/howto/reverse_proxy.xml index 6bc3c45401..6a04192bdf 100644 --- a/docs/manual/howto/reverse_proxy.xml +++ b/docs/manual/howto/reverse_proxy.xml @@ -26,26 +26,19 @@ 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.

+

Besides serving static and dynamic content directly, Apache httpd + can act as a reverse proxy server (sometimes called a gateway).

+ +

In this mode, httpd does not generate the content itself. Instead, + it forwards each client request to one or more backend servers that + have no direct connection to the external network. The backend + processes the request and returns the content to httpd, which then + delivers the HTTP response to the client.

+ +

Common reasons include security, high availability, load balancing, + and centralized authentication. The backend infrastructure should be isolated from the external + network; as far as the client is concerned, the reverse proxy + is the sole source of all content.

A typical implementation is below:

reverse-proxy-arch

@@ -79,31 +72,37 @@ to a single backend:

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

- To ensure that and Location: headers generated from + 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 with be proxied to the specified backend, otherwise it will be handled + path will be proxied to the specified backend, otherwise it will be handled locally.

@@ -112,28 +111,27 @@ ProxyPassReverse "/images" "http://www.example.com/" 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 + 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 as - shown: + BalancerMember directives:

- + + <Proxy balancer://myset> - BalancerMember http://www2.example.com:8080 - BalancerMember http://www3.example.com:8080 - ProxySet lbmethod=bytraffic +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 @@ -157,24 +155,24 @@ ProxyPassReverse "/images/" "balancer://myset/" 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: + 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 +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/" - + + @@ -182,9 +180,9 @@ ProxyPassReverse "/images" "balancer://myset/" Failover

- You can also fine-tune various failover scenarios, detailing which workers - and even which balancers should be accessed in such cases. For example, the - below setup implements three failover cases: + You can fine-tune failover scenarios, specifying which workers and + balancers handle traffic when others fail. The setup below + implements three failover cases:

  1. @@ -207,33 +205,33 @@ ProxyPassReverse "/images" "balancer://myset/"

- Thus, it is possible to have one or more hot spares and hot standbys for - each load balancer set. + 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 +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/" - + +

- For failover, hot spares are used as replacements for unusable workers in - the same load balancer set. A worker is considered unusable if it is - draining, stopped, or otherwise in an error/failed state. Hot standbys are - used if all workers and spares in the load balancer set are - unavailable. Load balancer sets (with their respective hot spares and - standbys) are always tried in order from lowest to highest. + 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.

@@ -242,23 +240,22 @@ ProxyPassReverse "/images/" "balancer://myset/" 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: + 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 +SetHandler balancer-manager +Require host localhost </Location> - + + Warning

Do not enable the balancer-manager until you have

- 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: + When you access that URL + (e.g. http://rproxy.example.com/balancer-manager/), you + will see a page like this:

balancer-manager page

- 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: + From here you can adjust parameters, take workers offline, change + load balancing methods, and add new workers. Clicking on the + balancer itself shows:

balancer-manager page

@@ -287,8 +284,8 @@ ProxyPassReverse "/images/" "balancer://myset/"

balancer-manager page

- To have these changes persist restarts of the reverse proxy, ensure that - BalancerPersist is enabled. + To persist these changes across restarts, enable + BalancerPersist.

@@ -297,12 +294,11 @@ ProxyPassReverse "/images/" "balancer://myset/" 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. + 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.