Skip to content

Design: dns-control block entries and allow entries

See openspec/changes/archive/2026-10-08-dns-control-block-entries/proposal.md for the reason, the two spikes of 2026-10-05 and the scope. The specs are openspec/specs/dns-operator-list/spec.md and openspec/specs/dns-blocklists/spec.md.

A list entry is a block entry or an allow entry. This design uses that term in the API, the store and the docs. The UI keeps the sidebar label “Block rules”, which the change dns-control-ui-rev reserved for this screen.

The parts of the estate that this design touches:

  • apps/dns-control holds curated host entries, zones and record sets. Every write is a stored plan and one apply. The apply writes the row and a pending audit row in one transaction and starts the Temporal workflow change.apply. The unique index change_audit_one_pending allows one pending change, so one change runs at a time. The subject of a change is a Go string constant (entry, zone, rrset, batch in internal/change/store.go), and a CHECK constraint on change_plans and change_audit holds the same list.
  • Most switches on the subject fall through to entry in their default branch. A new subject that one switch misses runs the entry path with no error.
  • ChangeWorkflow writes pdns and then, for an entry with a reservation, calls node.reservation_write on each node. nodeOrder puts the node that holds no VIP first. With no single VIP holder, the order of the leg file stands. A node activity runs once, and a failed node stops the write to the next node. Final.steps holds 8 steps at most.
  • The node worker already has node.list_write. It writes /var/lib/dns-worker/lists/operator-denylist.txt with a temporary file, mode 0644 and a rename. It refuses a wildcard entry, and nothing calls it. node.list_refresh posts /api/lists/refresh to both Blocky instances.
  • The node worker runs as dns-worker and is pinned apart from dns-control: dns_node_worker_version is 0.14.0 and dns-control runs 0.17.0. A new node activity is in force only after a converge of the dns-node-worker role on each node.
  • /var/lib/dns-worker is the StateDirectory of the worker unit, mode 0755. Blocky runs as blocky under ProtectSystem=strict, which makes the path read-only and leaves it readable.
  • The main Blocky instance names its full group set on every clientGroupsBlock key: default, the IPv4 and ULA key of each trusted leg, the tailnet CIDR 100.64.0.0/10 and the health client 127.0.0.1. The keepalived health check of the trusted legs queries dns-health.fzymgc.house. blockTTL is 30 seconds.
  • The export writes entries.json, zones.json and one audit object to the NAS bucket and to the B2 bucket after each change, and skips an object whose bytes the sink already holds.

docs/reference/network.md is the authority for the addresses that the specs use: the Main VIP 192.168.20.5 with sandiego .20.6 and portland .20.7, the Guest VIP 192.168.79.5 and the Lab VIP 192.168.200.5. This change allocates no address and no prefix. No Terraform resource changes, so no full-replace API is in scope.

Goals:

  • One plan and one apply put a list entry in force on both nodes within one minute.
  • A list change never reads succeeded unless both nodes wrote both files and Blocky reread them.
  • The entries stay in force while dns-control, k3s or Temporal is down.
  • A rebuilt node or a failed write recovers with one projection.

Non-Goals:

  • blocky-public does not read the list entries. Guest and Telework keep the public lists alone.
  • The 9 excepted names and the owned zones stay in the Ansible role.
  • No new alert. The metric dns_control_change_applies_total gets the label value block.
  • No per-leg entry. Every client of the main instance gets the same entries.
  • No drift reading of the operator files. A projection is the repair.

1. One table and one subject for both kinds

Section titled “1. One table and one subject for both kinds”

The store holds a table list_entries with the columns name (the primary key), kind (block or allow), reason, actor, change_id and updated_at. One change subject, block, covers both kinds. The plan carries the name in subject_key, and key stays empty, as the constraint change_plans_key_check requires for a subject other than entry.

The node write always carries both files, so one subject gives one workflow branch and one value of the metric label. A separate subject allow was rejected, because it would run the same branch under a second name.

The reason is required and holds 1 to 256 characters. The actor is the user name of the caller, or the client id of an agent, from the plan. The apply writes it.

The name uses the notation of Blocky and of the HaGeZi wildcard lists: example.org matches that name only, and *.example.org matches that name and every name under it. The stored name is the line that the worker writes. The role already uses the same notation in blocky_list_excepted_names.

A boolean field such as subdomains was rejected. It adds a field that every surface must render, and the stored name would then differ from the line in the file.

example.org and *.example.org are two names, so they are two rows.

A plan refuses these names before it stores anything:

Name Answer
Not a host name of 2 to 127 labels with an optional leading *. invalid on the field name
A name that holds a row of either kind invalid on the field name
A name that is a zone of the zone store, is in such a zone, or is a wildcard whose base is a parent of such a zone write_policy with the zone
The 10,001st entry of one kind invalid on the field name

