Skip to main content

Technitium DNS smart home integration, free and open source

Technitium DNS integration for Gladys Assistant

Technitium DNS Server: blocking pause, query statistics, DHCP leases, update alerts.

View on GitHubAll integrations

Follow and control your Technitium DNS Server from Gladys, over your local network: pause its blocking for five minutes from the dashboard when a website breaks, see its queries of the last hour and of the last day, count its DHCP leases, and know when it stops answering or when an update is out.

Tested against a real Technitium DNS Server 15 (the official Docker image), not yet with a real Gladys installation: feedback welcome. If something does not work as described, please say so on the Gladys forum or in the issues.

What you need​

  • Gladys Assistant 5.1.0 or later (5.2.0 or later for the Pause… button of the widget).
  • Technitium DNS Server 15 or later, its web console reachable from Gladys (port 5380 by default).
  • An API token. In the web console, open the user menu (top right) → Create API Token, type your password and a name (for example gladys), then copy the token shown. The token does not expire; delete it from Administration → Sessions to revoke it.

The token acts as its user. The admin user can do everything. To limit it, create a dedicated user in Administration → Users and give its group these permissions: Dashboard (view), Settings (view; modify to pause the blocking), Cache (delete, for the cache action), DHCP Server (view, optional: without it, no DHCP leases).

