Plain language

Glossary

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.

"This node has no IPv6 route"

No route to an upstream

This node can't reach the server's address: it is an IPv6 (or IPv4) address and the machine has no default route for that family. WrenDNS checks with a connection attempt that sends nothing, at start and every 30 seconds, never on the query path. The server fails on every query until the route exists.

When: A server you imported from Pi-hole, or added by address, is always failing.

Example: Cloudflare's [2606:4700:4700::1111] on a Pi with only IPv4: remove it from the group, or give the host IPv6. On the map the group's resolver stays yellow while the others answer.

Careful: A server given by hostname isn't checked this way; its failures show as connection errors. Docs

A device's day

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

A list is over its size limit

List size limit

A download bigger than the list's limit (64 MiB unless the list or [filter] max_list_bytes says otherwise) is refused so a wrong address can't fill the disk or memory; the last good copy stays in use. Raise the limit sets this list's own max_bytes (the size the server announced plus a quarter, or double the old limit) and downloads it again.

When: A list's row says it is larger than its limit.

Example: A big hosts list grew past 64 MiB: one click sets that list's limit to 128 MiB and the next download works.

Careful: A big list costs memory: about 20 bytes a name while running and about three times that while a snapshot compiles. The page offers up to 128 MiB for one list; past that, remove it or pick a smaller list. Check the address first: a limit hit on a list that should be small usually means the address returns something else. Docs

A list that adds nothing

Redundant list

Every name this list puts in the snapshot is also in one other enabled, enforcing list of the same kind, so removing it loses no blocking. It still costs a download and memory. Turn it off to keep it in the configuration, or remove it.

When: The Unique column reads 0 and the row says every name is in another list.

Example: A small list is wholly inside a bigger one you also use: turn the small one off.

Careful: Unique counts names, not regex rules, and is measured on the active snapshot: if you later remove the other list, this one is no longer redundant. Lists assigned to different groups overlap on purpose, so check the groups before removing. Docs

A list's address returns not found

List not found (404)

The server answered HTTP 404 or 410 for the list's address: the maintainer moved or deleted it. WrenDNS keeps the last good copy, if there was one, but it will never update. Remove the list, or edit it to the new address in Manage lists.

When: A list's row says the address returns not found.

Example: A project renamed its file: remove the old list and add the new address.

Careful: Removing a list that came from a configuration file hides it on this node; the file still lists it (Manage lists can revert that). Docs

A name's TTL and whether this node only keeps it answered with your own names

Record TTL (time to live)

How long other devices may keep an answer before they ask again, and whether only this node keeps the name.

When: A name changes often, so devices should ask again soon (a short TTL); or a name only this node should answer, such as a test name.

Example: printer.home.arpa with TTL 60 is asked again within a minute; a name marked this node only is not shared with the other nodes of a cluster.

Careful: A blank TTL means `[local] default_ttl`. A node-only name is missing on the other nodes of a cluster, so their devices don't get it. Docs

A password or token you type once

Secret field

A box for a password or token. Saved, it is kept encrypted on this node and never shown again: the field only says it's set. Replace it to change it, or clear it to stop the entry using it. If its name is already stored, the field offers to use that secret.

When: An integration needs a password or token, such as an alert's ntfy token or a router's API key.

Example: Type the ntfy access token once; the destination then says it is stored as alert.phone.token.

Careful: A file the configuration sets wins over a stored secret and can only be changed there. Over plain HTTP the server may refuse the value: turn on HTTPS first. Docs

A planned, short outage on one node

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

A replica can't reach its primary

Primary unreachable

A replica that hasn't heard from its primary for a minute is split off: it keeps answering DNS from its last copy, but it gets no configuration changes until it reconnects. It can still reach other members, which relay its state to this page, so a silent split shows here.

When: A replica shows this after a network change, or when its primary was moved or stopped. The alert fires once it has held for the rule's threshold (60 seconds by default) and its 'For at least' time.

Example: The Pi shows "no contact with the primary for 3m" while the pod still reaches it. Changes made on the primary won't reach the Pi until the link is back.

Careful: DNS on the replica keeps working. Check the network path between the replica and the primary; the alert clears by itself once they reconnect. Docs

A screen that stays on the wall

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 10.20.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

A second step when signing in

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

A witness only votes

Witness

A witness is a small vote-only member (wrendns cluster witness). It holds no configuration, no secrets and no DNS, so the Cluster page shows those as not applicable instead of behind or not ready. What it shows is whether it is up and linked, its version and uptime, and its vote: when it last answered this node's vote request or lease renewal, and the epoch it voted in.

When: Your cluster has two full nodes and a witness so that automatic failover has three voters, and the witness's row shows no configuration version.

Example: node-c (witness, votes only): up, last vote 4 s ago, epoch 7; configuration, secrets and DNS: not applicable. It is green in the topology while it is up.

Careful: A witness that is down is a real problem: with two voters left, one more failure leaves no majority and no primary can keep its lease. The checks, health reasons and the node_down alert still name it, but it never counts as behind, not serving or odd. Docs

Alert conditions

Alert condition (the when of a rule)

Each rule watches one condition. Pick the one that matches the problem you want to hear about; the list below says what each one means.

When: You are adding a rule and want to know what a condition covers before you choose it.

Example: A rule with when = "cert_expiring" and threshold = 30 tells you a DoT listener's certificate is within 30 days of expiring.

Careful: Threshold means different things: a percentage, days or seconds, depending on the condition. Conditions that don't use it ignore it. Docs

  • upstream_down: an upstream is benched (its circuit breaker is open); one alert per upstream.
  • node_down: a cluster node isn't connected; one alert per node.
  • sync_lag: a replica is behind the primary's configuration; one alert per node. Set for_secs so a normal sync stays quiet.
  • primary_unreachable: a replica hasn't reached its primary for threshold seconds (default 60, 15 to 86400); one alert per replica.
  • list_failing: a list fails to download; one alert per list.
  • list_stale: a URL list's content hasn't changed in stale_after_days; one alert per list.
  • servfail_rate: SERVFAIL above threshold percent (default 5) of queries over 5 minutes, at least 50 queries; one alert per node.
  • anomaly: a device anomaly is found (not acknowledged or muted); one alert per finding.
  • new_device: a device WrenDNS has never seen starts asking; once per device, quiet for the first day after a fresh start.
  • disk_full: a node's data disk is more than threshold percent full (default 90); one alert per node.
  • plan_pending: an AI agent's change waits for your approval; once per plan.
  • update_available: a newer WrenDNS build is out; once per version.
  • maintenance: a node is in maintenance; resolves when it leaves. Set for_secs to 0 to hear at once.
  • credential_redirected: an admin changed where an entry's credential is sent; once per change.
  • secrets_exported: a backup with the stored secrets was made through the API; once per backup.
  • slo_burn: a service-level objective spends its error budget too fast (14.4 times over an hour and 5 minutes, or 6 times over 6 hours and 30 minutes); one alert per objective.
  • probe_failing: a listener or extra target hasn't answered its probe twice in a row, on any node; one alert per node and target.
  • cert_expiring: a DoT, DoH or DoQ listener's certificate expires within threshold days (default 14, from 1 to 365); one alert per node and listener.
  • rollout_failed: a staged rollout's guard failed a version and pinned the cluster to the one before; once per version, with the reason.
  • cluster_pinned: the cluster is pinned to an older version, so configuration changes wait; raise for_secs if you pin on purpose for long.
  • chatty_loop: a device asks one domain at a steady rhythm faster than every 30 seconds (an informational finding the anomaly rule leaves out); one alert per finding.
  • drill_report: a failover drill's report is ready, scheduled or started by hand; once per drill, saying who followed, who was stuck and the coverage.

Alerts

Alert rules and destinations

Messages to ntfy, Gotify, Pushover, 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 a stored secret (the token field keeps it encrypted), not in the config file. Docs

Allow or block a site for one device or group

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. Press Edit on the Quick rules page to change one; it keeps who made it and when.

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 WrenDNS 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

