diff --git a/modules/dhcpcd/README.md b/modules/dhcpcd/README.md index 77948be..fb77d4a 100644 --- a/modules/dhcpcd/README.md +++ b/modules/dhcpcd/README.md @@ -2,17 +2,24 @@ 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. +private network's interface alone — and it writes that resolver file itself (ADR 0223). 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 +`/etc/resolv.conf`, whole: every resolver of the mesh by its private address — this machine's own +first when it holds one — and `options timeout:1 attempts:2 edns0`, rendered by the mesh from the +holders of `mesh-dns-resolver`. The same file every uplink module writes. Not dhcpcd's own static +`domain_name_servers`: dhcpcd writes the file only through its hook, with its own header, and reads +its configuration only at its next start, so a change to the mesh's resolvers would not reach the +file until then. + 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. + takes or renews, which would silently replace the resolvers this module writes there. - `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. @@ -32,12 +39,11 @@ 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. +still rewrites `/etc/resolv.conf`, and this module puts it back at the next push. 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 +It claims `node-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 index 23c658e..7d7b3bc 100644 --- a/modules/dhcpcd/module.json +++ b/modules/dhcpcd/module.json @@ -1,6 +1,9 @@ { "module": "dhcpcd", "version": "1", + "requires": [ + "wildcard-resolution" + ], "capabilities": [ "package-manager", "service-manager", @@ -12,6 +15,12 @@ "scope": "node" } ], + "facts": { + "resolvers": { + "path": "/etc/resolv.conf", + "template": "# Managed by the mesh, and written by the module holding this machine's uplink:\n# the program that manages the machine's network would otherwise rewrite this\n# file on every change of network, so its holder is the one that writes it\n# (novox/hq ADR 0117, ADR 0223). Replaced on every push; edit nothing here.\n#\n# Every resolver of the mesh, by address, and nothing else (novox/hq ADR 0223) \u2014\n# this machine's own first when it holds one, then the others by name. Each\n# answers the mesh's names from the same roster and forwards every other name, so\n# whichever answers first gives the one answer. There is no public resolver here:\n# a C library that asks every listed server at once and takes the first reply \u2014\n# musl, so every Alpine container \u2014 took a public resolver's \"no such name\" for\n# a mesh name and failed. A machine that reaches none of these has no names until\n# it does. Containers copy these lines from their machine.\n{{range index .Holders \"mesh-dns-resolver\"}}nameserver {{.Address}}\n{{end}}options timeout:1 attempts:2 edns0\n" + } + }, "resources": [ { "id": "package", @@ -25,7 +34,7 @@ "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" + "content": "# The mesh's two lines (module dhcpcd, novox/hq ADR 0117, ADR 0223): the\n# resolver file is this module's, written whole beside this file. Global\n# options, so 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 index 37c2ba7..e7286c8 100644 --- a/modules/networkmanager/module.json +++ b/modules/networkmanager/module.json @@ -1,6 +1,9 @@ { "module": "networkmanager", "version": "1", + "requires": [ + "wildcard-resolution" + ], "capabilities": [ "package-manager", "service-manager", @@ -12,6 +15,12 @@ "scope": "node" } ], + "facts": { + "resolvers": { + "path": "/etc/resolv.conf", + "template": "# Managed by the mesh, and written by the module holding this machine's uplink:\n# the program that manages the machine's network would otherwise rewrite this\n# file on every change of network, so its holder is the one that writes it\n# (novox/hq ADR 0117, ADR 0223). Replaced on every push; edit nothing here.\n#\n# Every resolver of the mesh, by address, and nothing else (novox/hq ADR 0223) \u2014\n# this machine's own first when it holds one, then the others by name. Each\n# answers the mesh's names from the same roster and forwards every other name, so\n# whichever answers first gives the one answer. There is no public resolver here:\n# a C library that asks every listed server at once and takes the first reply \u2014\n# musl, so every Alpine container \u2014 took a public resolver's \"no such name\" for\n# a mesh name and failed. A machine that reaches none of these has no names until\n# it does. Containers copy these lines from their machine.\n{{range index .Holders \"mesh-dns-resolver\"}}nameserver {{.Address}}\n{{end}}options timeout:1 attempts:2 edns0\n" + } + }, "resources": [ { "id": "package", @@ -23,7 +32,7 @@ "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" + "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: this module writes /etc/resolv.conf itself,\n# listing the mesh's resolvers (novox/hq ADR 0223). Without this line\n# 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.\n#\n# Not NetworkManager's own global DNS ([global-dns-domain-*] with rc-manager=file):\n# it writes its own header and composes the options line itself, so it cannot\n# write the mesh's file byte for byte, and the three uplink modules would write\n# three different files for one fact. dns=none, and the file declared beside it.\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", diff --git a/modules/resolv-conf/README.md b/modules/resolv-conf/README.md new file mode 100644 index 0000000..83fa961 --- /dev/null +++ b/modules/resolv-conf/README.md @@ -0,0 +1,8 @@ +# resolv-conf — retiring + +`/etc/resolv.conf` belongs to the module holding `node-uplink` (novox/hq ADR 0223): networkmanager, +systemd-networkd and dhcpcd each write it, listing the mesh's resolvers. This module declares +nothing any more. It stays in the catalogue for one release so that the file passes from it to the +uplink's holder in one apply on every machine — the host hands a whole file to the resource +declaring its path now, rather than removing it first. Once every machine has applied that, it is +unassigned everywhere, forgotten, and removed with the seat `node-resolver-config`. diff --git a/modules/resolv-conf/module.json b/modules/resolv-conf/module.json index 406092d..31fa4fe 100644 --- a/modules/resolv-conf/module.json +++ b/modules/resolv-conf/module.json @@ -2,19 +2,10 @@ "module": "resolv-conf", "version": "1", "slug": "resolv", - "requires": [ - "wildcard-resolution" - ], "claims": [ { "name": "node-resolver-config", "scope": "node" } - ], - "facts": { - "resolvers": { - "path": "/etc/resolv.conf", - "template": "# Managed by the mesh.\n#\n# The machine's network manager is told to leave this file alone by the module\n# holding its uplink, which the mesh requires beside this one (novox/hq ADR 0117,\n# 0220): without it, the first change of network would rewrite the file.\n#\n# Every resolver of the mesh, by address, and nothing else (novox/hq ADR 0223) —\n# this machine's own first when it holds one, then the others by name. Each\n# answers the mesh's names from the same roster and forwards every other name, so\n# whichever answers first gives the one answer. There is no public resolver here:\n# a C library that asks every listed server at once and takes the first reply —\n# musl, so every Alpine container — took a public resolver's \"no such name\" for\n# a mesh name and failed. A machine that reaches none of these has no names until\n# it does. Containers copy these lines from their machine.\n{{range index .Holders \"mesh-dns-resolver\"}}nameserver {{.Address}}\n{{end}}options timeout:1 attempts:2 edns0\n" - } - } + ] } diff --git a/modules/systemd-networkd/module.json b/modules/systemd-networkd/module.json index 9e12003..8fcc15d 100644 --- a/modules/systemd-networkd/module.json +++ b/modules/systemd-networkd/module.json @@ -1,6 +1,9 @@ { "module": "systemd-networkd", "version": "1", + "requires": [ + "wildcard-resolution" + ], "capabilities": [ "service-manager", "uplink-systemd-networkd" @@ -11,13 +14,19 @@ "scope": "node" } ], + "facts": { + "resolvers": { + "path": "/etc/resolv.conf", + "template": "# Managed by the mesh, and written by the module holding this machine's uplink:\n# the program that manages the machine's network would otherwise rewrite this\n# file on every change of network, so its holder is the one that writes it\n# (novox/hq ADR 0117, ADR 0223). Replaced on every push; edit nothing here.\n#\n# Every resolver of the mesh, by address, and nothing else (novox/hq ADR 0223) —\n# this machine's own first when it holds one, then the others by name. Each\n# answers the mesh's names from the same roster and forwards every other name, so\n# whichever answers first gives the one answer. There is no public resolver here:\n# a C library that asks every listed server at once and takes the first reply —\n# musl, so every Alpine container — took a public resolver's \"no such name\" for\n# a mesh name and failed. A machine that reaches none of these has no names until\n# it does. Containers copy these lines from their machine.\n{{range index .Holders \"mesh-dns-resolver\"}}nameserver {{.Address}}\n{{end}}options timeout:1 attempts:2 edns0\n" + } + }, "resources": [ { "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 — 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# — Name=*, Type=ether, a file with no [Match] at all — 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" + "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 — 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# — Name=*, Type=ether, a file with no [Match] at all — 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, which the mesh does not run (novox/hq ADR 0196). So this\n# module declares the resolver file itself, beside this one, listing the\n# mesh's resolvers (novox/hq ADR 0223).\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",