Apache Module mod_proxy_hcheck

Summary

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 modulerequires the service ofmod_watchdog.

Topics

• Usage examples

Directives

• ProxyHCExpr
• ProxyHCTemplate
• ProxyHCTPsize

Bugfix checklist

• httpd changelog
• Known issues
• Report a bug

See also

• mod_proxy
• Comments

Usage examples

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 aGET /status.phprequest to that server and seeing that the returned page does not include the stringUnder maintenance. Ifit does, that server is put in health-check fail mode, and disabled. This dynamic check is performedevery 30 seconds, which is the default.

http://www2.example.com/ is checked by sending a simpleHEAD request every10 seconds and making sure that the response status is 2xx, 3xx or 4xx.http://www3.example.com/ is checkedevery 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 outof rotation. Finally,http://www4.example.com/ isnot dynamically checked at all.

ProxyHCExprDirective

TheProxyHCExpr 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 thehcexpr parameter.

ProxyHCExpr ok234 {%{REQUEST_STATUS} =~ /^[234]/}ProxyPass "/apps"     "balancer://foo"<Proxy balancer://foo>  BalancerMember http://www2.example.com/  hcmethod=HEAD hcexpr=ok234 hcinterval=10</Proxy>

If using a health check method (eg:GET) which results in a response body, that body itself can be checked viaap_expr using thehc() expression function, which is unique to this module.

In the following example, we send the backend aGET request and if the response body contains the phraseUnder maintenance, we want to disable the backend.

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>

NOTE: Since response body can quite large, it is best if used against specific status pages.

ProxyHCTemplateDirective

TheProxyHCTemplate directive allows for creating a named set (template) of health check parameters that can then be assigned to balancer members via thehctemplate parameter.

ProxyHCTemplate tcp5 hcmethod=tcp hcinterval=5ProxyPass "/apps"     "balancer://foo"<Proxy balancer://foo>  BalancerMember http://www2.example.com/ hctemplate=tcp5</Proxy>

ProxyHCTPsizeDirective

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. TheProxyHCTPsize directive determines the size of this threadpool. If set to0, no threadpool is used at all, resulting in serialized health checks.

ProxyHCTPsize 32