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.

Protocol

POST /collect

Request:

{
  "key": "ping",
  "target": {"userId": "...", "domainId": "..."},
  "options": {
    "addresses": ["1.2.3.4", "2001:db8::1"],
    "count": 5
  }
}

Response:

{
  "data": {
    "targets": [
      {
        "address": "1.2.3.4",
        "rtt_min": 1.2,
        "rtt_avg": 3.4,
        "rtt_max": 5.6,
        "packet_loss": 0,
        "sent": 5,
        "received": 5
      }
    ]
  }
}

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.