Questions people ask

FAQ

Short answers, each with a link to the details. Missing yours? Open an issue and it may end up here.

Is it right for me?

Is it a replacement for Pi-hole or AdGuard Home with Unbound?

Yes, it can replace that combination. It filters with blocklists and per-device groups, and it can also resolve names itself from the root servers, so there is no second program to run.

Two things to know. There is no DHCP server (below), and the importers cover Pi-hole (telltale import pihole) and Technitium but not AdGuard Home, so you would add those lists again. Lists written in AdGuard syntax work as they are. Upgrades, backups, and moving in walks through it.

Can I run it next to my existing DNS server instead of replacing it?

Yes. Point your devices at TelltaleDNS and add your current server as an upstream, or send only some domains to it (conditional forwarding), or point your current server's forwarder at TelltaleDNS. When you want to move zones across, zone files import. See Encrypted DNS and upstreams.

What is it good at?

Three things it was built around:

  • Explaining. The query log says why each question was answered or blocked, which list and rule did it, and which upstream answered.
  • Trying before you commit. You can run a new list or rule against yesterday's real traffic and see what it would have blocked before you save it. See Change things safely.
  • Seeing. Per-device and per-group statistics, service-level objectives, and Prometheus metrics. See the tour of the web UI.
Does it include a DHCP server?

No, on purpose. DHCP stays on your router or another server. TelltaleDNS reads device names from your router's lease list (UniFi and OPNsense) and from mDNS, so devices still show up by name. See how devices get their names.

Is it a firewall or a network monitor?

No. It sees DNS lookups and only those: which devices ask for which names, and what happened to each question. It needs nothing installed on the devices, and it sits comfortably next to a firewall or an endpoint monitor, which watch different things.

Who builds it, and will it be maintained?

One maintainer builds it and runs it at home. It is free and open source, under either the Apache 2.0 or the MIT license, and the aim is community-driven development as it grows. Issues, pull requests, and ideas are welcome, and everyone who contributes is credited in the README.

It is developed with Claude Code, and every commit it worked on carries a Co-Authored-By: Claude line. The README says so under Built with Claude.

Resolving names

Can it resolve from the root servers instead of Quad9, Cloudflare, or another public resolver?

Yes. Use a recursive:// upstream:

[[upstream]]
name = "recursive"
url = "recursive://"

[[upstream_group]]
name = "default"
members = ["recursive"]

No public resolver then sees your lookups. Each server is asked only as much of the name as it needs (so the root servers see com, not the whole name), answers can be checked with DNSSEC, and delegations are remembered, so only the first lookup in a new zone takes a few round trips.

The trade-off: the authoritative servers see your address, and your ISP still sees the traffic. You can mix it with a forwarder as a fallback in a failover group. Details: recursive resolution.

My domain's servers are authoritative-only (BIND with recursion off, NSD, Knot). How do I send the domain to them?

Use a stub zone. In Names on my network → Send a domain to another server, tick These servers only know this domain (or set stub_zone and stub_servers on a recursive:// upstream). Names under the domain then start at those servers, without asking them to recurse, and delegations to sub-domains are followed. Health checks ask the zone's SOA instead of . NS, which servers like these refuse. Details: stub zones.

Can it serve my own names and zones?

Yes, at two levels. Local records answer single names (A, AAAA, CNAME, PTR, TXT, MX, SRV, with wildcards), and PTR records for your A and AAAA records are made for you. Local zones make TelltaleDNS the authority for a whole domain, from an RFC 1035 zone file or written inline, and a zone can be limited to some groups for split-horizon DNS. Manage them in the web UI or the API, or import a zone export with telltale import zone.

It is built for home and office zones, not as a public authoritative server: there are no zone transfers or secondary zones. Details: local records and zones.

How do reverse (PTR) lookups of my LAN addresses work?

By default, reverse lookups for private addresses answer NXDOMAIN, so your LAN layout never goes to a public resolver. To resolve them, add records yourself, or send your reverse zone to the server that knows your devices, such as your router:

[[upstream]]
name = "home-router"
url = "udp://192.168.1.1"

[[upstream_group]]
name = "lan"
members = ["home-router"]

[[route]]
match_suffix = ["home.arpa", "168.192.in-addr.arpa"]
upstream_group = "lan"

The same thing is a few clicks in Send a domain to another server.

Can a script add DNS records, for example when a container starts?

Yes. The API takes a record per name:

curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"records": [{"type": "A", "value": "192.168.1.10"}]}' \
  http://dns.lan:8053/api/v1/records/nas.home.arpa

Add ?dryRun=true to preview a change. Tokens are made in the web UI (Users and sign-in). If your configuration comes from Git, changes go through Git instead and the API refuses them.

Blocking

Does it block ads and security threats?

Yes. Setup offers several starting blocklists, and you can add your own by URL in hosts, plain-domain, wildcard, AdBlock/AdGuard DNS, or Pi-hole regex format. Lists apply per group, and every block says which list and rule caused it. See Block, allow, and explain.

Can I block whole categories, such as adult content?

