From 3ab11c96ef8ad3d40d577751a8a7417991bf7441 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 27 Aug 2026 21:06:00 +0200 Subject: [PATCH] Say what the host process is: a root service, installed as a package The design described what the host does and never what it is at runtime. The words daemon, long-running, interval, poll and heartbeat appeared nowhere in it or in the relevant decisions. What exists is a command that runs and exits; what the design needs is a process holding a link. Nobody had written down that those differ, so several questions had no answer. 0057 settles them. It runs on every node -- the host is what makes a machine managed, so a machine without one is not a node. Root, because no useful subset of the job is unprivileged. A systemd unit, because something must survive a reboot to hold the link. It never manages its own unit. The temptation is obvious and it ends with a host stopping itself half way through an apply, leaving a machine with nothing running to fix it. The installation owns the host; the host owns everything else. Installed as a package, with a tarball as the floor. The package carries the unit file, the state directory and an upgrade path, which a bare binary does not. But the mesh's package repository is hosted on the mesh, so any route that needs the mesh to install the thing that joins the mesh is a circle -- the tarball is the path that must never acquire a dependency. Reconciles on start, on a declaration, on a timer and on reconnect. The timer is the one easy to leave out, and without it `owned` reports what the host applied rather than what is there -- ADR 0035 violated by omission. The records checker caught this commit on its first attempt: 05 listed 0057 in its frontmatter while 0057 is still proposed, and a to-be document may not rest on an unaccepted record. The section now says so in the body instead. --- ...s-a-root-service-installed-as-a-package.md | 126 ++++++++++++++++++ 03-DESIGN/01-to-be/05-the-node-host.md | 95 ++++++++++++- 2 files changed, 220 insertions(+), 1 deletion(-) create mode 100644 02-DECISIONS/0057-the-host-is-a-root-service-installed-as-a-package.md diff --git a/02-DECISIONS/0057-the-host-is-a-root-service-installed-as-a-package.md b/02-DECISIONS/0057-the-host-is-a-root-service-installed-as-a-package.md new file mode 100644 index 0000000..e80e756 --- /dev/null +++ b/02-DECISIONS/0057-the-host-is-a-root-service-installed-as-a-package.md @@ -0,0 +1,126 @@ +--- +status: proposed +date: 2026-08-27 +deciders: jochen +reconstructed: false +extends: 0041-the-host-depends-on-nothing.md +--- + +# 57. The host is a root service, installed as a package, that never manages itself + +## Context + +[`05-the-node-host.md`](../03-DESIGN/01-to-be/05-the-node-host.md) describes what the host *does* +and never says what it *is* at runtime. Searched: the words *daemon*, *long-running*, *interval*, +*poll* and *heartbeat* appear in none of it, nor in +[ADR 0038](0038-a-node-joins-by-linking-first.md) or +[ADR 0039](0039-the-link-is-the-security-boundary.md). + +What exists today is a command that runs and exits — `mesh-host apply FILE`. What the design +requires is a process holding an outbound link to the control plane. Nobody wrote down that +these are different things, so several questions have no answer: does it reconcile on a timer, +what happens when the link drops, and who installs the unit that starts it — given that the host +is the thing that installs units. + +## Decision + +### It runs on every node, and that is what a node is + +[ADR 0036](0036-a-node-is-a-managed-machine.md) defines a node as a managed machine. **The host +is what makes it managed**, so a machine without one is not a node with a missing component; it +is not a node. There is no partial mode, no agentless node, and no second way in. + +### It is a root service + +**Root**, because there is no useful subset of its job that is not privileged: it writes under +`/etc`, installs packages, manages units, and runs containers. A host that dropped privilege +could apply almost nothing, and the almost is where the confusion would live. + +**A service rather than a command**, because it holds the link, and something must survive a +reboot to hold it. The command-line entry points remain — they are how a person inspects and +rescues a machine — but the ordinary case is a unit that is always up. + +### It never manages its own unit + +**The host's own service file is not a resource the host applies.** The temptation is obvious — +it manages units, and its own unit is a unit — and it ends with a host stopping itself half way +through an apply, leaving a machine in a state nothing is running to fix. + +So the boundary is: **the installation owns the host; the host owns everything else.** A +declaration that names the host's own unit is refused rather than obeyed. + +### It is installed as a package, and a tarball is the floor + +Two mechanisms, and the second is not a fallback for the first failing — it is what makes the +first possible. + +| | | +|---|---| +| **package** — `pacman -S nox-mesh-host` | the ordinary path. Carries the binary, the unit file, the state directory, and an upgrade path | +| **tarball** — `curl … \| tar -xz` | the floor. One static binary, no repository, no distribution assumed | + +**Why a package rather than only a binary.** [ADR 0041](0041-the-host-depends-on-nothing.md) says +copying the binary onto a machine is the whole installation, and that remains true of the +*binary*. But a unit file, a state directory and an upgrade path are real, and something has to +own them. A package that installs one statically linked binary plus a unit file adds no runtime +dependency — 0041 is about what must already be present for the host to work, not about how the +bytes arrived. + +**Why the tarball must keep working.** The package lives in a repository, and the mesh's own +repository is hosted on the mesh. A first node cannot fetch from a mesh that does not exist yet, +and neither can a node whose mesh is down — which is exactly when somebody is trying to fix it. +**Any path that requires the mesh to install the thing that joins the mesh is a circle**, so the +tarball is the path that is never allowed to acquire a dependency. + +### The mesh does not upgrade the host + +A running process replacing its own binary and restarting mid-apply is the self-management +problem wearing a different hat. **Upgrading the host is an act on the machine**, by the package +manager, not a declaration the host applies to itself. + +Recorded as a limit rather than a plan: it means a fleet-wide host upgrade is not currently a +mesh operation, and that will be felt. + +### It reconciles on four triggers + +| Trigger | Why | +|---|---| +| **start** | the machine may have changed while nothing was running | +| **a declaration arrives** | the ordinary path | +| **a timer** | drift. Something other than the host changed the machine — a person, a package upgrade replacing a config file | +| **reconnect** | it may have missed declarations while disconnected ([ADR 0036](0036-a-node-is-a-managed-machine.md)) | + +**The timer is what makes the store's claim true.** Without it a machine that drifted stays +drifted until somebody changes a declaration, and `owned` reports what the host *applied* rather +than what is *there* — which is +[ADR 0035](0035-a-picture-is-read-from-what-runs.md) violated by omission. + +**Ten minutes**, configurable. Short enough that drift is bounded by something a person would +notice anyway, long enough that a fleet is not doing constant work. The reconcile is cheap: it +asks the package database, the service manager and the container runtime about resources the +host already knows it owns. + +## Consequences + +- **Adoption becomes two concrete steps**, which is the point of writing this down: + install the package, then hand it a token. Nothing else. +- **The host gains a mode it does not have**, and it is the larger half of stage 3. Today every + entry point runs and exits. +- **Refusing to manage its own unit needs enforcing, not just stating.** A declaration naming + the host's unit must be refused by name, and that refusal is a test. +- **A host that cannot reach the mesh keeps reconciling from its store**, which is + [ADR 0036](0036-a-node-is-a-managed-machine.md) made operational rather than aspirational: a + disconnected node is not merely tolerated, it is actively holding its machine in the last + state it was told to hold. +- **The timer makes drift visible and also makes it loud.** A resource the host cannot apply + will now fail every ten minutes rather than once. That is correct and it needs somewhere to go + other than a log nobody reads — which is `observability`'s, and it does not exist yet. +- **Host upgrades are outside the mesh**, so a fleet-wide upgrade is currently manual. Nothing + here solves it and it should not be solved by giving the host a self-upgrade path. + +## References + +- [ADR 0041](0041-the-host-depends-on-nothing.md) — the property the package must not break. +- [ADR 0036](0036-a-node-is-a-managed-machine.md) — what a node is, which this makes operational. +- [ADR 0039](0039-the-link-is-the-security-boundary.md) — the link the process exists to hold. +- [ADR 0051](0051-the-enrolment-token-carries-the-mesh.md) — the second of the two adoption steps. diff --git a/03-DESIGN/01-to-be/05-the-node-host.md b/03-DESIGN/01-to-be/05-the-node-host.md index feef773..15e8ed5 100644 --- a/03-DESIGN/01-to-be/05-the-node-host.md +++ b/03-DESIGN/01-to-be/05-the-node-host.md @@ -2,7 +2,7 @@ layer: to-be status: in-progress code: [mesh-host] -updated: 2026-08-26 +updated: 2026-08-27 decisions: - 02-DECISIONS/0030-the-repository-structure.md - 02-DECISIONS/0036-a-node-is-a-managed-machine.md @@ -113,6 +113,99 @@ work: a node is a node, and what varies between them is here rather than in the What this machine *is* — its identity, what it holds, what it has applied. Reported upward over the link; never asked downward. +## The process + +> **Proposed, not yet decided** — +> [ADR 0057](../../02-DECISIONS/0057-the-host-is-a-root-service-installed-as-a-package.md) is +> awaiting review. This section is written against it and moves into the document's `decisions:` +> when the record is accepted. + +**One `root` service on every node, plus command-line entry points for a person.** A machine +without one is not a node ([ADR 0036](../../02-DECISIONS/0036-a-node-is-a-managed-machine.md)) — +the host is what makes a machine managed, so there is no agentless node and no partial mode. + +Root because there is no useful unprivileged subset: it writes under `/etc`, installs packages, +manages units and runs containers. + +### Installing it + +Two steps, and there is nothing else: + +``` +# 1 — put the host on the machine +pacman -S nox-mesh-host +systemctl enable --now nox-mesh-host + +# 2 — hand it the mesh +nox-mesh-host enrol --token +``` + +The token carries the broker's address, the fingerprint to expect, and the right to join +([ADR 0051](../../02-DECISIONS/0051-the-enrolment-token-carries-the-mesh.md)). After that the +node is in the mesh and takes declarations like every other one. + +**On a machine with no package repository, or no mesh to serve one:** + +``` +curl -fsSL https:///mesh-host--x86_64.tar.gz | tar -xz -C /usr/local/bin +``` + +That path must never acquire a dependency. **The mesh's package repository is hosted on the +mesh**, so any installation route that needs the mesh is a circle — a first node cannot use it, +and neither can anyone repairing a mesh that is down. + +### The unit + +```ini +[Unit] +Description=Novox Mesh node host +After=network-online.target +Wants=network-online.target + +[Service] +Type=notify +ExecStart=/usr/bin/nox-mesh-host run +Restart=always +RestartSec=5s +StateDirectory=mesh-host + +[Install] +WantedBy=multi-user.target +``` + +**The package owns this file. The host never does.** It manages `service` resources, and its own +unit is a service — the temptation is obvious and it ends with a host stopping itself half way +through an apply, leaving a machine with nothing running to fix it. A declaration naming the +host's own unit is **refused**, and that refusal is a test rather than a convention. + +The line to hold: **the installation owns the host; the host owns everything else.** + +### What it does while running + +| | | +|---|---| +| holds the **link** | one outbound connection, node-initiated, nothing listening ([ADR 0039](../../02-DECISIONS/0039-the-link-is-the-security-boundary.md)) | +| **applies** what arrives | declarations of known shape, in the order given | +| **reads back and reports** | what it did, and what it now owns | +| **reconciles** | on start, on a declaration, on a timer, and on reconnect | + +**The timer is the one that is easy to leave out.** Without it, a machine that drifted — a +person edited a file, a package upgrade replaced a config — stays drifted until somebody happens +to change a declaration. `owned` would then report what the host *applied* rather than what is +*there*, which is [ADR 0035](../../02-DECISIONS/0035-a-picture-is-read-from-what-runs.md) +violated by omission. **Ten minutes, configurable.** + +**Disconnected is a working state, not a degraded one.** The host keeps reconciling against its +own store, so a laptop shut for a week comes back and reconciles rather than coming back and +asking what it is. That is +[ADR 0036](../../02-DECISIONS/0036-a-node-is-a-managed-machine.md) made operational. + +### Upgrading it + +**By the package manager, not by the mesh.** A running process that replaces its own binary and +restarts part-way through an apply is the self-management problem again. Recorded as a limit: +a fleet-wide host upgrade is not currently a mesh operation. + ## Where a declaration comes from One behaviour, two sources