Adoption mode: a node in use is adopted before it is converged (hq ADR 0100–0103) #20

2026-09-22T17:28:24Z

jschoubben commented

2026-09-22 17:28:24 +00:00

Implements adoption mode for the host and the installer, per hq ADRs 0100, 0101, 0102 and 0103.

Merge first. Hosts must be upgraded before the controller sends adoption, opening, into or reload-on, because the host parses declarations strictly. Merge order: mesh-host, then mesh-controller, then mesh-catalog.

What it does:

Declarations carry the adoption state. A declaration says whether the node is adopted and which modules are taken or not yet taken. Nothing changes for a declaration without it.
Found things are held. "Found" means present with no record. On an adopted node, anything found for a module not yet taken is held until that module is taken: files (the original is kept), containers, directories, running or enabled services, containers that would mount found data, archives, processes, users, and actions inside held containers. Held things are reported and never removed. A change to them is reported, not reverted.
Openings go through the found firewall. Openings are converged through the ufw found on the machine, marked, and re-checked on every reconcile. If an existing rule already admits the opening, it counts as satisfied: the mesh adds nothing and later removes nothing. A rule ufw would merge with the mesh's that is not a plain allow refuses the opening.
The found firewall is retired only on the flip. It is disabled only on a declared, converged apply; FORWARD policies are read before disabling and restored after. Returning to adopted enables it again.
Report: held things, the firewall found, and what is reachable. A reconcile report is published only when one of these changed.
Shared files are written into, not over (ADR 0102). A file with into: json has only the mesh's keys set, and list members are added rather than replacing the list. Undeclaring gives back exactly what the file held. A service with reload-on is reloaded rather than restarted.
systemd: the host reloads unit files before restarting a service whose reflected file changed.
Written-over files are kept. Before the host writes over a file it has no record of, it keeps the original once.
Installer:
- it refuses a machine in use, ignoring the operating system's own network daemons (ADR 0101);
- the foundation's ports are inputs: they are checked free, rewritten in the bundle and set as node settings; the overlay range is checked;
- --adopted replaces the base filter with the refusal-only guard (only traffic addressed to this machine, store/AMQP/management ports), and takes the foundation modules;
- a re-run keeps the adoption state it finds on the machine.

Measured on lab machines, not imagined:

ufw rule forms, and deleting route rules;
ufw merging rules that differ only in comment or action;
ufw disable opening FORWARD;
fail2ban's tables;
a fresh machine's listeners;
the container runtime reloading its registry trust with no container restart.

Tests: go build ./... && go vet ./... && go test ./... all pass. The adoption lab bed (mesh-lab, same branch) passed 18 of 19 checks. The one failure tested the found firewall's inbound policy rather than the mesh. That check was rewritten, and the new form was verified by hand on the kept machine.

Three independent reviews were done, and every finding is fixed. Follow-ups are recorded as hq issues 085 and 086.

Implements adoption mode for the host and the installer, per hq ADRs 0100, 0101, 0102 and 0103. **Merge first.** Hosts must be upgraded before the controller sends `adoption`, `opening`, `into` or `reload-on`, because the host parses declarations strictly. Merge order: mesh-host, then mesh-controller, then mesh-catalog. What it does: - **Declarations carry the adoption state.** A declaration says whether the node is adopted and which modules are taken or not yet taken. Nothing changes for a declaration without it. - **Found things are held.** "Found" means present with no record. On an adopted node, anything found for a module not yet taken is held until that module is taken: files (the original is kept), containers, directories, running or enabled services, containers that would mount found data, archives, processes, users, and actions inside held containers. Held things are reported and never removed. A change to them is reported, not reverted. - **Openings go through the found firewall.** Openings are converged through the ufw found on the machine, marked, and re-checked on every reconcile. If an existing rule already admits the opening, it counts as satisfied: the mesh adds nothing and later removes nothing. A rule ufw would merge with the mesh's that is not a plain allow refuses the opening. - **The found firewall is retired only on the flip.** It is disabled only on a declared, converged apply; FORWARD policies are read before disabling and restored after. Returning to adopted enables it again. - **Report:** held things, the firewall found, and what is reachable. A reconcile report is published only when one of these changed. - **Shared files are written into, not over (ADR 0102).** A file with `into: json` has only the mesh's keys set, and list members are added rather than replacing the list. Undeclaring gives back exactly what the file held. A service with `reload-on` is reloaded rather than restarted. - **systemd:** the host reloads unit files before restarting a service whose reflected file changed. - **Written-over files are kept.** Before the host writes over a file it has no record of, it keeps the original once. - **Installer:** - it refuses a machine in use, ignoring the operating system's own network daemons (ADR 0101); - the foundation's ports are inputs: they are checked free, rewritten in the bundle and set as node settings; the overlay range is checked; - `--adopted` replaces the base filter with the refusal-only guard (only traffic addressed to this machine, store/AMQP/management ports), and takes the foundation modules; - a re-run keeps the adoption state it finds on the machine. Measured on lab machines, not imagined: - ufw rule forms, and deleting route rules; - ufw merging rules that differ only in comment or action; - `ufw disable` opening FORWARD; - fail2ban's tables; - a fresh machine's listeners; - the container runtime reloading its registry trust with no container restart. Tests: `go build ./... && go vet ./... && go test ./...` all pass. The adoption lab bed (mesh-lab, same branch) passed 18 of 19 checks. The one failure tested the found firewall's inbound policy rather than the mesh. That check was rewritten, and the new form was verified by hand on the kept machine. Three independent reviews were done, and every finding is fixed. Follow-ups are recorded as hq issues 085 and 086.

jschoubben added 35 commits 2026-09-22 17:28:24 +00:00

Read a node's adoption from every declaration, so the host knows which modules are untaken (hq ADR 0100) fcc447c216

Keep what an adopted node was found holding until its module is taken, and report it held (hq ADR 0100) 3a613113be

Converge openings through the firewall an adopted node was found with, and retire it only when the node converges (hq ADR 0100) 3c90d155b3

Report what an adopted node holds, its firewall and what is reachable, and speak unasked when that changes (hq ADR 0100) 770f589401

Take the foundation's ports as genesis inputs, check them free, and hand them to the controller as the node's settings (hq ADR 0100) 3964d9da0a

Refuse a converged genesis on a machine in use, naming every container and listener counted (hq ADR 0100) 4811f176fd

Raise a machine in use adopted: keep its firewall, load no dropping table, guard the mesh's own ports, and take only the mesh's own modules (hq ADR 0100) 5e3dd3f59c

Delete a forwarded opening the way ufw accepts it, and read a fresh machine's resolver as not in use — both measured on a lab machine (hq ADR 0100) 3e0e6e6b7e

Reload the service manager's units before restarting a service whose files changed, and start the guard before the network as the controller declares it (hq ADR 0100) 6eabed63eb

Write into a file the machine shares instead of over it, and reload a service that re-reads its configuration instead of restarting it (hq ADR 0102) 0f126d137c

Publish a reconcile report when what is reachable changed, so the controller's converge preview stays fresh (hq ADR 0100) 1e0c6a3516