The same explanations as the "?" buttons in the web UI: named for what each feature does, with the DNS term underneath, so you can use the depth without the jargon.
Device timeline (swimlanes)
One device over a window as lanes, one per domain it talks to, with a cell per few minutes: darker for more queries, red underline for blocked, amber tick for slow; its answer time below and what happened (first contacts, anomalies, blocked bursts, changes) above.
When: You want to know when something on a device started and what else it was doing at the time.
Example: The ntp.org lane is empty until 14:00, then dark every 5 minutes until 18:30, with a hollow dot at 14:00: its first query to ntp.org.
Careful: It reads the query log, so it reaches back only as far as the log keeps (the rest is grey), and only the rows that reached the node you're on. Docs
Drill
A failover drill: one node deliberately leaves some devices unanswered for a short time, to see whether they switch to another node.
When: You see the status drilled in the query log, or a drill marker on a chart.
Example: drilled: the node didn't answer this query because a drill targeted the device.
Careful: Queries marked drilled got no answer from that node; if the device has another DNS server, it asked that one. Docs
Wall display
A link for an unattended screen: opened once on its browser, it stays signed in and shows only the wall (the traffic map, the flow, the service level, the heatmaps, and the live queries). It can't open other pages or change anything.
When: You want the wall on a monitor in the hallway or a tablet on a shelf without leaving an account signed in there.
Example: hallway, only from 192.168.2.40: open the link on the hallway monitor; revoke it here and the monitor shows the sign-in page.
Careful: It shows the live queries (device and name), like a viewer sees them. Limit it to the screen's address, and revoke it when the screen goes. Docs
Two-factor authentication (TOTP)
After your password, a 6-digit code from an authenticator app; recovery codes get you in if the phone is lost.
When: Anyone who can change settings should turn it on.
Example: Scan the QR code with any authenticator app, enter the code, and keep the recovery codes somewhere safe.
Careful: Lose both the phone and the recovery codes and an admin must reset it for you. Docs
Alert rules and destinations
Messages to ntfy, Gotify, Slack-compatible channels, or a webhook when an upstream is down, a node drops out, a list fails, SERVFAILs climb, a device behaves oddly, or an update is out.
When: You want to hear about problems without watching the dashboard.
Example: An ntfy push to your phone when Quad9 has been unreachable for a minute, and another when it's back.
Careful: Set for_secs long enough that short blips stay quiet. Keep tokens in token_file, not in the config. Docs
Quick rules
A quick rule allows or blocks a site (and everything under it) for one device, a group, or everyone, for a while or until you remove it. It decides before any list: a device's rule beats its group's, which beats everyone's. It takes effect on the next query.
When: Unblock a game's server on one phone for an evening; block a site on the kids' tablets until tomorrow; allow something a list blocks by mistake while you report it.
Example: Allow game.example.com for Mom's phone for 2 hours. Block videos.example.com for the kids group until midnight.
Careful: DNS sees whole sites, not pages, and an app often uses many sites. A rule follows a device only as well as TelltaleDNS recognizes it (give it a fixed address, or turn off its private Wi-Fi address for your network). Devices may keep an old answer for a few minutes, and mobile data, a VPN, or a hard-coded DNS server get around it. Docs
Upstream truth checks (second opinions, DNSSEC, EDE)
Whether each upstream's answers can be trusted: the DNSSEC verdicts on them, the error codes it attaches (EDE 15 Blocked, 16 Censored, 17 Filtered mean it filters names itself), and, if you turn them on, second opinions: a small sample of questions asked again of another upstream, with the two answers compared.
When: A site works on one network but not yours, an upstream seems to block things you didn't, or you want to know whether an upstream rewrites answers (an ISP's resolver, a 'family' filter).
Example: family-dns answered NXDOMAIN for casino.example.org while quad9 had an address: a 'filtered' disagreement, and family-dns's answers carry EDE 17 (Filtered).
Careful: Different addresses are normal for big sites (CDNs answer per resolver). Second opinions are off by default because the second upstream sees the sampled names; one in 1,000 is a good start. Docs
Latency heatmap with exemplars
Each column is a minute (or an hour), each row a band of answer time from 50 µs to over 5 s, and the colour how many answers landed there. Dots are real queries from those bands: select one to open it in the query log. The dashed line is the latency objective.
When: A percentile says answers got slower; the heatmap shows whether it's a few slow ones (a tail), everything slower, or a stripe that starts at a moment (a change, an upstream).
Example: A stripe of upstream answers at 250–500 ms from 07:00 to 07:05 after a restart, while the cache stays at the bottom: the encrypted connections were warming up.
Careful: Bands are the Prometheus histogram's buckets, so a band is a range, not an exact time. Dots are a sample (at most one per band and path a second, the last 512 per node), kept in memory only. Docs
Cache
Recent answers are kept for as long as the name's owner allows (its TTL), so repeat questions are answered in microseconds.
When: Always on; it's why most lookups never leave your network.
Example: The tenth device asking for youtube.com gets the answer from memory.
Careful: Changing a name's address elsewhere takes up to its TTL to show here (flush the cache to force it). Docs
Blocked services
One switch blocks every domain of a service (TikTok, Roblox, Netflix, ...) for a group, without hunting down its domains.
When: A group (kids, guests) shouldn't reach a particular app or game at all.
Example: The kids group blocks TikTok and Fortnite; the rest of the house is unaffected.
Careful: Apps change domains over time; the catalog is updated with TelltaleDNS. Add a quick rule for anything it misses. Docs
List kind
A block list stops names from resolving; an allow list makes names always work, even if a block list has them.
When: Use an allow list to fix a site a block list breaks.
Example: Allow cdn.example.com when a block list's rule for example.com breaks your streaming app.
Careful: Allow lists beat block lists, so an overly broad allow rule lets ads back in. Docs
Filter lists (blocklists and allowlists)
Lists of names, maintained by others or by you, that TelltaleDNS blocks (or always allows), refreshed automatically.
When: You want ads, trackers, malware, or adult sites blocked for every device at once.
Example: HaGeZi Pro blocks about 150,000 ad and tracker names; an allowlist keeps your bank's analytics working.
Careful: Bigger isn't better: very aggressive lists break sites. Start with one balanced list. Docs
Configuration overrides
Entries made here are stored on the server and shared with the cluster; the config files are never rewritten, so a file's entry can be overridden, hidden, or brought back.
When: You want to add a list or switch an upstream without editing files or redeploying.
Example: Edit the file's upstream 'quad9' to use DNS over TLS: the row shows 'overrides the file' until you revert it.
Careful: On a node configured from Git, also add the change to Git (the UI shows what to add), or a rebuild won't have it. Docs
DNS64 (RFC 6147)
IPv6-only devices get IPv6 addresses for IPv4-only names, made from the IPv4 address in a NAT64 prefix.
When: A network (or group) of IPv6-only devices behind a NAT64 gateway.
Example: github.com has no IPv6 address; DNS64 answers 64:ff9b::8c52:7004 and the NAT64 gateway connects to 140.82.112.4.
Careful: Only useful with a NAT64 gateway on the path; without one, the made-up addresses go nowhere. Docs
Failover drill
One node stops answering chosen devices (or a group, or everyone) for 15 seconds to 5 minutes while the other nodes keep serving. Devices with a working second DNS server switch to it within a few seconds; a report then says, per device, who followed, how fast, who was stuck, and who came back afterwards.
When: You hand out two DNS servers (say the Pi and a second machine) and want to know they both work for every device, before the day one of them breaks. On a healthy network a device never touches its second server, so nothing else can tell you.
Example: A 30-second drill on the Pi for your laptop: the laptop asks the other node after about a second and is listed as followed in 1.1 s; the TV, drilled next, is stuck: it only has the Pi as its DNS server.
Careful: Devices without a working second server lose DNS for the drill's length. Start with one device for 30 seconds, then a group, then everyone. A drill is a maintenance window too: the node reports not ready and its alerts pause until it ends; a restart cancels it. Docs
Schedules
A schedule changes a group's filtering during weekly windows: block everything (bedtime), or add lists or blocked services only at certain times.
When: Devices should be offline at night, or a game blocked during school hours.
Example: The kids group blocks everything from 21:00 to 07:00 on school nights; a quick allow keeps the homework site reachable.
Careful: Windows use the schedule's time zone (tz), else the server's. Changes take effect within 15 seconds of the window's time. Docs
List refresh
Lists are downloaded again on a schedule (daily by default); a failed download keeps the last good copy.
When: A list shows an error or an old update time.
Example: A list maintainer's site is down: TelltaleDNS keeps blocking with yesterday's copy and retries later.
Careful: Each list is stored compressed in the data directory; very large lists take memory while compiling. Docs
Rhythm strip (inter-arrival histogram)
For each domain a device talks to most, how its queries are spaced: one column per gap between two queries, on a log scale from under a second to two hours, darker where more of the gaps fall.
When: A device is chattier than it should be and you want to know whether it's a timer (one dark cell) or a person (a smear).
Example: A thermostat asks ntp.org every 2.5 s: one dark cell in the 2.2–3.3 s column, about 1,400 an hour, all answered from the cache.
Careful: It shows the rhythm; it doesn't judge it. Only a new regular rhythm between 30 s and an hour, for 4 hours, becomes a beacon finding. It needs the anomaly engine (privacy level 0). Docs
DNS resolution
Every device asks TelltaleDNS where a name (like youtube.com) lives; it answers from memory, from your own names, with a block, or by asking a public DNS server.
When: Read this first: every other setting changes one step of this path.
Example: Your TV asks for ads.example.com: it's on a blocklist, so TelltaleDNS answers "nowhere" and the ad never loads.
Careful: Devices only use TelltaleDNS if your router hands out its address as the DNS server. Docs
Circuit breaker
Closed means healthy; open means TelltaleDNS stopped asking it after failures and will test it again soon.
When: Lookups are slow or failing.
Example: An ISP outage opens the breaker for one server; the others keep answering.
Careful: If every server's breaker is open, only cached and local answers work. Docs
Node comparison
Every node side by side over the same window: queries per second, SERVFAIL, slow, from-cache and upstream-failure shares, p50 and p99, each with a sparkline on a shared scale. A node that deviates from the others is outlined, with when it started.
When: One node looks worse on the dashboard and you want to know whether it really is, or only has less traffic.
Example: The Pi has 15 SERVFAILs and the pods 14, but the Pi answered a tenth as much: a grey note says it's a smaller base, not more failures.
Careful: Shares on few answers swing a lot; the table's 95 % intervals show how much. It's a lens, not an alarm: nothing alerts on it. Docs
Backup and restore
One file with your settings, users, API tokens, the devices and names you added, the audit log, and statistics history.
When: Before an upgrade, before moving to new hardware, or just to have a copy.
Example: Download a backup on the old Pi, then run telltale backup restore on the new one.
Careful: The file holds password hashes: keep it private. The query log is only included from the command line (--include-qlog). Docs
Exclusions
Names and devices whose queries are still answered, but left out of the query log, the live view, the dashboard and top lists, anomalies, and exports. Prometheus metrics still count them.
When: Noise drowns out what matters: phones' connectivity checks, time servers, a monitoring probe that asks every few seconds, or a device you don't care to watch.
Example: Add connectivitycheck.gstatic.com and ntp.org, and the monitoring host 192.168.1.10: the top domains show what people use, and the probe's queries no longer fill the log.
Careful: Excluded queries can't be searched later, and the dashboard's totals leave them out (Prometheus doesn't). Queries logged before stay. Under a Git-managed configuration, change [exclusions] in Git. Docs
API tokens
A secret for Homepage, Grafana, scripts, or AI agents to use the API without your password; revoke it any time.
When: Connecting another tool to TelltaleDNS.
Example: A read token for a Homepage widget, valid for a year.
Careful: Give each tool its own token with the smallest scope; the token is shown once. Docs
Agent tokens
A token for an AI agent or automation that can do only what you tick, must say why it changes anything, and can be switched off for the whole cluster at once.
When: You want an assistant to answer "why is the TV slow?" or tidy up device names, without giving it your account.
Example: A read-only token for an assistant with statistics and device names; a second token, restricted to the kids group, that can rename those devices.
Careful: The query log shows who looked up what: tick it only for agents you trust with that. Revoke a token here, or stop all agents with [agents] enabled = false. Docs
Over-blocking suspects
Blocked names that someone seems to want: a device got the name answered within 10 minutes of a block (you paused blocking or allowed it), or an app kept retrying it 10 or more times a minute.
When: Something broke on a device and you suspect a blocklist; or you want allowlist candidates.
Example: login.bank.example: blocked by oisd, then answered 3 minutes later on the same phone after a pause, twice this week. A good candidate for the allowlist.
Careful: Ad libraries retry blocked names too, so retry bursts alone are weak evidence; 'allowed soon after' is the stronger sign. Docs
Synthetic probes
Every 30 seconds each node asks each of its own DNS listeners a question the way a device would: over UDP, TCP, DNS over TLS, DNS over HTTPS (HTTP/2 or HTTP/3), or DNS over QUIC. It also reads when each encrypted listener's certificate expires, and with HTTPS on the web UI ([api] tls) checks the web UI and its certificate too, showing the SHA-256 fingerprint to compare with your browser's.
When: Devices say DNS is broken but the dashboard looks fine: a listener can be bound and still not answer (a stuck TLS handshake, a firewall, a load balancer in front). Add the load balancer's address under [probe] targets to check the path devices really use.
Example: tls://127.0.0.1:853 answers in 1.8 ms, certificate expires in 9 days: the health icon turns amber so you renew it before Android's Private DNS stops working.
Careful: Probes connect by IP, so they don't check the certificate's name; the expiry is read from the certificate file. A listener with PROXY protocol on is skipped (probes don't send the header). Docs
Node maintenance
A timeboxed flag on one node (an hour by default, a day at most) for planned work: it reports not ready, so load balancers and Kubernetes stop sending it new queries, but every listener keeps answering whatever still arrives. Alerts and the health level leave it out, and it isn't elected primary, until the window ends or someone ends it. The window survives a restart.
When: Before swapping a Pi's SD card, moving a box, or upgrading a node by hand: start maintenance with a reason, do the work, end it (or let it run out).
Example: Maintenance on the Pi for 30 minutes, "SD card swap": the router's secondary DNS entry still gets answers, no node_down alert fires while it's off, and the health icon stays green with "1 node in maintenance".
Careful: In Kubernetes one readiness probe serves every Service that selects the pod, so a controller pod in maintenance also leaves the API Service (use another node's UI or a port-forward), and a StatefulSet rollout waits for it. On the primary under automatic failover, maintenance hands the primary role to another node first (about 30 s without configuration changes); in manual mode it stays the primary, so promote another node first if you're taking it offline. A node that's really failing during its window stays quiet until the window ends. Docs
Clients
Give an address (or a MAC, or a client ID) a name so every view shows "Living room TV" instead of 192.168.1.42, and put it in groups.
When: You see an address you don't recognize, or want different rules for one device.
Example: Name 192.168.1.42 "Living room TV" and add it to the kids group: its history relabels at once.
Careful: Addresses can change when a device reconnects; match by MAC for devices that don't keep their address (a DHCP reservation also works). Docs
Local records (zone)
Names TelltaleDNS answers itself, like nas.home.arpa → 192.168.1.10, so you type a name instead of an address.
When: You run a NAS, printer, or server at home and want a name for it.
Example: nas.home.arpa → 192.168.1.10, and a wildcard *.dev.home.arpa → 192.168.1.20.
Careful: Use home.arpa (made for this) or a domain you own, not an invented .local or .lan name that might clash. Docs
First-seen domains and DGA scores
Domains a device contacted for the first time, each with a score for how machine-generated its name looks (0 to 1).
When: Checking what a new app or device started talking to, or looking for malware that generates its domains (DGA).
Example: A laptop that suddenly looks up xjwqkzpvb.com and a8f3k2j9x1.org (scores 1.00 and 0.80) is worth a look.
Careful: Names made of real words score low even when generated, and some vendor IDs score high: treat the score as a hint. A device's first day isn't listed, while its usual domains are learned. Docs
AAAA filtering
The group's devices get no IPv6 (AAAA) answers, so they connect over IPv4. Your own names (local records and zones) still answer, and blocked names stay blocked.
When: A network whose IPv6 is broken or half set up: pages hang for a while before falling back to IPv4.
Example: The guest Wi-Fi gets IPv6 from the ISP but its firewall drops it: turn this on for the guest group and pages load at once.
Careful: HTTPS records can still carry IPv6 hints some browsers use. Not with DNS64, which makes IPv6 answers on purpose. Docs
Pin (roll back)
Every node serves an older kept version again (its configuration and filter snapshot), published as a new version number, until someone unpins. The guard pins by itself when a staged rollout fails; an admin can pin any kept version from the Cluster page. While pinned, configuration changes are refused with the list of what the pin holds back.
When: A change went out and something broke: pin to the version before it, fix the change at your leisure, then unpin.
Example: Pin to version 3.124 with the reason "new list blocks the bank": all nodes serve 3.124 within seconds, the banner shows "Held back since then: list: changed", and the cluster_pinned alert keeps reminding you until you unpin.
Careful: A pin doesn't rewrite your files, the entries made in the UI, or Git: unpinning publishes them as they are, so undo the bad change there first (or right after unpinning, while it bakes on the canaries). The primary keeps the last 20 versions; older ones can't be pinned. A node promoted to primary keeps the pin. Docs
Kubernetes workloads as devices
TelltaleDNS watches your cluster's pods and names each pod address by its workload (media/deploy/jellyfin): a Deployment's replicas are one device, so its queries, anomalies, rhythm, and timeline survive every rollout.
When: You run apps in Kubernetes and want to see which workload asked for which domain, or give a namespace its own lists.
Example: media/deploy/jellyfin talks to api.themoviedb.org every 15 minutes; label the media namespace telltaledns.io/group=media and every pod in it gets the media group's lists.
Careful: Pods show up as themselves only when they ask TelltaleDNS directly (the cluster's DNS pointed at it, or a workload's dnsConfig); through CoreDNS they all look like CoreDNS. Docs
DNS rebinding
Refuses private-network addresses in answers for public names, so websites can't use DNS to reach devices on your network.
When: On networks with browsers and devices that have web interfaces (routers, cameras, printers).
Example: attacker.example answering 192.168.1.1 is blocked; nas.home.example (allowed) still answers.
Careful: Services that hand out private addresses on purpose (plex.direct) need rebinding_allow. Your local records and routed domains are always allowed. Docs
Plans and approval (MCP)
An AI agent connected over MCP proposes a change as a plan: what it does, why, and who asked. It changes nothing until the agent applies it, and with approval turned on, only after an operator approves it here.
When: You let an assistant manage your DNS but want the final say on changes.
Example: An agent plans to block ads.example for the kids group; you see the plan, approve it, and the agent applies it.
Careful: Turn approval on with [agents] require_approval = true. A plan expires after 10 minutes, and goes stale if the configuration changes before it's applied. Docs
DNS rewrite
Answer a name with your own address, or another name, for one group's devices.
When: Split-horizon names, test servers, pointing a device at a different backend.
Example: nas.example.com answers 192.168.1.10 at home, while everyone else gets the public address.
Careful: Blocks still win. For a name everyone should get, use local records. Docs
Safe search enforcement
Google, Bing, DuckDuckGo, Yandex, and Pixabay only show safe results, and YouTube uses Restricted Mode, for the group's devices, whatever their settings.
When: Children's devices, or a classroom network.
Example: The kids group searches on Google and gets safe results; adults on the same network don't.
Careful: A browser using its own encrypted DNS bypasses it, like all filtering. YouTube's strict mode hides many videos; moderate is gentler. Docs
Query log
A searchable history of each lookup: which device asked, for what, and what happened (answered, blocked, from memory).
When: A site or app is broken, or you want to know what a device talks to.
Example: Filter by the smart plug's address to see it contacting a dozen servers every hour.
Careful: The log shows names, not page contents. How long it's kept is set by [telemetry.qlog] retention_days. Docs
Traffic map
One tile per service, site, or name, sized by how often it was looked up this hour: blue tiles were answered, red ones were blocked.
When: You want one picture of what people on the network are using right now, for example on a wall screen.
Example: A big blue YouTube tile with a pulsing ring means streaming is the busiest thing on the network and still growing.
Careful: It shows the busiest 100 names and 100 blocked names, with approximate counts. Phones and apps look up many background names, so busy isn't always the same as used by a person. Docs
Client IP preservation
TelltaleDNS needs each query's real sender to tell devices apart; a router, Docker bridge, or Kubernetes setting can hide them behind one address.
When: The banner says client IPs appear masked, or every query shows the same address.
Example: Hand out TelltaleDNS's address in DHCP instead of the router's, or use host networking for Docker.
Careful: Until it's fixed, per-device rules and statistics see only the one address. Docs
Conditional forwarding (routes)
Questions for one domain go to a specific server instead of the public ones, such as your work network's or your router's.
When: Names like nas.home or corp.example only exist on another server.
Example: Send everything under corp.example to 10.0.0.53 so work names resolve at home over the VPN.
Careful: That server sees those questions; private reverse lookups never leave your network by default. Docs
Service-level objectives (SLOs) and error budgets
Two promises about DNS on your network: answers that work (not SERVFAIL) and answers that are quick (within 250 ms). Each allows a few bad answers a month, its error budget; the card shows how much of it is left and how fast it's going right now.
When: You want one honest number for "is DNS good here?" over a month, and a warning when a problem is eating the month's allowance fast, not every time one lookup fails.
Example: Target 99.9%: of 1,000,000 answers this month, 1,000 may be SERVFAIL. If an upstream outage causes 300 in an hour, the burn rate jumps far above 1, the card says "burning fast", the health icon turns amber, and a slo_burn alert goes out.
Careful: A target of 100% leaves no budget, so it isn't allowed. On a quiet network a few bad answers can look like a big share: alerts wait for at least 50 answers in the short window and 10 bad ones in the long one. Docs
Groups
A group picks which block and allow lists apply, and can send its devices to their own DNS servers.
When: Different people in the house need different filtering.
Example: default: ads and trackers; kids: also adult content and gambling, with safe search.
Careful: The highest-priority group's settings win when a device is in several. Docs
Cluster
A cluster keeps TelltaleDNS nodes on the same configuration. The primary's settings and blocklists reach every node within seconds, and each node keeps answering from its last copy if the others are down. This page shows every node's link, configuration version, and whether it's serving DNS.
When: You run TelltaleDNS on more than one machine (a Pi and Kubernetes, say) and hand out both as DNS servers.
Example: Two nodes: the k8s pod is the primary (config from GitOps), the Pi follows it; both show version 12, in sync, ready.
Careful: Change configuration on the primary. Each node keeps its own listeners, sign-in, query-log retention, and cache size. Docs
Detail level
Simple shows what most homes need; Advanced adds the technical detail (raw rules, record types, protocol specifics; on the dashboard, service levels, traffic by group, where time goes, and the upstreams). Your choice is remembered for you.
When: Switch to Advanced when you're troubleshooting or know DNS well.
Example: Simple shows each list's name and size; Advanced adds its URL, format, and rule counts.
Careful: Simple only hides detail; it never hides something that changes how queries are answered.
Staged rollout (canary)
A configuration change reaches a few canary nodes (and the primary) first. After a bake time (5 minutes by default) every other node gets it, unless a guard saw trouble: a canary that can't apply the change, isn't ready, fails its listener checks, disappears, or answers SERVFAIL clearly more often than before. Then the cluster is pinned to the version before the change and you're told why. Off until you name canaries: nodes, a site, or the Kubernetes resolver pods.
When: When a bad change would cost the whole house its DNS: let the Kubernetes pods (or one Pi) take each change first while the others keep the version that works.
Example: Canaries: the resolver pods, bake 5 minutes. A new upstream group goes to the pods and the primary at once; the Pi in the garage keeps the old one. The pods' SERVFAIL share jumps from 1% to 30%, so after the bake the guard pins the cluster to the version before, and the Pi never saw the bad one.
Careful: The primary always runs a change at once (it's where you made it), so it's judged with the canaries. With too little traffic (under 50 answers in the bake) the guard can only check health, not answers, unless you require traffic. A newer change during a bake replaces the one baking. Nodes on older versions of TelltaleDNS are never canaries; they get each change after the bake. Docs
DNS cache
Each node (each Kubernetes pod) keeps its own cache of upstream answers. Here you see, per node: its hit rate over the last hour, how full it is, what it holds (answers, names that don't exist, no data, SERVFAIL, stale answers kept for emergencies), its busiest, largest, or soonest-expiring entries, the settings in effect, and whether it started warm from its saved cache.
When: To check the cache is doing its job: a home network usually answers well over half its queries from the cache. A low hit rate on one pod usually means it just started. The Size line says whether a bigger cache would really help (estimated from names asked again after they were evicted) or a smaller one would do.
Example: pi: 72% hits in the last hour, 4,210 answers, 2.1 MiB of 32 MiB, started warm with 3,900 answers. Its most-hit entry: connectivity-check.ubuntu.com, 1,204 hits.
Careful: The top entries walk the whole cache, so they load when you open the page or press Refresh, not every few seconds. Changing the settings is done under [cache] in the configuration. Docs
Topology
Each site is a box. Inside it are its nodes and, for Kubernetes, its resolver pods grouped by the Kubernetes node they run on (more than six fold into +N). A line runs from the primary to every other node or pod group: as thick as its share of the queries, labelled with the round-trip time when this node measured it.
When: To see where queries go and what's unhealthy: green is serving and in sync, amber is not ready or behind on configuration, red and dashed is down. Select a node or pod to jump to its row and its machine.
Example: home: the Pi (replica, 30% of queries, 4 ms). k8s: the controller (primary) and node k3s-1 with 3 pods, one amber because it's still loading the configuration.
Careful: Each pod has its own cache and rate limits, so a new pod starts cold. Uneven line thickness between a site's pods means the load balancer isn't spreading queries; the Load balance check explains what to do. Docs
Client name
Shown everywhere instead of the address, including on past queries, and usable in rules ($client='Kids tablet').
When: Always: a name you'll recognize in a month.
Example: "Kids tablet", "Office printer", "Ring doorbell".
Careful: Names must be unique; renaming keeps the device's groups. Docs
Host resources
Each node reports its machine every 15 seconds: memory (and its container's limit), CPU and load, free space where its data lives, temperature, and its process limits. Bars turn amber, then red, as a resource runs low, and the line under each bar shows the last hour.
When: A node feels slow, restarts, or stops answering: check here first for a full disk, memory pressure, a CPU limit that throttles it, or a hot Pi.
Example: pi: data disk 93% full (query log 6.1 GB), 58 °C. Fix: shorten the query log's retention_days, or move the data to a bigger disk.
Careful: A container sees its own limits: 'container limit' is what can kill TelltaleDNS, not the host's total. Values a node can't read (a minimal image has no OS name; many machines have no temperature sensor) are left out, not shown as zero. Docs
System information
Version, uptime, the addresses TelltaleDNS listens on, and whether the blocklists are loaded.
When: Checking an upgrade, or why something isn't listening.
Example: udp://0.0.0.0:53 and dot://0.0.0.0:853 listeners, filter snapshot 12 with 2.7 million names.
Careful: Changes to listeners take effect on reload without dropping queries. Docs
Exemplars and traces
Each latency bucket on /metrics carries an exemplar: a recent query that landed in it, named by a trace ID. The same ID is on the query's trace when traces are exported. Opening the query log with ?trace=<ID> shows that one query.
When: A latency graph spikes and you want a concrete slow query behind it: click the exemplar dot in Grafana, then open its trace ID here.
Example: The p99 for upstream answers jumps to 800 ms; the exemplar in that bucket is 00065d61…, which turns out to be a TXT lookup that waited on a slow upstream.
Careful: An exemplar is replaced at most once a second, so it's a recent example, not the slowest query. Prometheus keeps exemplars only with --enable-feature=exemplar-storage. Docs
List overlap
Unique names are the ones no other list has. When almost everything in a list is also in another, the list adds little.
When: Deciding which lists to drop to save memory and compile time.
Example: "97% also in hagezi-pro": removing this list would lose only its unique names.
Careful: Hits count since the node started, so a list with no hits after a restart may just be new. Docs
HTTP Basic authentication
Lets tools like Prometheus send a username and password with each request instead of a token.
When: A tool can't send a bearer token.
Example: A Prometheus scrape job with basic_auth.
Careful: Only over HTTPS: on plain HTTP anyone on the network path can read the password. Docs
Analytics in one query
A small query language over the query log: filter, group, top lists, percentiles, and time series, with the cost shown. Never SQL.
When: Asking a question no dashboard answers, yourself or through an AI agent (the MCP tool vqlog).
Example: from -7d | where group = kids and status = blocked | top 10 domain
Careful: Long windows over busy networks read a lot: check with a dry run (dryRun=true) first. Agents need the querylog:read scope. Docs
Live tail
New queries appear here the moment they're answered, with the same filters as the log.
When: Reproducing a problem: open the app on the device and watch what it asks for.
Example: Start the live view filtered to your phone, open an app, and see each name it looks up.
Careful: Very busy networks show a sample (it says how many it skipped) so the page keeps up. Docs
Token scope
read can look, write can also change settings like device names, admin can manage users; never more than its owner's role.
When: Creating a token.
Example: Dashboards need read; a script that names devices needs write.
Careful: An admin token can create users: keep those rare and short-lived. Docs
Change markers (annotations)
Thin vertical lines on the time charts for what was done to a node or what it did to itself: a configuration change (and whether it came from the web UI, the API, an agent, Git, or the config files), a new build, a restart, a list refresh that changed the rules, a rollout, maintenance, a pause, a cache flush, an upstream's circuit breaker. Hover one to see what and who; Note… adds your own.
When: A graph changed and you want to know why: line the change up with the moment it happened instead of reading logs. Leave a note for what the network can't see itself, like a new access point or an ISP outage.
Example: SERVFAILs stop right after a diamond that says configuration 313 applied (gitops, 1 section changed): the commit fixed it. A dot at 10:05 reads moved the AP to the hallway (admin).
Careful: Each node keeps its last 20,000 markers and 90 days. A replica knows a change's version and whether Git made it, but not who: the primary's marker says who. Notes can't be edited or deleted; add a correcting one. Docs
Device identification
A guess at what each address is, from three things TelltaleDNS already sees: the maker of its network card (the MAC address's registered vendor), the name it announces (to your router or over mDNS), and the domains it talks to. They're scored against a catalog of common home devices that ships with TelltaleDNS: "Looks like a Roku player (likely)". Likely and possibly say how sure; unknown shows the maker alone.
When: A new address shows up and you want to name it, or put it in the right group: the guess fills in the naming form, and a group that asks for that kind of device (device_classes) is suggested.
Example: 192.168.2.77 talks to ring.com and has a Ring MAC address: "Looks like a Ring camera or doorbell (likely)", and the IOT group, which asks for cameras, is suggested. Nothing moves until you add it.
Careful: It's a guess: it never names a device, moves it, or changes how its queries are answered. Phones use private Wi-Fi addresses, so their maker is unknown; behind a router or proxy that hides addresses, many devices look like one. Wrong? Name the device and set "What it is" ([[client]] kind), which wins. Off at query-log privacy level 1 and above. Docs
Workload
The Kubernetes object that runs a set of pods: a Deployment, StatefulSet, DaemonSet, Job, or CronJob. TelltaleDNS names it namespace/kind/name and treats it as one device, whichever pods it runs.
When: You see a name like kube-system/ds/cilium where you'd expect an address.
Example: db/sts/postgres is the StatefulSet postgres in the db namespace; its pod postgres-0 asks from 10.42.0.21.
Careful: A pod address is reused when pods come and go: TelltaleDNS names each logged query by the workload that held the address at the time. Docs
Change simulation
Before you save a change, replay the query log with it: every query logged in the last day (or the window you pick) is decided again with and without the change, and only the differences are shown. Newly blocked, newly allowed, a different upstream group, or a different answer (a local record, a rewrite, no IPv6 addresses), with the names, the list or rule that decided, the devices, and the groups. In a cluster every node replays its own log and the counts are added up.
When: Before blocking a domain for the kids, adding a big list, or moving a device to another group: see whether it would have hit something you need, using yesterday's real traffic instead of a guess.
Example: Block tiktok.com for the kids group, then "What would this have done?": 412 queries newly blocked from 2 devices, most of them to tiktokcdn.com, decided by the quick rule. Nothing else changes.
Careful: It's about the past and about decisions only: it can't count names nobody asked, and it doesn't predict latency, the cache, or what an upstream would answer. It takes seconds (longer on a Pi) and runs one at a time per node, at background priority; past its time or row limit the answer says partial. At query-log privacy level 1 names are hashed, so only device moves between groups with the same lists can be checked; at 2 and above nothing can. Pauses of blocking aren't replayed. Docs
DNS cache
TelltaleDNS keeps upstream answers until their time to live runs out, so repeat questions are answered in microseconds. Here you can see each node's hit rate, look up what's cached for a name (and how long it stays fresh), and flush a name, everything under it, or the whole cache, on every node or one.
When: A site moved to a new address and you don't want to wait for the old answer to expire, or you're checking whether an answer came from the cache.
Example: Look up www.example.com: A, NOERROR, 1 answer, validated, 212 s left, on both nodes. Flush it, and the next query asks the upstreams again.
Careful: Flushing doesn't clear devices' own caches (a phone or browser may keep the old answer for a few minutes). Blocked answers are never cached, so unblocking needs no flush. To change what a name resolves to, use Names on my network instead. Each node in a cluster has its own cache. Docs
Anomaly detection
TelltaleDNS learns each device's usual behavior over its first week, then points out spikes in queries, heavy traffic to one domain, a burst of brand-new domains, or a regular phone-home, with the numbers behind each. A chatty loop (a domain asked every few seconds) is shown for your information and not counted.
When: A smart plug, TV, or camera starts acting oddly, or you want to know what changed on your network.
Example: Living room TV → vendor.example: 4,100 queries in an hour; usually 119 ± 30.
Careful: Findings never block anything. Some are harmless (an app update, a new streaming service); open the device's queries before acting. Docs
Rhythm heatmap
A grid of days (or a typical week) by time of day, each cell coloured by how many queries were asked then: for the whole network, one device, or one name.
When: You want to see a pattern over time: a burst in the morning, a device that never sleeps, a tablet's bedtime, or when a name is asked for.
Example: A bright band from 10:00 to 14:00 on Thursday only, from one device asking pool.ntp.org every couple of seconds.
Careful: A device or a name is counted from each hour's top 100: hatched hours had it below the list (unknown, not zero). 15-minute and minute slots reach back 7 days; hours back 400. Docs
Upstreams (forwarders)
The public DNS servers TelltaleDNS asks for names it doesn't know yet, ideally encrypted so your ISP can't read them.
When: Choosing privacy (Quad9, Cloudflare) or filtering (family resolvers) at the source.
Example: DNS over TLS to Cloudflare and Quad9, using whichever answers faster.
Careful: Every upstream you add sees the names you look up. The breaker benches a failing server automatically. Docs
Query flow (Sankey diagram)
One diagram from groups through the decision (cached, forwarded, blocked, …) and the upstream to the response code, each band as wide as its number of answers.
When: You want proportions at a glance: how much of the kids' traffic is blocked, which upstream gives the SERVFAILs, or how one device's queries are answered.
Example: A thin red band from quad9-1 to SERVFAIL: 40 of the hour's 1,000 answers, every one from that upstream.
Careful: Each band is counted for exactly its pair, never split in proportion. A device's flow comes from the query log (the last 24 hours at most). Minutes from before 0.5 have no flow counts. Docs
Group membership
A device gets every blocklist of every group it's in; other settings (like how blocks are answered) come from its first group.
When: Some devices need stricter or looser rules than the rest.
Example: Kids' tablets in a kids group with an extra adult-content list; a work laptop in an allowlist-heavy group.
Careful: Devices in no group use the default group. Docs
Server affinity
Per device, its queries on each node over the last week, and the share on the node it uses most: mostly pi, both, or several.
When: You want to see which devices lean on one server, for example before taking that server down.
Example: The TV: mostly pi (100 %); the laptop: both. That doesn't mean the TV has no second server.
Careful: A device that has only used one server may still have a second one configured; most systems use their first server until it stops answering. Run a drill to find out. Docs
Version and update status
The exact build (version, commit, channel), and whether a newer one exists on your channel, checked once a day against a signed release list.
When: Before reporting a problem, or to know when to update.
Example: 0.1.0-edge.60 · commit abc1234 · edge: Update available 0.1.0-edge.64.
Careful: TelltaleDNS never updates itself from the UI: follow the step shown for your install (self-update, a new image, or a chart upgrade), replicas first in a cluster. Turn the check off with [updates] check = false. Docs
Users and roles
viewer can look, operator can also change everyday settings (devices, pauses), admin can manage users and security.
When: Giving family members or colleagues access.
Example: A teenager as viewer to see what's blocked; a partner as operator to name new devices.
Careful: Keep at least two admins, or set up break-glass access, so you can't lock yourself out. Docs
Audit log
Every change (users, tokens, sign-ins, device names, reloads) with who made it, from where, and why; chained so tampering shows.
When: Something changed and you want to know who did it.
Example: client.put Living room TV by alex from 192.168.1.20.
Careful: "Verify chain" proves nothing was edited or removed since it was written. Docs
Access control
Only private networks may query TelltaleDNS by default; everyone else is refused.
When: Exposing TelltaleDNS beyond your home network.
Example: Add your VPN's range so phones on the VPN can use it.
Careful: Never allow the whole internet: open resolvers are abused for attacks. Docs
Error-budget attribution
For each service-level objective, the bad answers of its window broken down: which devices and names got them, from which upstream, with which status and response code, on which node, and when, as a burn-down of the budget left.
When: The Service level card says the budget is running out and you want to know why before changing anything.
Example: Ten of 15 bad answers were one reverse-lookup name from one laptop, answered from the cache with SERVFAIL; the rest came before a fix two weeks ago.
Careful: Devices and names are approximate top lists (each count may be up to its ± over); the other lists are exact. Links open the query log, which keeps fewer days than the budget's window. Older nodes and resolver pods that are gone count in the totals but have no device or name lists. Docs
Explain
Shows the exact path a question would take for one device: which group it's in, every rule that matches with its list and line, and where the answer comes from.
When: Something is blocked that shouldn't be, or the other way round.
Example: Explain ads.example.com for 192.168.1.20: blocked by hagezi-pro line 7102, because the device is in the kids group.
Careful: It explains how the query would be handled now; lists may have changed since a logged query. Docs
Shadow lists
A list in shadow mode is downloaded and checked like any other but never blocks. Every question your devices ask that it would have blocked is counted here: how many, from how many devices, and which names most often.
When: Before turning on a new or aggressive list: run it in shadow mode for a week, look at what it would have blocked, then switch it to enforce (or don't).
Example: hagezi-ultimate in shadow mode: 4,210 queries from 9 devices this week; the top names are telemetry and ad hosts, plus one banking app's login server. Add that one to an allowlist, then enforce.
Careful: Counts start over when TelltaleDNS restarts. A shadow list is checked off the query path, so a very busy server may skip some (counted as dropped events), never slow down. Docs
Account and password
Change your password; at least 10 characters, and a passphrase is easiest.
When: First sign-in, or if a password may have leaked.
Example: correct-horse-battery-staple style passphrases are long and memorable.
Careful: Changing it signs out your other sessions. Docs