diff --git a/modules/dhcpcd/README.md b/modules/dhcpcd/README.md new file mode 100644 index 0000000..77948be --- /dev/null +++ b/modules/dhcpcd/README.md @@ -0,0 +1,43 @@ +# dhcpcd + +The uplink seat's module for a machine whose own network is dhcpcd's (novox/hq ADR 0117). It +asks two things of dhcpcd, and nothing else: leave the resolver file to the mesh, and leave the +private network's interface alone. It never declares an interface, an address, a route, a +wireless network or its credentials — the link dhcpcd keeps is the only channel the mesh reaches +the machine over. + +## What it writes + +Two lines into `/etc/dhcpcd.conf`, as the mesh's marked region (`into: block`) — dhcpcd reads no +drop-in directory, so the mesh writes into its one file rather than over it (ADR 0102): + +- `nohook resolv.conf` — dhcpcd's resolv.conf hook rewrites `/etc/resolv.conf` on every lease it + takes or renews, which would silently replace the resolver `resolv-conf` names. +- `denyinterfaces mesh0` — dhcpcd never asks for a lease on the private network's interface, and + never takes it down. dhcpcd leaves a point-to-point interface alone by default; this says so + rather than relying on it. + +**At the start of the file** (`at: start`). Both are global options, and dhcpcd reads every line +after an `interface` or `ssid` line as that interface's own. A configured machine's file ends in +exactly such a block (the interface, its static address), so appended at the end these two would +quietly apply to one interface only. + +## Why it declares no service + +dhcpcd is the machine's, not the mesh's. The mesh never starts, stops or enables it: stopping it +drops the address the machine is reached at, and a module unassigned by mistake must not be able +to do that. And there is nothing to reload it with — `dhcpcd.service` reports `CanReload=no`, and +a restart drops the lease. So the two lines take effect at **dhcpcd's next start**. + +On an adopted machine that is normally no gap: the predecessor wrote the same `nohook` line, and +it is already in force. **On a machine that was not adopted, it is one:** until dhcpcd next +starts (a reboot, or the operator restarting it in a window of their choosing), a lease renewal +still rewrites `/etc/resolv.conf`, and `resolv-conf` puts it back at the next push. Assign this +module before `resolv-conf` on such a machine, and restart dhcpcd once, by hand, when losing the +link for a moment is acceptable. + +## One manager per machine + +It claims `the-uplink`: a machine runs one network manager, and assigning a second module that +claims the seat is refused. Assigning this one to a machine whose network is NetworkManager's +installs the package and writes the two lines, and starts nothing. diff --git a/modules/dhcpcd/module.json b/modules/dhcpcd/module.json new file mode 100644 index 0000000..1e7aa67 --- /dev/null +++ b/modules/dhcpcd/module.json @@ -0,0 +1,30 @@ +{ + "module": "dhcpcd", + "version": "1", + "capabilities": [ + "package-manager", + "service-manager" + ], + "claims": [ + { + "name": "the-uplink", + "scope": "node" + } + ], + "resources": [ + { + "id": "package", + "type": "package", + "package": "dhcpcd" + }, + { + "id": "config", + "type": "file", + "path": "/etc/dhcpcd.conf", + "mode": "0644", + "into": "block", + "at": "start", + "content": "# The mesh's two lines (module dhcpcd, novox/hq ADR 0117). Global options, so\n# kept above any interface line; read at dhcpcd's next start.\nnohook resolv.conf\ndenyinterfaces mesh0\n" + } + ] +} diff --git a/modules/networkmanager/module.json b/modules/networkmanager/module.json new file mode 100644 index 0000000..6bf00f1 --- /dev/null +++ b/modules/networkmanager/module.json @@ -0,0 +1,36 @@ +{ + "module": "networkmanager", + "version": "1", + "capabilities": [ + "package-manager", + "service-manager" + ], + "claims": [ + { + "name": "the-uplink", + "scope": "node" + } + ], + "resources": [ + { + "id": "package", + "type": "package", + "package": "networkmanager" + }, + { + "id": "config", + "type": "file", + "path": "/etc/NetworkManager/conf.d/50-mesh.conf", + "mode": "0644", + "content": "# Managed by the mesh (module networkmanager). Replaced on every push; edit the\n# catalogue instead.\n#\n# This machine's uplink is NetworkManager's, and this file is the whole of what\n# the mesh asks of it (novox/hq ADR 0117): leave the resolver file to the mesh,\n# and leave the private network's interface alone. Nothing more. The mesh never\n# declares a connection profile, an address, a route, a wireless network or its\n# credentials \u2014 those are joined at the machine, by the person using it, and\n# the link they make is the only channel the mesh reaches this machine over. A\n# push that got a link wrong could not be undone by the next one.\n#\n# A drop-in of the mesh's own, beside NetworkManager.conf and whatever else the\n# operator keeps in this directory. NetworkManager reads the files here sorted by\n# name and a later one wins a key it sets again \u2014 so a file of the operator's\n# that sorts after this one (any name starting with a letter does) and sets dns=\n# or unmanaged-devices= overrides it. That is the operator's to decide, and the\n# reason this file sets nothing but the two keys it must.\n#\n# NetworkManager itself is the machine's: the mesh never starts, stops, enables\n# or disables it (its service is declared with no state), because stopping it\n# takes every link down, this machine's channel to the mesh included \u2014 and a\n# module unassigned by mistake must not be able to do that. When this file\n# changes, a running NetworkManager is reloaded (its D-Bus Reload call, which\n# re-reads its configuration \u2014 NetworkManager(8)), never restarted.\n\n[main]\n# The resolver file is the mesh's: resolv-conf writes /etc/resolv.conf and names\n# the mesh's resolver. Without this line NetworkManager rewrites that file on\n# every connectivity change \u2014 every network joined, every lease renewed \u2014\n# and the mesh's resolver is silently replaced while every surface of the mesh\n# still reads green. none: \"NetworkManager will not modify resolv.conf. This\n# implies rc-manager unmanaged\" (NetworkManager.conf(5), 1.58). On an adopted\n# machine the predecessor wrote the same line in a file of its own; both say one\n# thing, and the predecessor's is retired by hand after the take.\ndns=none\n\n[keyfile]\n# mesh0 is the private network's interface: the mesh brings it up and the mesh\n# alone configures it. A manager that considers every interface its own could\n# try to configure it, or tear it down on a profile change.\n#\n# unmanaged-devices rather than a [device-mesh0] section with managed=0, because\n# NetworkManager.conf(5) says a device unmanaged by this key \"is strictly\n# unmanaged and cannot be overruled by using the API like nmcli device set\n# $IFNAME managed yes\", while device*.managed \"can be overruled at runtime via\n# D-Bus\". The same page adds that device*.managed \"may be a better choice\" for\n# exactly those reasons \u2014 for an interface the operator might want to hand back\n# at runtime. For the mesh's own interface, strict is the point.\n#\n# += rather than =: the same page documents appending to a list-valued key set\n# earlier (\"plugins+=another-plugin\") as an extension of its key file format,\n# and unmanaged-devices is a device list. = would replace whatever devices the\n# operator already keeps NetworkManager away from; += adds this one to them\n# (novox/hq ADR 0102: a list is added to, never replaced). A file of the\n# operator's read after this one that sets the key with = replaces it again;\n# that is the operator's to decide.\nunmanaged-devices+=interface-name:mesh0\n" + }, + { + "id": "service", + "type": "service", + "unit": "NetworkManager.service", + "reload-on": [ + "config" + ] + } + ] +} diff --git a/modules/systemd-networkd/module.json b/modules/systemd-networkd/module.json new file mode 100644 index 0000000..c4f6b51 --- /dev/null +++ b/modules/systemd-networkd/module.json @@ -0,0 +1,36 @@ +{ + "module": "systemd-networkd", + "version": "1", + "capabilities": [ + "package-manager", + "service-manager" + ], + "claims": [ + { + "name": "the-uplink", + "scope": "node" + } + ], + "resources": [ + { + "id": "package", + "type": "package", + "package": "systemd" + }, + { + "id": "config", + "type": "file", + "path": "/etc/systemd/network/00-mesh0.network", + "mode": "0644", + "content": "# Managed by the mesh (module systemd-networkd). Replaced on every push; edit\n# the catalogue instead.\n#\n# This machine's uplink is systemd-networkd's, and the mesh asks one thing of it\n# here (novox/hq ADR 0117): leave the private network's interface alone. mesh0\n# is the mesh's; the mesh brings it up and configures it itself. The mesh never\n# declares a link, an address, a route, a wireless network or its credentials,\n# nor a network file for any of this machine's own interfaces \u2014 those are\n# the operator's, and the link they make is the only channel the mesh reaches\n# this machine over.\n#\n# 00-: networkd applies the first .network file, in alphanumeric order across\n# every directory, that matches an interface, and ignores every later one even\n# if it matches too (systemd.network(5), [Match]). A catch-all of the operator's\n# \u2014 Name=*, Type=ether, a file with no [Match] at all \u2014 sorted before\n# this one would claim mesh0 first. 00 sorts before every numbered prefix the\n# man page recommends.\n#\n# Unmanaged=yes: \"no attempts are made to bring up or configure matching links,\n# equivalent to when there are no matching network files\" (systemd.network(5),\n# [Link], since 233). A match that ends the search, and does nothing else.\n#\n# No DNS setting, because none is needed: networkd never writes\n# /etc/resolv.conf. What it learns from a lease it hands only to\n# systemd-resolved, and the resolver file stays whatever resolv-conf wrote.\n# Whether resolved runs, and what it does with that, is the resolver\n# configuration's question, not the uplink's.\n#\n# The service is reloaded when this file changes, never restarted: a restart\n# drops the links networkd holds, this machine's channel to the mesh among them.\n[Match]\nName=mesh0\n\n[Link]\nUnmanaged=yes\n" + }, + { + "id": "service", + "type": "service", + "unit": "systemd-networkd.service", + "reload-on": [ + "config" + ] + } + ] +}