The zone rule protects two things. A block entry under fzymgc.house would fail the health check of the trusted legs on both nodes at once and move no VIP. An allow entry there would unblock the internal namespace for a client on no trusted leg, because an allow in one Blocky group beats a block in another group (spike of 2026-10-05). The rule reads the zone store, so a new zone is covered with no code change.

dns-control does not hold the owned public zones (holomush.dev, fzymgc.net, hl-assets.dev) or the excepted names. Decision 7 allows them in the operator group, so a block entry for one of them is stored and has no effect. The runbook says so.

The limit of 10,000 is the wire limit of ListWriteInput.

The apply checks the zone rule and the limit again inside its transaction, as the apply of a host entry checks its lane rule again. A zone or another entry can land between the plan and the apply.

dns-control and the node worker check a name with one function, nodeops.NormalizeListEntry. Both sides already import the contract package nodeops, so a name that dns-control stores is always a line that the worker accepts.

4. Every switch on the subject names block

Section titled “4. Every switch on the subject names block”

The constant SubjectBlock = "block" gets an explicit case in each switch whose default is the entry path: the encode and decode of the two sides, the subject name and the names column, Store.Apply, RoleForPlan, Project, LoadChange and PdnsWrite. PdnsWrite refuses a list change with a non-retryable error, because the workflow never runs it for one. The REST filter of GET /api/changes and the MCP schema text name block too.

Four places need no case. The ledger matches on the sides that are set, so a list change gives no record. The finalize revert acts on a batch only. The list filter of the store takes any subject. The CLI restore builds steps for an entry, a zone and a record set only.

A test for each switch feeds the subject block and fails when the entry path runs. Changing every default branch to an error was rejected for this change. It touches every subject, and it belongs to its own change.

The activity keeps its name. Its messages in proto/dnscontrol/nodeops/v1/actions.proto gain fields:

Message Field Number Rule
ListWriteInput entries (the block list, unchanged) 1 10,000 items, 253 characters each
ListWriteInput allow_entries 2 10,000 items, 253 characters each
ListWriteResult allow_path 5 4,096 characters
ListWriteResult allow_entries 6 0 or more
ListWriteResult allow_sha256 7 lower-case hex or empty
ListWriteResult refresh 8 ActionResult, absent when no refresh ran

The field entries keeps its name, because a rename changes the JSON form of the payload.

A worker of 0.14.0 ignores field 2, writes the block file only and returns a succeeded result with no refresh. The workflow treats a succeeded result with no refresh as an invalid result, so the step reads failed. A worker of 0.14.0 also refuses an entry with *. as invalid_list_entry. A skipped allow file or a skipped refresh therefore never reads as success.

refresh is not a required field. A worker that refuses or fails a write runs no refresh, and a required field would make it invent one.

A new activity name was rejected. It gives the same loud failure with more churn, and the old name has no caller. A second activity call to node.list_refresh after the write was rejected too. That activity refreshes blocky-public, which reads no operator file, and it doubles the steps of a change.

6. The worker writes both files and then refreshes the main instance

Section titled “6. The worker writes both files and then refreshes the main instance”

The activity first makes sure that every entry of both lists is valid. A valid entry can start with one *.. One invalid entry refuses the whole write with invalid_list_entry and leaves both files unchanged.

The activity then writes both new files in full as temporary files in the same directory, and only then renames each one over its old file. A failed write of either file leaves both old files in place. Each file gets mode 0644 on the temporary file before the rename, so the umask does not change it. Each file starts with a fixed header and holds one sorted, unique name per line, so the same set gives the same bytes. The new path is OperatorAllowListPath = /var/lib/dns-worker/lists/operator-allowlist.txt in internal/nodeops.

After both writes, the activity posts /api/lists/refresh to the main instance at 127.0.0.1:4000 only. A 2xx status sets refresh to succeeded. Any other status, a timeout or a refused connection sets the step to failed with the new reason list_refresh_failed and the status in the detail. The detail never carries the response body, as HTTPBlocky.post does today. The call keeps the control timeout of 30 seconds, under the start-to-close timeout of 60 seconds.

When a write fails, the activity returns failed and does not refresh. Blocky then keeps the entries that it read last, as the spike measured.

7. The Blocky role adds the operator group

Section titled “7. The Blocky role adds the operator group”

