4.2 KiB
topic, status, date, deciders, reconstructed, extends
| topic | status | date | deciders | reconstructed | extends |
|---|---|---|---|---|---|
| the mesh | accepted | 2026-09-27 | jochen | false | 0105-the-mesh-adopts-the-predecessors-tunnel-in-place.md |
119. A taken tunnel's predecessor is retired once the take is proven
Context
ADR 0105 has the private network take over the tunnel it finds: the found unit stopped and disabled, never flushed, and its configuration left on disk, kept like any held file. That was the right caution for the take itself — if the mesh's interface failed to come up, the host starts the found unit again and the peers never notice — and every apply since stops the found unit again should anyone start it.
What it leaves is a predecessor that never finishes leaving. On every machine that has enrolled, the tunnel is the mesh's and has been proven so — its interface up with the found key, the peers handshaking, the machines resolving and reaching each other over it — and still the predecessor's configuration sits where its unit reads it, held for a module that has long since replaced it. The predecessor itself is being deprecated. A tunnel that can be started again by one command, with a configuration nothing maintains any more, is not a rollback path; it is a second way onto the network that nobody is watching. And the hold never ends, so every node report keeps listing it.
Considered Options
1. Keep it, as 0105 says. Rejected: the caution it bought is spent once the take is proven, and what remains is a live, unmaintained way back onto the network.
2. Delete it at the take. Rejected: the take is exactly the moment the fallback is needed. If the mesh's interface does not come up, the host must still be able to raise the found one.
3. Retire it once the take is proven. Chosen.
Decision
Once the mesh's interface has proven it carries the tunnel, the found interface's configuration is removed from where its unit reads it.
- Proven means: the tunnel's state is taken — the found unit down and disabled, the mesh's interface up with the found key — and the mesh's interface has completed a handshake with at least one peer. Not before: until then, a failed take still falls back to the found unit.
- Retired means: the configuration file the found unit reads is removed. Its original was already kept, before anything happened to it (ADR 0100), and stays kept; that copy is the record of what the predecessor was, and a person's way back if one is ever wanted.
- The found unit stays disabled. Without its configuration it cannot raise the interface, so the every-apply stop that guarded against it becomes a check that finds nothing to do.
- The hold ends. What was held for the private network has been replaced; the node stops reporting it.
- The mesh never brings it back. Undeclaring the private network does not restore the found tunnel: the mesh stopped it, and nothing is started on the way out (ADR 0118, in review). A machine whose private network is unassigned has no tunnel until it is assigned again — which is what unassigning it means.
Consequences
- On every machine that took a tunnel, the predecessor's tunnel configuration disappears at the first apply after the take is proven. Nothing a peer sees changes; the mesh's interface already carries the same key, port, address and peers.
- A take that is never proven — no peer ever handshakes — keeps the found configuration, and the node says so, so a broken take is visible rather than silently retired.
- Rolling back to the predecessor's tunnel becomes a deliberate act: copy the kept original back and start its unit. The mesh does neither.
- 0105's "its configuration stays on disk, kept like any held file" holds until the take is proven, and not after.