Apache 2.4 mod_proxy_hcheck: Configuring Dynamic Health Checks and BalancerMember Probes

Dynamic Balancer Member Health Checking in Apache 2.4

Starting in Apache HTTP Server 2.4.21, the extension module mod_proxy_hcheck provides dynamic health checking for load-balanced backend workers managed by mod_proxy_balancer. These health check probes run independently of actual reverse proxy client requests. When health checks fail according to configured thresholds, the module sets a dedicated balancer member status flag (C) and takes the worker offline until subsequent passing checks re-enable it.

Core Architecture and Prerequisites

According to the official Apache 2.4 documentation for mod_proxy_hcheck and mod_proxy_balancer, several modules and system dependencies must be present in the server:

• Proxy Framework and Balancing Modules: mod_proxy_balancer requires mod_proxy. In addition, the load-balancing scheduler algorithm is not provided by mod_proxy_balancer itself, but by scheduler modules such as mod_lbmethod_byrequests, mod_lbmethod_bytraffic, mod_lbmethod_bybusyness, or mod_lbmethod_heartbeat. Therefore, mod_proxy, mod_proxy_balancer, and at least one load-balancing scheduler algorithm module must be present.
• Protocol Provider Modules: Load balancing requires a protocol module matching the backend service, such as mod_proxy_http for HTTP, mod_proxy_ftp for FTP, mod_proxy_ajp for AJP13, or mod_proxy_wstunnel for WebSocket.
• Watchdog Service: mod_proxy_hcheck requires the background service of mod_watchdog.
• Version Availability: mod_proxy_hcheck is available in Apache 2.4.21 and later. HTTP/1.1 probe methods (OPTIONS11, HEAD11, and GET11) require version 2.4.55 and above.
• Thread Support: If Apache httpd and APR are built with thread support, health check operations offload to a threadpool associated with the Watchdog process, enabling parallel checks.

Security Warning for Reverse Proxying and Management

The documentation for mod_proxy_balancer includes an explicit security warning: do not enable proxying until you have secured your server. Open proxy servers are dangerous both to your local network and to the Internet at large.

Similarly, administrative endpoints must be strictly protected. The balancer manager interface exposes direct control over backend workers and operational flags. When enabling management handlers, access controls such as host or IP restrictions must prevent unauthorized access.

Configuring BalancerMember Probe Parameters

Dynamic health checks are enabled worker by worker using parameters configured on BalancerMember directives via ProxyPass:

Documented BalancerMember Health Check Parameters

Status Code Rules: For HTTP probe methods, unless hcexpr is used, any 2xx or 3xx HTTP status returned by the backend is interpreted as passing the health check. When an hcexpr expression is assigned, the expression replaces this default status evaluation rule.

Custom Response Evaluation with ProxyHCExpr

The ProxyHCExpr directive creates a named condition expression evaluated against the backend response. It is valid in server configuration and virtual host contexts. Syntax:

ProxyHCExpr name { ap_expr expression }

Expressions can use curly braces ({}) as quoting delimiters in addition to normal quotes. You can evaluate response headers (such as REQUEST_STATUS) or test the response body using the specialized hc('body') function unique to mod_proxy_hcheck. Because response bodies can be quite large, official documentation notes that body matching is best used against specific status pages specified with hcuri.

Example: Health Check Configuration

The following configuration illustrates how probe methods, intervals, and expression evaluations are applied across backend cluster members:

# Expression accepting 2xx, 3xx, and 4xx status codes as healthy
ProxyHCExpr ok234 {%{REQUEST_STATUS} =~ /^[234]/}

# Expression checking that the response body does not contain maintenance text
ProxyHCExpr in_maint {hc('body') !~ /Under maintenance/}

<Proxy "balancer://appcluster">
    # Health checked by sending GET /status.php every 30 seconds; disabled if body contains "Under maintenance"
    BalancerMember "http://node1.example.com/" hcmethod=GET hcuri=/status.php hcexpr=in_maint

    # Checked every 10 seconds via HEAD; accepts 2xx, 3xx, or 4xx responses via ok234
    BalancerMember "http://node2.example.com/" hcmethod=HEAD hcexpr=ok234 hcinterval=10

    # Socket-level TCP check every 5 seconds; requires 3 consecutive failures to disable and 2 passes to re-enable
    BalancerMember "http://node3.example.com/" hcmethod=TCP hcinterval=5 hcpasses=2 hcfails=3

    # Not dynamically checked
    BalancerMember "http://node4.example.com/"
</Proxy>

ProxyPass "/" "balancer://appcluster/"
ProxyPassReverse "/" "balancer://appcluster/"

Reusable Configurations: ProxyHCTemplate and ProxyHCTPsize

Standardizing Worker Settings with ProxyHCTemplate

The ProxyHCTemplate directive creates a named template of health check parameters to apply to multiple balancer members using the hctemplate parameter. It is supported in server configuration and virtual host contexts. Syntax:

ProxyHCTemplate name parameter=setting [...]

Example definition and assignment:

ProxyHCTemplate tcp5 hcmethod=tcp hcinterval=5

<Proxy "balancer://appcluster">
    BalancerMember "http://node1.example.com/" hctemplate=tcp5
    BalancerMember "http://node2.example.com/" hctemplate=tcp5
</Proxy>

Parallel Checks and Threadpool Sizing (ProxyHCTPsize)

When Apache httpd and APR are compiled with thread support, the health check module offloads checking tasks to a threadpool associated with the Watchdog process, allowing parallel checks. The ProxyHCTPsize directive sets the total server-wide size of this threadpool:

• Syntax: ProxyHCTPsize size
• Default: ProxyHCTPsize 16
• Context: Server config only.
• Serialized Fallback: If set to 0, no threadpool is used at all, resulting in serialized health checks.

Monitoring Worker State with Balancer Manager

When a worker is taken offline due to failures determined by mod_proxy_hcheck, the status flag C is set on the member. As documented in mod_proxy_balancer, this flag can be viewed and modified via the balancer-manager web interface.

To enable the balancer manager, both mod_status and mod_proxy_balancer must be present in the server. Access should be restricted to trusted administrators inside a Location container:

<Location "/balancer-manager">
    SetHandler balancer-manager
    Require host example.com
</Location>

Administrators can access the manager at http://your.server.name/balancer-manager to inspect worker status, modify balance factors, or change offline modes. Note that only balancers defined outside of <Location ...> containers can be dynamically controlled by the balancer manager.

Research Method and Limitations

This technical guide was prepared solely from the supplied public documentation excerpts for Apache HTTP Server 2.4 (specifically mod_proxy_hcheck and mod_proxy_balancer). No competing coverage or external third-party sources were supplied, so independent competitive comparison and third-party benchmark evaluations are unavailable. Furthermore, the supplied documentation excerpt for mod_proxy_balancer was truncated, limiting analysis to the visible passages.

Source references

• httpd.apache.org documentation
• httpd.apache.org documentation