Skip to content

Design: per-leg DNS blocklists on the resolver pair

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 of fzymgc.house and the reverse zones, and trusted-clients, which is empty. clientGroupsBlock maps default to [internal-namespace] and maps each trusted leg’s IPv4 and ULA /64 CIDR to [trusted-clients]. It also maps three extra keys to [trusted-clients]: the appliance 192.168.20.1, the tailnet 100.64.0.0/10 and the health client 127.0.0.1 (roles/blocky/templates/blocky-config.yml.j2, roles/blocky/defaults/main.yml).
  • blocky-public has no blocking: section and no log: 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 the blocky.service rows.
  • loading.strategy is blocking, 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. The nrd list 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:

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

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.

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-clients plus the leg’s list groups.
  • default maps to internal-namespace plus blocky_default_list_groups.
  • The three extra keys map to trusted-clients plus blocky_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.

  • 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’s crypto_nl.
  • domains: an inline list of moltbook.com, etrack05.com, video-loop-hero.no-plans.com and dhysjggxbupogifgdhje.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.

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.

  • [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.
  1. The pull request lands the per-leg lists, the JSON log, the collector change and the runbook section on the lists.
  2. Converge one node at a time, the node that holds no VIP first: scripts/dns-playbook.sh --limit <node> --tags blocky,dns-otel-collector.
  3. 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.