checker-matrix

Matrix federation checker for happyDomain.

Queries a Matrix Federation Tester instance to verify that a Matrix homeserver is correctly federating, stores the full report as an observation, and renders a rich HTML summary (connections, certificates, well-known, DNS/SRV resolution).

Usage

Standalone HTTP server

make
./checker-matrix -listen :8080

The server exposes the standard happyDomain external checker endpoints (/health, /definition, /collect, /evaluate, /html-report).

Docker

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

happyDomain plugin

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

Rules

Code	Description	Severity
`matrix.connection_reachable`	Checks that every discovered federation endpoint accepts an inbound connection.	CRITICAL
`matrix.federation_ok`	Reports the overall federation status returned by the Matrix Federation Tester.	CRITICAL
`matrix.srv_records`	Checks that the Matrix SRV lookup (`_matrix-fed._tcp` / `_matrix._tcp`) succeeded or was skipped.	CRITICAL
`matrix.tls_checks`	Reviews the TLS posture on every reachable federation endpoint (chain, hostname, Ed25519 key).	CRITICAL
`matrix.version`	Checks that the homeserver responds to `/_matrix/federation/v1/version` with name and version.	WARNING
`matrix.well_known`	Checks that `/.well-known/matrix/server` (if published) is valid and points at the server_name.	CRITICAL

Options

Scope	Id	Description
Run	`serviceDomain`	Matrix domain to test (auto-filled, default `matrix.org`)
Admin	`federationTesterServer`	Federation Tester URL template (default: `https://federationtester.matrix.org/api/report?server_name=%s`)

The checker only applies to services of type abstract.MatrixIM.

License

This project is licensed under the MIT License (see LICENSE). 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.

3.4 KiB Raw Permalink Blame History