Feature 57 (config and provisioning): modules declare config and provisions, their files rendered from templates; synced with main (issues of feature 57, 874)

2026-10-16 07:37:43 +00:00
parent 1a2c917abf
commit 9652b2d5ce
771 changed files with 52063 additions and 1774 deletions
@@ -0,0 +1,63 @@
+# Managed by the mesh (module networkmanager). Replaced on every push; edit the
+# catalogue instead.
+#
+# This machine's uplink is NetworkManager's, and this file is the whole of what
+# the mesh asks of it (novox/hq ADR 0117): leave the resolver file to the mesh,
+# and leave the private network's interface alone. Nothing more. The mesh never
+# declares a connection profile, an address, a route, a wireless network or its
+# credentials — those are joined at the machine, by the person using it, and
+# the link they make is the only channel the mesh reaches this machine over. A
+# push that got a link wrong could not be undone by the next one.
+#
+# A drop-in of the mesh's own, beside NetworkManager.conf and whatever else the
+# operator keeps in this directory. NetworkManager reads the files here sorted by
+# name and a later one wins a key it sets again — so a file of the operator's
+# that sorts after this one (any name starting with a letter does) and sets dns=
+# or unmanaged-devices= overrides it. That is the operator's to decide, and the
+# reason this file sets nothing but the two keys it must.
+#
+# NetworkManager itself is the machine's: the mesh never starts, stops, enables
+# or disables it (its service is declared with no state), because stopping it
+# takes every link down, this machine's channel to the mesh included — and a
+# module unassigned by mistake must not be able to do that. When this file
+# changes, a running NetworkManager is reloaded (its D-Bus Reload call, which
+# re-reads its configuration — NetworkManager(8)), never restarted.
+
+[main]
+# The resolver file is the mesh's: this module writes /etc/resolv.conf itself,
+# listing the mesh's resolvers (novox/hq ADR 0223). Without this line
+# NetworkManager rewrites that file on
+# every connectivity change — every network joined, every lease renewed —
+# and the mesh's resolver is silently replaced while every surface of the mesh
+# still reads green. none: "NetworkManager will not modify resolv.conf. This
+# implies rc-manager unmanaged" (NetworkManager.conf(5), 1.58). On an adopted
+# machine the predecessor wrote the same line in a file of its own; both say one
+# thing, and the predecessor's is retired by hand after the take.
+#
+# Not NetworkManager's own global DNS ([global-dns-domain-*] with rc-manager=file):
+# it writes its own header and composes the options line itself, so it cannot
+# write the mesh's file byte for byte, and the three uplink modules would write
+# three different files for one fact. dns=none, and the file declared beside it.
+dns=none
+
+[keyfile]
+# mesh0 is the private network's interface: the mesh brings it up and the mesh
+# alone configures it. A manager that considers every interface its own could
+# try to configure it, or tear it down on a profile change.
+#
+# unmanaged-devices rather than a [device-mesh0] section with managed=0, because
+# NetworkManager.conf(5) says a device unmanaged by this key "is strictly
+# unmanaged and cannot be overruled by using the API like nmcli device set
+# $IFNAME managed yes", while device*.managed "can be overruled at runtime via
+# D-Bus". The same page adds that device*.managed "may be a better choice" for
+# exactly those reasons — for an interface the operator might want to hand back
+# at runtime. For the mesh's own interface, strict is the point.
+#
+# += rather than =: the same page documents appending to a list-valued key set
+# earlier ("plugins+=another-plugin") as an extension of its key file format,
+# and unmanaged-devices is a device list. = would replace whatever devices the
+# operator already keeps NetworkManager away from; += adds this one to them
+# (novox/hq ADR 0102: a list is added to, never replaced). A file of the
+# operator's read after this one that sets the key with = replaces it again;
+# that is the operator's to decide.
+unmanaged-devices+=interface-name:mesh0