Answer a whole domain from its own records answered with your own names

Authoritative zone

WrenDNS answers every name under a domain itself, from the records you list; a name it doesn't have gets “no such name”.

When: A private domain such as home.example.com should be answered only from your own records, and a made-up name under it should fail at once.

Example: home.example.com with printer.home.example.com → 192.168.1.20; ghost.home.example.com gets “no such name” at once, from this node.

Careful: Only the groups you pick see the zone (split horizon). A zone the configuration file defines, or its zone file, is read-only here. The negative TTL is how long devices may remember “no such name”. Docs

Answer quality

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. The sampling rate, reference group and history size are set under “Change the second opinions” (operators). Docs

Answer time over time

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

Answers from memory answered from memory

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

Block a whole service

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 WrenDNS. Add a quick rule for anything it misses. Docs

Block list or allow list

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

Block or allow whole categories of sites blocked

Filter lists (blocklists and allowlists)

Lists of names, maintained by others or by you, that WrenDNS 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

Bring your Pi-hole setup over

Import from Pi-hole

Reads a Pi-hole Teleporter export (or its gravity.db), shows what would be added, changed or skipped, and applies the preview as one change once you confirm it.

When: You are moving from Pi-hole to WrenDNS, or want to see what a Pi-hole export holds before you decide.

Example: Upload the Teleporter zip from Pi-hole v6. The preview lists its upstreams, local names, lists and groups, and the notes say what has no equivalent, such as the DHCP server and the query history. Apply writes them in one change, which the audit log records as import.pihole.

Careful: Nothing changes until you apply. Names the config files define are skipped, and DNSSEC is set in the file, not here. The Points to column shows where each entry goes: a file list reads a file on this machine, and the notes say so. Discard forgets a preview without a change. Only admins can import, and agents can't. A preview expires after ten minutes; if the configuration changes meanwhile, preview again. Docs

Cache memory

Memory budget of the DNS cache

How much memory a node may use for the answers it keeps, and how many answers it may keep at most.

When: The Size line on the Cache page says a bigger cache would answer more lookups from memory, or the node's bar is near full.

Example: A node with spare memory can take 64 MiB; the Cache page then shows how much of it the answers use.

Careful: Applies when the node restarts, not at once. The budget is taken from the node's memory, so a big cache on a small Raspberry Pi can crowd out other work. Docs

Change upstreams, lists, and groups here

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

Check a router before you save it

Check it

Check it reads the router once with the form's settings and saves nothing. A stored credential is sent only to the address and TLS settings it was saved with, or to a new router's own secret named after it.

When: You want to know the key, address, and certificate work before the router is saved and read every few minutes.

Example: A check of a new UniFi router that reports 12 devices and 3 networks read, with nothing saved.

Careful: When the address or the certificate differs from the saved router's, a stored credential isn't sent, and the check says so. Docs

Check the answers match

Compare with Pi-hole

Resolves a sample of names (addresses for A and AAAA) through your Pi-hole and through WrenDNS, and lists each name whose answers differ. The sample is the import's own local names and CNAMEs, up to 20 blocked names, plus any extra names you type (comma-separated).

When: Before you switch your network's DNS to WrenDNS, to see what would change for the names you use.

Example: The sample has your local names, the CNAMEs, and a few blocked domains. A difference such as NXDOMAIN on WrenDNS against an address on the Pi-hole means that name isn't answered the same yet.

Careful: WrenDNS answers from its running configuration. Run the imported configuration first, or the comparison shows what the node answers now. Each name costs two queries to each server, and the comparison stops after a minute. Docs

Checking for new builds

Update check

Once a day this node reads the signed release index of its channel to see whether a newer build exists. Nothing else leaves the node.

When: You want to hear about a new build without checking yourself, or you want no outside request at all.

Example: With the check off, the status says off and no request is made to the release index.

Careful: Applies after a restart of this node. Docs

Choose each person's role from their groups

Group to role rules

Each rule maps one group the provider reports to a role. A person gets the highest role any of their groups maps to, at every sign-in. People in no mapped group get the role for everyone else, or can't sign in when there is none.

When: You decide who is an admin, an operator or a viewer by the groups they are in at the provider.

Example: dns-admins is admin, family is viewer, and no role for everyone else: a stranger with an account at the provider is refused.

Careful: Leave the role for everyone else empty unless every account at the provider should get in. The groups claim (default groups) has to be in the provider's tokens: add it to the client's scope there. Docs

Choosing from a long list

Search and multi-select

Type to narrow the list, click or press Enter to pick, Select all and Deselect all act on what the search shows, Backspace removes the last pick.

When: A setting offers many devices, groups, lists or networks.

Example: In a group's networks, type "10.20.2" and Select all.

Careful: Escape closes the list without changing the choice. Docs

CMDB: one record for each thing on your network

Configuration item (CI)

The CMDB keeps one record for each real thing on your network (a laptop, a switch, a camera, a VLAN) and remembers what every source said about it: your router, a managed switch, Home Assistant, the neighbour table, the clients that asked DNS, and your own configuration.

When: Turn it on to see everything about a device in one place, and to correct a device the sources get wrong. Leave it off if you don't want WrenDNS to keep a record of your devices.

Example: Your laptop has a Wi-Fi and an Ethernet address. The router sees two clients and Home Assistant knows one device with two MAC addresses. The CMDB shows one device with two interfaces, and the record each source made.

Careful: It only reads: it never writes to a router or a device, and it never changes a DNS answer, a filtering decision or a device's name in DNS. Only one node runs it, the node the network inventory is designated to, even when the inventory itself is off. It can't be on at privacy level 2 or 3; at level 1 names are hashed. Only an administrator changes its settings. Docs

Connect a UniFi console

UniFi API key or local user

A UniFi OS console (UDM, UCG) or the Network application, read with an API key (UniFi Network 9 and later) or with a local user that can read clients and networks.

When: You want the devices your UniFi console knows, by the names it gives them.

Example: Address https://192.168.1.1, an API key stored as unifi.home-gateway.api_key, and the console's certificate fetched and trusted.

Careful: Trust the console's own certificate (Fetch the console's certificate). Skipping verification lets anything on the LAN pose as the console. The certificate changes when the console renews it: fetch it again then. Docs

Content categories

Category

A category is a named kind of site (adult content, gambling, malware, social networks, ad block) backed by an open list its maintainer publishes. A profile chooses categories; this node downloads each list once, however many profiles use it, and blocks the names in it for that profile's devices only.

When: You want to keep a kind of site away from some devices, such as adult content and gambling on the children's tablets, without writing a list yourself.

Example: A Kids profile with Basic filtering blocks adult content, malware, phishing and scams. The Teens profile adds Gambling and Social networks. The default profile blocks none of them.

Careful: A category block is a DNS block: it stops names, not pages. A device on mobile data, a VPN or its own encrypted DNS goes around it, apps cache answers, and no list is complete. It is not a promise of child safety. Docs

Device anomaly settings answered with your own names

Anomaly detection (per device)

How readily WrenDNS reports a device that suddenly asks for much more, or for many new domains, or beacons to a service on a schedule.

When: Too many findings for devices that are normal (lower the sensitivity, or lengthen the learning period); or a device that should be watched more closely (raise the sensitivity).

Example: Learning for 14 days and low sensitivity: only large departures from a device's own baseline are reported.

Careful: Admins only: these are node-managed and apply on every node, and the files win field by field. Findings already recorded stay as they are. Ignored domains are never reported. Docs

DNS64

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

DNSSEC validation

DNSSEC

DNSSEC lets WrenDNS check that an answer was really published by the owner of the name. Off passes answers through, validate refuses bogus ones, and validate-and-count only counts them.

When: You want to stop forged answers from reaching your devices, or to see how many would be refused before you turn refusing on.

Example: A domain whose server is internal and not signed goes in the list of domains not validated, so its answers aren't refused.

Careful: Validation takes effect on every node within seconds. A wrong trust anchor makes answers for a signed domain fail. Docs

Does the second DNS server work?

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

