novox/hq
9
0
Fork 0
Code Issues Pull Requests 1 Releases Wiki Activity

ADR 0247: a machine with a VPN client routes names by domain, through a resolver of its own #179

Merged
mesh-admin merged 3 commits from decision/0247-split-dns-on-a-machine-with-a-vpn-client into main 2026-10-07 19:46:08 +00:00
Conversation 1 Commits 3 Files Changed 11
+450 -5
mesh-admin commented 2026-10-07 19:34:16 +00:00
Contributor
Copy Link
Copy Source

Graduates research 033 into ADR 0247 and to-be 50, as the operator approved on 2026-10-07 ("yes, write the split-dns decision and build it").

Decided

  • A node seat node-resolver, held by a new module systemd-resolved, which provides split-dns at the machine's reach. It is installed only where something requires it.
  • Where it is held, it writes /etc/resolv.conf (the machine's private address alone), and the uplink's holder steps back from that file by a controller rule.
  • Verbs routes, route {link, domains, servers}, unroute {link}, served on the mesh and, over a root-only socket, on the machine.
  • Its guard keeps an outside write. It puts its own file back at once when a module took the write, and after 90 s otherwise, so a write nothing handles is still raised by ADR 0241.
  • The forticlient module requires split-dns and carries the adapter.

Differs from research 033's recommendation in who runs it: a module of its own rather than the uplink's two holders, and the VPN module's adapter rather than a declared VPN setting. The interim defer setting is not adopted. The record's options say why.

Also amended: connectivity §2, to-be 48 §10, the seats (26), the glossary (split DNS), and dated pointer notes in ADR 0223 and 0241.

Checks: records, index, cycle and words pass locally.

Code: mesh-controller feat/node-resolver-seat; mesh-catalog feat/systemd-resolved-split-dns, then feat/forticlient-split-dns. ADR 0246 (hq #178) is cited in plain text, not linked, so this PR does not depend on #178's merge order.

Graduates research 033 into **ADR 0247** and **to-be 50**, as the operator approved on 2026-10-07 ("yes, write the split-dns decision and build it"). **Decided** - A node seat `node-resolver`, held by a new module `systemd-resolved`, which provides `split-dns` at the machine's reach. It is installed only where something requires it. - Where it is held, it writes `/etc/resolv.conf` (the machine's private address alone), and the uplink's holder steps back from that file by a controller rule. - Verbs `routes`, `route {link, domains, servers}`, `unroute {link}`, served on the mesh and, over a root-only socket, on the machine. - Its guard keeps an outside write. It puts its own file back at once when a module took the write, and after 90 s otherwise, so a write nothing handles is still raised by ADR 0241. - The `forticlient` module requires `split-dns` and carries the adapter. **Differs from research 033's recommendation** in who runs it: a module of its own rather than the uplink's two holders, and the VPN module's adapter rather than a declared VPN setting. The interim *defer* setting is not adopted. The record's options say why. **Also amended:** connectivity §2, to-be 48 §10, the seats (26), the glossary (split DNS), and dated pointer notes in ADR 0223 and 0241. Checks: records, index, cycle and words pass locally. Code: mesh-controller `feat/node-resolver-seat`; mesh-catalog `feat/systemd-resolved-split-dns`, then `feat/forticlient-split-dns`. ADR 0246 (hq #178) is cited in plain text, not linked, so this PR does not depend on #178's merge order.
mesh-admin added 1 commit 2026-10-07 19:34:16 +00:00
ADR 0247: a machine with a VPN client routes names by domain, through a resolver of its own
mesh/merge-gate pass: the change touches no module of the mesh's graph
Details
mesh/repo-check pass: its merge-check.sh passed
Details
mesh/delivery superseded: a newer head of the same pull request
Details
478a198e9a 
Research 033 measured the laptop's VPN client and the mesh overwriting each
other's resolver file in nine of nine sessions, each time cutting off one
kind of name. The operator chose a resolver module on a node seat of its
own, installed only where something requires split-dns, with the VPN
client's module carrying the adapter. Graduates research 033 into to-be 50,
and amends connectivity §2, to-be 48 §10, the seats and the glossary.
mesh-admin commented 2026-10-07 19:34:33 +00:00
Author
Contributor
Copy Link
Copy Source

Delivery novox/hq@6373ca815b23 — delivered since 2026-10-07T19:46:27Z

Delivery plan — builds nothing: the change touches no module of the mesh's graph

Transitions

  • 2026-10-07 19:35 (new) → proposed (announced): novox/hq#179's head announced
  • 2026-10-07 19:36 proposed → checked (checked): the verdict names this commit
  • 2026-10-07 19:36 checked → ready (accepted): the gate passed or warned, and the repository's own check did not fail
  • 2026-10-07 19:46 ready → published (merged): on the trunk its modules follow: merged there, and its walk opened — or nothing for a walk to move
  • 2026-10-07 19:46 published → delivered (done): nothing for a walk to move

The commit's note under refs/notes/mesh-plan keeps every transition: git log --notes=mesh-plan.

<!-- mesh-delivery:view --> **Delivery** `novox/hq@6373ca815b23` — **delivered** since 2026-10-07T19:46:27Z **Delivery plan** — builds nothing: the change touches no module of the mesh's graph **Transitions** - 2026-10-07 19:35 (new) → proposed (announced): novox/hq#179's head announced - 2026-10-07 19:36 proposed → checked (checked): the verdict names this commit - 2026-10-07 19:36 checked → ready (accepted): the gate passed or warned, and the repository's own check did not fail - 2026-10-07 19:46 ready → published (merged): on the trunk its modules follow: merged there, and its walk opened — or nothing for a walk to move - 2026-10-07 19:46 published → delivered (done): nothing for a walk to move The commit's note under `refs/notes/mesh-plan` keeps every transition: `git log --notes=mesh-plan`.
jschoubben added 1 commit 2026-10-07 19:35:24 +00:00
ADR 0247: say what is to confirm live about resolved and the resolver file, not a guess
mesh/delivery superseded: a newer head of the same pull request
Details
mesh/merge-gate pass: the change touches no module of the mesh's graph
Details
mesh/repo-check pass: its merge-check.sh passed
Details
7e9d0dfe7b
jschoubben added 1 commit 2026-10-07 19:35:44 +00:00
ADR 0247: say exactly where the VPN's domains go and do not
mesh/merge-gate pass: the change touches no module of the mesh's graph
Details
mesh/repo-check pass: its merge-check.sh passed
Details
mesh/delivery delivered
Details
6373ca815b
mesh-admin merged commit dda850863f into main 2026-10-07 19:46:08 +00:00
mesh-admin deleted branch decision/0247-split-dns-on-a-machine-with-a-vpn-client 2026-10-07 19:46:09 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
mesh/ready
Reviewed and ready: mesh-delivery merges at the marked head once its checks pass (hq ADR 0364)
No labels
Milestone
No items
No Milestone
Assignees
Clear assignees
agent-ace agent-g14 agent-novox agent-shanks jschoubben mesh-tools miel.truyen nox-agent
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: novox/hq#179