From 2f76da210854af91de9864f9abf8167d65fa9ffd Mon Sep 17 00:00:00 2001 From: Vuong Hoang Date: Wed, 22 Apr 2026 11:26:17 -0700 Subject: [PATCH] docs/pbs-deployment: note ZFS case-insensitive + NFSv4 incompatibility Discovered during Phase 1.3 (mount NAS datastore). The Debian NAS's /mnt/backup is on ZFS with casesensitivity=insensitive; NFSv4 writes fail with EACCES even for root with no_root_squash. Known-bad combination at the ZFS-on-Linux + NFSv4 layer. Workaround: mount the NFS share with vers=3. PBS's chunk-based access pattern works fine over NFSv3. Added a section 0.5 to Phase 0 documenting the issue + both fixes (quick: use NFSv3; cleaner: create case-sensitive child dataset). Future deployments against this NAS won't rediscover the same wall. --- docs/runbooks/pbs-deployment.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/runbooks/pbs-deployment.md b/docs/runbooks/pbs-deployment.md index 64c76f8..414fa2d 100644 --- a/docs/runbooks/pbs-deployment.md +++ b/docs/runbooks/pbs-deployment.md @@ -63,6 +63,36 @@ so Cockpit doesn't clobber it. Not blocking PBS work but worth tightening during a Cockpit pass — reduce to `10.0.0.0/8` or more specific. Open item, not blocker. +### 0.5. ZFS case-insensitivity breaks NFSv4 writes + +The Debian NAS's `/mnt/backup` is a ZFS dataset with +`casesensitivity=insensitive`. ZFS + NFSv4 + case-insensitive dataset +is a known-bad combo: lookups/readdir work, `create`/`write` ops fail +with EACCES even for root with `no_root_squash`. + +**Workaround:** mount with NFSv3 instead of NFSv4. Update the VM's +`/etc/fstab` filesystem type to `nfs` and options to `vers=3`. PBS's +access pattern (dedupe chunks are writen-once/read-many) works fine +over NFSv3. + +Example `/etc/fstab` line that works: + +``` +10.250.50.50:/mnt/backup/pbs-ana /mnt/pbs-datastore nfs defaults,_netdev,bg,hard,timeo=600,retrans=2,vers=3 0 0 +``` + +**Cleaner long-term fix** (not required, but nicer): create a +case-sensitive child dataset for PBS's data: + +``` +sudo zfs create -o casesensitivity=sensitive -o mountpoint=/mnt/backup/pbs-ds \ + NASPool/backupStore/pbs-ds +``` + +Then export/mount `/mnt/backup/pbs-ds` via NFSv4 as originally planned. +Case-sensitivity can't be changed on an existing dataset, which is why +the parent is stuck on case-insensitive. + ## Phase 1 — Provision PBS-ANA (VM on pfi-pve) **Target state:** a fresh Debian 12 VM on pfi-pve running