Filter by the time of day

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

Filter profiles

Profile

A profile is a group with a friendlier editor: who it applies to (networks and devices), Ad Block, Safe Search for each engine, a filtering level (Off, Basic or Enhanced with the categories you tick) and a schedule. Every other setting of the group stays under Advanced settings.

When: You want one set of rules for a kind of device: the children's devices, the smart-TV network, the guests.

Example: The Kids profile applies to the kids' VLAN and to Maya's iPad, has Basic filtering, Safe Search for Google and YouTube, and a bedtime schedule.

Careful: A device can be in several profiles: the lists are the union and the other settings come from the profile with the higher priority. A device with a private Wi-Fi address may stop matching when the address changes: select it by address or router name instead. Docs

Find encrypted DNS by itself (DDR)

DDR (RFC 9462)

Devices that support it ask resolver.arpa where an encrypted resolver is. With a DDR name set, this node answers with its DoT, DoH, and DoQ listeners.

When: Windows 11, iOS 16 and later, and macOS 13 and later should use encrypted DNS on your network without a profile.

Example: Set dns.home.arpa on a node whose certificate carries that name: a device that asks learns the listeners and uses them.

Careful: A listener bound to loopback, or one behind PROXY protocol, isn't advertised. The certificate must cover the name and the address the device connects to; the listener checks show whether it does. Docs

Fixing a wrong link

Link, unlink, merge, split

Move a record to another device, unlink it, merge two devices, or split records out of one. Each shows a preview of the records that would move before anything is written, and each stays after the next report: your decision is kept.

When: A record is on the wrong device, or one thing is shown as two, or two things as one.

Example: A printer's mDNS record attached to the wrong device. Unlink it: it will not be matched to that device again and stands on its own, or Move it to the printer's own item.

Careful: A MAC address identifies an interface, so moving or unlinking a record with a MAC moves the whole interface with every record of that MAC. Operators and admins may do this; nothing here changes the network. Docs

Forgot the password

Offline password reset

On the machine that runs WrenDNS, with it stopped, an admin on the machine sets a new password for any user. Their web sessions end.

When: Only when nobody can sign in: no admin remembers a password and no second admin exists.

Example: Stop the service, then run: printf '%s\n' "$NEW_PASSWORD" | wrendns auth reset-password alice -c /etc/wrendns/wrendns.toml, or run it without the pipe and type the password twice.

Careful: It needs the node stopped, and it can't run on a cluster replica (reset the password on the primary). Whoever can run it controls the node, so it's for the person who runs the box. A web session ends, but API tokens and HTTP Basic logins keep working. Typing the password, Ctrl-C then Enter cancels it. Docs

Getting back after a guarded change

Guarded recovery

If a guarded change leaves a node unreachable, the way back never needs the UI: set the value in the configuration file and restart (a file always wins), run wrendns guarded list and wrendns guarded clear on the stopped node, or start it once with WRENDNS_IGNORE_GUARDED=1 so it runs on its files alone. Two failed starts after a staged change also drop it automatically.

When: The UI is unreachable after an address, certificate or proxy change, DNS stopped after a listener change, you cannot sign in behind a proxy, the secret store is locked after a key change, or a Restart now did not bring the node back.

Example: On Kubernetes, set WRENDNS_IGNORE_GUARDED=1 on the pod and let it restart: it ignores every stored guarded setting and uses its ConfigMap. Fix the setting, remove the variable, and restart again.

Careful: wrendns guarded clear needs the node stopped and only clears that node's entries. WRENDNS_IGNORE_GUARDED ignores entries without deleting them, and never ignores the file. Docs

Guarded settings

Guarded change

Some settings can lock every admin out, put passwords on the wire, re-encrypt your stored secrets or replace a node's configuration. They are changed in two steps: a review that says what the change does and gives a phrase, then the change itself once you type that phrase. A change to an address, a certificate or the trusted proxies is applied as pending and kept only if you confirm it through the new address within the window (120 seconds by default); otherwise it rolls back by itself. A change that weakens security also needs a sign-in from the last 10 minutes and is marked in red.

When: Before changing a listener, the API address, TLS, trusted proxies, the secrets key or the cluster from the UI.

Example: You move the API from port 8053 to 9000. The node opens 9000 beside 8053, gives you a link to the new address, and keeps the change only if you open it and press Confirm. If the new address is unreachable, do nothing: it rolls back and you are still where you were.

Careful: Admins only, never AI agents or API tokens. A value set in the configuration file wins over the UI and locks the control ("set by file"). Restart now exists only where the node declares a supervisor that starts it again. Docs

How blocked names are answered

Block response

What a blocked name gets back: a zero address (null_ip), no such name (NXDOMAIN), no data (NODATA), a refusal, or your own landing-page addresses (custom_ip). The block TTL says how long clients may keep it, and the Extended DNS Error code says why.

When: You want a blocked site to show a "blocked" page of your own, or a family group's blocks to say they are parental controls.

Example: The kids group answers custom_ip with 192.168.1.2 for 60 seconds and Extended DNS Error 17 (filtered), without naming the list.

Careful: custom_ip needs at least one block address. A long TTL keeps a block in clients' caches after you lift it. Docs

How lists stay current

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: WrenDNS 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

How long answers are kept

Cache time to live (TTL)

The shortest and longest time an answer is kept, how long names that don't exist and SERVFAIL are kept, whether old answers are served when upstreams fail, and whether popular answers are refreshed before they expire.

When: Answers change often and you want them fresher, or your upstreams are slow or flaky and you want old answers to keep working while they recover.

Example: A shortest TTL of 60 s makes an answer that says 5 s live for a minute; serve stale keeps the last answer for the first clients when the upstream doesn't reply in time.

Careful: Applies when the node restarts, not at once. A long TTL means changes to a name reach devices later. Docs

How regularly does it ask?

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

How WrenDNS answers a question sent to a public DNS server

DNS resolution

Every device asks WrenDNS 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 WrenDNS answers "nowhere" and the ad never loads.

Careful: Devices only use WrenDNS if your router hands out its address as the DNS server. Docs

Icons beside domain names

Domain icons

A small mark left of a name in the dashboard's lists and the query log: a brand's colour and glyph when WrenDNS knows the brand, otherwise a letter in a colour that is always the same for that owner. It is drawn here; nothing is fetched.

When: Pick Monogram only if you'd rather not see brand marks, Small for denser lists, or Off for plain names.

Example: netflix.com shows Netflix's red tile, cdn.example.org a letter C, and nas.home.arpa, a name of your own network, a house.

Careful: The choice is kept per user in this browser, not on the server. When a privacy level hides names, there are no icons.

Internet and internal names

Internal names

Internal names are your network talking to itself: reverse lookups of private addresses and, in Kubernetes, the cluster's own names (cluster.local). They have their own top list, so Top domains shows what your devices and workloads reach outside.

When: Top domains is full of cluster.local or in-addr.arpa names; switch to Internal to see which Services your workloads call most, or which private addresses get looked up.

Example: A pod looking up api.github.com first tries api.github.com.argocd.svc.cluster.local and two more cluster names (its search list); those failures land under Internal, not in Top domains or the NXDOMAIN list.

Careful: Nothing is hidden: internal names stay in the query log, the live view, a device's own top domains, and the blocked list. Add your own (e.g. lan) with [telemetry] internal_names on each node. Docs

Inventory workers

Discovery worker

The inventory's SNMP reads run in a separate small process, so a problem there can't slow or stop DNS. WrenDNS restarts it when it stops, and waits longer each time it keeps failing.

When: Look here when the inventory shows no data, or when the health icon names a discovery worker.

Example: A worker is refused because it was built from a different version than this node. Upgrade the node so both match, and the worker starts again.

Careful: A worker that keeps crashing is a sign of a fault in the inventory or in a device's reply. DNS keeps answering while it is down. Docs

Is each server healthy? sent to a public DNS server

Upstream health (circuit breaker)

