# REPORT — v0.152.0 + felhom-samba 1.1.0: mDNS for macOS (S-3), and the connect card stops offering a dead form

**Date:** 2026-07-20 · **Repo:** felhom-controller (v0.151.0 → **v0.152.0**) + **felhom-samba
1.0.0 → 1.1.0** · Trunk, pushed to `main`.
**Origin:** operator report — `smb://FELHOM` still failing from a Mac after v0.151.0; S-3 of
`felhom.eu/documentation/audits/DIAG-sharing-2026-07-20.md`.

## Baselines

| Repo / artifact | start | end |
|---|---|---|
| felhom-controller | `5c105fb`, v0.151.0 live on 9201 | `37e12c8` (+ this docs commit), **v0.152.0** |
| felhom-samba | `1.0.0` | **`1.1.0`**, digest `sha256:1c17c094…` |
| felhom.eu | `a7d9837` | `1d1d60a` |

## The finding that redirected the fix

My earlier conclusion — "macOS no longer does NetBIOS" — **was wrong**, and a packet capture on the
box disproved it. On a bare `smb://FELHOM` from the operator's Mac (`192.168.0.11`):

```
11:18:30.222080  .11:52844 > 192.168.0.255:137   NBNS query, 50 B
                 name → "FELHOM" + 9 pad + suffix 0x20  (File Server Service — correct for SMB)
11:18:30.222220  .104:137 > .11:52844            NBNS response, 62 B, +140 µs
                 flags 0x8580 = response, AUTHORITATIVE, RCODE=0 · ANCOUNT 1
                 TTL 259200 · NB_FLAGS 0x0000 (unique, B-node) · RDATA 192.168.0.104
```

**macOS asked correctly, was answered correctly in 140 microseconds, and never opened a TCP
connection.** It retried once, was answered again, gave up. Sixteen seconds later the same Mac
queried `FELHOM.local` over mDNS and went straight to port 445.

So NetBIOS on macOS feeds legacy browsing, not `smb://` URL resolution: **the bare `smb://<NÉV>`
cannot be made to work from a Mac by any change on our side**, and nmbd — which the R-6/S4b spike
was right to insist on — was never the broken part. It is precisely what serves Windows.

Investigated and dismissed: the box answers **twice** per broadcast (nmbd holds `0.0.0.0:137`,
`<ip>:137` and `<bcast>:137`; a broadcast lands on two). Standard Samba, and a duplicated correct
answer is still a correct answer that macOS declined to use.

### Proven matrix

| Client | Working form | Served by |
|---|---|---|
| Windows | `\\<NÉV>` | nmbd (+ wsdd for the Network view) |
| macOS | **`smb://<NÉV>.local`** | avahi/mDNS — new in 1.1.0 |
| Any | `smb://<IP>` | direct |

## Method — spike before publish (operator's call, and it paid)

avahi was installed by hand into the *running* container and configured, then proven from a second
machine before any image was built. The operator confirmed `smb://FELHOM.local` connects. Only then
was 1.1.0 built. The spike also chose the design: a **static avahi service file** beats smbd's own
`multicast dns register`, because `smb.conf` is bind-mounted READ-ONLY and owned by the controller's
renderer, and a static file additionally publishes `_device-info._tcp`.

## Changes

| File | Change |
|---|---|
| `controller/infra-images/samba/Dockerfile` | `avahi` + `dbus` added; `rm` of packaged service files; header documents the captured NBNS proof and that sidebar discovery is NOT claimed |
| `controller/infra-images/samba/entrypoint.sh` | templates `avahi-daemon.conf` + `_smb._tcp`/`_device-info._tcp` service file **from `FELHOM_SERVER_NAME`**; starts dbus + avahi, both **non-fatal** |
| `controller/internal/infra/infra.go` | `SambaImage` pin → `1.1.0` (`Images()` and the golden bake follow automatically) |
| `controller/internal/web/templates/sharing.html` | Mac line `smb://<NÉV>` → **`smb://<NÉV>.local`**; Windows flat name untouched |
| `controller/internal/web/sharing_connect_card_test.go` | assertions updated + new `TestSharingConnectCard_MacLineIsDotLocalNotBareName` |
| `controller/internal/infra/samba_test.go` | tag assertion derives from `SambaImage`; adds an explicit non-`:latest` assertion |
| `controller/internal/web/handler_export_upload_test.go` | async-race fix (below) |
| `CHANGELOG.md`, `controller/README.md`, `REPORT.md` | docs |

## Tests

**23/23 packages green, run twice with `-count=1`.**

Red-proofs, both mutated → FAILED → restored:

