checker-ping

ICMP ping checker for happyDomain.

Checks reachability, round-trip time, and packet loss for IP addresses associated with a domain's services.

Usage

Standalone HTTP server

# Build and run
make
./checker-ping -listen :8080

# With privileged ICMP (requires CAP_NET_RAW or root)
./checker-ping -listen :8080 -privileged

The server exposes:

• GET /health, health check
• POST /collect, collect ping observations (happyDomain external checker protocol)

Docker

make docker
docker run -p 8080:8080 happydomain/checker-ping

# With privileged ICMP
docker run --cap-add NET_RAW -p 8080:8080 happydomain/checker-ping -privileged

happyDomain plugin

make plugin
# produces checker-ping.so, loadable by happyDomain as a Go plugin

The plugin exposes a NewCheckerPlugin symbol returning the checker definition and observation provider, which happyDomain registers in its global registries at load time.

Versioning

The binary, plugin, and Docker image embed a version string overridable at build time:

make CHECKER_VERSION=1.2.3
make plugin CHECKER_VERSION=1.2.3
make docker CHECKER_VERSION=1.2.3

happyDomain remote endpoint

Set the endpoint admin option for the ping checker to the URL of the running checker-ping server (e.g., http://checker-ping:8080). happyDomain will delegate observation collection to this endpoint.

Deployment

The /collect endpoint has no built-in authentication and will issue ICMP probes to whatever hostnames or IP addresses the caller supplies, including private (RFC 1918), loopback, link-local, and cloud metadata addresses (e.g. 169.254.169.254). It is meant to run on a trusted network, reachable only by the happyDomain instance that drives it. Restrict access via a reverse proxy with authentication, a network ACL, or by binding the listener to a private interface; do not expose it directly to the public internet.

Rules

Code	Description	Severity
ping.reachable	Verifies every target replied to at least one ICMP probe.	CRITICAL
ping.rtt	Flags targets whose average round-trip time crosses the warning or critical threshold.	CRITICAL
ping.ipv6_reachable	Verifies that at least one IPv6 target replied to an ICMP probe.	WARNING
ping.packet_loss	Flags targets whose packet-loss ratio crosses the warning or critical threshold.	CRITICAL

License & licensing roadmap

This project is currently licensed under the GNU Affero General Public License v3.0 (see LICENSE), because it still imports happydns.ServiceMessage and abstract.Server from the happyDomain server module (git.happydns.org/happyDomain/model and git.happydns.org/happyDomain/services/abstract), which are themselves distributed under AGPL-3.0 and a commercial license.

The core checker types (CheckerOptions, CheckerDefinition, ObservationProvider, CheckRule, …) have already been migrated to checker-sdk-go; only the service-message types remain on the AGPL side.

Planned relicensing: as soon as the remaining ServiceMessage / abstract.Server dependency has been removed (moved into a dedicated permissively licensed module), this project will be relicensed under the MIT License, in line with the rest of the happyDomain checker ecosystem (see checker-dummy for the target shape).

Contributors notice: by submitting a contribution to this repository, you accept that your contribution will be relicensed from AGPL-3.0 to MIT at the time of the relicensing described above. If you do not agree with this, please do not submit contributions until the relicensing has taken place.

The third-party Apache-2.0 attributions for checker-sdk-go are recorded in NOTICE and must accompany any binary or source redistribution of this project.