Healthy means the server is answering. Benched means WrenDNS stopped asking it after failures and will test it again soon; Probing is that test. (In the circuit breaker's words: closed, open, half-open.)

When: Lookups are slow or failing.

Example: An ISP outage benches one server; the others keep answering.

Careful: If every server is benched, only cached and local answers work. Docs

Is something odd with that node?

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

Keep a copy of your setup

Backup and restore

One file with your settings, users, API tokens, the devices and names you added, the audit log, and statistics history. Tick "Include the stored secrets" to carry the passwords and tokens you stored in the UI too, encrypted with a passphrase you choose.

When: Before an upgrade, before moving to new hardware, or just to have a copy.

Example: Download a backup with a passphrase on the old Pi, then run wrendns backup restore --secrets-passphrase-file on the new one: the stored secrets come back under the new node's own key.

Careful: The file holds password hashes: keep it private. Without a passphrase the stored secrets are left out (the page says how many); with one, they need that passphrase to come back, and a backup with secrets needs a sign-in from the last 10 minutes. The query log is included only if you tick it, or from the command line (--include-qlog). Docs

Keep a password or token on the node, encrypted

Stored secret

A password or token (a router's API key, an alert's token, an OIDC client secret) kept in WrenDNS's own database, encrypted with the node's key, and never shown again once saved. Settings → Integrations & secrets lists them and shows where each one is used.

When: You'd rather type a password or token into the UI than put a file on the machine.

Example: api_key_ref = "router-key" uses the stored secret named router-key as the UniFi console's API key.

Careful: A credential set in the config file wins and can't be changed in the UI. Keep a copy of the node's key: without it, stored secrets can't be read. Backups leave them out unless you give a passphrase (Settings → System → Backup). Docs

Keep the cache across restarts

Warm start

The node writes its cache to disk when it stops and reads it back when it starts, so it doesn't start empty; in a cluster it also asks the other nodes for their most-used names.

When: After an upgrade or a restart a cold cache means slower first answers for every client.

Example: With the cache kept, a node that restarts answers its first lookups from the saved answers that are still fresh.

Careful: The file is owner-only, since it shows what was looked up. Applies when the node restarts. Docs

Keep the names of offline devices

Offline clients

A UniFi console remembers the devices that have left the network. WrenDNS keeps their names for this many days, so a phone that is off Wi-Fi still shows its name in the query log and the top lists. Those devices don't count as seen: they don't make a device look present on the network, they give no address to the device inventory, they aren't published as DNS names, and they aren't counted in a network's device totals. They are listed in the leases with an "offline" marker (see Offline devices in the leases).

When: A device you know by name shows as a bare address once it has left, and the log's names for it disappear with it.

Example: With 30 days (the default), a laptop asleep since last Tuesday still shows as "Kitchen laptop" in the query log; a guest's phone last seen 90 days ago shows as an address again.

Careful: 0 keeps only the connected devices and the ones with a fixed address (a DHCP reservation, which always keeps its name). The window is at most 365 days, and the console still has to keep its history: an older Network application without it gives the connected devices only. Docs

Keeping support logs

Support logs

Whether this node keeps its log files on disk, so a support package made later includes them.

When: You are asked for a support package after something went wrong, and the earlier logs are needed.

Example: With the logs kept, the support package of last night's failure still has its log lines.

Careful: Applies after a restart of this node. Logs take disk space. Docs

Kept out of the log

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

Kept out of the query log only

Log-only exclusions

Devices, domains and this node's own lookups whose queries are answered and counted in the dashboard and top lists, but never written to the query log, the live view or the event sinks.

When: The log fills with the node's own lookups (client 127.0.0.1, name localhost) from a health check or a watchdog, or with one chatty device or domain, and you still want them in the statistics.

Example: Turn on the node's own lookups and add *.lan: the log shows only real devices asking for real names, while the dashboard's totals stay complete.

Careful: Excluded queries can't be searched later. Queries logged before stay. A device name that no client has matches nothing. To leave a query out of the statistics too, use the Names and Devices fields above. Docs

Keys for scripts and dashboards

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 WrenDNS.

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

Let an AI assistant help, safely

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

Let people sign in with an account they already have

OIDC sign-in provider

Keycloak, Authentik, Google or any OpenID Connect provider. A person signs in at the provider and WrenDNS gives them a role from the groups the provider reports. A provider you add, change or remove here applies on every node within seconds, with no restart.

When: You want family or colleagues to sign in with their own account instead of a password kept here.

Example: Issuer https://id.example.com/realms/home, client ID wrendns, the client secret stored as oidc.keycloak.client_secret, and the group dns-admins mapped to admin.

Careful: Register each node's redirect URI (shown on the provider's card) with the provider. Each node's configuration file sets its own public_url; without it the provider is inactive on that node. Removing a provider ends the sessions it opened. The break-glass admin's password sign-in is never affected. A provider the configuration file defines is read-only here. Docs

Let Pi-hole tools talk to WrenDNS

Pi-hole compatible API

Answers the part of Pi-hole's API that the Home Assistant Pi-hole integration, phone apps and dashboards use: the statistics, and turning blocking off for a while and back on. Off until you turn it on; one token you make here.

When: You already have Home Assistant, a phone app or a dashboard set up for Pi-hole and want it to keep working against WrenDNS.

Example: Turn it on, copy the token, then in Home Assistant add the Pi-hole integration with this server's address, location admin, and the token as the API key. Its sensors show queries and blocked today, and its switch turns blocking off for a while.

Careful: The token is shown once and only its hash is kept: make a new one if you lose it, and the old one stops working. It can read the statistics and pause blocking, nothing else. A pause with no timer lasts the longest pause you set (60 minutes by default), so a phone cannot leave filtering off. Prefer Pi-hole v6 mode in your tool: v5 puts the token in the address, which logs may keep. Docs

Likely over-blocking

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

List size and staleness

List limits

How large a downloaded list may be, how often URL and file lists are refreshed, and when a list nobody has confirmed for a long time is flagged as stale.

When: A list is big enough to be refused, or a list's source may have been abandoned and you want to hear about it.

Example: A list over 64 MiB is refused and the last good copy is kept; a list not confirmed for 30 days shows as stale.

Careful: The refresh and stale settings apply after a restart. A list's own limit overrides the lists' default. Docs

Listener checks

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). Their interval, timeout, extra targets and certificate warning are set under “Change the listener checks” on this page (operators). Docs

Maintenance mode

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

Make a group from a network

Group

Opens the Groups editor with this network already filled in as the group's networks, so the devices on it follow the group's lists and settings.

When: A network has no group yet, so its devices use the default group.

Example: A new IoT network: make a group named iot from it, then pick its lists.

Careful: Groups are checked when you apply them. A network that another group already covers isn't offered this button.

Merge proposals

Merge proposal

When the sources point at two devices for one record, or two devices share a host name on one network, the CMDB never guesses: it keeps both devices and proposes the merge. A proposal changes nothing until a person applies it.

When: Look at the proposals after you add a router or a switch, when new records arrive that name the same thing in different ways.

Example: A switch's record has a MAC that belongs to one device and a serial number that belongs to another. Both devices stay, and a proposal asks whether they are one.

Careful: A host name match alone is only a proposal: two phones can share a name on one VLAN. Merging moves the records and leaves the old id as an alias that redirects for 90 days. Docs

More from your routers

Extra router reads

The inventory can ask UniFi for more than its device list: more fields of each connected client (port or access point, VLAN, network, first seen), clients it has seen before (history), and its own devices with each switch port's MAC table and LLDP neighbours. It can also ask Home Assistant for devices that have a MAC address and no entity. Every read only reads, adds to the inventory only, and is capped at 4 MiB and 8,192 rows (Home Assistant 1 MiB).

When: Turn these on when the inventory shows a device with no place: you want to know which switch port or access point a device is on, or to keep the name of a phone that left last week.

Example: With the devices read on, a printer's row shows the switch and port it plugs into. With history on, a laptop that has been away for ten days is listed as history, with the last address UniFi saw, and it never answers for the address now.

