felhom.eu/documentation/controller/sharing.md

Controller — LAN file sharing over SMB („Megosztás")

Code-verified feature doc. Matches felhom-controller v0.144.0 (R-7 slice 1) and the infra image gitea.dooplex.hu/admin/felhom-samba:1.0.0. Transport/discovery verdicts come from documentation/audits/SPIKE-lan-discovery-2026-07-18.md (R-6). Where this doc and the code disagree, the code wins — update this file.

What the customer gets

The box behaves like a NAS on the home network. On „Megosztás" → „Hálózati megosztás" the customer turns sharing on, sets ONE household SMB password, and exports folders. The box then appears in Windows Explorer's Network view (and in Mac Finder) as \\FELHOM; opening a share and writing to it works from any household device. Sharing is LAN-only — it is never exposed through the tunnel.

Why it is NOT a catalog app

SMB ships as an embedded controller feature — the fourth protected infra stack (traefik / cloudflared / filebrowser / samba). Three reasons, all structural:

1. Host networking is mandatory. The R-6 spike proved the default Docker bridge is categorically deaf to the LAN multicast that WSD and mDNS discovery need; only a container in the guest's own network namespace can send and receive it.
2. Its config is a generated share list, rendered into smb.conf — not a handful of env vars a catalog template could carry.
3. Its share roots must ride the backup classification, which catalog metadata cannot express for absolute, customer-chosen paths.

The image (felhom-samba:1.0.0)

Built from controller/infra-images/samba/ by controller/scripts/build-samba-image.sh. Pinned alpine 3.21 (by digest) running three daemons under tini:

Daemon	Port(s)	Why
smbd	445	the SMB/CIFS server itself
nmbd	137/138	NetBIOS flat-name resolution — without it the box is visible in Explorer but the double-click fails 0x80070035 (S4b of the spike: WSD hands Explorer an icon, not a name→IP mapping)
wsdd	3702 / 5357	WS-Discovery, so the box appears in Explorer's Network view at all

The image is deliberately dumb: /etc/samba/smb.conf is bind-mounted READ-ONLY by the controller, nothing is templated inside, and no share name or password is ever baked in. The passdb lives on a named volume (samba-passdb) so the household password survives container recreation. Never tagged :latest; the controller pins the exact tag in the compose it generates.

Configuration model

Persisted in settings.json (internal/settings/smb.go):

• smb: {enabled, server_name, user_set} — server_name is the NetBIOS name (≤15 chars, letters/digits/hyphen/underscore; default FELHOM).
• smb_shares: [{name, path, read_only, offsite, created_at}] — the share registry.

The SMB password is never persisted. Only the boolean user_set is stored. The secret is passed to smbpasswd on STDIN (never argv, which is world-readable via /proc), is never logged, and never appears in smb.conf, the compose file, or settings.json.

Generated smb.conf

Global block (hardened, all controller-managed):

  server min protocol = SMB2      # no SMB1
  security = user                 # named auth only
  map to guest = never            # no anonymous access, ever
  disable netbios = no            # nmbd on → \\NAME resolves
  bind interfaces only = yes
  interfaces = lo eth0            # LAN + loopback ONLY, never the docker bridges

Each share adds a section with force user/force group = felhom (uid:gid 1000), so files written over SMB carry the same ownership the apps and both backup tiers expect:

[dokumentumok]
  path = /mnt/felhom-drives/hdd_1/shares/dokumentumok
  read only = no
  valid users = felhom
  force user = felhom
  force group = felhom

A read-only share gets read only = yes and a :ro bind in the compose file — defence in depth, so a samba misconfiguration alone cannot make it writable.

Lifecycle

ensureSamba runs inside EnsureBaseStack (boot + every health tick) after filebrowser, gated on smb.enabled — the same conditional-deploy shape cloudflared uses. ReconcileSamba runs after every share/settings mutation: re-render → atomic write (tmp + fsync + rename) → compose up -d.

• Idempotent: unchanged config plus a running container performs zero compose calls.
• No password, no deploy: with sharing on but no household password set, the stack stays undeployed and the UI blocks with „először adj meg jelszót". (Setting the password brings the stack up as part of that action — safe, because security = user + map to guest = never means nothing is reachable until the password lands.)
• Dead mounts are never exported: a share whose drive is disconnected or decommissioned is rendered ABSENT from smb.conf (publishing a missing mountpoint would show an empty share and let a write land on the underlying root instead of the drive). Its configuration is retained, and the UI row shows „A meghajtó nem elérhető."

This feature never deletes customer data

There is no file-removal path in it at all. Disabling sharing is compose down (the passdb volume and every shared folder are kept). Deleting a share is a config-only edit — the UI says so explicitly: „A megosztás törölve — a mappa és a fájlok megmaradtak." The only directory creation is the guarded new-share-folder create.

Choosing what to share — the picker guard

Shares can be a new folder under <storage>/shares/, or any existing folder, with one exception class: system data. Every customer-supplied path goes through sharingResolvePath:

1. must be absolute;
2. EvalSymlinks before the containment check — a symlink planted inside a storage root cannot point outside it;
3. must resolve inside a registered, live storage root (decommissioned roots are out);
4. must not be inside a deny-listed system subtree — appdata/ (sharing a live app database writable over SMB is a corruption foot-gun), backups/, the legacy felhom-data/ nest;
5. the drive root itself is refused (a whole drive is never shareable) — an exact-match rule, so ordinary user-data folders under it stay shareable;
6. must be a directory.

Every refusal returns the same message („Ez a mappa nem osztható meg.") so the picker can never be used as an oracle for what exists outside the customer's storage.

The deny-list is derived from stacks.ProtectedHDDPaths (each entry is emitted only if that guard already contains it), so it can only ever shrink relative to the delete guard — it can never drift into a stale second source of truth. media/ and Dokumentumok/ are protected there as delete targets but are customer data and remain shareable.

The new-folder flow uses a separate, strictly tighter check (sharingResolveStorageRoot) that accepts exactly a registered live storage root — because there the root is the parent, not the share.

Backup classification

ClassifiedBinds("samba") resolves from the shares registry instead of catalog metadata (samba has no .felhom.yml, and its binds are absolute share paths):

Per-share „Felhőmentés"	Class	Tiers
ON (default for new shares)	mandatory	offsite and tier-2
OFF	optional	tier-2 only (never offsite)

smb.conf and the passdb are config, not customer data, and are never classified.

KNOWN GAP — share data is classified but not yet backed up. Making this seam correct does not by itself put share data into a live run: backup.RunTier2 short-circuits on a missing recovery unit before it ever calls GetStackClassifiedBinds, and the offsite runner enumerates settings.GetOffboxApps(). Both engines are recovery-unit shaped, which a share-only infra stack has not. Teaching them about one is a structural change, so it was reported as a design fork rather than improvised inside the engines. Until it is resolved, do not tell a customer that files dropped on a share are backed up. See felhom-controller/REPORT.md §4.

Operator notes

• samba is protected in code (config.alwaysProtectedStacks), because cfg.Stacks.Protected comes from the golden-generated controller.yaml and predates the feature. Consequence: monitor.EffectiveProtected does not monitor samba liveness — a dead samba container raises no "protected container missing" issue. Deliberate for slice 1 (the safe direction: no false alarms while the feature is off).
• Discovery depends on the household LAN. The R-6 spike's §7d caveat applies: a customer network with IGMP snooping enabled and no querier could prune the discovery multicast, and a BYO topology may put the guest on a bridge with no L2 path to the household LAN. The page carries an honest hint that the device list can lag while \\NÉV always works.
• The customer authenticates as user felhom with the household password.

Not in slice 1 (→ slice 2)

avahi / .local name publishing for modern + Apple clients; curated app-folder presets (one-click paperless consume/); per-share users and guest access; a recycle bin. DLNA is a separate item (R-8).