docs(nas): add DW-Backups activation checklist (root-context autofs, not Finder mount)

fb2f00f3f4ce691b3b8895741d00841781927db7 · 2026-08-07 08:21:47 -0700 · Steve Abrams

Cleanup 2/2 from TK-10323: the NAS 2TB share isn't racked yet, so mounting
can't be scripted today. Documents the copy-paste activation steps for when it
arrives, and flags the root-vs-user mount gotcha — the nightly runs as a root
LaunchDaemon so a per-user Finder SMB mount won't be seen; use autofs (Path B).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Files touched

A patches/nas-activation-checklist.md

Diff

commit fb2f00f3f4ce691b3b8895741d00841781927db7
Author: Steve Abrams <steve@designerwallcoverings.com>
Date:   Fri Aug 7 08:21:47 2026 -0700

    docs(nas): add DW-Backups activation checklist (root-context autofs, not Finder mount)
    
    Cleanup 2/2 from TK-10323: the NAS 2TB share isn't racked yet, so mounting
    can't be scripted today. Documents the copy-paste activation steps for when it
    arrives, and flags the root-vs-user mount gotcha — the nightly runs as a root
    LaunchDaemon so a per-user Finder SMB mount won't be seen; use autofs (Path B).
    
    Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 patches/nas-activation-checklist.md | 101 ++++++++++++++++++++++++++++++++++++
 1 file changed, 101 insertions(+)

diff --git a/patches/nas-activation-checklist.md b/patches/nas-activation-checklist.md
new file mode 100644
index 0000000..872ddaf
--- /dev/null
+++ b/patches/nas-activation-checklist.md
@@ -0,0 +1,101 @@
+# NAS 2 TB share (`DW-Backups`) — activation checklist
+
+**Status:** NOT ACTIVE yet (no NAS on the network as of 2026-08-07). `latest.json`
+verdict is `PARTIAL` — Henry leg PASS, NAS leg correctly skipped. Backups are **not**
+at risk: you still have 2 current copies (Kamatera cloud dump + Henry local dump).
+This adds the *third* copy / second on-prem medium for full 3-2-1.
+
+Copy-paste this the day the NAS is racked. Ref: TK-10323.
+
+---
+
+## ⚠️ Read first — the root-context gotcha (this is the TK-10323 trap all over again)
+
+The nightly pull now runs as a **root `LaunchDaemon`** (`/Library/LaunchDaemons/com.steve.nas-dwdump-mirror-root.plist`,
+`HOME=/var/root`, fires 03:45). That was the fix for the original problem: a *user*
+process couldn't write the external volume under launchd (TCC).
+
+The same context boundary bites SMB: **a share mounted via Finder → Connect As is a
+per-user session mount.** A root daemon may not see it, and it drops when you log out.
+So do NOT rely on a Finder mount for the nightly. Two paths below:
+
+- **Path A (quick, attended only):** Finder mount — fine to *test* the pull by hand, but
+  the root nightly likely won't see it. Don't stop here.
+- **Path B (robust, what the nightly needs):** a root-context mount (autofs) so the
+  daemon reliably sees `/Volumes/DW-Backups` regardless of who's logged in. **Do Path B.**
+
+---
+
+## 1. On the NAS web admin (Synology DSM / QNAP / TrueNAS)
+
+1. Create two shares: `DW-Archive` (4 TB) and `DW-Backups` (2 TB).
+2. Enable **SMB** on both.
+3. Create a dedicated NAS user (e.g. `fleet`) with **read/write** on both shares. Save the
+   password — you'll route it via the `secrets` skill and into the root keychain (step 3).
+4. Note the NAS hostname or IP (call it `<nas-host>` below).
+
+## 2. Sanity-test the mount by hand (Path A — proves creds/share work)
+
+```sh
+open "smb://<nas-host>/DW-Backups"     # Finder → Connect As → user 'fleet' → save to Keychain
+ls /Volumes/DW-Backups                 # should list the share root
+```
+
+Optional one-shot attended pull to confirm the script writes it:
+
+```sh
+NAS_BACKUP_DIR=/Volumes/DW-Backups/dw_unified ~/Projects/nas-setup/scripts/pull-dw-dump.sh
+cat ~/Projects/nas-setup/data/latest.json   # expect verdict PASS (both legs) once mounted
+```
+
+The script needs **no changes** — `pull-dw-dump.sh` already calls the NAS leg
+unconditionally (`NAS_BACKUP_DIR` default `/Volumes/DW-Backups/dw_unified`) and skips it
+with a logged WARNING while unmounted.
+
+## 3. Make the root nightly see it (Path B — autofs, root-context)
+
+A user Finder mount won't reliably reach the root daemon. Mount via **autofs** so it's
+system-wide and credential-backed for root. These are `sudo` steps — surface them to
+Steve to paste (classifier blocks autonomous sudo):
+
+```sh
+# a. store the fleet creds for root (nsmb.conf is root-readable; or use root keychain)
+sudo tee -a /etc/nsmb.conf >/dev/null <<'EOF'
+[<NAS-HOST>:FLEET]
+addr=<nas-host>
+EOF
+# password: prefer `security add-internet-password` in the ROOT keychain, not plaintext.
+
+# b. autofs map entry
+echo '/-  auto_dwbackups  -nosuid' | sudo tee -a /etc/auto_master >/dev/null
+sudo tee /etc/auto_dwbackups >/dev/null <<'EOF'
+/Volumes/DW-Backups  -fstype=smbfs  ://fleet@<nas-host>/DW-Backups
+EOF
+sudo automount -vc     # reload maps
+```
+
+Then confirm root can reach it (mirror the probe that validated the Henry root daemon):
+
+```sh
+sudo -H bash -c 'ls /Volumes/DW-Backups && touch /Volumes/DW-Backups/.root-write-probe && rm /Volumes/DW-Backups/.root-write-probe && echo ROOT-WRITE-OK'
+```
+
+## 4. Kick the daemon and verify the verdict flips to PASS
+
+```sh
+sudo launchctl kickstart -k system/com.steve.nas-dwdump-mirror-root
+tail -5 ~/Projects/nas-setup/data/latest.json    # verdict should be PASS (Henry + NAS both OK)
+tail -20 ~/Projects/nas-setup/data/launchd-dwdump-root.out.log
+```
+
+Repeat step 3–4 keyed to `com.steve.nas-realestate-dump-mirror-root` if you also want the
+realestate dump on the NAS (its `NAS_BACKUP_DIR` would be `/Volumes/DW-Backups/realestate`).
+
+## 5. Don't forget
+
+- **4 TB `DW-Archive` share + Time Machine** are separate, later steps (see README.md §
+  "not live yet"). This checklist only covers the `DW-Backups` backup leg.
+- Add the NAS to `disk-space-canary` once mounted — see sibling
+  `patches/disk-space-canary-add-nas.md`.
+- After the NAS is live, `verdict:"PARTIAL"` becomes the *alert* condition (it should be
+  PASS every night); until then PARTIAL is expected/healthy.

← 0003120 auto-data-snapshot: 2026-08-07T08:00:20 (3 data files) — lau · back to Nas Setup · chore(nas): commit root-daemon installer scripts (TK-10323 a 17bd6ce →