Careful: History is never a current address: it can't give a device a DNS name, and it never replaces an address a router reports now. A console that refuses a read (a key without the right to read devices, for example) is reported once in the table, and the other reads carry on. Home Assistant can only list a device with no entity when the device sits in an area or has a label. Docs

Muting a finding that is harmless

Anomaly mute

A mute stops one kind of finding from counting for one device or group: the finding is still recorded and listed (turn on Show muted), but the sidebar badge, the anomaly alert, the health level and the totals skip it. Every other device is still checked. Give it an end date or a note so it doesn't outlive its reason.

When: A device does something harmless over and over: a TV that looks up every address on your network once an hour, a backup job that is busy every night.

Example: Living room TV, Burst of failed lookups, for a week: its hourly reverse-DNS sweep stops raising an alert, and the finding stays listed as muted.

Careful: A mute can also hide a real problem on that device for as long as it lasts. Mute the narrowest kind, for the shortest time you are comfortable with, and say why. Docs

Name devices from Home Assistant

Long-lived access token

Home Assistant names devices by the MAC addresses in its registry. WrenDNS reads them with a long-lived access token, which must come from an administrator's account, because the template it renders needs one.

When: Your devices (Shelly, ESPHome, Sonos, TVs) have names in Home Assistant you'd like WrenDNS to use.

Example: Address http://homeassistant.local:8123 and a token stored as home_assistant.ha.api_key (the form names it `<kind>.<router name>.api_key`).

Careful: The token is an administrator's: anyone holding it can read your Home Assistant. Keep it stored, never in a file in Git. Docs

Name devices from your routers

Router integration

A UniFi console, an OPNsense firewall, or Home Assistant that WrenDNS reads, read-only, to learn the names and addresses of the devices on your network.

When: Devices show as bare addresses, or your router already names them and you want WrenDNS to use those names too.

Example: A UniFi console named home-gateway reports a laptop called laptop at 192.168.1.20: its queries then show that name.

Careful: Give it a read-only account or a key that can only read. Only an admin adds, changes, or removes a router. Each stored credential is encrypted on the node and never shown again. A router with a stored credential is read by the primary only: on a replica its card shows the primary's last read, marked as read by the primary, and the credential never leaves the primary. Docs

Name devices in DNS

Device names

Devices WrenDNS knows by name answer as name.domain, such as kitchen-tablet.home.arpa, with a reverse name too. Names come from your devices, your routers' DHCP leases, Home Assistant, and mDNS when it's on.

When: You want to open kitchen-tablet or nas by name from any device, and the router's DHCP names aren't in DNS.

Example: Set home.arpa: a router lease for kitchen-tablet answers kitchen-tablet.home.arpa within about 10 seconds, and the reverse lookup gives the name back.

Careful: local is refused: mDNS owns it. mDNS names need the mDNS switch, which only an admin turns on, because it opens multicast listening on every node. That switch takes effect after a restart on every node. Docs

Name your devices

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. Under Discovered on your network, each device shows the DNS name it answers as (copyable) and the router that named it (for example "router: udm (UniFi)" or "router: home-assistant (Home Assistant)"). Routers are added on the Routers page, under Devices.

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

Names on your network answered with your own names

Local records (zone)

Names WrenDNS 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

Names with a special meaning

Special names

Names that have a standard meaning are answered here, not on the internet: iCloud Private Relay's names, Firefox's DoH canary, localhost, CHAOS queries, reverse lookups of private addresses, and one-label names like nas.

When: Apple devices bypass your filters because Private Relay is on, a bare name like nas goes out to the internet, or a browser setting skips this resolver.

Example: Leave Private Relay names blocked: an iPhone on your Wi-Fi then uses this resolver and its filters. It shows Private Relay as off for this network, which is what Apple expects.

Careful: Turning a switch off sends its names to the internet again, at once and on every node. The DDR name is one name for the whole cluster, and it must be on every encrypted listener's certificate: only an admin sets it. Docs

Network inventory

Network inventory

WrenDNS can list the devices on your network that routers and Home Assistant already know, and read a few facts from your managed switches and gateway. It only reads: it never scans the network itself.

When: Turn it on when you want to see devices that never ask DNS for anything, such as printers or devices with fixed addresses. Leave it off if you don't want WrenDNS reading switches or gateways at all.

Example: You list your gateway's subnet 192.168.1.0/24 and turn the inventory on. The gateway's ARP table then tells WrenDNS which MAC address sits behind each address on that subnet.

Careful: Only one node runs the inventory: the primary, or the node you name. Changes are for administrators only. Turning it on is refused while privacy level is 2 or 3, because the inventory needs client addresses. Docs

New domains

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

No IPv6 addresses

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

Offline devices in the leases

Offline

The leases (the Clients page's Discovered list and a network's device list) include the devices the router remembers but doesn't see now, marked offline. They show the address and the name the router gave, but no DNS name, and they don't count in a network's device total. So the Discovered tab's count can be higher than the device count on the Networks page.

When: You want to see a device that has left the network, or check why a known device has no DNS name.

Example: A phone marked offline in Discovered still shows its name in the query log, but asking DNS for its name gets no answer until it is back on the network.

Careful: An offline row is the router's memory, not a live answer. Its address may belong to another device by now, which is why it gives no DNS name and no binding to the device inventory. Docs

Per-client metric series answered with your own names

Per-client metrics (Prometheus)

Whether /metrics has a series for each device, and how many devices get one.

When: You want to graph one device's queries in Prometheus or Grafana.

Example: Per device with a cap of 100: the first 100 devices get their own series, the rest count as “other”.

Careful: High cardinality: every device is a time series in your Prometheus, so keep the cap low. Admins only; no agent can change it. Docs

Pick your upstream servers

Upstream picker (simple view)

Tick the public DNS servers you want, choose encrypted or plain DNS and IPv4 and/or IPv6, and Save. WrenDNS asks the fastest of the servers you ticked. The Custom row takes an address of your own. The Advanced view is the technical list and forms.

When: Setting up, or changing which public servers answer for you, without writing addresses by hand.

Example: Tick Quad9 and Cloudflare, leave Encrypted on, and Save: DNS over TLS to both, using whichever answers faster.

Careful: Every server you tick sees the names you look up, so read its note. Plain DNS isn't private. IPv6 is greyed out when this node has no IPv6 route. Servers set up another way (config files, an import, the Advanced view) are shown and left alone, and stay in the default group. Docs

Pinning the cluster to a version

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

Pods named by what they run

Kubernetes workloads as devices

WrenDNS 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 wrendns.com/group=media and every pod in it gets the media group's lists.

Careful: Pods show up as themselves only when they ask WrenDNS directly (the cluster's DNS pointed at it, or a workload's dnsConfig); through CoreDNS they all look like CoreDNS. Docs

Prune lists

Prune

Previews the block lists that add less than a threshold of their own entries (names no other list has, plus their regexes), and turns them off after you confirm. They stay in the configuration; Undo turns them on again.

When: Several big lists overlap and you want fewer lists to download and compile.

Example: At 1%, a list where 99.5% of the names are also in hagezi-pro is proposed; turning it off could stop blocking at most the 0.5%.

Careful: Allow lists, shadow lists and lists a group names are never proposed. Overlap is by name, so a regex or a wildcard another list covers isn't seen: the plan only errs toward keeping a list. Docs

Push metrics to an OpenTelemetry collector

OTLP export

The same metrics Prometheus scrapes can be pushed to an OpenTelemetry collector (the OpenTelemetry Collector, Grafana Alloy, a hosted backend) every interval. A header such as an API key is a stored secret, read for every export.

When: Your metrics live in a hosted backend, or Prometheus can't reach this node.

Example: Collector http://otel-collector:4318, every 60 seconds, with the header x-api-key taken from the stored secret otlp.default.header-x-api-key.

Careful: Only an admin changes it, and it applies on every node without a restart. If the configuration file sets the collector, headers or header references, the file wins and the card is read-only; an inline header value in the file is never shown (it reads <redacted>). Trace settings stay in the file and are read at start. Docs

