Design: per-leg DNS blocklists on the resolver pair
Context
Section titled “Context”docs/reference/network.md is the addressing authority for every leg. This change allocates no
address or prefix.
Observed in the repository and on the estate on 2026-09-29:
- The main Blocky instance has a
blocking:section that hides the internal namespace from untrusted sources. It has two groups:internal-namespace, with an inline list offzymgc.houseand the reverse zones, andtrusted-clients, which is empty.clientGroupsBlockmapsdefaultto[internal-namespace]and maps each trusted leg’s IPv4 and ULA/64CIDR to[trusted-clients]. It also maps three extra keys to[trusted-clients]: the appliance192.168.20.1, the tailnet100.64.0.0/10and the health client127.0.0.1(roles/blocky/templates/blocky-config.yml.j2,roles/blocky/defaults/main.yml). blocky-publichas noblocking:section and nolog:section. Its verify criterion PUB-01 fails the play when a top-level key outside an allowed set appears. Its query rows reach the journal as text, and the collector parses only theblocky.servicerows.loading.strategyisblocking, so the inline internal-namespace list is in force before the first answer. No list is downloaded today.- Blocky is pinned at 0.35.0. It exits on SIGHUP, so no refresh can rely on a reload.
- Each resolver node has 4 GB of memory, about 3.3 GB available, and runs both instances.
- The Firewalla sees no ordinary client query. A client sends its queries to the on-link leg VIP,
and Blocky sends its upstream queries to Control D over DoT. The Firewalla redirects only a
query sent to another resolver, and it forwards that query to the pair from
192.168.20.1. - The Firewalla’s DNS block rules that move:
oisd(target list of 56,908 entries, 15.8 million hits),crypto_nl(the Firewalla reports 23,720 entries, but its source URL holds about 1,280 today), and four single-domain rules. Thenrdlist and the device-group category rules do not move (see proposal.md). The Firewalla’s fence rules (intranet,internet) are not DNS rules, and the gateway change owns them.
Goals / Non-Goals
Section titled “Goals / Non-Goals”Goals:
- One inventory value per leg decides which list groups its clients get.
- The list tier never weakens the internal-namespace rules.
- Both instances record blocks in one queryable shape.
Non-Goals:
- Per-device blocking. Blocky keys on the leg, never on one device.
- Control D profile changes. The Control D profile keeps its own filtering as it is.
- The Firewalla fence rules.
Decisions
Section titled “Decisions”D1: Each leg declares blocky_list_groups
Section titled “D1: Each leg declares blocky_list_groups”Each dns_vlan_interfaces entry gains blocky_list_groups, a list of group names, for example
[oisd, crypto, domains]. Both host_vars files carry the same value for a leg, as they do for
kea_pool. blocky_default_list_groups in the role defaults holds the groups for default.
The templates render each leg’s two CIDR keys from the leg’s value. The main instance renders the
trusted legs, and blocky-public renders Guest and Telework. The groups themselves are defined
once, in blocky_list_sources in the role defaults, as a map from group name to its sources. A
leg that names an undefined group fails the render under StrictUndefined.
Alternative: one estate-wide list set in the role defaults. Rejected by Sean on 2026-09-29. It makes a per-leg difference a template change instead of an inventory value.
Alternative: key on client names from Kea’s leases. Rejected. A name is a client claim, and the leg CIDR is a fact of the network.
D2: Every key names its full group set
Section titled “D2: Every key names its full group set”Blocky’s documentation does not state what clientGroupsBlock does when a client matches more
than one key. The design does not depend on it:
- A trusted leg key maps to
trusted-clientsplus the leg’s list groups. defaultmaps tointernal-namespaceplusblocky_default_list_groups.- The three extra keys map to
trusted-clientsplusblocky_default_list_groups. The appliance address lies inside Main’s CIDR, so its key and Main’s key both match it. Both keys name the same list groups today, so either rule gives the same answer.
The main instance listens only on the trusted legs, so it renders no key for Guest or Telework.
blocky-public renders those two legs’ keys, each naming the leg’s list groups, and default
with the default groups. It knows no internal name, so it has no internal-namespace group. A
leg that declares no lists names an empty group, no-lists, because an empty list under
clientGroupsBlock falls through to default.
D3: The owned zones are an allowlist on every list group
Section titled “D3: The owned zones are an allowlist on every list group”Blocky applies an allowlist per group, and a group that has an allowlist and no denylist blocks
every name that is not on the allowlist. So every list group gets the same inline allowlist of
the owned zones (fzymgc.house, holomush.dev, fzymgc.net, hl-assets.dev, each with its
wildcard), and no group has an allowlist alone. internal-namespace gets no allowlist, so its
behaviour does not change.
D4: Sources and loading
Section titled “D4: Sources and loading”oisd: oisd small,https://small.oisd.nl/domainswild. Each line is*.<domain>, which blocks the domain and every subdomain.crypto:https://blocklistproject.github.io/Lists/alt-version/crypto-nl.txt, the source of the Firewalla’scrypto_nl.domains: an inline list ofmoltbook.com,etrack05.com,video-loop-hero.no-plans.comanddhysjggxbupogifgdhje.supabase.co.
loading.strategy stays blocking, so the internal-namespace list is in force before the first
answer. A download that fails leaves only its own group empty. loading.downloads bounds each
download at 30 seconds and 3 attempts, so a start with no internet waits at most a few minutes on
one node. The other node keeps its VIPs during that time. loading.refreshPeriod is 6 hours,
which reloads each list four times a day in the running process.
D5: blocky-public logs JSON, and the collector parses it
Section titled “D5: blocky-public logs JSON, and the collector parses it”blocky-public gains log.format: json and the same blocking: shape. PUB-01’s allowed set
grows by blocking and log. The collector’s parse stage matches blocky-public.service as well
as blocky.service, so both produce the same LogAttributes, and ServiceName tells them
apart. The row filter that hides Blocky rows from the MCP users covers the new rows too.
D6: Verify reads the rendered file and the live metric
Section titled “D6: Verify reads the rendered file and the live metric”The blocky verify block asserts that each rendered leg key names the groups its leg declares,
and that each list group reports a non-zero entry count in the instance’s own metrics after a
start. The molecule scenario covers the per-leg difference and the unreachable source, as the
spec states.
D7: The Firewalla gets no change
Section titled “D7: The Firewalla gets no change”The Firewalla’s DNS block rules stay as they are. A query that the Firewalla redirects reaches
Blocky from 192.168.20.1, and D2 gives that key the default lists, so Blocky blocks it too.
Pausing the rules would change no answer. The nrd list and the category rules stop when the box
goes, which is when Sean’s decision to drop them takes effect. firewalla-teardown removes the
rules with the box.
Alternative: pause the rules after the pair shows blocks. Rejected. It is an operator action that changes no answer.
Risks / Trade-offs
Section titled “Risks / Trade-offs”- [A list blocks a name someone needs] → The runbook section shows how to find the block row in ClickStack and which list holds the name. The fix is a per-leg change or an allowlist entry.
- [A download fails at start with no internet] → D4 bounds the wait, and one node restarts at a time.
- [A list grows until memory is short] → oisd small and the crypto list hold about 80,000 entries together. Verify reads the entry counts, and the runbook names the node memory as the limit for any new list.
Migration Plan
Section titled “Migration Plan”- The pull request lands the per-leg lists, the JSON log, the collector change and the runbook section on the lists.
- Converge one node at a time, the node that holds no VIP first:
scripts/dns-playbook.sh --limit <node> --tags blocky,dns-otel-collector. - Run the acceptance checks of the spec from Main and from a Guest throwaway client.
Rollback: revert the pull request, then run
scripts/dns-playbook.sh --limit <node> --tags blocky,dns-otel-collector on each node, one at a
time.