2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision: 1734326 $ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <modulesynopsis metafile="mod_proxy_hcheck.xml.meta">
25 <name>mod_proxy_hcheck</name>
26 <description>Dynamic health check of Balancer members (workers) for
27 <module>mod_proxy</module></description>
28 <status>Extension</status>
29 <sourcefile>mod_proxy_hcheck.c</sourcefile>
30 <identifier>proxy_hcheck_module</identifier>
31 <compatibility>Available in Apache 2.4.21 and later</compatibility>
34 <p>This module provides for dynamic health checking of balancer
35 members (workers). This can be enabled on a worker-by-worker
36 basis. The health check is done independently of the
37 actual reverse proxy requests.</p>
39 <p>This module <em>requires</em> the service of <module>mod_watchdog</module>.</p>
41 <note><title>Parameters</title>
42 <p>The health check mechanism is enabled via the use of additional
43 BalancerMember parameters, which are configured in the standard
44 way via <directive module="mod_proxy">ProxyPass</directive>:</p>
46 <p>A new BalancerMember status state (flag) is defined via this module: "<code>C</code>".
47 When the worker is taken offline due to failures as determined by the health
48 check module, this flag is set, and can be seen (and modified) via the
49 <code>balancer-manager</code>.</p>
52 <tr><th>Parameter</th>
54 <th>Description</th></tr>
57 <td>No dynamic health check performed. Choices are:
59 <tr><th>Method</th><th>Description</th><th>Note</th></tr>
60 <tr><td>None</td><td>No dynamic health checking done</td><td></td></tr>
61 <tr><td>TCP</td><td>Check that a socket to the backend can be created: e.g. "are you up"</td><td></td></tr>
62 <tr><td>OPTIONS</td><td>Send an <code>HTTP OPTIONS</code> request to the backend</td><td>*</td></tr>
63 <tr><td>HEAD</td><td>Send an <code>HTTP HEAD</code> request to the backend</td><td>*</td></tr>
64 <tr><td>GET</td><td>Send an <code>HTTP GET</code> request to the backend</td><td>*</td></tr>
66 <tr><td>CPING</td><td><strong>AJP only</strong> Do <code>CPING/CPONG</code> check</td><td></td></tr>
67 <tr><td>PROVIDER</td><td>Name of <code>provider</code> to be used to check health</td><td></td></tr>
69 <tr><td colspan="3"></td></tr>
70 <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>
75 <td>Number of successful health check tests before worker is re-enabled</td></tr>
78 <td>Number of failed health check tests before worker is disabled</td></tr>
79 <tr><td>hcinterval</td>
81 <td>Period of health checks in seconds (e.g. performed every 30 seconds)</td></tr>
84 <td>Additional URI to be appended to the worker URL for the health check.</td></tr>
85 <tr><td>hctemplate</td>
87 <td>Name of template, created via <directive>ProxyHCTemplate</directive> to use for setting health check parameters for this worker</td></tr>
90 <td>Name of expression, created via <directive>ProxyHCExpr</directive>, used to check response headers for health.<br/>
91 <em>If not used, 2xx thru 3xx status codes imply success</em></td></tr>
96 <seealso><module>mod_proxy</module></seealso>
98 <section id="examples">
100 <title>Usage examples</title>
101 <p>The following example shows how one might configured health checking
102 for various backend servers:</p>
104 <!-- This section should probably be extended with more, useful examples -->
105 <highlight language="config">
106 ProxyHCExpr ok234 {%{REQUEST_STATUS} =~ /^[234]/}
107 ProxyHCExpr gdown {%{REQUEST_STATUS} =~ /^[5]/}
108 ProxyHCExpr in_maint {hc('body') !~ /Under maintenance/}
110 <Proxy balancer://foo>
111 BalancerMember http://www.example.com/ hcmethod=GET hcexpr=in_maint hcuri=/status.php
112 BalancerMember http://www2.example.com/ hcmethod=HEAD hcexpr=ok234 hcinterval=10
113 BalancerMember http://www3.example.com/ hcmethod=TCP hcinterval=5 hcpasses=2 hcfails=3
114 BalancerMember http://www4.example.com/
117 ProxyPass "/" "balancer://foo"
118 ProxyPassReverse "/" "balancer://foo"
121 <p>In this scenario, <code>http://www.example.com/</code> is health checked by sending a <code>GET /status.php</code>
122 request to that server and seeing that the returned page does not include the string <em>Under maintenance</em>. If
123 it does, that server is put in health-check fail mode, and disabled. This dynamic check is performed
124 every 30 seconds, which is the default.</p>
126 <p><code>http://www2.example.com/</code> is checked by sending a simple <code>HEAD</code> request every
127 10 seconds and making sure that the response status is 2xx, 3xx or 4xx. <code>http://www3.example.com/</code> is checked
128 every 5 seconds by simply ensuring that the socket to that server is up. If the backend is marked as
129 "down" and it passes 2 health check, it will be re-enabled and added back into the load balancer.
130 It takes 3 back-to-back health check failures to disable the server and move it out
131 of rotation. Finally, <code>http://www4.example.com/</code> is
132 not dynamically checked at all.</p>
137 <name>ProxyHCExpr</name>
138 <description>Creates a named condition expression to use to determine health of the backend based on its response.</description>
139 <syntax>ProxyHCExpr name {ap_expr expression}</syntax>
140 <contextlist><context>server config</context><context>virtual host</context>
144 <p>The <directive>ProxyHCExpr</directive> directive allows
145 for creating a named condition expression that checks the response
146 headers of the backend server to determine its health. This named
147 condition can then be assigned to balancer members via the <code>hcexpr</code>
150 <example><title>ProxyHCExpr: Allow for 2xx/3xx/4xx as passing</title>
151 <highlight language="config">
152 ProxyHCExpr ok234 {%{REQUEST_STATUS} =~ /^[234]/}
153 ProxyPass "/apps" "http://backend.example.com/" hcexpr=ok234
158 The <a href="../expr.html">expression</a> can use curly-parens ("{}") as
159 quoting deliminators in addition to normal quotes.
162 <p>If using a health check method (eg: <code>GET</code>) which results in a response
163 body, that body itself can be checked via <code>ap_expr</code> using the <code>hc()</code>
164 expression function, which is unique to this module.</p>
166 <p>In the following example, we send the backend a <code>GET</code> request
167 and if the response body contains the phrase <em>Under maintenance</em>,
168 we want to disable the backend.</p>
170 <example><title>ProxyHCExpr: Checking response body</title>
171 <highlight language="config">
172 ProxyHCExpr in_maint {hc('body') !~ /Under maintenance/}
173 ProxyPass "/apps" "http://backend.example.com/" hcexpr=in_maint hcmethod=get hcuri=/status.php
177 <p><em>NOTE:</em> Since response body can quite large, it is best if used against specific status pages.</p>
183 <name>ProxyHCTemplate</name>
184 <description>Creates a named template for setting various health check parameters</description>
185 <syntax>ProxyHCTemplate name parameter=setting <...></syntax>
186 <contextlist><context>server config</context><context>virtual host</context>
190 <p>The <directive>ProxyHCTemplate</directive> directive allows
191 for creating a named set (template) of health check parameters
192 that can then be assigned to balancer members via the <code>hctemplate</code>
195 <example><title>ProxyHCTemplate</title>
196 <highlight language="config">
197 ProxyHCTemplate tcp5 hcmethod=tcp hcinterval=5
198 ProxyPass "/apps" "http://backend.example.com/" hctemplate=tcp5
206 <name>ProxyHCTPsize</name>
207 <description>Sets the size of the threadpool used for the health check workers.</description>
208 <syntax>ProxyHCTPsize <size></syntax>
209 <contextlist><context>server config</context><context>virtual host</context>
213 <p>If Apache httpd and APR are built with thread support, the health check
214 module will offload the work of the actual checking to a threadpool
215 associated with the Watchdog process, allowing for parallel checks.
216 The <directive>ProxyHCTPsize</directive> directive
217 determines the size of this threadpool. If set to <code>0</code>, no threadpool
218 is used at all, resulting in serialized health checks. The default size is 16.</p>
220 <example><title>ProxyHCTPsize</title>
221 <highlight language="config">