From c11cb994705b75c2222b3c27e8d842efa11d2504 Mon Sep 17 00:00:00 2001 From: jochen Date: Tue, 13 Oct 2026 10:40:27 +0200 Subject: [PATCH] Give ADR 0341 a home in design 52: the home network's SMB and NFS shares become modules' (issue 613) --- 00-META/glossary.md | 4 +- 03-DESIGN/01-to-be/52-shares-and-mounts.md | 50 ++++++++++++++++++++-- 2 files changed, 50 insertions(+), 4 deletions(-) diff --git a/00-META/glossary.md b/00-META/glossary.md index cd4b9b94..4490cf86 100644 --- a/00-META/glossary.md +++ b/00-META/glossary.md @@ -257,7 +257,9 @@ and Health and repair. **Decided by** ADR 0100, 0126, 0176, 0181, 0207, 0221, 02 only by a person (ADR 0230). - **share** — a folder one node offers to the mesh's other nodes over the private network: the provision `nfs-share`, provided by the holder of the node seat `node-nfs-server`, one share per folder - (ADR 0263). + (ADR 0263). A share may also be granted to the machine's local network (ADR 0341). An **SMB share** is + a folder the holder of the node seat `node-smb-server` serves to devices on the local network, and is + not a provision (ADR 0341). - **mount** — a share, or an occasional source, made visible at a path on one node by the holder of the node seat `node-mounts`, as a mount unit and an automount unit, mounted on access (ADR 0263). - **occasional source** — a share on a device that is not a node and comes and goes, such as a USB disk; diff --git a/03-DESIGN/01-to-be/52-shares-and-mounts.md b/03-DESIGN/01-to-be/52-shares-and-mounts.md index 701a8230..8057e15d 100644 --- a/03-DESIGN/01-to-be/52-shares-and-mounts.md +++ b/03-DESIGN/01-to-be/52-shares-and-mounts.md @@ -5,8 +5,11 @@ code: - mesh-controller internal/catalogue (the seats node-nfs-server and node-mounts) - mesh-catalog modules/nfs-server - mesh-catalog modules/mounts -updated: 2026-10-10 + - mesh-catalog modules/smb-server (to be built) +updated: 2026-10-13 decisions: + - "ADR 0341" + - "ADR 0340" - "ADR 0283" - "ADR 0277" - "ADR 0263" @@ -233,9 +236,50 @@ separate decision. **Stop at once** when a share reads `failed` for a reason not understood, when a dry run would touch a line or a dataset other than the one asked for, or when anything under the library changes owner. +## 6. The home network (ADR 0341, after ADR 0340) + +*2026-10-13.* The home server's SMB share and its NFS export to the home network are still used (the +operator, on issue 613), so both become modules' and neither is retired. Both are reached from the +home server's local network and the private network only, through the reach `local-network` of +ADR 0340, and neither is built into use before that reach is accepted and built. + +- **`smb-server`** holds the node seat `node-smb-server`, with the verbs `shares` (r), `sessions` (r), + `test` (r), `reload` (a) and `adopt` (a). Its setting `shares` lists the shares (a name, the path, + read-only or read-write) and its setting `users` the login names. It provides no provision: its + clients are devices that are not nodes, and a node that wants the library mounts the NFS share. +- **Identity.** Every client acts as the shared folder's owner (`force user`, `force group`, read from + the folder after any symbolic link), and the refusals of section 1 hold for SMB shares too. +- **Protocol.** SMB 2.1 and later on 445/tcp alone; NetBIOS is off, so 137, 138 and 139 stay closed + and `nmb` is stopped once the module's configuration takes over. +- **Passwords.** One secret per login, `smb-password-`, a member of a family the mesh never makes + a value for (ADR 0283). A login already in Samba's password database whose secret is not given keeps + its password, said as kept as found. +- **The configuration file.** Once adopted, the module writes it whole from its settings and checks it + with Samba's own checker before it reloads. `adopt` shows each hand-written share beside its + rendering, refuses while one has no counterpart in the settings, and keeps a dated copy. +- **NFS to the home network.** `nfs-server`'s `grants` may name `local-network` for a share, beside + node names. The export line names the subnets the home server's local network resolved to, never a + range typed in a setting, with `all_squash` and `mp` as in section 1. The module refuses that grant + while port 2049 is not bound with the reach `local-network`, and says so. +- **The ZFS property** is cleared by `node-nfs-server.adopt` only once the module's own export covers + every client the property exported to, so for the home network only after the module's + `local-network` export is in the kernel's table. ZFS's own file in `/etc/exports.d` goes with the + property. This replaces step 6 of section 5 for a property that exports to the home network. +- **No jail.** The mesh's jails never ban a private address (ADR 0186), so a jail on 445 could ban + nobody. +- **No data moves.** The library, its owner and modes, its dataset, and Samba's password database + stay where they are. + +Taking it into use, in order: the two modules are built and the home server's `smb-server` assignment +is made with its settings reproducing the hand-written share; `adopt`'s dry run is read; the operator +confirms it; a device on the home network lists the library over SMB; the NFS grant to `local-network` +is set and a device mounts it with NFS version 4; then the ZFS property is adopted. Each step's undo +is the one before it: unassign, the dated copy, the old property value set by a person. + ## Not in this design -- **Samba.** Kept as found. An `smb-share` seat follows when a node needs it. -- **Clients on the underlay.** NFS for devices that are not nodes waits on issue 154. +- **Finding a share by announcement.** A device finds the SMB share by the home server's name or + address; announcing it over mDNS waits on issue 154. +- **NFS version 3 for devices on the home network.** The server serves version 4 only (section 1). - **Mounting when a device appears.** Waits on a local-link reach (issue 154), because the packet filter drops mDNS. The automount already mounts on the next access.