79 lines
2.6 KiB
Markdown
79 lines
2.6 KiB
Markdown
# checker-alias
|
|
|
|
CNAME / DNAME / ALIAS chain checker for [happyDomain](https://www.happydomain.org/).
|
|
|
|
Walks the alias chain of a name, validates hop count, TTLs, target
|
|
resolvability, apex coexistence (RFC 1912 §2.4, RFC 1034 §3.6.2,
|
|
RFC 2181 §10.1), DNAME substitutions, and DNSSEC signing of the CNAME
|
|
RRset.
|
|
|
|
## Usage
|
|
|
|
### Standalone HTTP server
|
|
|
|
```bash
|
|
# Build and run
|
|
make
|
|
./checker-alias -listen :8080
|
|
```
|
|
|
|
The server exposes:
|
|
|
|
- `GET /health` — health check
|
|
- `POST /collect` — collect alias observations (happyDomain external checker protocol)
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
make docker
|
|
docker run -p 8080:8080 happydomain/checker-alias
|
|
```
|
|
|
|
### happyDomain plugin
|
|
|
|
```bash
|
|
make plugin
|
|
# produces checker-alias.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 alias checker to the URL of the
|
|
running checker-alias server (e.g., `http://checker-alias:8080`).
|
|
happyDomain will delegate observation collection to this endpoint.
|
|
|
|
## Options
|
|
|
|
| Id | Type | Default | Description |
|
|
|---------------------------|------|---------|-----------------------------------------------------------------------------|
|
|
| `maxChainLength` | uint | `8` | Above this number of hops the chain is reported as critical. |
|
|
| `minTargetTTL` | uint | `60` | Hops with a TTL below this threshold are flagged as a warning. |
|
|
| `requireResolvableTarget` | bool | `true` | When enabled, a final target with no A/AAAA is critical (otherwise warning).|
|
|
| `allowApexCNAME` | bool | `false` | When enabled, a CNAME at apex is only a warning (RFC 1912 forbids it). |
|
|
| `recognizeApexFlattening` | bool | `true` | Recognize provider-side ALIAS/ANAME flattening as informational. |
|
|
|
|
Finding codes emitted by the checker include: `alias_no_apex`,
|
|
`alias_loop`, `alias_chain_too_long`, `alias_query_failed`,
|
|
`alias_rcode`, `alias_low_ttl`, `alias_cname_at_apex`,
|
|
`alias_apex_flattening`, `alias_coexisting_rrset`,
|
|
`alias_cname_not_signed`, `alias_target_unresolvable`,
|
|
`alias_multiple_records`.
|
|
|
|
## License
|
|
|
|
Licensed under the **MIT License** (see `LICENSE`).
|