Troubleshooting

Each section starts from what you see, then gives the likely causes and the fix. The commands run on the router over SSH unless the text says to run them on a client. The examples use a LAN of 192.168.1.0/24 with the router at 192.168.1.1.

Find out why a site is blocked

1. Check which policy the client gets. Open Access Policies → Preview, look up the device or its IP address, and read the Resolution chain. See Preview a client.

2. Ask the router which rule matched. Every policy answers a TXT query for a blocked name with a report. Run this on the affected client, or on another client that gets the same policy:

   dig @192.168.1.1 ads.example.com TXT +short

   "source=advanced-blocking-app; group=Students; blockListUrl=https://adguardteam.github.io/HostlistsRegistry/assets/filter_1.txt; domain=example.com"

   group is the policy, blockListUrl is the list that matched, and domain is the entry in it. A match from Block domains, or from the DoH provider list, has no blockListUrl. A match from a regex shows regex instead of domain, and a match from a regex list names it as regexBlockListUrl. On Windows, use nslookup -type=TXT ads.example.com 192.168.1.1.

3. Look at the query log. On Reports → Query log, filter on the client's address and turn on Blocked only. A page often loads from several domains, and each blocked one appears here.

Don't test from the router itself: its own queries use an unfiltered group, so nothing is ever blocked there.

A site is blocked but shouldn't be

A device gets the wrong policy

If the result in the Preview is right but the client still behaves differently, check the compiled mapping of addresses to policies on the router:

sudo jq '.networkGroupMap' "/var/lib/technitium-dns-server/apps/Advanced Blocking/dnsApp.config"

Each key is an address or range, and each value a policy name. A device with a working reservation and device-tier policy has its own /32-style entry, such as "192.168.1.120": "Staff".

The block page shows a certificate warning

That's expected for HTTPS sites: the block page can only offer the router's own self-signed certificate, and sites that use HSTS never show the page at all. The router has no setting that avoids it. Plain HTTP requests show the page directly. See HTTPS sites show a certificate warning.

If even plain HTTP requests show no page, check that the client's policy uses Blocking address rather than NXDOMAIN, that Serve a block page is on and applied, and that the Block Page app bound ports 80 and 443:

sudo sh -c 'grep -h "Web server" /var/lib/technitium-dns-server/logs/*.log | tail -n 4'

Filtering does nothing

Technitium logs each list download:

sudo sh -c 'grep -h "Advanced Blocking app" /var/lib/technitium-dns-server/logs/*.log | tail -n 20'

Directory groups don't resolve

Work through the layers on the router, replacing the domain and login with yours:

systemctl status sssd
sudo sssctl config-check
sudo sssctl domain-status school.example.org
getent passwd jdoe
id -Gn jdoe
journalctl -u router-directory-sync -n 50

getent passwd with no name returning no directory users is expected. A name that is right in the directory but wrong on the router is usually cached: run sudo sss_cache -E and sudo systemctl restart nscd, then click Sync now on the Users page. Policies keep working on the last good data; a missing or stale directory only affects the directory group tier. Directory groups covers each message.

The reconcile failed

technitium-reconcile.service pushes the whole DNS configuration. When it fails, the router keeps answering with the previous configuration.

journalctl -u technitium-reconcile -n 50

It retries on its own after 15 seconds, with at most four starts in five minutes. After you fix the cause, run it again. It stays "active" after a successful run, so use restart rather than start:

sudo systemctl restart technitium-reconcile

Local names don't resolve

See Split-horizon DNS for how the zones are built.

Reset the Technitium admin password

The router manages Technitium's admin password in /var/lib/router-technitium/admin.pass. To recreate Technitium's accounts from that file, for example after someone changed the password through the API:

sudo systemctl stop technitium-dns-server
sudo rm /var/lib/technitium-dns-server/auth.config
sudo systemctl start technitium-dns-server
sudo systemctl restart technitium-reconcile

To also generate a new password, delete the password file and regenerate it before starting the server:

sudo systemctl stop technitium-dns-server
sudo rm /var/lib/technitium-dns-server/auth.config /var/lib/router-technitium/admin.pass
sudo systemctl restart router-dns-secrets
sudo systemctl start technitium-dns-server
sudo systemctl restart technitium-reconcile

The reconcile recreates the Cockpit dashboard account and its token.

Inspect Technitium

The router's Technitium build has no web console. Everything that manages the DNS server, the router's own services and Cockpit alike, uses its HTTP API, which listens only on the router's loopback address, port 5380 by default. Run this on the router. It signs in as admin with the password the router manages, lists the zones and prints the server settings:

sudo sh -c '
  api=http://127.0.0.1:5380/api
  token=$(curl -s --get $api/user/login \
    --data-urlencode user=admin \
    --data-urlencode "pass=$(cat /var/lib/router-technitium/admin.pass)" | jq -r .token)
  curl -s --get $api/zones/list --data-urlencode "token=$token" | jq -r ".response.zones[].name"
  curl -s --get $api/settings/get --data-urlencode "token=$token" | jq .response
'

To delete a zone, swap in a request to $api/zones/delete with --data-urlencode zone=example.com. The apps' configurations are plain files, readable without the API: see /var/lib/technitium-dns-server/apps/*/dnsApp.config. The router reapplies its settings, app configurations and managed zones on every reconcile, so make lasting changes in Cockpit or the settings file, not through the API.

Useful commands

Files on the router