roles/blocky adds one group, operator, to the main instance only:

  • Under denylists:, the source is the path of the block file. Under allowlists:, the sources are the path of the allow file and the inline list of blocky_list_allowlist and blocky_list_excepted_names. Every list group of the role already carries that inline list.
  • The group always declares its denylist, also when the file is empty. A group with an allowlist and no denylist blocks every other name.
  • Every clientGroupsBlock key of the main instance names the group: default, both keys of each trusted leg and each entry of blocky_extra_trusted_clients. The health client gets the group too, and decision 3 keeps its name out of reach.
  • A source string with no newline is a file path for Blocky, so each path is a quoted string. The paths sit in blocky_operator_denylist_path and blocky_operator_allowlist_path and restate the constants of the worker.
  • templates/blocky-public-config.yml.j2 does not change.

8. The dns-node-worker role creates the directory and seeds the files

Section titled “8. The dns-node-worker role creates the directory and seeds the files”

The proposal put the seed in the blocky role. It moves to the dns-node-worker role, which owns the user.

On the live nodes, /var/lib/dns-worker already belongs to dns-worker. systemd re-owns the tree of a StateDirectory only when the top directory has the wrong owner. A lists/ directory that a root task creates would therefore stay root’s, and every write of the worker would fail. The Kea role met the same trap with /var/lib/dns-worker/kea (pull request #2570).

The role creates /var/lib/dns-worker/lists with owner dns-worker and mode 0755. It writes each operator file with the header alone, owner dns-worker, mode 0644 and force: false, so a file that exists belongs to the worker and a converge never writes its entries.

The dns-node-worker-verify tag makes sure that each file exists with mode 0644 and owner dns-worker, and reads each file as the user blocky. A read as root proves only what root can read.

On a fresh node the blocky play runs before the dns-node-worker play. Blocky then starts with no operator file, logs a failed source and loads an empty group. It reads the files at its next refresh. A fresh node has no entries until a projection anyway.

The seed is empty, not read from the export as the Kea role does. A node with no reservation file hands out wrong addresses, so Kea must seed from the export. An empty operator list blocks less and allows less, and one projection repairs it. The rebuild procedure of the runbook gains that projection.

ChangeRequest in proto/dnscontrol/change/v1/change.proto gains bool lists. LoadChange sets it for the subject block. When it is set, applySteps does not run PdnsWrite. It runs the new control activity change.load_lists, which returns the whole current set as two sorted lists, and then node.list_write on each node in the order of nodeOrder. The step name is list_write. A failed node stops the write to the next node with previous_node_failed, as the reservation write does.

The activity reads the store when it runs, not the plan. One change runs at a time, so the store then holds the result of this change. The whole set goes to each node, because the file is the whole set and the worker holds no earlier state.

A workflow that started before the release has lists false and runs the same commands on a replay, so the branch needs no workflow.GetVersion.

With no single VIP holder, the order of the leg file stands, as for the reservation write. A list write moves no VIP, so a refusal like the one of the ops actions is not needed.

10. A projection is one unchanged change of the whole set

Section titled “10. A projection is one unchanged change of the whole set”

Project gains case SubjectBlock. It stores one plan with the subject block, the subject key all and the whole set as both sides. The constraint change_plans_subject_key_check refuses an empty key, and no list entry can take all, because a name holds two labels at least. Its apply changes no row and runs the workflow branch of decision 9. This works with an empty store, which writes two files with the header alone.

A projection of each entry was rejected. Each entry change writes the whole set and refreshes Blocky twice, so 50 entries would cost 100 refreshes.

Surface Read Write
REST GET /api/list-entries (dns-reader) POST /api/list-entries/plan with op (create or delete), name, kind and reason. Apply through POST /api/changes/apply. Project through POST /api/changes/project with subject: block (dns-writer)
MCP dns_list_list_entries dns_create_list_entry (name, kind, reason), dns_delete_list_entry (name), apply through dns_apply_change, project through dns_project_entries with the subject block
UI The Block rules screen lists every entry with its name, kind, reason, actor and time A writer gets a create dialog and a delete action. Both use the plan, diff and apply steps of EntryDialog

RoleForPlan names dns-writer for the subject block, as it does for an entry. A change of an entry’s kind or reason is a delete and a create. The store supports change for the projection, and no surface offers it.

The UI screen follows dns-control-web-ui: a table from 768 pixels and cards below, one status bar, and the hash route #/blocks. The sidebar item loses its “Soon” badge. The Changes screen lists a list change with the name in its row.

blocks.json is {"version": 1, "entries": [{"name", "kind", "reason"}]} sorted by name. It leaves out the actor, the change id and the time, so its bytes depend on the set alone, as entries.json does. The audit object of each change carries the actor and both sides.

The export sink writes it beside the two other objects with the same skip rule. The work touches SinkClient.Write, Written, ExportSinkResult in change.proto, and two new columns of change_exports: blocks_sha256 and blocks_version_id.

internal/audit/migrations/00008_list_entries.sql creates list_entries, adds block to the subject CHECK constraints of change_plans and change_audit, and adds the two columns of change_exports. Every part is additive, so the release before this change runs on the migrated database.

14. The tests stay on the code that this repository owns

Section titled “14. The tests stay on the code that this repository owns”
  • Unit tests cover the name rule and the zone rule, the rendering of a list file, the worker activity with a fake of the BlockyControl interface, the workflow branch in the Temporal test suite, each subject switch of decision 4 and the bytes of blocks.json.
  • The store and the migration run against Postgres in a testcontainer, behind the integration build tag.
  • No molecule scenario covers the operator group. The template adds a group name to every key in a loop, and a loop is not a filter that this repository wrote. The estate proof is the dig commands of the specs.
  • [A refresh reloads every group, so a public list source that is down or slow fails the refresh] → The change reads failed with list_refresh_failed, also when Blocky read both operator files. Three download attempts of 30 seconds each can also run past the control timeout of 30 seconds. The files stay on disk, so the next scheduled refresh (every 6 hours) or dns_refresh_lists puts them in force. A projection after the source recovers gives a clean change row.

  • [A refresh rebuilds every list in memory] → It refreshes the main instance only. It takes about 3 seconds with Pro++ and TIF medium. An ops refresh holds another lock and can run beside a change, which doubles the peak for those seconds. On 2026-10-05 each node had about 3.3 GiB free before TIF medium, and the change that added TIF medium put its cost at about 560 MiB.

  • [A switch that misses block runs the entry path] → Decision 4: an explicit case and a test for each switch.

  • [A node runs worker 0.14.0 when dns-control sends the new input] → Decision 5 turns it into a failed step. The worker pin merges and converges before the dns-control pin.

  • [A block entry for an owned public zone or an excepted name has no effect] → The spec states it, the runbook says so, and the entry is in the export like any other.

  • [A node that does not answer stops every list change] → This is the rule of the reservation write. Bring the node back, then project.

  • [A failed write leaves the two nodes or the two files out of step] → Both files are written in full before either rename, so only a failed rename can leave one new file and one old file. The store holds the truth, and a projection writes both nodes again.

  • [dns-control is down and an entry must go now] → Break glass on each node, the node that holds no VIP first:

    Terminal window
    sudo install -o dns-worker -g dns-worker -m 0644 /tmp/operator-denylist.txt \
    /var/lib/dns-worker/lists/operator-denylist.txt
    curl -fsS -X POST http://127.0.0.1:4000/api/lists/refresh

    The next change or projection writes the file from the store again. Make the same change in dns-control when it is back.

  • [The dns-control pin rolls back after a list change] → The release before this change reads a block audit row as an entry when it lists changes. The rows are append-only, so the fix is to roll forward.

  • [A device cached the block answer of a name that is now allowed] → blockTTL is 30 seconds, so the device asks again within 30 seconds.

The pull requests follow the proposal. Each one is one converge, one release or one sync.

  1. The roles. The dns-node-worker role creates the directory and seeds both files (decision 8), and the blocky role adds the operator group (decision 7). On the node that holds no VIP, run scripts/dns-playbook.sh --limit <node> --tags dns-node-worker, then --tags blocky, then --tags dns-node-worker-verify,blocky-verify. Repeat on the other node in a later window. Proof on each node: dig @<Main address> googlesyndication.com reads NXDOMAIN and dig +short @<Main address> example.org prints an address. Rollback: revert the pull request and run scripts/dns-playbook.sh --limit <node> --tags blocky on each node, the node that holds no VIP first. The seeded files can stay.
  2. The code of dns-control and the node worker, with a changie fragment and the runbook. No deployment.
  3. The release, through scripts/release.sh dns-control (docs/operations/releases.md). Rollback: none needed, because a release changes no running process.
  4. The worker pin. Set dns_node_worker_version to the new version. Run scripts/dns-playbook.sh --limit <node> --tags dns-node-worker and then --tags dns-node-worker-verify on the node that holds no VIP, then on the other node in a later window. Rollback: revert the pin and run the same two commands on each node.
  5. The dns-control pin. Set the new version and digest in argocd/app-configs/dns-control/deployment.yaml and argocd/app-configs/external-dns/values.yaml. ArgoCD rolls dns-control, and the migration runs at the start. Rollback: revert the pull request, and ArgoCD rolls back. The migration stays, because the earlier release runs on it.

After pull request 5, run the acceptance of the proposal: a block entry for example.org and an allow entry for api2.amplitude.com, each read at the Lab VIP within one minute, and then the delete of both.