NAS Kopia v1 backs up live datasets, deferring snapshot consistency

Date: 2026-06-28 Status: Accepted Decision: hl-zrbh Deciders: Sean Brandt

Context

ADR hl-9uzu chose per-leaf ZFS snapshot consistency for the NAS Kopia→B2 backup: a TrueNAS periodic snapshot task plus a Kopia --before-folder-action reading the newest per-leaf .zfs snapshot inside the nas-support sandbox. That design was explicitly gated on a build-time spike proving .zfs visibility through the sandbox bind-mount, with a “persistent-device” fallback.

The build spike (hl-ney2.1) and a follow-up salvage spike (hl-ney2.6) proved the assumption false and unrecoverable. The unprivileged libvirt/LXC sandbox bind-mounts are private and kernel-locked (MNT_LOCKED): ZFS snapshot automounts live in the host mount namespace and never propagate into the container; mount --make-rslave inside the container fails; and the TrueNAS FILESYSTEM device schema exposes no mount-propagation option. No per-run snapshot can become visible in the sandbox without restarting the container. The persistent-device fallback therefore reduces to “restart the container on every refresh.”

The epic’s stated priority is to protect currently-unprotected irreplaceable data as soon as possible.

Decision

For v1, Kopia (in the nas-support sandbox) backs up the LIVE datasets directly — no ZFS snapshots. The sandbox reads the data via host-side read-only ACLs (role nas-kopia-acls, the surviving half of hl-9uzu’s design). Point-in-time / application consistency for the actively-changing datasets (fzymgc-house/incus AresMUSH, paperless, future immich) is a documented fast-follow.

Rationale

• The salvage spike conclusively ruled out no-restart snapshot exposure (unprivileged-LXC mount lock); restart-per-backup was rejected for v1 because it disrupts the shared curation container and adds snapshot→reconfigure→restart→backup orchestration.
• The bulk of the scope is cold or append-mostly (multimedia, machine-archives, bwcgroup-data, cloud-sync-backup), where live reads are effectively consistent and Kopia tolerates concurrent change.
• An offsite, Object-Lock-protected backup running now beats blocking the entire epic on snapshot-consistency perfection.

Alternatives Considered

• Persistent snapshot as a FILESYSTEM device + container restart per refresh (deferred): gives consistency but restarts the sandbox per backup and adds orchestration; held for the consistency fast-follow.
• Hybrid — snapshots only for the live datasets (deferred): best correctness/effort balance but the most moving parts and per-dataset config; revisit in the fast-follow.

Consequences

• Positive: simplest path to protecting the data; removes the snapshot-task role, the .zfs selector (hl-ney2.9), and all restart orchestration; the hl-36m6 sandbox ships unchanged.
• Negative: a backup taken mid-write to a running VM/container image (incus/AresMUSH) may be inconsistent on restore until the consistency fast-follow lands.
• Neutral: supersedes hl-9uzu. The read-only ACL mechanism (idempotent POSIX1E/NFSv4 grants for uid 2147000001) is carried forward from hl-9uzu’s design and remains in use.

References

• Supersedes: hl-9uzu