| Mutation | Result |
|---|---|
| revert the template's Mac line to the bare `smb://{{.SMBServerName}}` | `TestSharingConnectCard_MacLineIsDotLocalNotBareName` **FAILED** on both the missing `.local` and the present bare form, for both configured names (`FELHOM`, `OTTHON`) |
| delete `os.Remove(job.partPath)` from `expireIdleUpload` | `TestFabUpload_GCAndIdleTimeout` **FAILED** — `idle-expired .part must be deleted` |

### Two test bugs found, neither a production defect

1. **`TestRenderSambaCompose` pinned the literal tag `1.0.0`**, so a routine image bump read as a
   renderer regression. Now derives from `SambaImage`, plus a separate assertion for what actually
   matters — the tag is explicit and never `:latest`.
2. **`TestFabUpload_GCAndIdleTimeout` raced.** `expireIdleUpload` nils the slot, releases the mutex,
   and only *then* closes and unlinks the `.part` — so "the slot is free" does not yet mean "the file
   is gone", and the test stat-ed immediately. It passed in isolation and failed in the full package
   once this release's new render tests made `web` heavier. **Not caused by this change and not a
   production bug** (a new upload mints a fresh random `.part`, so the gap is harmless); the test was
   asserting an async post-condition synchronously. It now waits on the same 3 s deadline with the
   assertion unchanged.

Design gates `template_id_gate` / `emoji_gate` / `native_confirm_gate` / `offbox_rename_gate`: **OK**.

## Build, publish, deploy

```
./controller/scripts/build-samba-image.sh 1.1.0 --push   → sha256:1c17c09422be…
smoke test (DooPlex, DEFAULT BRIDGE — never --network host on this host, it would bind 445/5353)
  → smbd · nmbd · wsdd · dbus-daemon · avahi-daemon: running [SMOKETEST.local]   (all 5 up)
  → host-name=SMOKETEST, allow-interfaces=eth0, _smb._tcp/445 in the service file
anonymous pull from guest 9201 (no registry creds) → OK
./build.sh 0.152.0 --push  → deployed to 9201
```

Live: `felhom-controller:0.152.0 Up (healthy)` · `felhom-samba:1.1.0 Up` — the controller's reconcile
recreated the samba container onto the real image, discarding the hand-patched spike.

## Live validation

**Method: on-the-wire from a second machine (felhom-pve) + endpoint-level for the page.**

```
mDNS from felhom-pve, against the SHIPPED image:
  FELHOM.local (A)     -> A 192.168.0.104              (from 192.168.0.104)
  _smb._tcp (browse)   -> PTR FELHOM._smb._tcp.local   (from 192.168.0.104)

daemons in felhom-samba:1.1.0: smbd · nmbd · wsdd · dbus-daemon · avahi-daemon: running [FELHOM.local]

GET /sharing            -> smb://FELHOM.local   smb://192.168.0.104   \\FELHOM
GET /sharing/status ×2  -> phase:"idle", running:true   (v0.151.0 contract still holding)
```

Operator, from the Mac: **`smb://FELHOM.local` connects and prompts for credentials.**

## Still open

- **Finder-sidebar discovery — NOT shipped, NOT claimed.** The `_smb._tcp` record is published and
  answers browse queries on the wire, but FELHOM did not appear in the operator's Finder sidebar.
  That window showed no Network/Bonjour section at all, which points at **Finder Settings → Sidebar
  → Locations** rather than at the box — unverified either way. Next: that setting, and
  `dns-sd -B _smb._tcp` on the Mac. Zero-typing discovery was the R-6 spike's original ambition and
  is still not demonstrated.
- **Windows was not retested** this session. `\\FELHOM` is served by nmbd, which this release does
  not touch, and the capture proves nmbd answers correctly — but no Windows client was exercised.

## Observations — noticed, not acted on

- **The username trap.** macOS prefills the local account name (`Viktor.Nagyfenyvesi`) in the SMB
  credential dialog; the household account is `felhom`. The page states this in the password card,
  but not next to the connect addresses where the customer is looking at that moment. Worth a
  sentence in the connect card — deliberately not added mid-session without a design pass.
- **nmbd's duplicate answer** is harmless here but would look alarming in any future capture. Noted
  in the DIAG so the next person does not re-investigate it.
- **The spike left avahi installed by hand** in the old container. It was discarded when the
  reconcile recreated the container on 1.1.0 — worth remembering that hand-patching a *managed*
  infra container is always temporary by construction, which is a safety property, not a limitation.
- **`dns-sd`/`avahi-browse` were not available** anywhere on the box side, so both the NBNS and mDNS
  verifications were done with small hand-written UDP probes run from felhom-pve. That turned out to
  be the more valuable method anyway: querying from a *second machine* is what distinguishes "the
  daemon answers itself" from "the daemon answers the network", and it is what proved the box
  innocent before any code changed.