Not with a single switch, and that is by design: TelltaleDNS never looks at page content, which keeps it fast. Categories come from the people who maintain category blocklists. You can get the same result for just the devices that need it:

  • Add a category blocklist by URL and give it only to that group.
  • Send that group to a family-filtering upstream (the presets include several).
  • Turn on safe search for the group, and block specific services such as TikTok or Roblox with one setting.

A group with no list setting uses every list, so give your other groups an explicit list of the ones they should use.

Devices and encrypted DNS

Can each device use DoH or DoT with its own identity?

Yes. Every encrypted listener (DoT, DoH, DoH over HTTP/3, and DoQ) takes a client ID: use https://dns.example.com/dns-query/kids-tablet, or the name kids-tablet.dns.example.com with a wildcard certificate. Match it in the configuration with [[client]] match = ["id:kids-tablet"], and the device lands in a group with its own lists, schedule, safe search, and upstream. The ID follows the device, even on mobile data.

The ID names a device; it is not a password. Who may ask at all is decided by the sender's address ([access] allowed_networks). If you host it on the internet for phones, put it behind a VPN such as WireGuard or Tailscale (Tailscale's range is allowed by default) or open that setting deliberately. Details: Encrypted DNS and upstreams.

This is one of the newer areas, so reports from real setups are especially welcome.

How does it name my devices?

In order: names you give them, then your router's DHCP leases (UniFi and OPNsense, read through their APIs every few minutes), then the names devices announce over mDNS. Clients → Discovered lists everything found. See Groups, devices, and VLANs.

Two things it doesn't do yet: look up a device's reverse (PTR) record to name it, and accept dynamic DNS updates (RFC 2136) from a DHCP server. Lease and mDNS names label devices in the interface and the query log; they are not served as DNS answers. If you need either, an issue describing your setup helps.

Every query shows the same client address. What's wrong?

Something between your devices and TelltaleDNS rewrites the sender, and the web UI shows a "Client IPs appear masked" banner naming the address. The usual causes and fixes:

  • A router that forwards DNS: hand out TelltaleDNS's address in DHCP instead. If it has to forward, enable the router's EDNS MAC option (dnsmasq add-mac) and list it in [clients] trust_edns_mac_from.
  • Kubernetes with externalTrafficPolicy: Cluster: use Local (the chart's default) or hostNetwork: true.
  • Docker with a proxy or bridge: use network_mode: host.

Details: seeing real client IPs.

Clusters and availability

Does it support high availability, and does the configuration sync?

Yes. Nodes form a cluster with one primary. Its configuration and blocklists reach every node within seconds over an encrypted, mutually authenticated link, every node answers DNS, and every node's dashboard and query log show the whole cluster. Nodes can be different platforms: a Kubernetes node with a Raspberry Pi, two Pis, or several pods. See Build a cluster.

Is it active-active? Does it need an external database?

No external database. Each node keeps its own small embedded store, so there is nothing shared to keep consistent. Answering DNS is active-active: every node, including extra resolver pods, answers queries with the same configuration. Configuration changes go through one primary and are signed and copied to the others.

What happens if the primary, or my Kubernetes cluster, goes down?

DNS keeps working. Every other node keeps answering from the last configuration it received, even after a restart. What pauses is changing the configuration. Promote another eligible node from the Cluster page or with telltale cluster promote, or use automatic failover with a third voter such as a small witness node.

If the configuration comes from Git, a node that isn't Git-managed can only be promoted as an emergency primary, which keeps the cluster on its last version until a Git-managed node is back. Manual promotion is the predictable choice there.

Can a Raspberry Pi be the primary, with the configuration coming from Git?

Yes. Any eligible node that has the same [cluster.git] section can take over and keep following the repository, so the Pi can follow your repository directly while Argo CD or Flux keeps managing the Kubernetes side. Join the Pi with a token made for eligible nodes. Details under "Where configuration comes from" in the cluster documentation.

Isn't DNS in Kubernetes risky when Kubernetes needs DNS itself?

The chart is built around that. TelltaleDNS's own pods keep asking CoreDNS for the cluster's names, so they never depend on their own Service, and you can leave CoreDNS as the second server for your pods, so lookups still work if the TelltaleDNS Service has no ready pods. You can also keep a node outside the cluster, such as a Pi, as a replica, so the rest of the network has DNS even while the cluster is down. See Run on Kubernetes.

Monitoring

Does it have Prometheus metrics, and can I use Grafana?

Yes. /metrics is served on port 9153 by default, limited to your allowed networks. It covers queries per transport, the cache, upstream latency and health, blocks per list and group, and where the time goes inside each answer. The Helm chart has an optional ServiceMonitor, alert rules, and a Grafana dashboard, and metrics can be pushed to an OpenTelemetry collector instead. See Monitoring and alerts.

Why do upstream health labels say "open", "closed", and "half_open"?

They come from the circuit-breaker pattern, named after an electrical circuit: closed means current flows, so requests go through and the upstream is healthy. After enough failures the breaker trips open and the upstream is benched for a while. Half-open lets a trial query through to see whether it has recovered. The same names appear in the API and in the telltale_upstream_breaker_state metric. Plainer labels for the web UI are planned.