Guide

Block, allow, and explain

Add the blocklists you trust, make quick exceptions for one device or a whole group, set rules by the time of day, and when something is blocked, see exactly which rule did it.

• Add a blocklist
• List formats
• How blocked names are answered
• Quick block and allow rules
• Bedtime and other schedules
• Blocked services and safe search
• Try a list first
• Find out why
• Troubleshooting

Add a blocklist

A list can be a URL, a local file, or rules you type in. Downloads run in the background: DNS answers while they run, and a failed download never affects answers.

[[list]]
name = "hagezi-pro"                     # lowercase letters, digits, - and _
url = "https://raw.githubusercontent.com/hagezi/dns-blocklists/main/adblock/pro.txt"

[[list]]
name = "family-allow"
kind = "allow"                          # block (default) or allow
match = "exact"                         # subtree (default) or exact
path = "/etc/telltale/allow.txt"        # a local file, re-read on every refresh

[[list]]
name = "manual"
rules = ["||ads.example.com^", "@@||cdn.example.com^"]

telltale ctl put lists/hagezi-pro --data '{"url": "https://raw.githubusercontent.com/hagezi/dns-blocklists/main/adblock/pro.txt"}'
telltale ctl lists                      # with unique names and hits

Every [[list]] and [filter] key is in the configuration reference; compiling and memory sizing are in the detailed docs.

List formats

Every common format works, and formats can be mixed in one list:

Rules that only make sense in a browser (cosmetic ## rules, URL paths, $third-party) are counted as unsupported and skipped, not treated as errors. The full syntax table has every modifier.

How blocked names are answered

A query is checked against the filter after local records and before the cache, so a blocked name never reaches an upstream. The answer is set per group (the device's highest-priority group decides):

[[group]]
name = "kids"
block_mode = "null_ip"      # default: A → 0.0.0.0, AAAA → ::, other types → no records
                            # or "nxdomain", "nodata", "refused", "custom_ip"
block_ips = ["192.168.1.2", "fd00::2"]   # for "custom_ip", e.g. a "blocked" page
block_ttl = 60              # how long clients may cache the block
ede = "filtered"            # "blocked" (EDE 15, default) or "filtered" (EDE 17: parental controls)
ede_text = true             # name the list in the EDE text (false hides list names)

null_ip is the default, as in Pi-hole and Technitium: apps treat it as unreachable and give up quickly, while NXDOMAIN makes some apps retry or fall back to another resolver. In the UI, the blocked-answer mode is on the group's editor in the Advanced view.

CNAMEs are checked too: if an answer leads through a CNAME to a blocked name, the client gets its block answer. When rules disagree, the most important one wins:

1. Important allow (@@||cdn.example.com^$important)
2. Important block (||ads.example.com^$important)
3. Allow (allowlists and @@ rules)
4. Block

Quick block and allow 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. Unblock a game's server on one phone for an evening, or allow something a list blocks by mistake while you report it.

[[rule]]
id = "kids-videos"
action = "block"                 # or "allow"
domain = "videos.example.com"    # and its subdomains
groups = ["kids"]                # or devices = ["Mom phone", "192.168.1.40"]; neither = everyone
expires = "2026-10-06T07:00:00Z" # optional (RFC 3339)
note = "school night"

telltale ctl block tiktok.com --group kids --for 120 --note "homework time"   # 120 minutes
telltale ctl allow cdn.example.com --device living-room-tv
telltale ctl rules                     # what's in effect; `ctl unrule <id>` removes one

• Quick rules decide before any list, on the next query; nothing is recompiled. They also decide CNAME targets.
• A rule for the device beats one for its group, which beats one for everyone. Within those, the more specific site wins, then allow over block.
• A rule with an end time stops at that moment on every node. The query log shows quick allow or quick block with the rule's note.

Quick rules aren't parental controls: there's no screen time and no content categories. Before saving, What would this have done? replays recent queries with the change.

Bedtime and other schedules

A schedule changes a group's filtering by time of day and day of week. block_all blocks every name; block_services and enable_lists add services or lists only during the windows.

[[group]]
name = "kids"
networks = ["192.168.20.0/24"]
schedules = ["bedtime", "school-hours"]

[[schedule]]
name = "bedtime"
action = "block_all"
tz = "Europe/Berlin"                        # default: the system's time zone
window = [
  { days = ["sun", "mon", "tue", "wed", "thu"], start = "21:00", end = "07:00" },
  { days = ["fri", "sat"], start = "22:30", end = "08:00" },
]

[[schedule]]
name = "school-hours"
action = "block_services"                   # or "enable_lists" with `lists = [...]`
services = ["tiktok", "youtube", "roblox"]
window = [{ days = ["weekdays"], start = "08:00", end = "15:00" }]

• An end at or before the start runs past midnight: 21:00–07:00 on Sunday covers Sunday night into Monday morning.
• During block_all, quick allow rules still win (a homework site can stay reachable), and local names still answer.
• Schedules are checked every 15 seconds. Pausing a group's blocking pauses its schedules too.

Blocked services and safe search

Both apply only to the group's devices. The service catalog and safe-search table are part of the binary and change with updates.

Try a list first

Not sure a list is safe for your network? Add it in shadow mode: it's downloaded and checked like any other, but never blocks.

[[list]]
name = "hagezi-ultimate"
url = "https://cdn.jsdelivr.net/gh/hagezi/dns-blocklists@latest/wildcard/ultimate.txt"
mode = "shadow"          # enforce (the default) or shadow

1. Add it in shadow mode: Mode → shadow on the Lists page, or mode = "shadow" in the file.
2. Watch Would have blocked on the Lists page: per shadow list, how many queries it would have blocked, from how many devices, the names most often, and the last one.
3. Turn it on when those are names you want gone: change mode to enforce, or edit the list on the Lists page.

• The same page shows Likely over-blocking: blocked names that someone seems to want, with the lists that blocked them. They're candidates for an allowlist, or a sign a list is too aggressive.
• Counting runs off the query path and respects groups and allow lists. Counts start again at each restart.
• The API has GET /api/v1/analytics/shadow-lists and GET /api/v1/analytics/overblocking.

Find out why

Explain shows what happens to a name for a given device: who the device is recognized as and its groups, every matching rule in every list with its file line, which rule decides, and where the query would be forwarded. It follows the same steps as the server, including quick rules, a schedule that blocks everything, rewrites, and safe search.

telltale explain ad.doubleclick.net --client 192.168.1.50 -c telltale.toml
# client   tablet (identified by ip); groups: kids
# outcome  ALLOWED: allowed by list family-allow; resolved normally
# rules    snapshot 1, in precedence order (* decides, - list not used by this client, ~ shadow list)
#   * allow  family-allow         doubleclick.net (and subdomains)
#              family-allow:1  @@||doubleclick.net^
#   - block  stevenblack          ad.doubleclick.net (and subdomains)
#              stevenblack:7102  0.0.0.0 ad.doubleclick.net

Explain covers the query name only. To see why a CNAME target was blocked, explain the target name. More in the detailed docs.

Troubleshooting