Pushover keys

Pushover application token and user key

A Pushover destination needs two secrets: the API token of an application you make for WrenDNS, and your user key (or a delivery group's key).

When: You are adding a Pushover alert destination and need to know where the two values come from.

Example: On pushover.net, sign in: your user key is shown at the top right of the dashboard. Under Your Applications choose Create an Application/API Token, name it WrenDNS, and copy its API Token/Key. Paste the token into the Token field and the user key into the User or group key field.

Careful: Both are stored encrypted on the node and never shown again; anyone with them can send you messages. If one leaks, reset the token on pushover.net and store the new one. Alerts go out with priority 0 (firing) and -1 (resolved) unless you change them; emergency priority is not offered. Docs

Query history in a backup

Query history

Whether the backup includes the query log, the record of every answer this node gave. It can be large.

When: You need to move the history to another node, or keep it for a record.

Example: A backup without the history is small; with it, the file can be over 256 MiB, and the API then refuses it.

Careful: The history shows what devices looked up. Keep the backup as private as the network it came from. Docs

Query log store, retention and privacy answered with your own names

Query log (retention and privacy level)

How long the query log is kept, how much disk it may use, and how much of each query it keeps.

When: The log holds more than you want to keep (shorten the retention), or it should not show the names or the devices (raise the privacy level).

Example: Privacy level 2 keeps the domains but hides the devices; retention of 7 days keeps the last week.

Careful: Admins only, since privacy and retention are at stake. The privacy level applies within seconds; turning the log on or off, its retention and its flush settings take effect after a restart. Docs

Read the network map

Network map

Your gateway, networks, devices, WrenDNS nodes, answer kinds and upstreams, joined by the flows between them. A wider, denser pulse is more lookups a second; the shape and the word on each node (OK, Warning, Failing, Idle) say how it is doing, so the colour is never the only sign.

When: You want to see at a glance which device, node or upstream is having trouble, then click it to open its queries, Explain or anomalies. Use the Table view for the same data as text.

Example: A device is Failing: its flow to the resolver is red because a quarter of its lookups got SERVFAIL. Open the device, then Show its queries.

Careful: The map is drawn from a sample of lookups, so the rates are estimates (a banner says 1 in N when it is thinned) and a quiet device is Idle, not healthy. At privacy level 2 devices are hidden; at 3 only totals show. No domain name appears on the map. Docs

Read the world view

World view

A dot-grid world map with an arc from your network to each country the answers point at. A wider, denser pulse is more lookups a second; the colour and the shape at the country's end (OK, Warning, Failing, Idle) say how many of those answers were slow. Diamonds mark where your upstreams are.

When: You want to see where your devices' answers lead, or whether one region is slow. The Table view is the same data as text.

Example: Most arcs end in your own country and one thick arc ends in the US with a Warning shape: a fifth of the answers there took longer than your latency objective.

Careful: Placing answers needs the GeoIP database (Settings, Query handling, GeoIP), which an admin turns on. WrenDNS does not yet record the address each answer points at, so until it does the view shows only where your upstreams are, labelled as that, not where answers point. Countries are a database's best guess: good for a picture, not for compliance. Failed, blocked and local answers have no location and are counted apart. Docs

Rebinding protection

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

Review what AI agents want to change

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

Rewrites

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

Scheduled failover drills

Failover drill

A drill moves the devices of the nodes you name to a standby for a few minutes, to prove the failover works before you need it.

When: You want the failover tested every month, without someone remembering to do it.

Example: Once a month, the node node-b drills itself at night for two minutes; the Cluster page shows the last report.

Careful: A drill changes where devices get their answers, for a short time. Only admins change the schedule. Docs

See a device's IPv6 addresses

IPv6 addresses

When your router reports IPv6 addresses for a device (UniFi does for connected clients), each one answers AAAA under the device's DNS name and has an ip6.arpa reverse name, by the same rules as the IPv4 address. The Discovered list and a network's device list show them.

When: You reach a device by name over IPv6, or want to check why a name has no AAAA answer.

Example: kitchen-tablet.home.arpa answers A 192.0.2.21 and AAAA 2001:db8:1::21; the reverse lookup of that IPv6 address gives kitchen-tablet.home.arpa.

Careful: Link-local addresses (fe80::) are never published: they're the same on every link. A device that left the network has none, as for IPv4. A device the router knows only by an IPv6 address isn't named yet. Devices rotate privacy addresses, so the list changes as the router's does. A device with more than four addresses publishes the four lowest by value, not the most stable, because the router doesn't say which are temporary. Docs

See every question your devices ask

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: Each filter has a "not" box that flips it to everything except the match (no rcode on Live). The log shows names, not page contents. How long it's kept is set by [telemetry.qlog] retention_days. Docs

See what your network is reaching

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

Seeing real devices

Client IP preservation

WrenDNS 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 WrenDNS'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

Send a domain to another server sent to the server you chose for that domain

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. If that server only knows this domain (it refuses other questions and hands sub-domains to other servers), tick the stub zone box. Limit it with groups (only their devices are sent) and query types (only PTR, say), and leave the DNSSEC box ticked unless the domain is signed or you know why it isn't. Ticking “Only on this node” keeps the route here: the other nodes answer as if it weren't there. Docs

Send an upstream's queries from one address

Source address (bind address)

The address on this node that an upstream's queries leave from. A network such as 198.51.100.0/24 means the address each node holds in it, so one shared upstream works on every node.

When: A DNS filter knows your network by the address its queries come from, or the node sits on several networks and you want one of them.

Example: The family filter is asked from the 198.51.100.x address, so a service that keys on that network sees it.

Careful: The node must hold the address (on a real interface); saving one it doesn't is refused. If it is missing at start or disappears later, only that upstream's queries fail and the health icon says why. Binding an address doesn't pick the interface: add a routing rule for it (see the runbook). In a cluster, name a network, not one node's address. This is not what makes a gateway's content filtering apply: that works on traffic, whatever DNS is used. Docs

Send every query to your own log pipeline

Event sink

A sink copies each query event, as it happens, to a file on this node, a syslog collector or a webhook (Loki, Vector, Splunk, a SIEM). You add, change or remove one here and it applies on every node within seconds, with no restart.

When: You want the query log in your own tooling, or an alert on blocked queries in a SIEM.

Example: A webhook sink to https://logs.example.net/ingest with the token stored as sink.loki.token: events go out in batches of 500, or every 5 seconds, whichever comes first.

Careful: A slow or missing destination never slows DNS: its buffer fills and new events are dropped and counted (wrendns_sink_dropped_total). Names and clients follow the query log's privacy level. A sink the configuration file defines is read-only here, and so are its token file and CA: set those in the file. Docs

Send port 80 to HTTPS

HTTP to HTTPS redirect

When the web UI is served over HTTPS (for example on 443), this opens a second, plain-HTTP listener (for example 0.0.0.0:80) that answers every request with a redirect to the https:// address of the same host and path, and answers the health probes. It serves nothing else.

When: You put the UI on port 443 with [api] tls and want http://host/ to reach it. Leave it empty to keep it off.

Example: Address 0.0.0.0:80 with the UI on 443: typing http://dns.example.com in a browser lands on https://dns.example.com/. With the UI on 8053 the redirect adds the port: https://dns.example.com:8053/.

Careful: Needs [api] tls, and takes effect at the next start (Restart now where the node has a supervisor). Port 80 needs CAP_NET_BIND_SERVICE: the systemd unit has it; in Docker and Kubernetes publish the port yourself. If it can't bind, only a log line says so: DNS and the UI are not affected. A value set in the configuration file wins and locks the control. Docs

Service level

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. The objectives are set on this card (under “Change the objectives”): operators change them, and the files win field by field. Docs

Sets of rules for sets of devices blocked

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

Setting up SNMP on your devices

SNMP setup

Turn SNMP on in your gateway and switches, create a read-only SNMPv3 user (SHA with AES), allow only the DNS host's address, then put the user's password in a file WrenDNS can read and add the agent here.

When: Do this once per device before you add it as an agent. Prefer SNMPv3: a v2c community crosses your network in clear text.

Example: On a UniFi gateway, enable SNMPv3 in the controller's SNMP settings with a user and one password (UniFi uses it for both authentication and privacy), and allow the DNS host's address. Save the password in a file under /run/secrets, add a credential with that file, then add the gateway as an agent and press Test.

Careful: A password lives in a file under the node's secret directories, never in the settings. On Kubernetes outside the host network, devices see the node's address after address translation: allow that address. A v2c host credential tells every device in the subnet the community in clear text. Docs

Several nodes, one configuration

Cluster

A cluster keeps WrenDNS 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 WrenDNS 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

Share what's wrong without sharing yourself

Support package

One file for a bug report: build facts, your settings without secrets, cluster and health, upstreams, a metrics snapshot, and this node's recent log (tick "Every node in the cluster" for each node's own part: every node redacts its own log, and the key map is turned off). At the default level, addresses and names become pseudonyms (device-1, 10.4.7.9) that stay consistent inside the file, and nothing is uploaded: you look it over and attach it yourself.

