Design: dns-control block entries and allow entries
Context
Section titled “Context”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-controlholds 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 workflowchange.apply. The unique indexchange_audit_one_pendingallows one pending change, so one change runs at a time. The subject of a change is a Go string constant (entry,zone,rrset,batchininternal/change/store.go), and a CHECK constraint onchange_plansandchange_auditholds the same list.- Most switches on the subject fall through to
entryin theirdefaultbranch. A new subject that one switch misses runs the entry path with no error. ChangeWorkflowwrites pdns and then, for an entry with a reservation, callsnode.reservation_writeon each node.nodeOrderputs 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.stepsholds 8 steps at most.- The node worker already has
node.list_write. It writes/var/lib/dns-worker/lists/operator-denylist.txtwith a temporary file, mode0644and a rename. It refuses a wildcard entry, and nothing calls it.node.list_refreshposts/api/lists/refreshto both Blocky instances. - The node worker runs as
dns-workerand is pinned apart from dns-control:dns_node_worker_versionis0.14.0and dns-control runs0.17.0. A new node activity is in force only after a converge of thedns-node-workerrole on each node. /var/lib/dns-workeris the StateDirectory of the worker unit, mode0755. Blocky runs asblockyunderProtectSystem=strict, which makes the path read-only and leaves it readable.- The main Blocky instance names its full group set on every
clientGroupsBlockkey:default, the IPv4 and ULA key of each trusted leg, the tailnet CIDR100.64.0.0/10and the health client127.0.0.1. The keepalived health check of the trusted legs queriesdns-health.fzymgc.house.blockTTLis 30 seconds. - The export writes
entries.json,zones.jsonand 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 / Non-Goals
Section titled “Goals / Non-Goals”Goals:
- One plan and one apply put a list entry in force on both nodes within one minute.
- A list change never reads
succeededunless 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-publicdoes 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_totalgets the label valueblock. - 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.
Decisions
Section titled “Decisions”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.
2. The name is the line of the file
Section titled “2. The name is the line of the file”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.
3. The names that a plan refuses
Section titled “3. The names that a plan refuses”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.
5. The wire contract of node.list_write
Section titled “5. The wire contract of node.list_write”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. Underallowlists:, the sources are the path of the allow file and the inline list ofblocky_list_allowlistandblocky_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
clientGroupsBlockkey of the main instance names the group:default, both keys of each trusted leg and each entry ofblocky_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_pathandblocky_operator_allowlist_pathand restate the constants of the worker. templates/blocky-public-config.yml.j2does 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.
9. The workflow branch
Section titled “9. The workflow branch”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.
11. The surfaces
Section titled “11. The surfaces”| 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.
12. The export adds blocks.json
Section titled “12. The export adds blocks.json”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.
13. One migration
Section titled “13. One migration”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
BlockyControlinterface, the workflow branch in the Temporal test suite, each subject switch of decision 4 and the bytes ofblocks.json. - The store and the migration run against Postgres in a testcontainer, behind the
integrationbuild 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
digcommands of the specs.
Risks / Trade-offs
Section titled “Risks / Trade-offs”-
[A refresh reloads every group, so a public list source that is down or slow fails the refresh] → The change reads
failedwithlist_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) ordns_refresh_listsputs 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
blockruns 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
failedstep. 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.txtcurl -fsS -X POST http://127.0.0.1:4000/api/lists/refreshThe 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
blockaudit 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] →
blockTTLis 30 seconds, so the device asks again within 30 seconds.
Migration Plan
Section titled “Migration Plan”The pull requests follow the proposal. Each one is one converge, one release or one sync.
- The roles. The
dns-node-workerrole creates the directory and seeds both files (decision 8), and theblockyrole adds the operator group (decision 7). On the node that holds no VIP, runscripts/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.comreadsNXDOMAINanddig +short @<Main address> example.orgprints an address. Rollback: revert the pull request and runscripts/dns-playbook.sh --limit <node> --tags blockyon each node, the node that holds no VIP first. The seeded files can stay. - The code of dns-control and the node worker, with a changie fragment and the runbook. No deployment.
- The release, through
scripts/release.sh dns-control(docs/operations/releases.md). Rollback: none needed, because a release changes no running process. - The worker pin. Set
dns_node_worker_versionto the new version. Runscripts/dns-playbook.sh --limit <node> --tags dns-node-workerand then--tags dns-node-worker-verifyon 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. - The dns-control pin. Set the new version and digest in
argocd/app-configs/dns-control/deployment.yamlandargocd/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.