| <?xml version="1.0"?> |
| <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <modulesynopsis metafile="mod_proxy_hcheck.xml.meta"> |
| |
| <name>mod_proxy_hcheck</name> |
| <description>Dynamic health check of Balancer members (workers) for |
| <module>mod_proxy</module></description> |
| <status>Extension</status> |
| <sourcefile>mod_proxy_hcheck.c</sourcefile> |
| <identifier>proxy_hcheck_module</identifier> |
| <compatibility>Available in Apache 2.4.21 and later</compatibility> |
| |
| <summary> |
| <p>This module provides for dynamic health checking of balancer |
| members (workers). This can be enabled on a worker-by-worker |
| basis. The health check is done independently of the |
| actual reverse proxy requests.</p> |
| |
| <p>This module <em>requires</em> the service of <module>mod_watchdog</module>.</p> |
| |
| <note><title>Parameters</title> |
| <p>The health check mechanism is enabled via the use of additional |
| <directive module="mod_proxy">BalancerMember</directive> parameters, which are configured |
| in the standard way via <directive module="mod_proxy">ProxyPass</directive>:</p> |
| |
| <p>A new BalancerMember <a href="mod_proxy.html#status_table">status</a> state (flag) |
| is defined via this module: "<code>C</code>". |
| When the worker is taken offline due to failures as determined by the health |
| check module, this flag is set, and can be seen (and modified) via the |
| <code>balancer-manager</code>.</p> |
| |
| <table> |
| <tr><th>Parameter</th> |
| <th>Default</th> |
| <th>Description</th></tr> |
| <tr><td>hcmethod</td> |
| <td>None</td> |
| <td>No dynamic health check performed. Choices are: |
| <table> |
| <tr><th>Method</th><th>Description</th><th>Note</th></tr> |
| <tr><td>None</td><td>No dynamic health checking done</td><td></td></tr> |
| <tr><td>TCP</td><td>Check that a socket to the backend can be created: e.g. "are you up"</td><td></td></tr> |
| <tr><td>OPTIONS</td><td>Send an <code>HTTP OPTIONS</code> request to the backend</td><td>*</td></tr> |
| <tr><td>HEAD</td><td>Send an <code>HTTP HEAD</code> request to the backend</td><td>*</td></tr> |
| <tr><td>GET</td><td>Send an <code>HTTP GET</code> request to the backend</td><td>*</td></tr> |
| <!-- |
| <tr><td>CPING</td><td><strong>AJP only</strong> Do <code>CPING/CPONG</code> check</td><td></td></tr> |
| <tr><td>PROVIDER</td><td>Name of <code>provider</code> to be used to check health</td><td></td></tr> |
| --> |
| <tr><td colspan="3"></td></tr> |
| <tr><td colspan="3">*: Unless <code>hcexpr</code> is used, a 2xx or 3xx HTTP status will be interpreted as <em>passing</em> the health check</td></tr> |
| </table> |
| </td></tr> |
| <tr><td>hcpasses</td> |
| <td>1</td> |
| <td>Number of successful health check tests before worker is re-enabled</td></tr> |
| <tr><td>hcfails</td> |
| <td>1</td> |
| <td>Number of failed health check tests before worker is disabled</td></tr> |
| <tr><td>hcinterval</td> |
| <td>30</td> |
| <td>Period of health checks in seconds (e.g. performed every 30 seconds)</td></tr> |
| <tr><td>hcuri</td> |
| <td> </td> |
| <td>Additional URI to be appended to the worker URL for the health check.</td></tr> |
| <tr><td>hctemplate</td> |
| <td> </td> |
| <td>Name of template, created via <directive module="mod_proxy_hcheck">ProxyHCTemplate</directive>, |
| to use for setting health check parameters for this worker</td></tr> |
| <tr><td>hcexpr</td> |
| <td> </td> |
| <td>Name of expression, created via <directive module="mod_proxy_hcheck">ProxyHCExpr</directive>, |
| used to check response headers for health.<br/> |
| <em>If not used, 2xx thru 3xx status codes imply success</em></td></tr> |
| </table> |
| </note> |
| |
| </summary> |
| <seealso><module>mod_proxy</module></seealso> |
| |
| <section id="examples"> |
| |
| <title>Usage examples</title> |
| <p>The following example shows how one might configured health checking |
| for various backend servers:</p> |
| |
| <!-- This section should probably be extended with more, useful examples --> |
| <highlight language="config"> |
| ProxyHCExpr ok234 {%{REQUEST_STATUS} =~ /^[234]/} |
| ProxyHCExpr gdown {%{REQUEST_STATUS} =~ /^[5]/} |
| ProxyHCExpr in_maint {hc('body') !~ /Under maintenance/} |
| |
| <Proxy balancer://foo> |
| BalancerMember http://www.example.com/ hcmethod=GET hcexpr=in_maint hcuri=/status.php |
| BalancerMember http://www2.example.com/ hcmethod=HEAD hcexpr=ok234 hcinterval=10 |
| BalancerMember http://www3.example.com/ hcmethod=TCP hcinterval=5 hcpasses=2 hcfails=3 |
| BalancerMember http://www4.example.com/ |
| </Proxy> |
| |
| ProxyPass "/" "balancer://foo" |
| ProxyPassReverse "/" "balancer://foo" |
| </highlight> |
| |
| <p>In this scenario, <code>http://www.example.com/</code> is health checked by sending a <code>GET /status.php</code> |
| request to that server and seeing that the returned page does not include the string <em>Under maintenance</em>. If |
| it does, that server is put in health-check fail mode, and disabled. This dynamic check is performed |
| every 30 seconds, which is the default.</p> |
| |
| <p><code>http://www2.example.com/</code> is checked by sending a simple <code>HEAD</code> request every |
| 10 seconds and making sure that the response status is 2xx, 3xx or 4xx. <code>http://www3.example.com/</code> is checked |
| every 5 seconds by simply ensuring that the socket to that server is up. If the backend is marked as |
| "down" and it passes 2 health check, it will be re-enabled and added back into the load balancer. |
| It takes 3 back-to-back health check failures to disable the server and move it out |
| of rotation. Finally, <code>http://www4.example.com/</code> is |
| not dynamically checked at all.</p> |
| |
| </section> |
| |
| <directivesynopsis> |
| <name>ProxyHCExpr</name> |
| <description>Creates a named condition expression to use to determine health of the backend based on its response</description> |
| <syntax>ProxyHCExpr <em>name</em> {<em>ap_expr expression</em>}</syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive>ProxyHCExpr</directive> directive allows |
| for creating a named condition expression that checks the response |
| headers of the backend server to determine its health. This named |
| condition can then be assigned to balancer members via the <code>hcexpr</code> |
| parameter.</p> |
| |
| <example><title>ProxyHCExpr: Allow for 2xx/3xx/4xx as passing</title> |
| <highlight language="config"> |
| ProxyHCExpr ok234 {%{REQUEST_STATUS} =~ /^[234]/} |
| ProxyPass "/apps" "balancer://foo" |
| |
| <Proxy balancer://foo> |
| BalancerMember http://www2.example.com/ hcmethod=HEAD hcexpr=ok234 hcinterval=10 |
| </Proxy> |
| </highlight> |
| </example> |
| |
| <note> |
| The <a href="../expr.html">expression</a> can use curly-parens ("{}") as |
| quoting deliminators in addition to normal quotes. |
| </note> |
| |
| <p>If using a health check method (eg: <code>GET</code>) which results in a response |
| body, that body itself can be checked via <code>ap_expr</code> using the <code>hc()</code> |
| expression function, which is unique to this module.</p> |
| |
| <p>In the following example, we send the backend a <code>GET</code> request |
| and if the response body contains the phrase <em>Under maintenance</em>, |
| we want to disable the backend.</p> |
| |
| <example><title>ProxyHCExpr: Checking response body</title> |
| <highlight language="config"> |
| ProxyHCExpr in_maint {hc('body') !~ /Under maintenance/} |
| ProxyPass "/apps" "balancer://foo" |
| |
| <Proxy balancer://foo> |
| BalancerMember http://www.example.com/ hcexpr=in_maint hcmethod=get hcuri=/status.php |
| </Proxy> |
| </highlight> |
| </example> |
| |
| <p><em>NOTE:</em> Since response body can quite large, it is best if used against specific status pages.</p> |
| </usage> |
| </directivesynopsis> |
| |
| |
| <directivesynopsis> |
| <name>ProxyHCTemplate</name> |
| <description>Creates a named template for setting various health check parameters</description> |
| <syntax>ProxyHCTemplate <em>name</em> <em>parameter</em>=<em>setting</em> [...]</syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive>ProxyHCTemplate</directive> directive allows |
| for creating a named set (template) of health check parameters |
| that can then be assigned to balancer members via the <code>hctemplate</code> |
| parameter.</p> |
| |
| <example><title>ProxyHCTemplate</title> |
| <highlight language="config"> |
| ProxyHCTemplate tcp5 hcmethod=tcp hcinterval=5 |
| ProxyPass "/apps" "balancer://foo" |
| |
| <Proxy balancer://foo> |
| BalancerMember http://www2.example.com/ hctemplate=tcp5 |
| </Proxy> |
| </highlight> |
| </example> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>ProxyHCTPsize</name> |
| <description>Sets the total server-wide size of the threadpool used for the health check workers</description> |
| <syntax>ProxyHCTPsize <em>size</em></syntax> |
| <default>ProxyHCTPsize 16</default> |
| <contextlist><context>server config</context> |
| </contextlist> |
| |
| <usage> |
| <p>If Apache httpd and APR are built with thread support, the health check |
| module will offload the work of the actual checking to a threadpool |
| associated with the Watchdog process, allowing for parallel checks. |
| The <directive>ProxyHCTPsize</directive> directive |
| determines the size of this threadpool. If set to <code>0</code>, no threadpool |
| is used at all, resulting in serialized health checks.</p> |
| |
| <example><title>ProxyHCTPsize</title> |
| <highlight language="config"> |
| ProxyHCTPsize 32 |
| </highlight> |
| </example> |
| |
| </usage> |
| </directivesynopsis> |
| |
| </modulesynopsis> |