128 lines
5.8 KiB
Markdown
128 lines
5.8 KiB
Markdown
# checker-srv
|
|
|
|
Generic SRV records checker for [happyDomain](https://www.happydomain.org/).
|
|
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
make docker
|
|
docker run -p 8080:8080 happydomain/checker-srv
|
|
```
|
|
|
|
### happyDomain plugin
|
|
|
|
```bash
|
|
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:
|
|
|
|
```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 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`](https://git.happydns.org/checker-tls/tree/master/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`](https://git.happydns.org/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.
|