afaf019076
Files changed: engine/.embcache.json engine/changelog.md engine/lint-report.md vault/.obsidian/workspace.json vault/docs/hardware/environment.md vault/docs/services/services.md vault/projects/fleet-storage-memory-upgrade.md vault/projects/navi-recon-separation.md vault/runbooks/omv-add-nfs-share.md vault/runbooks/peertube-sitemap-redis-oom.md vault/runbooks/pve-guest-park-and-adopt.md
147 lines
4.7 KiB
Markdown
147 lines
4.7 KiB
Markdown
---
|
|
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.
|