When: Something broke and a maintainer asks for logs and settings.

Example: A node won't talk to its upstream: the package shows the upstream's state, the warnings from the log, and the settings, with your addresses replaced.

Careful: Log lines are redacted by pattern, which is best effort: read the file before you attach it. The pseudonym map holds your real names; keep it to yourself. Docs

Show queries from several devices

Client filter

Search by a device's name, or by its address, and pick as many devices as you like; the log shows the queries from all of them, and "not" shows every other device.

When: You want one person's phone and laptop together, or everything except the server that asks the most.

Example: Type "tv", pick the living room and bedroom TVs, and the log lists both. Tick "not" to see everything else.

Careful: A device is found by the address it has now (a router name or a Kubernetes workload is followed to its addresses); at most 100 devices and 256 addresses per search. Docs

Signing in when the provider is down

Break-glass sign-in

With local sign-in turned off, an admin can still sign in with a password from the break-glass networks. By default that is this computer only.

When: Only if you turn off password sign-in for your provider (disable_local_login).

Example: Set allowed_admin_networks = ["192.168.1.0/24"] to allow your home network, or leave it out and sign in from the server itself.

Careful: Behind a reverse proxy on the same machine, or published through Docker, your sign-in may come from the proxy or the Docker gateway. Then it is refused unless the proxy is in trusted_proxies or the networks include it. Docs

Simple or Advanced view

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.

SNMP agents

SNMP agent

An SNMP agent is a device WrenDNS may ask what it knows about the network: your gateway's ARP table (which MAC address sits behind each IP address), a switch's forwarding table (which port and VLAN a device is on) and the neighbours each switch port sees. WrenDNS only reads: it sends read requests and has no way to change a setting on the device. It asks every few minutes, one request at a time and no more than 20 a second.

When: Add your gateway to see every device on every VLAN with its MAC address, and your managed switches to see where each device is plugged in. Press Test to see what a device answers before you rely on it: a table the device doesn't answer is skipped, never assumed.

Example: Your gateway answers the ARP table over SNMPv3 but has no switch tables, so Test shows ARP and interfaces answering and the bridge and LLDP tables skipped. Your managed switch answers the forwarding table and LLDP, so it is added as a second agent with its own credential.

Careful: Only a private IPv4 address can be an agent, named by you; the Test button takes the agent's name, never an address. Ports that lead to another switch or the gateway are left out when placing a device, so a device isn't shown on the wrong switch. If a device still answers the default community 'public' once SNMPv3 works, turn that off on the device. Docs

Staged rollouts

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 WrenDNS are never canaries; they get each change after the bake. Docs

Stored secrets reach every full member

Secrets replication

A secret stored in the UI is copied to every full member over the cluster's encrypted channel, and each member re-encrypts it with its own key. This column shows each node's secrets head, the head it has applied from the primary, and how many secrets it can't read.

When: You stored a credential on one node and want to know every node has it, or a node reports a secret it can't read.

Example: The primary's head is 2.14 and the Pi has applied 2.14, so it's in sync. The Pi shows 1 unreadable: its key file was replaced, so enter that secret again on the primary.

Careful: A secret never goes to a resolver pod or a witness, and never to a file or a backup. A 'held' count means the primary couldn't decrypt those secrets to send them, so this node keeps its own copy. Docs

The Cache page

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

The cluster at a glance

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

The device's name

Client name

Shown everywhere instead of the address, including on past queries, and usable in rules ($client='Kids tablet'). It can also match the name your router gave the device ("Also recognize it by its router name"), so it stays matched when the device gets a new address.

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. A router name is in label form (Kitchen Tablet is kitchen-tablet) and matches the address the router gives that name now, after an address, a MAC and any network that holds the device; a group or a quick rule can name it too (Router names, Device by router name). A device picks its own host name, so any device can claim a router name such as kids-ipad, though a network that holds it takes it first. Where it matters, match by MAC or IP address instead. Router names cover IPv4 addresses only. Docs

The machines your nodes run on

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 WrenDNS, 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

The networks your routers know

Network

A LAN or VLAN your router reports, or one this node is directly on: its subnet, DHCP pool, domain and the group that covers it. Devices on it show how full it is.

When: You want to see which networks are filling up, or which networks no group covers yet.

Example: IoT (192.168.20.0/24, VLAN 20): 42 of 254 addresses in use, 38 of them from the DHCP pool.

Careful: Networks come from your routers, from the networks this node is directly on (marked this node: its own LAN and any tagged VLAN interface), and from your groups' networks. A network nothing reports shows as group only. A VLAN reached through the gateway is not on the node, so it shows only if a router reports it. This node means the node answering the API. A replica asks the primary, which reads the routers, for their networks and devices and adds the networks it is directly on; if the primary doesn't answer it shows only its own and says which node didn't. Inside a bridged Docker container there are none (set WRENDNS_HOST_NETWORK=1 on host networking).

The vqlog language

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

This server

System information

Version, uptime, the addresses WrenDNS 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

Trace IDs

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

Trust a console's certificate

Certificate (PEM)

The console's own certificate, fetched with Fetch the console's certificate and trusted with Trust this certificate. It's saved as the text of the certificate chain the console presents, and nothing else is trusted for that router.

When: The router's HTTPS address is refused because its certificate isn't one a public authority signed, which is the normal case for a console.

Example: The console at https://192.168.1.1 presents unifi.local; fetch it, trust it, and the name to check is unifi.local.

Careful: The certificate changes when the console renews it, and the router then fails until the new one is saved. Skipping the check is not offered: anything on the LAN could pose as the console. Docs

Tune the network map's colours and sampling

Map thresholds

The map is drawn from a sample of lookups. Each node samples up to N lookups a second (10 to 2,000), and something is coloured only after it has enough answers (the minimum). It turns Warning when a share of its answers are slow, fail or (for a device) are blocked, and Failing when the failures reach the higher threshold. Idle means too few answers to say.

When: The map is too jumpy or too calm for your network, shows Idle for quiet devices, or says it is sampled 1 in N on a busy network.

Example: A home network with a few chatty devices: leave the defaults. A network with one flaky upstream you accept: raise the failing threshold from 25% to 50% so it stays Warning.

Careful: The preview on the card is an estimate: it reclassifies the flows drawn now, one by one, while the server judges each device or upstream as a whole, so a value right at a threshold can colour differently once applied. The thresholds change only what the map shows, never an answer or an alert (alerts use the service-level objectives). A higher sampling rate costs a little CPU on every node and, above the default, is worth it only on a busy network. Slow means slower than the latency objective unless you set your own. Docs

Turn on the country database

GeoIP database

The world view needs a database that says which country an address is in. It is never bundled: an admin turns it on here, and each node that serves the console then downloads DB-IP's free IP to Country Lite file (about 5 MB, CC BY 4.0) in the background, at most once a day, verifies it and keeps it in the data directory. Nothing is fetched until you turn it on.

