diff --git a/02-DECISIONS/0101-a-machines-own-resolver-does-not-make-it-in-use.md b/02-DECISIONS/0101-a-machines-own-resolver-does-not-make-it-in-use.md new file mode 100644 index 0000000..daa1d0b --- /dev/null +++ b/02-DECISIONS/0101-a-machines-own-resolver-does-not-make-it-in-use.md @@ -0,0 +1,71 @@ +--- +topic: the mesh +status: proposed +date: 2026-09-22 +deciders: jochen +reconstructed: false +extends: 02-DECISIONS/0100-a-node-in-use-is-adopted-before-it-is-converged.md +--- + +# 101. A machine's own resolver does not make it in use + +## Context + +[ADR 0100](0100-a-node-in-use-is-adopted-before-it-is-converged.md) has a converged genesis +refuse a machine in use. It defines *in use* as a container running, or a port listening on an +address other than loopback that is not ssh's. That definition was written before anything was +measured. + +Measured on a freshly installed lab machine, running nothing but its operating system: + +| Listening | Held by | +|---|---| +| TCP and UDP on every address, the link-local name resolution port | the system's name resolver | +| UDP on every address, the multicast name resolution port | the system's name resolver | +| UDP on a link-local address, the address-configuration client port | the system's network manager | +| TCP and UDP on loopback | the resolver's stub and the container runtime | + +By ADR 0100's words, the resolver's TCP listener on every address makes **every** freshly +installed machine a machine in use. A converged genesis would refuse them all, and `--adopted` +would become the only way to raise anything. The refusal exists to catch a forgotten flag on a +working machine. Refusing an empty one defeats it, and teaches operators to pass the flag by +habit. + +## Considered Options + +1. **Keep the words.** Rejected: every fresh machine is refused. +2. **Count TCP only, ignore UDP.** Rejected: the resolver listens on TCP too, and a machine that + serves over UDP alone, a resolver or a tunnel, is in use. +3. **Ignore listeners held by the operating system's own network daemons**, a short named list, + on both protocols. Adopted. + +## Decision + +**A listener held by one of the operating system's own network daemons does not make a machine +in use.** The daemons are the name resolver, the network manager, the address-configuration +client and the time client, named in the installer's code beside the measurement that found +them. Everything else in ADR 0100's definition stands: a running container, or any other +listener on an address other than loopback that is not ssh's, makes the machine in use, and +genesis still names every one it counted. + +A daemon is added to the list only with a measurement of a fresh machine that holds it. + +## Consequences + +- A converged genesis on a fresh machine goes ahead, as it did before ADR 0100. +- A machine whose resolver is also serving other machines is not counted as in use by its + resolver alone. It is one of the daemons that serves nobody on a fresh machine, and the one + kind of service this lets through. +- The list is code, not configuration, so it changes by review. + +## How it is checked + +A unit test in the installer feeds the listeners captured from the fresh machine, as the +listening-socket tool printed them, and asserts the machine is not in use. The existing tests +still assert that a serving machine is in use and that every container and listener is named. +The adoption lab bed raises a converged genesis on a fresh machine and asserts it is not refused. + +## References + +- [ADR 0100](0100-a-node-in-use-is-adopted-before-it-is-converged.md) +- [research 012, *migrating a node that is in use*](../01-RESEARCH/012-the-minimum-viable-node/migrating-a-node-in-use.md) diff --git a/02-DECISIONS/README.md b/02-DECISIONS/README.md index e928743..0e754f1 100644 --- a/02-DECISIONS/README.md +++ b/02-DECISIONS/README.md @@ -89,6 +89,7 @@ python3 00-META/checks/index.py fail if stale - **0088** — [The foundation filters before anything listens](0088-the-foundation-filters-before-anything-listens.md) - **0090** — [A failure that repeats is said to be stuck](0090-a-failure-that-repeats-is-said-to-be-stuck.md) - **0100** — [A node in use is adopted before it is converged](0100-a-node-in-use-is-adopted-before-it-is-converged.md) +- **0101** — [A machine's own resolver does not make it in use](0101-a-machines-own-resolver-does-not-make-it-in-use.md) *(proposed)* ### Its tiers, from the bottom up