ADR 0101 proposed: a machine's own resolver does not make it in use, as measured on a fresh machine

2026-09-22 17:38:44 +02:00
parent 6165a7ae02
commit 347bbce633
2 changed files with 72 additions and 0 deletions
@@ -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)
@@ -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