When: You want the world view to place answers by country. Use your own HTTPS mirror as the source for a site with no internet access.

Example: Turn it on, press Update now: the state goes Downloading, then Ready with the month and size. A mirror at https://files.example.lan/dbip.csv.gz with its SHA-256 pinned makes the download exactly that file.

Careful: The checks (a size and row count, no overlaps, both address families, the gzip checksum and a pinned digest if you set one) guard against a truncated or tampered-with file; they don't prove who made it. A failed download keeps the old database and shows an error code. Delete database removes the file and nothing is fetched again until you press Update now. Only an admin changes this; everyone sees the status. Docs

Unique names and overlap

List overlap

Unique names are the ones no other list of the same side (block or allow) has, so an exception list never makes a block list look covered. 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 each node started (every node's added up), so a list with no hits after a restart may just be new. Docs

Update lists now

Update now (list refresh)

Downloads every enabled list again right away instead of waiting for its schedule, like Pi-hole's Update Gravity. Each list's row has its own Update now to download just that one. The page shows progress; each list's State says "updating" until its download ends, and Confirmed current shows when the list last downloaded fine.

When: A list maintainer fixed a false positive or added new names, or you just added a list. Use a row's Update now when only one list is in question.

Example: A site broke because of a list entry the maintainer removed this morning: the list's row Update now picks up the fix without waiting a day.

Careful: Unchanged lists cost one small request each, and blocking only changes if a list did. An off list can't be updated until it's on. In a cluster the primary downloads the lists for every node. Agents need the config:write:lists scope. Docs

Username and password for tools

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

Watch questions as they happen

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

What a selection costs

Entry budget

Each blocked name takes about 12 bytes in memory, and a big list also needs memory while it is compiled. The Categories view shows the entries and the memory a selection adds, counting a list shared by several categories once, against the entry budget (Settings, Filtering). A node too small for a selection refuses it and says why.

When: You are choosing categories on a Raspberry Pi or a small container, or choosing a heavy one (newly registered domains, the full threat feed).

Example: Basic is about 275,000 entries, about 3 MiB. Newly registered domains (7 days) is about 2.4 million entries and 40 MB to download every day: it passes the default budget by itself and is refused on a node with 256 MiB or less. Basic needs about 85 MiB by the estimate: a node with 128 MiB refuses it and one with 192 MiB takes it.

Careful: Heavy lists refresh once a day and ask for a confirmation that states the daily download. Raising the budget in Settings lets the view stop warning; it does not give the node more memory. Docs

What a token may do

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

What changed, on every chart

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 being benched or recovering. 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

What each source said

Source record

A source record is what one source said about one thing, kept as it said it: the router's client, the switch's port, Home Assistant's device, the neighbour table's entry, a query the device made, a name in your configuration. Records are matched to the item they describe by MAC address, serial number or a stable device key.

When: Open an item and read its sources side by side when two sources disagree, for example a different name for one laptop.

Example: The router calls a device "anna-laptop", Home Assistant calls it "Anna's MacBook" and mDNS says "macbook.local". All three records are kept; the item shows its best name and each source's own.

Careful: A source that stops reporting a thing doesn't remove it at once: its record is marked absent after two missed reports and removed after a week (imports after 30 days). A record that no source confirms makes an unconfirmed item. Docs

What is this device?

Device identification

A guess at what each address is, from three things WrenDNS 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 WrenDNS: "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: 10.20.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

What runs your pods

Workload

The Kubernetes object that runs a set of pods: a Deployment, StatefulSet, DaemonSet, Job, or CronJob. WrenDNS 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: WrenDNS names each logged query by the workload that held the address at the time. Docs

What would this have done?

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

What's in the cache, and flushing it

DNS cache

WrenDNS 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 your network instead. Each node in a cluster has its own cache. Docs

When a device behaves differently

Anomaly detection

WrenDNS 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

When things happen

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

Where answers come from sent to a public DNS server

Upstreams (forwarders)

The public DNS servers WrenDNS 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. A failing server is benched automatically. Docs

Where category lists come from

Category source

Every category is backed by lists maintained by someone else (HaGeZi, Steven Black, Perflyst, Bon-Appetit). Each row shows the maintainer, the licence and a link; the node downloads the list from the maintainer's own address while a profile uses it, and never bundles or redistributes it.

When: You want to know who maintains a list, how it is licensed, how big it is, or why a category you looked for is not offered.

Example: Adult content is HaGeZi's NSFW list (GPL-3.0). Its Extended size adds the Bon-Appetit list, which is licensed CC BY-SA 4.0 and shows its attribution next to the checkbox.

Careful: A category is offered only when an open, maintained, licensed list backs it. Categories without one are listed under Not available, with the reason, instead of appearing as a checkbox that does nothing. Docs

Where queries go

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

Which filters apply to this device?

A device's effective policy

Every filter and rule that applies to one device, and why: the group it is in, the key that matched it (a MAC, an address, a network, a client ID, a router name), then its lists, blocked services, SafeSearch, rewrites, schedules, quick rules and upstream group, each linking to where it is set.

When: A device is blocked, or not blocked, and you want to know which group, list, schedule or rule is responsible. Or you want to check that the right group took a new device.

Example: The kids' tablet matched by its MAC lands in group kids; its bedtime schedule is in effect now, so every name is blocked until 07:00; a quick rule for game.example ends at 22:00.

Careful: It is read the way a query from the device is matched. A device known only by a MAC that has not been seen at an address has no network, so a network group is not shown for it. Docs

Which nodes hold a stored secret

Secret held by every member

A stored secret is replicated, encrypted, to every full member of the cluster, so the node that becomes the primary can use it (a router's API key keeps working after a failover). This list is the same on every node: for each full member it shows whether it has the secret, can read it, holds an older version, or didn't answer. Only stamps and health are exchanged, never a value or a ciphertext. A resolver pod or a witness holds none, by design.

When: You see the secret on one node and wonder whether the cluster really keeps a copy on the others, or a warning says a member is missing one.

Example: node-a, node-b and node-c each show "has it" with the same stamp for the secret router-key: if node-b is lost, node-a reads the router with its own copy.

Careful: A member that is missing a secret, holds an older one or can't read it raises a warning and a degraded health reason (secret_not_held), never an unhealthy DNS: DNS doesn't use stored secrets. A member that didn't answer is shown as unknown, not as missing. Give it a minute, then check its secrets key. Docs

Which rules this device gets blocked

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

Which server each device uses

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

Which version is running?

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: WrenDNS 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

Who can sign in

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

Who changed what, when

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

Who may ask refused

Access control

Only private networks may query WrenDNS by default; everyone else is refused.

When: Exposing WrenDNS 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

Who may change a credential

Credential rules in forms

Some fields send a password or a token somewhere, or run a program. Only an admin changes those. An operator sees them read-only, with the reason. A value kept on this node isn't shown again: the entry says kept, and changing where it goes means entering the value again.

When: A form shows 'Only an admin can change this', or a saved entry shows 'kept: re-enter to change'.

Example: An alert destination with a stored token: an operator can rename it, but only an admin can change its address or type, because that is where the token goes.

Careful: A change that would send a kept credential to a new address is refused with a message that names the field. Enter the value again if you are the admin, or change the file if the form can't enter it. Docs

Who spent the error budget?

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

Why a provider is inactive on a node

public_url

Each node is opened at its own address, so each node's configuration file sets [auth.oidc] public_url. It makes the redirect URI the provider sends people back to. A node without it can't serve sign-in buttons, so it shows the providers as inactive.

When: A provider's card says Inactive on this node and names public_url.

Example: public_url = "https://dns.example.com" on one node and "http://192.168.1.2:8053" on another, each registered with the provider as <public_url>/api/v1/auth/oidc/<id>/callback.

Careful: It is not shared between nodes and can't be set here: it is part of how the node is reached. Set it in the node's file and reload. Docs

Why was this blocked (or not)? blocked

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

Would have blocked

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 WrenDNS 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

Your sign-in

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