happyDomain/checker-srv
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
checker-srv/README.md

5.8 KiB
Raw Permalink Blame History

checker-srv

Generic SRV records checker for happyDomain.

For every SRV record attached to a service, verifies:

  • DNS resolution of each target (A/AAAA)
  • RFC 2782 compliance: target is not "." (null), target is not a CNAME
  • TCP reachability on target:port (for _tcp SRVs)
  • UDP reachability on target:port (for _udp SRVs), via ICMP port-unreachable detection

TLS/certificate testing is intentionally out of scope, it belongs to a dedicated TLS checker.

The HTML report surfaces the most common failure scenarios at the top with actionable remediation guidance (DNS failure, CNAME-as-target, TCP unreachable, explicit null-target).

Usage

Standalone HTTP server

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

The server exposes:

  • GET /health, health check
  • GET /definition, checker definition (options, rules, availability)
  • POST /collect, collect SRV observations (happyDomain external checker protocol)
  • POST /evaluate, evaluate observations against the rules
  • POST /report, render the HTML report

Docker

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

happyDomain plugin

make plugin
# produces checker-srv.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 SRV checker to the URL of the running checker-srv server (e.g., http://checker-srv:8080). happyDomain will delegate observation collection to this endpoint.

Rules

Code Description Severity
srv_records_present At least one SRV record is published for this service. CRITICAL
srv_null_target Detects SRV records with target ., signaling the service is intentionally not available. WARNING
srv_target_not_cname RFC 2782: SRV targets must resolve directly to A/AAAA, not through a CNAME. WARNING
srv_targets_resolve Every SRV target resolves to at least one A/AAAA address. CRITICAL
srv_port_valid SRV records advertise a non-zero port that clients can actually connect to. CRITICAL
srv_priority_weight_sanity Priority/weight values follow RFC 2782 conventions (failover present, weights meaningful). WARNING
srv_tcp_reachable Every TCP SRV target:port accepts a TCP connection. CRITICAL
srv_udp_reachable UDP SRV targets do not return ICMP port-unreachable. WARNING
srv_redundancy At least two distinct SRV targets exist (avoids single point of failure). INFO

Discovered TLS endpoints

As a by-product of every /collect, this checker publishes DiscoveryEntry records of type tls.endpoint.v1 (see checker-tls/contract) so that the TLS checker can probe the targets without re-parsing SRV data:

  • Direct TLS entries (empty STARTTLS) for service names that imply implicit TLS on connect: _https, _ldaps, _sips, _imaps, _pop3s, _smtps, _submissions, _xmpps-client, _xmpps-server, _ftps, _nntps, _ircs, _telnets, _ipps, _mqtts, _coaps, _stuns, _turns.
  • STARTTLS entries for service names that upgrade mid-stream: _smtp (opportunistic), _submission (required), _imap (required), _pop3 (required), _xmpp-client (required), _xmpp-server (opportunistic), _ldap, _nntp, _ftp, _sieve, _postgresql.

Null targets (.) and unknown service names are skipped. SNI is set to the SRV target hostname.

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 from the happyDomain server module (git.happydns.org/happyDomain/model), which is itself 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 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.