mod_proxy_beacon - Apache HTTP Server Version 2.5
Modules | Directives | FAQ | Glossary | Sitemap | Report a bug Apache HTTP Server Version 2.5 Apache > HTTP Server > Documentation > Version 2.5 > Modules Apache Module mod_proxy_beacon Available Languages: en | fr Description: Dynamic Balancer membership where backends announce themselves to the reverse proxy over unicast UDP datagrams Status: Extension Module Identifier: proxy_beacon_module Source File: mod_proxy_beacon.c Compatibility: Available in Apache 2.5 and later Summary This module lets backend servers announce themselves to a front-end reverse proxy, which then adds each announcing backend as a live member (worker) of a mod_proxy_balancer balancer.
When a backend stops announcing, the proxy takes it out of rotation. This provides self-registering, self-healing balancer membership without editing the proxy configuration or driving the balancer-manager by hand. Communication uses plain unicast UDP datagrams (not multicast, which is filtered on most networks and does not traverse the public Internet). The data flows from backend to proxy: The reverse proxy binds a UDP socket and receives on a stable address ( ProxyBeaconListen ).
Each backend periodically sends a short announcement datagram to the proxy ( ProxyBeaconAddress ), advertising its own routable URL ( ProxyBeaconAdvertise ). Datagrams are fire-and-forget: a lost announcement is recovered by the next periodic one, and reordering is rejected by a per-backend timestamp check, so no connection, reconnect, or framing layer is needed. On the proxy, ProxyBeaconBalancer names the balancer that announced backends are added to.
Membership changes are applied using the same internal mechanism as the balancer-manager web interface, so a backend added this way behaves exactly like a statically configured or manually added BalancerMember , and is visible and editable in the balancer-manager . This module requires the service of mod_watchdog and mod_proxy_balancer . The background work (listening, publishing, adding and evicting members) runs in a single mod_watchdog child process, so it is not available under the prefork MPM behaviour where that singleton cannot run.
Authentication Any host that can reach the proxy's receive port could otherwise announce an arbitrary backend URL and cause the proxy to send client traffic to it (and a UDP source address is trivially spoofable). ProxyBeaconSecret is therefore required : it must be set to the same value on the proxy and on every backend, and the server fails to start if any participating server omits it. Announcements are authenticated with a keyed message-authentication code (MAC) and a timestamp, and the proxy drops any announcement that is not validly signed and recent.
There is no unauthenticated mode. Confidentiality Announcements are authenticated but not encrypted; the payload is operational metadata (backend URLs), not secret data. Transport confidentiality (e.g. DTLS) is not currently provided and would be a separate future layer. Topics Usage example Member identity Ownership and watchdog hand-off Administrator control of members Message validation and limits Directives ProxyBeaconAddress ProxyBeaconAdvertise ProxyBeaconBalancer ProxyBeaconInterval ProxyBeaconListen ProxyBeaconMaxSkew ProxyBeaconSecret ProxyBeaconTimeout Bugfix checklist httpd changelog Known issues Report a bug See also mod_proxy mod_proxy_balancer mod_proxy_hcheck mod_watchdog Usage example ¶ The following pair of configurations sets up a self-registering balancer.
The backends require no knowledge of each other and the proxy needs no pre-declared BalancerMember entries — only an empty balancer with room to grow. On the reverse proxy : # Receive backend announcements on the cluster network interface (UDP). ProxyBeaconListen 0.0.0.0:5555 ProxyBeaconSecret "hex:00112233445566778899aabbccddeeff" ProxyBeaconBalancer cluster # A backend is dropped from rotation if it does not announce for 30 seconds.
ProxyBeaconTimeout 30 # An initially-empty balancer with spare slots for the dynamic members. <Proxy balancer://cluster> ProxySet growth=16 </Proxy> ProxyPass "/" "balancer://cluster/" ProxyPassReverse "/" "balancer://cluster/" On each backend server: # Announce this backend's routable origin to the proxy every 10 seconds (UDP). ProxyBeaconAddress proxy.example.com:5555 ProxyBeaconAdvertise http://10.0.0.5:8080 ProxyBeaconSecret "hex:00112233445566778899aabbccddeeff" ProxyBeaconInterval 10 When a backend starts it begins sending announcements.
The proxy verifies each announcement against the shared secret, adds http://10.0.0.5:8080 as a member of balancer://cluster , and enables it. If that backend later stops announcing for longer than ProxyBeaconTimeout , the proxy disables the member (taking it out of rotation); a subsequent announcement re-enables it. A backend added at runtime occupies one of the balancer's growth slots for the lifetime of the server process; it is disabled rather than removed when it stops announcing, matching the behaviour of the balancer-manager (which can add, but not remove, workers at runtime).
Size growth for the maximum number of backends you expect to register. Member identity ¶ An announced URL identifies a backend origin : scheme://host[:port] , and nothing more. The proxy uses the same string as the member's identity everywhere: as the key under which it tracks the backend's lease and replay state, and as the worker name it creates in the balancer. To keep those identities equal, the proxy: canonicalizes every announced URL: the scheme and host are lower-cased, the scheme's default port is dropped ( HTTP://Backend.Example.com:80 and http://backend.example.com are the same member), and a single trailing / is ignored; drops any announcement that is not an origin: one carrying a path (other than / ), a query string, a fragment, user information, an invalid port (such as 0 ), or the unix: socket form.
The drop is logged (rate-limited) as unacceptable url and the backend is not added. Paths are refused because the balancer finds a member by longest prefix match. Announcements for http://10.0.0.5:8080/one and http://10.0.0.5:8080/one/two would be tracked as two members with separate leases but resolve to a single worker, so the lapse of one lease could disable a worker whose other lease was still current. Choose request paths on the proxy with ProxyPass , not through the advertised URL.
A backend that is announced successfully is confirmed to exist in the balancer before it is reported as added, enabled or evicted; an announcement that the proxy cannot turn into a member is logged and retried after a back-off rather than reported as a success. Ownership and watchdog hand-off ¶ Every worker that mod_proxy_beacon creates is marked with the Bcn status (flag B ), which is stored in the worker's shared state and shown by the balancer-manager .
The module only enables or evicts workers that carry this mark. A worker of the same name that does not — a BalancerMember from the configuration, or one added by an administrator — is left alone; an announcement for it is dropped and logged as member not managed by beacon . The announcements are received and the leases kept by a single mod_watchdog child process. If that process exits or is killed, the watchdog singleton moves to another child, which starts with no record of the members it did not add itself.
When a child becomes the owner it therefore takes over every worker in the balancer carrying the Bcn mark (logged as took over N existing member(s) ): each taken-over member gets a fresh lease starting at that moment, so a member that has since fallen silent is evicted ProxyBeaconTimeout after the hand-off instead of staying enabled indefinitely; a member that is already disabled is treated as evicted, and its next announcement re-enables it.
A dead backend can therefore stay in rotation for up to one ProxyBeaconTimeout after a hand-off. The per-member replay high-water mark is not carried over either
The rest of this page is on the live site.