echo6-docs/vault/runbooks/omv-add-nfs-share.md

title	type	tags	aliases	related	updated
Add an NFS Share on pi-nas (OpenMediaVault RPC)	runbook	storage		pi-nas-omv-runbook pve-guest-park-and-adopt proxmox-onboard-node proxmox-create-ubuntu-vm ct-runbook	2026-08-14

Add an NFS Share on pi-nas (OpenMediaVault RPC)

pi-nas runs OpenMediaVault 8.4.0 (Synchrony). Never hand-edit /etc/exports or /etc/fstab on this box. Both are auto-generated from OMV's config database and carry the warning header; hand edits are silently reverted the next time any OMV config is applied, which will happen eventually whether or not you trigger it.

Create shares through OMV's RPC instead. The web UI does the same thing, but RPC is scriptable and works over SSH.

Initial NAS build is pi-nas-omv-runbook.

---

Key facts

The new-object sentinel UUID is how OMV signals "create this, don't update":

fa4b1c66-ef79-11e5-87a0-0002b3a176b4

Resolve it yourself if ever in doubt:

sudo php -r 'require_once("/usr/share/php/openmediavault/autoloader.inc");
  echo \OMV\Environment::get("OMV_CONFIGOBJECT_NEW_UUID"),"\n";'

Filesystem references (mntentref) as of 2026-08-14:

Disk	Size / role	mntentref
sda+sdb	2.7 TB btrfs RAID1 — the only mirrored pool	423365c2-513c-4900-bbde-a2e7b21e6bd5
sdc1	24 TB ext4, single	a3c6d71c-527d-45a3-aab7-1868e858456f
sdd1	24 TB ext4, single — carries PeerTube	79238c6b-1064-4ac9-9564-b12fc8608b74

Re-read them at any time:

sudo omv-rpc -u admin "ShareMgmt" "getList" '{"start":0,"limit":-1}'

---

1. Create the shared folder

reldirpath is relative to the chosen filesystem's mount point and must end in /. It may not contain ...

sudo omv-rpc -u admin "ShareMgmt" "set" '{
  "uuid":"fa4b1c66-ef79-11e5-87a0-0002b3a176b4",
  "name":"pvebackup",
  "reldirpath":"pvebackup/",
  "comment":"Proxmox vzdump archives",
  "mntentref":"a3c6d71c-527d-45a3-aab7-1868e858456f",
  "mode":"775"
}'

It returns the created object. Keep the uuid — the NFS share references it.

2. Create the NFS share, once per client network

Pass the sentinel for mntentref as well; OMV overwrites it with the bind-mount entry it creates for /export/<name>.

no_root_squash is required for anything Proxmox writes as root, including vzdump. Omit it for shares that do not need it.

SF=<uuid from step 1>
NEW=fa4b1c66-ef79-11e5-87a0-0002b3a176b4

# LAN
sudo omv-rpc -u admin "NFS" "setShare" "{
  \"uuid\":\"$NEW\",\"sharedfolderref\":\"$SF\",\"mntentref\":\"$NEW\",
  \"client\":\"192.168.1.0/24\",\"options\":\"rw\",
  \"extraoptions\":\"subtree_check,insecure,no_root_squash\",
  \"comment\":\"pvebackup - local\"}"

# tailnet
sudo omv-rpc -u admin "NFS" "setShare" "{
  \"uuid\":\"$NEW\",\"sharedfolderref\":\"$SF\",\"mntentref\":\"$NEW\",
  \"client\":\"100.64.0.0/10\",\"options\":\"rw\",
  \"extraoptions\":\"subtree_check,insecure,no_root_squash\",
  \"comment\":\"pvebackup - tailnet\"}"

extraoptions is pattern-validated: comma-separated words only, no spaces.

3. Apply

Scope it to the modules actually affected rather than applying everything:

sudo omv-rpc -u admin "Config" "applyChanges" '{"modules":["fstab","nfs"],"force":false}'

This regenerates /etc/exports, creates the bind mount, and re-runs exportfs.

4. Verify — including that you broke nothing

exportfs re-runs against live clients. Existing mounts survived this in practice, but confirm rather than assume:

# on pi-nas
sudo exportfs -v | grep -A1 pvebackup
df -h /export/pvebackup
sudo exportfs -s | grep -oE '^/export/[a-z]+' | sort -u

Then check every existing consumer still reads. As of 2026-08-14 those are media (/mnt/peertube-storage) and cloud (/mnt/nfs-immich, /mnt/nfs-nextcloud) — see services.

---

Mounting it in Proxmox

Storage config is cluster-wide, so run this once on any node and all five pick it up:

pvesm add nfs pinas-backup --server 192.168.1.245 \
  --export /export/pvebackup --content backup --options vers=3

Confirm root can actually write, which is what no_root_squash buys:

dd if=/dev/zero of=/mnt/pve/pinas-backup/.writetest bs=1M count=32 && \
  rm /mnt/pve/pinas-backup/.writetest && echo OK

Content types matter. backup is for vzdump archives; images,rootdir would let guests run directly from NFS, which was deliberately not done — see pve-guest-park-and-adopt for why.

---

Redundancy warning

Only sda+sdb are mirrored (btrfs RAID1, 2.7 TB, ~2.1 TB free). sdc and sdd are single ext4 drives with no redundancy despite holding the bulk of the data, including PeerTube's library. Put anything that must survive a drive failure on the mirrored pool.