Apache HTTP Server Version 2.4
Apache HTTP Server Version 2.4
| Description: | Dynamic health check of Balancer members (workers) for
mod_proxy |
|---|---|
| Status: | Extension |
| ModuleIdentifier: | proxy_hcheck_module |
| SourceFile: | mod_proxy_hcheck.c |
| Compatibility: | Available in Apache 2.4.21 and later |
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.
This module requires the service of mod_watchdog.
The health check mechanism is enabled via the use of additional
BalancerMember parameters, which are configured in the standard
way via ProxyPass:
A new BalancerMember status state (flag) is defined via this module: "C".
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
balancer-manager.
| Parameter | Default | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| hcmethod | None | No dynamic health check performed. Choices are:
| ||||||||||||||||||||||||
| hcpasses | 1 | Number of successful health check tests before worker is re-enabled | ||||||||||||||||||||||||
| hcfails | 1 | Number of failed health check tests before worker is disabled | ||||||||||||||||||||||||
| hcinterval | 30 | Period of health checks in seconds (e.g. performed every 30 seconds) | ||||||||||||||||||||||||
| hcuri | Additional URI to be appended to the worker URL for the health check. | |||||||||||||||||||||||||
| hctemplate | Name of template, created via ProxyHCTemplate to use for setting health check parameters for this worker | |||||||||||||||||||||||||
| hcexpr | Name of expression, created via ProxyHCExpr, used to check response headers for health.If not used, 2xx thru 3xx status codes imply success | |||||||||||||||||||||||||
The following example shows how one might configured health checking for various backend servers:
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"
In this scenario, http://www.example.com/ is health checked by sending a GET /status.php
request to that server and seeing that the returned page does not include the string Under maintenance. 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.
http://www2.example.com/ is checked by sending a simple HEAD request every
10 seconds and making sure that the response status is 2xx, 3xx or 4xx. http://www3.example.com/ 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, http://www4.example.com/ is
not dynamically checked at all.
| Description: | Creates a named condition expression to use to determine health of the backend based on its response. |
|---|---|
| Syntax: | ProxyHCExpr name {ap_expr expression} |
| Context: | server config, virtual host |
| Status: | Extension |
| Module: | mod_proxy_hcheck |
The ProxyHCExpr 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 hcexpr
parameter
ProxyHCExpr ok234 {%{REQUEST_STATUS} =~ /^[234]/}
ProxyPass "/apps" "http://backend.example.com/" hcexpr=ok234
If using a health check method (eg: GET) which results in a response
body, that body itself can be checked via ap_expr using the hc()
expression function, which is unique to this module.
In the following example, we send the backend a GET request
and if the response body contains the phrase Under maintenance,
we want to disable the backend.
ProxyHCExpr in_maint {hc('body') !~ /Under maintenance/}
ProxyPass "/apps" "http://backend.example.com/" hcexpr=in_maint hcmethod=get hcuri=/status.php
NOTE: Since response body can quite large, it is best if used against specific status pages.
| Description: | Creates a named template for setting various health check parameters |
|---|---|
| Syntax: | ProxyHCTemplate name parameter=setting <...> |
| Context: | server config, virtual host |
| Status: | Extension |
| Module: | mod_proxy_hcheck |
The ProxyHCTemplate directive allows
for creating a named set (template) of health check parameters
that can then be assigned to balancer members via the hctemplate
parameter
ProxyHCTemplate tcp5 hcmethod=tcp hcinterval=5 ProxyPass "/apps" "http://backend.example.com/" hctemplate=tcp5
| Description: | Sets the total server-wide size of the threadpool used for the health check workers. |
|---|---|
| Syntax: | ProxyHCTPsize <size> |
| Context: | server config |
| Status: | Extension |
| Module: | mod_proxy_hcheck |
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 ProxyHCTPsize directive
determines the size of this threadpool. If set to 0, no threadpool
is used at all, resulting in serialized health checks. The default size is 16.
ProxyHCTPsize 32