granicus.if.org Git - apache/blob - docs/manual/howto/reverse_proxy.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
   4 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
   5 <!--
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7               This file is generated from xml source: DO NOT EDIT
   8         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   9       -->
  10 <title>Reverse Proxy Guide - Apache HTTP Server Version 2.5</title>
  11 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  12 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  13 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
  14 <script src="../style/scripts/prettify.min.js" type="text/javascript">
  15 </script>
  16
  17 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  18 <body id="manual-page"><div id="page-header">
  19 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  20 <p class="apache">Apache HTTP Server Version 2.5</p>
  21 <img alt="" src="../images/feather.png" /></div>
  22 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  23 <div id="path">
  24 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">How-To / Tutorials</a></div><div id="page-content"><div id="preamble"><h1>Reverse Proxy Guide</h1>
  25 <div class="toplang">
  26 <p><span>Available Languages: </span><a href="../en/howto/reverse_proxy.html" title="English">&nbsp;en&nbsp;</a> |
  27 <a href="../es/howto/reverse_proxy.html" hreflang="es" rel="alternate" title="Español">&nbsp;es&nbsp;</a> |
  28 <a href="../fr/howto/reverse_proxy.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
  29 </div>
  30
  31     <p>In addition to being a "basic" web server, and providing static and
  32     dynamic content to end-users, Apache httpd (as well as most other web
  33     servers) can also act as a reverse proxy server, also-known-as a
  34     "gateway" server.</p>
  35
  36     <p>In such scenarios, httpd itself does not generate or host the data,
  37     but rather the content is obtained by one or several backend servers,
  38     which normally have no direct connection to the external network. As
  39     httpd receives a request from a client, the request itself is <em>proxied</em>
  40     to one of these backend servers, which then handles the request, generates
  41     the content and then sends this content back to httpd, which then
  42     generates the actual HTTP response back to the client.</p>
  43
  44     <p>There are numerous reasons for such an implementation, but generally
  45     the typical rationales are due to security, high-availability, load-balancing
  46     and centralized authentication/authorization. It is critical in these
  47     implementations that the layout, design and architecture of the backend
  48     infrastructure (those servers which actually handle the requests) are
  49     insulated and protected from the outside; as far as the client is concerned,
  50     the reverse proxy server <em>is</em> the sole source of all content.</p>
  51
  52     <p>A typical implementation is below:</p>
  53     <p class="centered"><img src="../images/reverse-proxy-arch.png" alt="reverse-proxy-arch" /></p>
  54
  55   </div>
  56 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#related">Reverse Proxy</a></li>
  57 <li><img alt="" src="../images/down.gif" /> <a href="#simple">Simple reverse proxying</a></li>
  58 <li><img alt="" src="../images/down.gif" /> <a href="#cluster">Clusters and Balancers</a></li>
  59 <li><img alt="" src="../images/down.gif" /> <a href="#config">Balancer and BalancerMember configuration</a></li>
  60 <li><img alt="" src="../images/down.gif" /> <a href="#failover">Failover</a></li>
  61 <li><img alt="" src="../images/down.gif" /> <a href="#manager">Balancer Manager</a></li>
  62 <li><img alt="" src="../images/down.gif" /> <a href="#health-check">Dynamic Health Checks</a></li>
  63 <li><img alt="" src="../images/down.gif" /> <a href="#status">BalancerMember status flags</a></li>
  64 </ul><h3>See also</h3><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
  65 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  66 <div class="section">
  67 <h2><a name="related" id="related">Reverse Proxy</a><a title="Permanent link" href="#related" class="permalink">&para;</a></h2>
  68
  69   <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li><li><code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code></li><li><code class="module"><a href="../mod/mod_proxy_hcheck.html">mod_proxy_hcheck</a></code></li></ul></td><td><ul><li><code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code></li><li><code class="directive"><a href="../mod/mod_proxy.html#balancermember">BalancerMember</a></code></li></ul></td></tr></table>
  70   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  71 <div class="section">
  72 <h2><a name="simple" id="simple">Simple reverse proxying</a><a title="Permanent link" href="#simple" class="permalink">&para;</a></h2>
  73
  74
  75     <p>
  76       The <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code>
  77       directive specifies the mapping of incoming requests to the backend
  78       server (or a cluster of servers known as a <code>Balancer</code>
  79       group). The simpliest example proxies all requests (<code>"/"</code>)
  80       to a single backend:
  81     </p>
  82
  83     <pre class="prettyprint lang-config">ProxyPass "/"  "http://www.example.com/"</pre>
  84
  85
  86     <p>
  87       To ensure that and <code>Location:</code> headers generated from
  88       the backend are modified to point to the reverse proxy, instead of
  89       back to itself, the <code class="directive"><a href="../mod/mod_proxy.html#proxypassreverse">ProxyPassReverse</a></code>
  90       directive is most often required:
  91     </p>
  92
  93     <pre class="prettyprint lang-config">ProxyPass "/"  "http://www.example.com/"
  94 ProxyPassReverse "/"  "http://www.example.com/"</pre>
  95
  96
  97     <p>Only specific URIs can be proxied, as shown in this example:</p>
  98
  99     <pre class="prettyprint lang-config">ProxyPass "/images"  "http://www.example.com/"
 100 ProxyPassReverse "/images"  "http://www.example.com/"</pre>
 101
 102
 103     <p>In the above, any requests which start with the <code>/images</code>
 104       path with be proxied to the specified backend, otherwise it will be handled
 105       locally.
 106     </p>
 107   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 108 <div class="section">
 109 <h2><a name="cluster" id="cluster">Clusters and Balancers</a><a title="Permanent link" href="#cluster" class="permalink">&para;</a></h2>
 110
 111
 112     <p>
 113       As useful as the above is, it still has the deficiencies that should
 114       the (single) backend node go down, or become heavily loaded, that proxying
 115       those requests provides no real advantage. What is needed is the ability
 116       to define a set or group of backend servers which can handle such
 117       requests and for the reverse proxy to load balance and failover among
 118       them. This group is sometimes called a <em>cluster</em> but Apache httpd's
 119       term is a <em>balancer</em>. One defines a balancer by leveraging the
 120       <code class="directive"><a href="../mod/mod_proxy.html#proxy">&lt;Proxy&gt;</a></code> and
 121       <code class="directive"><a href="../mod/mod_proxy.html#balancermember">BalancerMember</a></code> directives as
 122       shown:
 123     </p>
 124
 125     <pre class="prettyprint lang-config">&lt;Proxy balancer://myset&gt;
 126     BalancerMember http://www2.example.com:8080
 127     BalancerMember http://www3.example.com:8080
 128     ProxySet lbmethod=bytraffic
 129 &lt;/Proxy&gt;
 130
 131 ProxyPass "/images/"  "balancer://myset/"
 132 ProxyPassReverse "/images/"  "balancer://myset/"</pre>
 133
 134
 135     <p>
 136       The <code>balancer://</code> scheme is what tells httpd that we are creating
 137       a balancer set, with the name <em>myset</em>. It includes 2 backend servers,
 138       which httpd calls <em>BalancerMembers</em>. In this case, any requests for
 139       <code>/images</code> will be proxied to <em>one</em> of the 2 backends.
 140       The <code class="directive"><a href="../mod/mod_proxy.html#proxyset">ProxySet</a></code> directive
 141       specifies that the <em>myset</em> Balancer use a load balancing algorithm
 142       that balances based on I/O bytes.
 143     </p>
 144
 145     <div class="note"><h3>Hint</h3>
 146       <p>
 147         <em>BalancerMembers</em> are also sometimes referred to as <em>workers</em>.
 148       </p>
 149    </div>
 150
 151   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 152 <div class="section">
 153 <h2><a name="config" id="config">Balancer and BalancerMember configuration</a><a title="Permanent link" href="#config" class="permalink">&para;</a></h2>
 154
 155
 156     <p>
 157       You can adjust numerous configuration details of the <em>balancers</em>
 158       and the <em>workers</em> via the various parameters defined in
 159       <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code>. For example,
 160       assuming we would want <code>http://www3.example.com:8080</code> to
 161       handle 3x the traffic with a timeout of 1 second, we would adjust the
 162       configuration as follows:
 163     </p>
 164
 165     <pre class="prettyprint lang-config">&lt;Proxy balancer://myset&gt;
 166     BalancerMember http://www2.example.com:8080
 167     BalancerMember http://www3.example.com:8080 loadfactor=3 timeout=1
 168     ProxySet lbmethod=bytraffic
 169 &lt;/Proxy&gt;
 170
 171 ProxyPass "/images"  "balancer://myset/"
 172 ProxyPassReverse "/images"  "balancer://myset/"</pre>
 173
 174
 175   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 176 <div class="section">
 177 <h2><a name="failover" id="failover">Failover</a><a title="Permanent link" href="#failover" class="permalink">&para;</a></h2>
 178
 179
 180     <p>
 181       You can also fine-tune various failover scenarios, detailing which workers
 182       and even which balancers should be accessed in such cases. For example, the
 183       below setup implements three failover cases:
 184     </p>
 185     <ol>
 186       <li>
 187         <code>http://spare1.example.com:8080</code> and
 188         <code>http://spare2.example.com:8080</code> are only sent traffic if one
 189         or both of <code>http://www2.example.com:8080</code> or
 190         <code>http://www3.example.com:8080</code> is unavailable. (One spare
 191         will be used to replace one unusable member of the same balancer set.)
 192       </li>
 193       <li>
 194         <code>http://hstandby.example.com:8080</code> is only sent traffic if
 195         all other workers in balancer set <code>0</code> are not available.
 196       </li>
 197       <li>
 198         If all load balancer set <code>0</code> workers, spares, and the standby
 199         are unavailable, only then will the
 200         <code>http://bkup1.example.com:8080</code> and
 201         <code>http://bkup2.example.com:8080</code> workers from balancer set
 202         <code>1</code> be brought into rotation.
 203       </li>
 204     </ol>
 205     <p>
 206       Thus, it is possible to have one or more hot spares and hot standbys for
 207       each load balancer set.
 208     </p>
 209
 210     <pre class="prettyprint lang-config">&lt;Proxy balancer://myset&gt;
 211     BalancerMember http://www2.example.com:8080
 212     BalancerMember http://www3.example.com:8080 loadfactor=3 timeout=1
 213     BalancerMember http://spare1.example.com:8080 status=+R
 214     BalancerMember http://spare2.example.com:8080 status=+R
 215     BalancerMember http://hstandby.example.com:8080 status=+H
 216     BalancerMember http://bkup1.example.com:8080 lbset=1
 217     BalancerMember http://bkup2.example.com:8080 lbset=1
 218     ProxySet lbmethod=byrequests
 219 &lt;/Proxy&gt;
 220
 221 ProxyPass "/images/"  "balancer://myset/"
 222 ProxyPassReverse "/images/"  "balancer://myset/"</pre>
 223
 224
 225     <p>
 226       For failover, hot spares are used as replacements for unusable workers in
 227       the same load balancer set. A worker is considered unusable if it is
 228       draining, stopped, or otherwise in an error/failed state. Hot standbys are
 229       used if all workers and spares in the load balancer set are
 230       unavailable. Load balancer sets (with their respective hot spares and
 231       standbys) are always tried in order from lowest to highest.
 232     </p>
 233
 234   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 235 <div class="section">
 236 <h2><a name="manager" id="manager">Balancer Manager</a><a title="Permanent link" href="#manager" class="permalink">&para;</a></h2>
 237
 238
 239     <p>
 240       One of the most unique and useful features of Apache httpd's reverse proxy is
 241           the embedded <em>balancer-manager</em> application. Similar to
 242           <code class="module"><a href="../mod/mod_status.html">mod_status</a></code>, <em>balancer-manager</em> displays
 243           the current working configuration and status of the enabled
 244           balancers and workers currently in use. However, not only does it
 245           display these parameters, it also allows for dynamic, runtime, on-the-fly
 246           reconfiguration of almost all of them, including adding new <em>BalancerMembers</em>
 247           (workers) to an existing balancer. To enable these capability, the following
 248           needs to be added to your configuration:
 249     </p>
 250
 251     <pre class="prettyprint lang-config">&lt;Location "/balancer-manager"&gt;
 252     SetHandler balancer-manager
 253     Require host localhost
 254 &lt;/Location&gt;</pre>
 255
 256
 257     <div class="warning"><h3>Warning</h3>
 258       <p>Do not enable the <em>balancer-manager</em> until you have <a href="../mod/mod_proxy.html#access">secured your server</a>. In
 259       particular, ensure that access to the URL is tightly
 260       restricted.</p>
 261     </div>
 262
 263     <p>
 264       When the reverse proxy server is accessed at that url
 265       (eg: <code>http://rproxy.example.com/balancer-manager/</code>, you will see a
 266       page similar to the below:
 267     </p>
 268     <p class="centered"><img src="../images/bal-man.png" alt="balancer-manager page" /></p>
 269
 270     <p>
 271       This form allows the devops admin to adjust various parameters, take
 272       workers offline, change load balancing methods and add new works. For
 273       example, clicking on the balancer itself, you will get the following page:
 274     </p>
 275     <p class="centered"><img src="../images/bal-man-b.png" alt="balancer-manager page" /></p>
 276
 277     <p>
 278       Whereas clicking on a worker, displays this page:
 279     </p>
 280     <p class="centered"><img src="../images/bal-man-w.png" alt="balancer-manager page" /></p>
 281
 282     <p>
 283       To have these changes persist restarts of the reverse proxy, ensure that
 284       <code class="directive"><a href="../mod/mod_proxy.html#balancerpersist">BalancerPersist</a></code> is enabled.
 285     </p>
 286
 287   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 288 <div class="section">
 289 <h2><a name="health-check" id="health-check">Dynamic Health Checks</a><a title="Permanent link" href="#health-check" class="permalink">&para;</a></h2>
 290
 291
 292     <p>
 293       Before httpd proxies a request to a worker, it can <em>"test"</em> if that worker
 294       is available via setting the <code>ping</code> parameter for that worker using
 295       <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code>. Oftentimes it is
 296       more useful to check the health of the workers <em>out of band</em>, in a
 297       dynamic fashion. This is achieved in Apache httpd by the
 298       <code class="module"><a href="../mod/mod_proxy_hcheck.html">mod_proxy_hcheck</a></code> module.
 299     </p>
 300
 301   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 302 <div class="section">
 303 <h2><a name="status" id="status">BalancerMember status flags</a><a title="Permanent link" href="#status" class="permalink">&para;</a></h2>
 304
 305
 306     <p>
 307       In the <em>balancer-manager</em> the current state, or <em>status</em>, of a worker
 308       is displayed and can be set/reset. The meanings of these statuses are as follows:
 309     </p>
 310       <table class="bordered">
 311         <tr><th>Flag</th><th>String</th><th>Description</th></tr>
 312         <tr><td>&nbsp;</td><td><em>Ok</em></td><td>Worker is available</td></tr>
 313         <tr><td>&nbsp;</td><td><em>Init</em></td><td>Worker has been initialized</td></tr>
 314         <tr><td><code>D</code></td><td><em>Dis</em></td><td>Worker is disabled and will not accept any requests; will be
 315                     automatically retried.</td></tr>
 316         <tr><td><code>S</code></td><td><em>Stop</em></td><td>Worker is administratively stopped; will not accept requests
 317                     and will not be automatically retried</td></tr>
 318         <tr><td><code>I</code></td><td><em>Ign</em></td><td>Worker is in ignore-errors mode and will always be considered available.</td></tr>
 319         <tr><td><code>R</code></td><td><em>Spar</em></td><td>Worker is a hot spare. For each worker in a given lbset that is unusable
 320                     (draining, stopped, in error, etc.), a usable hot spare with the same lbset will be used in
 321                     its place. Hot spares can help ensure that a specific number of workers are always available
 322                     for use by a balancer.</td></tr>
 323         <tr><td><code>H</code></td><td><em>Stby</em></td><td>Worker is in hot-standby mode and will only be used if no other
 324                     viable workers or spares are available in the balancer set.</td></tr>
 325         <tr><td><code>E</code></td><td><em>Err</em></td><td>Worker is in an error state, usually due to failing pre-request check;
 326                     requests will not be proxied to this worker, but it will be retried depending on
 327                     the <code>retry</code> setting of the worker.</td></tr>
 328         <tr><td><code>N</code></td><td><em>Drn</em></td><td>Worker is in drain mode and will only accept existing sticky sessions
 329                     destined for itself and ignore all other requests.</td></tr>
 330         <tr><td><code>C</code></td><td><em>HcFl</em></td><td>Worker has failed dynamic health check and will not be used until it
 331                     passes subsequent health checks.</td></tr>
 332       </table>
 333   </div></div>
 334 <div class="bottomlang">
 335 <p><span>Available Languages: </span><a href="../en/howto/reverse_proxy.html" title="English">&nbsp;en&nbsp;</a> |
 336 <a href="../es/howto/reverse_proxy.html" hreflang="es" rel="alternate" title="Español">&nbsp;es&nbsp;</a> |
 337 <a href="../fr/howto/reverse_proxy.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
 338 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
 339 <script type="text/javascript"><!--//--><![CDATA[//><!--
 340 var comments_shortname = 'httpd';
 341 var comments_identifier = 'http://httpd.apache.org/docs/trunk/howto/reverse_proxy.html';
 342 (function(w, d) {
 343     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 344         d.write('<div id="comments_thread"><\/div>');
 345         var s = d.createElement('script');
 346         s.type = 'text/javascript';
 347         s.async = true;
 348         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 349         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 350     }
 351     else {
 352         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 353     }
 354 })(window, document);
 355 //--><!]]></script></div><div id="footer">
 356 <p class="apache">Copyright 2018 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 357 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
 358 if (typeof(prettyPrint) !== 'undefined') {
 359     prettyPrint();
 360 }
 361 //--><!]]></script>
 362 </body></html>