docs/manual/mod/mod_proxy_hcheck.xml - httpd - Git at Google

 <?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 a <code>HTTP OPTIONS</code> request to the backend via <code>HTTP/1.0</code></td><td>*</td></tr>
         		<tr><td>HEAD</td><td>Send a <code>HTTP HEAD</code> request to the backend via <code>HTTP/1.0</code></td><td>*</td></tr>
         		<tr><td>GET</td><td>Send a <code>HTTP GET</code> request to the backend via <code>HTTP/1.0</code></td><td>*</td></tr>
         		<tr><td>OPTIONS11</td><td>Send a <code>HTTP OPTIONS</code> request to the backend via <code>HTTP/1.1</code></td><td>*</td></tr>
         		<tr><td>HEAD11</td><td>Send a <code>HTTP HEAD</code> request to the backend via <code>HTTP/1.1</code></td><td>*</td></tr>
         		<tr><td>GET11</td><td>Send a <code>HTTP GET</code> request to the backend via <code>HTTP/1.1</code></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).
         Uses the <a href="directive-dict.html#Syntax">time-interval</a> directive syntax.</td></tr>
     <tr><td>hcuri</td>
         <td>&nbsp;</td>
         <td>Additional URI to be appended to the worker URL for the health check.</td></tr>
     <tr><td>hctemplate</td>
         <td>&nbsp;</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>&nbsp;</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>

 <note><title>Compatibility:</title>
     <p><code>OPTIONS11</code>, <code>HEAD11</code> and <code>GET11</code> are
        available in 2.4.55 and above.</p>
 </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/}

 &lt;Proxy balancer://foo&gt;
   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/
 &lt;/Proxy&gt;

 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>
 <override>FileInfo</override>

 <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"

 &lt;Proxy balancer://foo&gt;
   BalancerMember http://www2.example.com/  hcmethod=HEAD hcexpr=ok234 hcinterval=10
 &lt;/Proxy&gt;
     </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"

 &lt;Proxy balancer://foo&gt;
   BalancerMember http://www.example.com/ hcexpr=in_maint hcmethod=get hcuri=/status.php
 &lt;/Proxy&gt;
     </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>
 <override>FileInfo</override>

 <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"

 &lt;Proxy balancer://foo&gt;
   BalancerMember http://www2.example.com/ hctemplate=tcp5
 &lt;/Proxy&gt;
     </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>
	<?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 a <code>HTTP OPTIONS</code> request to the backend via <code>HTTP/1.0</code></td><td>*</td></tr>
	<tr><td>HEAD</td><td>Send a <code>HTTP HEAD</code> request to the backend via <code>HTTP/1.0</code></td><td>*</td></tr>
	<tr><td>GET</td><td>Send a <code>HTTP GET</code> request to the backend via <code>HTTP/1.0</code></td><td>*</td></tr>
	<tr><td>OPTIONS11</td><td>Send a <code>HTTP OPTIONS</code> request to the backend via <code>HTTP/1.1</code></td><td>*</td></tr>
	<tr><td>HEAD11</td><td>Send a <code>HTTP HEAD</code> request to the backend via <code>HTTP/1.1</code></td><td>*</td></tr>
	<tr><td>GET11</td><td>Send a <code>HTTP GET</code> request to the backend via <code>HTTP/1.1</code></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).
	Uses the <a href="directive-dict.html#Syntax">time-interval</a> directive syntax.</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>

	<note><title>Compatibility:</title>
	<p><code>OPTIONS11</code>, <code>HEAD11</code> and <code>GET11</code> are
	available in 2.4.55 and above.</p>
	</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>
	<override>FileInfo</override>

	<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>
	<override>FileInfo</override>

	<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>