1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type" />
<!--
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
This file is generated from xml source: DO NOT EDIT
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-->
<title>mod_proxy_hcheck - Apache HTTP Server Version 2.4</title>
<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
<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" />
<script src="../style/scripts/prettify.min.js" type="text/javascript">
</script>
<link href="../images/favicon.ico" rel="shortcut icon" /></head>
<body>
<div id="page-header">
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.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>
<p class="apache">Apache HTTP Server Version 2.4</p>
<img alt="" src="../images/feather.png" /></div>
<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
<div id="path">
<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.4</a> > <a href="./">Modules</a></div>
<div id="page-content">
<div id="preamble"><h1>Apache Module mod_proxy_hcheck</h1>
<div class="toplang">
<p><span>Available Languages: </span><a href="../en/mod/mod_proxy_hcheck.html" title="English"> en </a> |
<a href="../fr/mod/mod_proxy_hcheck.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
</div>
<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Dynamic health check of Balancer members (workers) for
<code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></td></tr>
<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>proxy_hcheck_module</td></tr>
<tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_proxy_hcheck.c</td></tr>
<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.4.21 and later</td></tr></table>
<h3>Summary</h3>
<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 <code class="module"><a href="../mod/mod_watchdog.html">mod_watchdog</a></code>.</p>
<div class="note"><h3>Parameters</h3>
<p>The health check mechanism is enabled via the use of additional
<code class="directive"><a href="../mod/mod_proxy.html#balancermember">BalancerMember</a></code> parameters, which are configured
in the standard way via <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code>:</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 /></tr>
<tr><td>TCP</td><td>Check that a socket to the backend can be created: e.g. "are you up"</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 colspan="3" /></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 <code class="directive"><a href="#proxyhctemplate">ProxyHCTemplate</a></code>,
to use for setting health check parameters for this worker</td></tr>
<tr><td>hcexpr</td>
<td> </td>
<td>Name of expression, created via <code class="directive"><a href="#proxyhcexpr">ProxyHCExpr</a></code>,
used to check response headers for health.<br />
<em>If not used, 2xx thru 3xx status codes imply success</em></td></tr>
</table>
</div>
<div class="note"><h3>Compatibility:</h3>
<p><code>OPTIONS11</code>, <code>HEAD11</code> and <code>GET11</code> are
available in 2.4.55 and above.</p>
</div>
</div>
<div id="quickview"><a href="https://www.apache.org/foundation/contributing.html" class="badge"><img src="https://www.apache.org/images/SupportApache-small.png" alt="Support Apache!" /></a><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#examples">Usage examples</a></li>
</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#proxyhcexpr">ProxyHCExpr</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#proxyhctemplate">ProxyHCTemplate</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#proxyhctpsize">ProxyHCTPsize</a></li>
</ul>
<h3>Bugfix checklist</h3><ul class="seealso"><li><a href="https://www.apache.org/dist/httpd/CHANGES_2.4">httpd changelog</a></li><li><a href="https://bz.apache.org/bugzilla/buglist.cgi?bug_status=__open__&list_id=144532&product=Apache%20httpd-2&query_format=specific&order=changeddate%20DESC%2Cpriority%2Cbug_severity&component=mod_proxy_hcheck">Known issues</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&component=mod_proxy_hcheck">Report a bug</a></li></ul><h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li>
<li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="examples" id="examples">Usage examples</a></h2>
<p>The following example shows how one might configured health checking
for various backend servers:</p>
<pre class="prettyprint lang-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"</pre>
<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>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="ProxyHCExpr" id="ProxyHCExpr">ProxyHCExpr</a> <a name="proxyhcexpr" id="proxyhcexpr">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Creates a named condition expression to use to determine health of the backend based on its response</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyHCExpr <em>name</em> {<em>ap_expr expression</em>}</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy_hcheck</td></tr>
</table>
<p>The <code class="directive">ProxyHCExpr</code> 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>
<div class="example"><h3>ProxyHCExpr: Allow for 2xx/3xx/4xx as passing</h3><pre class="prettyprint lang-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></pre>
</div>
<div class="note">
The <a href="../expr.html">expression</a> can use curly-parens ("{}") as
quoting deliminators in addition to normal quotes.
</div>
<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>
<div class="example"><h3>ProxyHCExpr: Checking response body</h3><pre class="prettyprint lang-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></pre>
</div>
<p><em>NOTE:</em> Since response body can quite large, it is best if used against specific status pages.</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="ProxyHCTemplate" id="ProxyHCTemplate">ProxyHCTemplate</a> <a name="proxyhctemplate" id="proxyhctemplate">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Creates a named template for setting various health check parameters</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyHCTemplate <em>name</em> <em>parameter</em>=<em>setting</em> [...]</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy_hcheck</td></tr>
</table>
<p>The <code class="directive">ProxyHCTemplate</code> 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>
<div class="example"><h3>ProxyHCTemplate</h3><pre class="prettyprint lang-config">ProxyHCTemplate tcp5 hcmethod=tcp hcinterval=5
ProxyPass "/apps" "balancer://foo"
<Proxy balancer://foo>
BalancerMember http://www2.example.com/ hctemplate=tcp5
</Proxy></pre>
</div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="ProxyHCTPsize" id="ProxyHCTPsize">ProxyHCTPsize</a> <a name="proxyhctpsize" id="proxyhctpsize">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the total server-wide size of the threadpool used for the health check workers</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyHCTPsize <em>size</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyHCTPsize 16</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy_hcheck</td></tr>
</table>
<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 <code class="directive">ProxyHCTPsize</code> 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>
<div class="example"><h3>ProxyHCTPsize</h3><pre class="prettyprint lang-config">ProxyHCTPsize 32</pre>
</div>
</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_proxy_hcheck.html" title="English"> en </a> |
<a href="../fr/mod/mod_proxy_hcheck.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
</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&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed 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 Libera.chat, or sent to our <a href="https://httpd.apache.org/lists.html">mailing lists</a>.</div>
<script type="text/javascript"><!--//--><![CDATA[//><!--
var comments_shortname = 'httpd';
var comments_identifier = 'http://httpd.apache.org/docs/2.4/mod/mod_proxy_hcheck.html';
(function(w, d) {
if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
d.write('<div id="comments_thread"><\/div>');
var s = d.createElement('script');
s.type = 'text/javascript';
s.async = true;
s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
(d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
}
else {
d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
}
})(window, document);
//--><!]]></script></div><div id="footer">
<p class="apache">Copyright 2025 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>
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.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[//><!--
if (typeof(prettyPrint) !== 'undefined') {
prettyPrint();
}
//--><!]]></script>
</body></html>
|