Set up​

  1. Install the integration from the Gladys catalog.
  2. In Configuration, enter the Address of your server (for example 192.168.1.2: port 5380 is added; or the full address of its web console, such as https://dns.example.net), its API token, and optionally a Name. Two or three servers? Fill in the Second server and Third server sections too.
  3. Save, then click Test the connection: the message under the button says, for each server, whether it answers, its version and the state of its blocking.
  4. Open the Discover tab: one device per server. Click Add, pick a room, save.

Options:

  • Accept self-signed certificates: for an https:// address whose certificate the server signed itself. Leave it off for http:// addresses.
  • Refresh interval: how often the servers are read, from 30 seconds to 5 minutes (1 minute by default).
  • Turning the blocking switch off: what the switch of the device does when you turn it off: pause the blocking for 5 minutes (default), 15, 30 or 60 minutes, or disable it until you turn it back on.
  • Language of the feature names: English, French, German or Spanish. The names are given when a device is added (French by default).

The device of each server​

FeatureWhat it is
BlockingSwitch: on, the server blocks the listed domains; off, it lets all in
DNS queries (last hour)Queries received over the last 60 minutes
DNS queries (24 h)Queries received over the last day
Blocked queries (24 h)Queries blocked over the last day
Share blocked (24 h)Share of the queries blocked, in %, rounded
Clients (24 h)Devices that used the server over the last day
ZonesZones the server hosts (its own domains)
Blocked domainsDomains on the block lists, plus those you blocked by hand
Update available1 when a newer Technitium version is out, else 0
VersionThe installed version
DHCP leasesLeases of the enabled DHCP scopes (only when the DHCP server is used)

The day is the one of the Technitium dashboard (Last Day): the 24 full hours before the current one, so it lags up to an hour behind. The badge of the device shows Local when the server answers and Unreachable when it does not. Enabling or disabling a DHCP scope adds or removes the DHCP leases feature: Gladys then offers to Update the device in the Discover tab.

Dashboard​

Add the Technitium DNS widget to a dashboard. By default it shows all your servers together; choose one in its settings to show only that one. Pausing a single server out of two changes nothing: your devices then ask the other one.

The widget shows the queries, the blocked queries and the share blocked over the last day, the state of each server (blocking, paused with the minutes left, disabled, unreachable), the queries of the last hour, the clients, the blocked domains, the DHCP leases and the available update. Its buttons:

  • Pause 5 min and Pause 30 min: pause the blocking right away;
  • Pause…: opens a small form to type the duration in minutes (Gladys 5.2.0 or later; an older Gladys answers that it needs an update);
  • Resume: turns the blocking back on. It shows a check mark while the blocking is on everywhere.

Scenes​

Triggers​

  • Technitium blocking paused: the blocking was turned off, from Gladys or from elsewhere (the web console, another tool). Filter by server and by origin (From Gladys or Outside Gladys). The actions can read the name of the server and the length of the pause in minutes (duration_minutes, 0 when it has no end).
  • Technitium blocking resumed: the blocking is on again. The origin tells whether the pause ended on its own (End of the pause), from Gladys or from elsewhere; paused_minutes says how long it lasted.
  • Technitium update available: a new version of Technitium DNS Server is out. Announced once per version, even across restarts. version is the new version, current_version the installed one.
  • Technitium no longer answers: a server did not answer two reads in a row (the second one 15 seconds after the first). The DNS of your home may be down. error says why, in the language of the configuration.
  • Technitium answers again: it is back; down_minutes says after how long.

A refused token does not count as "no longer answers": the Configuration screen reports it.

Actions​

  • Pause Technitium blocking: pauses the blocking on one server, or on all of them when the field is left empty, for a number of minutes (5 by default, 0 until resumed, one day at most). The following actions can read how many servers were paused.
  • Resume Technitium blocking: turns the blocking back on, on one server or all of them.
  • Flush the Technitium DNS cache: empties the DNS cache, for example after changing a record, so the next queries are answered afresh.
  • Read the Technitium statistics: reads the queries of the last day into a sentence, such as "In the last 24 hours, 12,345 DNS queries, 1,234 blocked (10 %). Last hour: 456 queries.", in the language of the configuration. The following actions can send it (sentence) or use the figures (queries_last_day, blocked_last_day, blocked_percent, queries_last_hour, blocking_enabled).

The Blocking switch can also be used with the standard Gladys action that controls a device.

Scene ideas​

  • Morning report: every day at 8:00, Read the Technitium statistics, then send the sentence output in a message.
  • DNS alert: Technitium no longer answers → send a message "Technitium {{triggerEvent.data.server}} does not answer: {{triggerEvent.data.error}}". And Technitium answers again → "back after {{triggerEvent.data.down_minutes}} min".
  • Safety net: a scene every evening at 20:00 with Resume Technitium blocking, so a switch turned off "until turned back on" never stays off all night.

Troubleshooting​

  • "API token refused": the token was deleted, or mistyped. Create a new one and paste it into Gladys.
  • "access denied": the user of the token lacks a permission (see What you need). Reading needs Dashboard and Settings (view); pausing needs Settings (modify).
  • "no Technitium server at this address": something else answers there. The web console listens on port 5380 by default: enter 192.168.1.2, or http://192.168.1.2:5380.
  • "certificate refused": you entered an https:// address; tick Accept self-signed certificates, or use the http:// address.
  • "the address redirects": the web console sends HTTP visitors to HTTPS; enter the https:// address.
  • "does not answer": check that the web console opens from a computer on the network of Gladys. Names ending in .local usually do not work inside the integration: use the IP address.
  • Logs: on the page of the integration in Gladys, or docker logs on the host. They show the start, each server lost and back, the problems (once each, not at every reading) and your commands. Start the container with LOG_LEVEL=debug to see every reading and every retry. Your token never appears in the logs.

Limits​

  • One integration handles up to three servers. A Technitium cluster is seen server by server; the pause applies to the server you target (Technitium syncs it to the other nodes of a cluster).
  • The integration reads each server once per refresh interval (five small requests) and asks it to check for updates every six hours: no quota is at risk.
  • The share blocked is rounded in the device (Gladys has no decimal percentage sensor); the widget shows one decimal.
  • No presence detection from the DHCP leases: Gladys has other ways to do it.
  • The integration does not manage the zones, the block lists, the allowed or blocked domains, nor the DHCP scopes: use the web console for that.

This integration is not affiliated with Technitium.

Configuration settings​

These are the settings Technitium DNS asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Your Technitium serversectionNoTechnitium DNS Server 15 or later. Create an API token in its web console: user menu, Create API Token. Up to three servers.
AddressstringYesIP address or name of the server (port 5380 by default), or the full URL of its web console.
API tokensecretNoCreated in the web console: user menu (top right), Create API Token.
NamestringNoName of the device in Gladys. Empty: "Technitium" followed by the address.
Second server (optional)sectionNoSame fields, for another Technitium server of your network.
AddressstringNoIP address or name of the server (port 5380 by default), or the full URL of its web console.
API tokensecretNoCreated in the web console: user menu (top right), Create API Token.
NamestringNoName of the device in Gladys. Empty: "Technitium" followed by the address.
Third server (optional)sectionNoSame fields, for another Technitium server of your network.
AddressstringNoIP address or name of the server (port 5380 by default), or the full URL of its web console.
API tokensecretNoCreated in the web console: user menu (top right), Create API Token.
NamestringNoName of the device in Gladys. Empty: "Technitium" followed by the address.
OptionssectionNo
Accept self-signed certificatesbooleanNoFor https:// addresses with a self-signed certificate. Tick only for your own servers.
Refresh intervalselectNoHow often the Technitium servers are read.
Turning the blocking switch offselectNoPauses the blocking for this long, or until the switch is turned back on.
Language of the feature namesselectNoNames given to the features when a device is added, and texts of the scene events.

How to install Technitium DNS in Gladys​

  1. In Gladys, open Integrations: Technitium DNS appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-technitium:1.0.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/guim31/gladys-technitium.

Technitium DNS requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Technitium DNS is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on