Skip to content
fzymgc-house Cluster Docs

NAS Kopia snapshot consistency via TrueNAS snapshot-task plus per-leaf .zfs read

Date: 2026-06-28 Status: Superseded by hl-zrbh Decision: hl-9uzu Deciders: Sean Brandt

Context

Section titled “Context”

Kopia runs inside the UID-shifted nas-support LXC and cannot run host zfs; the TrueNAS host runs zfs but cannot run Kopia. hl-36m6’s sandbox bind-mounts only LEAF datasets (the pool root and parents-with-children fail to mount), and the sandbox’s macvlan NIC isolates host↔sandbox networking. The backup needs crash-consistent point-in-time reads, especially for the in-flight machine-archives Mac migration.

Decision

Section titled “Decision”

A host-autonomous TrueNAS periodic snapshot task (pool.snapshottask) snapshots each in-scope leaf nightly into main/<leaf>@kopia-<ts>. Kopia is invoked on the stable source path /mnt/main/<leaf> with a --before-folder-action (running inside the sandbox) that selects the newest per-leaf .zfs snapshot and points KOPIA_SNAPSHOT_PATH at it. No second NIC, no SSH channel, no sandbox→host privilege. A build-time spike must first prove .zfs visibility through the bind-mount.

Rationale

Section titled “Rationale”
  • Leaf-only mounts make per-leaf .zfs the natural read path; the host snapshot task decouples host and sandbox entirely — no networking or privilege crosses the boundary.
  • Kopia’s before-folder-action keeps a stable source identity (no --override-source) while redirecting reads to the snapshot, so incrementals stay clean.
  • It is strictly less privilege and complexity than the alternatives; the sandbox can only read its mounted data.

Alternatives Considered

Section titled “Alternatives Considered”
  • flock-coordinated two-timer fixed-name snapshot (rejected): clever, but torn-read-prone and needs a cross-boundary lock.
  • Bridge NIC + SSH-to-host + scoped zfs privilege + host-mounted snapshot (rejected): requires a pool-root shared mount that does not exist under leaf-only mounts, and adds a NIC, an SSH channel, and a host privilege.

Consequences

Section titled “Consequences”
  • Positive: simplest and safest option; the sandbox stays exactly as hl-36m6 shipped it; snapshots are appliance-native (UI-visible, upgrade-safe).
  • Negative: depends on the unproven .zfs-through-bind-mount assumption, gated by a mandatory build spike with a persistent-device fallback.
  • Neutral: timestamped snapshots require a small “pick newest” selector script.

References

Section titled “References”
  • Superseded by: hl-zrbh