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

---
title: Add an NFS Share on pi-nas (OpenMediaVault RPC)
type: runbook
tags:
  - storage
aliases: []
related:
  - [[pi-nas-omv-runbook]]
  - [[pve-guest-park-and-adopt]]
  - [[proxmox-onboard-node]]
  - [[proxmox-create-ubuntu-vm]]
  - [[ct-runbook]]
updated: 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:

```bash
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:

```bash
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 `..`.

```bash
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.

```bash
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:

```bash
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:

```bash
# 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:

```bash
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:

```bash
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.