101 lines
5.5 KiB
Markdown
101 lines
5.5 KiB
Markdown
# checker-authoritative-consistency
|
|
|
|
Authoritative name server consistency checker for [happyDomain](https://www.happydomain.org/).
|
|
|
|
Probes every authoritative name server of a zone and verifies they agree
|
|
with each other and with the parent delegation: NS RRset alignment
|
|
(RFC 1034 §4.2), SOA serial and field consistency (RFC 1035 §3.3.13,
|
|
RFC 1912 §2.2), reachability over UDP and TCP (RFC 7766), EDNS0 support
|
|
(RFC 6891), authoritative answers (no lame delegation), and response
|
|
latency.
|
|
|
|
## Usage
|
|
|
|
### Standalone HTTP server
|
|
|
|
```bash
|
|
# Build and run
|
|
make
|
|
./checker-authoritative-consistency -listen :8080
|
|
```
|
|
|
|
The server exposes:
|
|
|
|
- `GET /health`: health check
|
|
- `POST /collect`: collect authoritative-consistency observations (happyDomain external checker protocol)
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
make docker
|
|
docker run -p 8080:8080 happydomain/checker-authoritative-consistency
|
|
```
|
|
|
|
### happyDomain plugin
|
|
|
|
```bash
|
|
make plugin
|
|
# produces checker-authoritative-consistency.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:
|
|
|
|
```bash
|
|
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 propagation checker to the URL
|
|
of the running checker-authoritative-consistency server (e.g.,
|
|
`http://checker-authoritative-consistency:8080`). happyDomain will
|
|
delegate observation collection to this endpoint.
|
|
|
|
## Options
|
|
|
|
| Id | Type | Default | Description |
|
|
|----------------------|------|---------|--------------------------------------------------------------------------------------------------------|
|
|
| `requireTCP` | bool | `true` | When enabled, an authoritative server that fails to answer over TCP is critical (otherwise warning). |
|
|
| `checkEDNS` | bool | `true` | Probe each name server for EDNS0 (RFC 6891). Servers that drop or mishandle EDNS0 break DNSSEC. |
|
|
| `checkLatency` | bool | `true` | Measure response time of every name server and warn on slow responders. |
|
|
| `latencyThresholdMs` | uint | `500` | Response times above this value trigger a slow-server warning. |
|
|
| `useParentNS` | bool | `true` | Query the parent zone for the delegation NS RRset and compare it to the service's declared NS list. |
|
|
| `warnOnStaleSaved` | bool | `true` | When the saved SOA serial in happyDomain is newer than what authoritative servers publish, warn. |
|
|
| `minNameServers` | uint | `2` | Below this count, a warning is emitted (RFC 1034 recommends at least 2). |
|
|
|
|
## Rules
|
|
|
|
Each rule emits a finding code. Severity can be affected by the options above.
|
|
|
|
| Code | Default severity | Condition |
|
|
|------|-----------------|-----------|
|
|
| `authoritative_consistency_no_ns` | critical | No name servers could be discovered for the zone (declared list empty and parent query returned nothing). |
|
|
| `authoritative_consistency_too_few_ns` | warning | Fewer name servers are declared than `minNameServers` (RFC 1034 recommends at least 2). |
|
|
| `authoritative_consistency_parent_query_failed` | warning | The parent delegation query failed (network error, REFUSED, etc.). |
|
|
| `authoritative_consistency_parent_drift` | warning | The parent zone's NS RRset does not match the NS declared in the service. |
|
|
| `authoritative_consistency_ns_unresolvable` | critical | A declared name server has no A or AAAA record. |
|
|
| `authoritative_consistency_ns_udp_failed` | critical | A name server did not answer any SOA query over UDP/53. |
|
|
| `authoritative_consistency_ns_tcp_failed` | critical with `requireTCP` / warning otherwise | A name server did not answer over TCP/53 (required by RFC 7766 and DNSSEC). |
|
|
| `authoritative_consistency_lame` | critical | A name server answered without the AA bit set for the zone (lame delegation). |
|
|
| `authoritative_consistency_no_soa` | critical | A name server is authoritative but returned no SOA for the zone. |
|
|
| `authoritative_consistency_edns_unsupported` | warning | A name server drops or mishandles EDNS0 queries (RFC 6891). |
|
|
| `authoritative_consistency_slow_ns` | info | A name server's response time exceeded `latencyThresholdMs`. |
|
|
| `authoritative_consistency_serial_drift` | warning | Authoritative servers disagree on the SOA serial (zone not fully propagated). |
|
|
| `authoritative_consistency_serial_stale_vs_saved` | warning | The saved SOA serial in happyDomain is newer than what authoritative servers publish (likely an un-pushed change). |
|
|
| `authoritative_consistency_serial_ahead_of_saved` | info | Authoritative servers publish a SOA serial newer than the one saved in happyDomain (out-of-band change). |
|
|
| `authoritative_consistency_soa_fields_drift` | warning | Authoritative servers disagree on SOA fields (MNAME, RNAME, refresh, retry, expire, minimum). |
|
|
| `authoritative_consistency_ns_rrset_drift` | warning | Authoritative servers disagree on the NS RRset they publish at the apex. |
|
|
| `authoritative_consistency_ns_rrset_mismatch_config` | warning | The NS RRset published by authoritative servers does not match the NS declared in the service. |
|
|
|
|
## License
|
|
|
|
Licensed under the **MIT License** (see `LICENSE`).
|