Document the Technitium DNS integration

README and INTEGRATIONS: what it reads, the config and token (15.0 or later),
the DNS test, the alerts and metrics, that its API has no CPU, memory or disk
figures, and how it differs from the Technitium DNS provider. ROLES: the page.
DATABASE: technitium_state, migrations to 0081, 91 tables. MONITORING: the
five alerts. PROMETHEUS-GRAFANA: the homelab_technitium_* metrics.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-11-01 21:52:20 +01:00
1 parent 312093d3f7
commit a2ff0f7daa
6 files changed
+64 -4

No files matched your search

+13 -1
View File
@@ -15,7 +15,7 @@ the dashboard views themselves load fine. (UniFi, Nginx Proxy Manager, Home Assi
### Checking what an integration can read
On the Integrations page an administrator has an **Inspect** button on each integration that reads through the shared HTTP helper (Authentik, Immich, Jellyfin, NetBox, Nextcloud, Paperless-ngx, Prometheus, Hetzner Cloud, Speedtest Tracker, Fragnet, Sonarr, Radarr, Prowlarr, Lidarr, Readarr, AdGuard Home and Grafana). It runs the integration's reader once and shows:
On the Integrations page an administrator has an **Inspect** button on each integration that reads through the shared HTTP helper (Authentik, Immich, Jellyfin, NetBox, Nextcloud, Paperless-ngx, Prometheus, Hetzner Cloud, Speedtest Tracker, Fragnet, Sonarr, Radarr, Prowlarr, Lidarr, Readarr, AdGuard Home, Technitium DNS and Grafana). It runs the integration's reader once and shows:
- **what was asked** — each request, its path (with the *names* of the query parameters, not their values), the status, how long it took and how many bytes;
- **what came back** — the *shape* of each JSON answer to three levels: the names of the fields and the kind of each (`string`, `number`, `array(12) of { … }`), with a `?` on a field that only some items of a list have. Never a value, never a token, so the report can be copied into a message;
@@ -446,6 +446,17 @@ osTicket's API cannot close a ticket, so this is the one place in the app that *
- `/metrics` has `homelab_adguard_running`, `homelab_adguard_protection_enabled`, `homelab_adguard_dns_up`, `homelab_adguard_dns_probe_seconds`, `homelab_adguard_queries`, `homelab_adguard_blocked` and `homelab_adguard_avg_processing_seconds`.
- **Not verified against a live install** — the endpoints and fields are as AdGuard Home's published OpenAPI file has them (`ServerStatus`, `Stats`, `FilterStatus`), and the reader (and the DNS question, against a pretend DNS server) is tried against pretend ones. The statistics are over AdGuard Home's own period (a day unless set otherwise). A DNS question is asked of the host in the URL: with a proxy in front, set *DNS server address*.
### Technitium DNS
- **Config fields:** the **URL** of its web console (`http://dns.example.lan:5380`) and an **API token** — a non-expiring one, made under Administration → Sessions → *Create Token*; stored encrypted — of a user who may **view** the dashboard, the settings and the zones (and the DHCP server, for the DHCP counts). Optional: the **DNS server address** (the host of the URL unless told — fill it in if a reverse proxy sits in front of the console), the **name to test DNS with** (`example.com`) and *Allow self-signed certificate*. Zones and records are connected separately, as a **DNS provider** on the DNS page, with a token of its own; this integration only says how the server is doing.
- **Required access:** the console reachable from the app over HTTP(S) and — for the DNS test — the DNS port (the first of the server's listening endpoints, usually 53) reachable from the app **over UDP**. The token goes in an `Authorization: Bearer` header, which Technitium **15.0 and later** require; an older server answers "token not accepted". If the app sits where UDP 53 to it is blocked, the test says so (no answer) and DNS is reported down; allow it or set the DNS server address to one the app can reach.
- **What it does:** every **two minutes** it reads `GET /api/settings/get` (version, when it started, whether blocking is on, the block lists and when they are next updated, the cache limit, recursion, DNSSEC, the DNS port), `GET /api/dashboard/stats/get?type=LastDay` (the last day's queries and how each ended, clients, cache entries, zone and list counts, the clients and names asked about and blocked most), `GET /api/zones/list` (which secondary zones have expired or cannot sync; the server's own internal zones and switched-off zones are not judged) and `GET /api/dhcp/scopes/list` and `…/leases/list` (scopes and lease counts) — and puts **one DNS question** to its DNS server, as for AdGuard Home. **Network → Technitium DNS** shows it all. Nothing is changed: blocking is never switched, no block list refreshed, no zone touched.
- **Alerts** (source *Technitium DNS*; held back by maintenance on the integration): the test question **unanswered in every read for ten minutes** (critical — one lost packet is not an outage); a **secondary zone that has expired** (critical — it no longer answers), or zones that **cannot sync** (warning), one alert for all the zones; **blocking switched off for an hour** while block lists are set up (warning — with none, off is how it is); **block lists whose update was due more than six hours ago** (warning). See [MONITORING.md](docs/MONITORING.md#technitium-dns).
- If it cannot be read for ten minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other. A part that could not be read (the statistics, the zones, DHCP) is shown as *could not be read*, never as none; the settings are the one part that must work, since they say it is there and the token is accepted.
- `/metrics` has `homelab_technitium_dns_up`, `homelab_technitium_dns_probe_seconds`, `homelab_technitium_blocking_enabled`, `homelab_technitium_uptime_seconds`, `homelab_technitium_block_lists_overdue`, `homelab_technitium_queries`, `homelab_technitium_blocked`, `homelab_technitium_cached`, `homelab_technitium_recursive`, `homelab_technitium_server_failures`, `homelab_technitium_clients`, `homelab_technitium_cache_entries`, `homelab_technitium_zones`, `homelab_technitium_zone_problems` and `homelab_technitium_dhcp_leases`.
- **No CPU, memory or disk.** Technitium's API has no figures for the machine it runs on (its "resource" numbers are the DNS server's own: queries, cache, zones). Put a **server agent** on that machine for those.
- **Not verified against a live install** — the endpoints and fields are as Technitium's own API documentation (`APIDOCS.md`) has them, and the reader (and the DNS question, against a pretend DNS server) is tried against pretend ones. The statistics are over the **last day**; the zones are read up to 1000 at a time; the page shows the share of failed queries in yellow from 20% (with at least 200 queries), which is not an alert. A DNS question is asked of the host in the URL: with a proxy in front, set *DNS server address*. Cluster state and the version-behind comparison of the Versions page are not read.
### Grafana
- **Config fields:** the **URL** and a **service account token** (Administration → Users and access → Service accounts → add a service account with the *Viewer* role → add a token; shown once; stored encrypted), and *Allow self-signed certificate*. To also test the data sources the service account needs permission to read and query them (the Viewer role usually has it); without it they are shown as *could not be listed* and the rules still work.
@@ -589,3 +600,4 @@ osTicket's API cannot close a ticket, so this is the one place in the app that *
- **Auth:** Bearer token
- **Actions used:** list zones, read zone records, add/delete records (an "update" is implemented as delete + add)
- **Required access:** A token tied to a Technitium user account with **Zones: View + Modify** permission — view-only will fail on record changes since updates are add/delete calls under the hood.
- **This is the DNS provider** (zones and records, on the DNS page). How the *server* is doing — queries, blocking, zone health, a real DNS test, alerts — is a separate integration with its own token: see [Technitium DNS](#technitium-dns) under the integrations above.