homelab-blueprint/docs/unas/nfs-mounts.md

U-NAS Pro Mounts on Proxmox

Persistent mounts for the UniFi Drive shares on the Proxmox host, and how to bind-mount each share into the LXC that consumes it. Most shares use NFS; mobile_photos and youtube_downloads use SMB/CIFS.

Understanding the U-NAS Path Structure

UniFi Drive stores share data under a volume UUID path. The UUID is permanent for the lifetime of the Btrfs pool and is the same UUID you see when you run ll /volume/ on the UNAS.

Each share's user data lives inside a .data subdirectory. The sibling .trashcan, .uploads, .snapshot, and similar directories are UniFi Drive internals — never mount or write to them directly.

/volume/<UUID>/.srv/.unifi-drive/<share>/
├── .data/        ← actual user data, this is what you mount
├── .trashcan/    ← UniFi Drive internal
└── .uploads/     ← UniFi Drive internal

Your volume UUID confirmed from ll /volume/:

b69055de-0b30-4e8c-b7ef-b533d92733c3

Share Map

Share	Proxmox host mountpoint	LXC consumer
arr_data	/mnt/unas/arr_data	arr-stack LXC
forgejo_data	/mnt/unas/forgejo_data	forgejo LXC
gramps_data	/mnt/unas/gramps_data	gramps-web LXC (mounted as /mnt/gramps_media)
immich_data	/mnt/unas/immich_data	immich LXC
mobile_photos	/mnt/unas/mobile_photos	immich LXC (PhotoSync SMB target; mounted read-only as /mnt/mobile)
paperless_data	/mnt/unas/paperless_data	paperless LXC
pbs_backup	/mnt/unas/pbs_backup	PBS datastore (host-level, no LXC bind)
youtube_downloads	/mnt/unas/youtube_downloads	Youtarr LXC 103 (ytd)

1. Enable NFS

1a. Enable the NFS service globally

NFS is a global service that must be switched on before any per-share settings appear.

1. Open the UniFi OS web interface.
2. Go to Drive → Settings → Services.
3. Enable NFS.
4. Save.

1b. Enable NFS and set squash mode per share

Repeat for every share in the list.

1. Go to Drive → Shares.
2. Click a share name to open its settings.
3. Under Sharing Protocols, enable NFS.
4. Under NFS Hosts, add the Proxmox host IP (not the LXC IP).
5. Set the squash mode:
   • arr_data, forgejo_data, gramps_data, immich_data, paperless_data: set to No Root Squash (Isolated Mode). This allows the Proxmox host root to chown files so that container users (UID 1000) can write.
   • pbs_backup: default squash mode is fine.
6. Set access to Read/Write.
7. Save and confirm before moving to the next share.

LXC containers do not mount NFS directly. The Proxmox host is the only NFS client; LXCs get access via bind mounts from the host.

mobile_photos and youtube_downloads are mounted on the Proxmox host over SMB/CIFS using /etc/unas-smb-credentials, then bind-mounted into their consumer LXCs.

Why No Root Squash for some shares? UniFi Drive's default NFS mode squashes the client root to an anonymous UID (977:988). That anonymous user cannot chown files to UID 1000, so container services would be locked out. No Root Squash lets the Proxmox host root set ownership once during setup. The NFS export is already restricted to a single trusted IP, so the security exposure is contained.

2. Install NFS Client Tools on Proxmox

apt update && apt install -y nfs-common

3. Discover the Exact Export Paths

UniFi Drive exports at the .data level. Use showmount to confirm the exact paths before writing anything to fstab.

UNAS_IP=10.0.10.25
showmount -e "$UNAS_IP"

Expected output — the UUID segment must match what you see in /volume/:

Export list for 10.0.10.25:
/volume/b69055de-0b30-4e8c-b7ef-b533d92733c3/.srv/.unifi-drive/arr_data/.data          10.0.10.10
/volume/b69055de-0b30-4e8c-b7ef-b533d92733c3/.srv/.unifi-drive/forgejo_data/.data       10.0.10.10
/volume/b69055de-0b30-4e8c-b7ef-b533d92733c3/.srv/.unifi-drive/gramps_data/.data        10.0.10.10
/volume/b69055de-0b30-4e8c-b7ef-b533d92733c3/.srv/.unifi-drive/immich_data/.data        10.0.10.10
/volume/b69055de-0b30-4e8c-b7ef-b533d92733c3/.srv/.unifi-drive/paperless_data/.data     10.0.10.10
/volume/b69055de-0b30-4e8c-b7ef-b533d92733c3/.srv/.unifi-drive/pbs_backup/.data         10.0.10.10

If a share is absent from the output, return to step 1 and confirm NFS is enabled for that share with the Proxmox host IP in the allowed-hosts list.

The two SMB shares will not appear in showmount.

4. Create Mountpoints

mkdir -p \
  /mnt/unas/arr_data \
  /mnt/unas/forgejo_data \
  /mnt/unas/gramps_data \
  /mnt/unas/immich_data \
  /mnt/unas/mobile_photos \
  /mnt/unas/paperless_data \
  /mnt/unas/pbs_backup \
  /mnt/unas/youtube_downloads

5. Add fstab Entries

Back up the current fstab, then open it for editing:

cp /etc/fstab /etc/fstab.bak
nano /etc/fstab

Add the following lines. The UUID in the export path must match what showmount -e returned in step 3. UniFi Drive 4.x exports NFSv3 only — vers=3 is required.

# U-NAS Pro NFS shares (NFSv3)
10.0.10.25:/volume/b69055de-0b30-4e8c-b7ef-b533d92733c3/.srv/.unifi-drive/arr_data/.data          /mnt/unas/arr_data          nfs vers=3,noatime,nofail,_netdev,x-systemd.automount,x-systemd.mount-timeout=10s 0 0
10.0.10.25:/volume/b69055de-0b30-4e8c-b7ef-b533d92733c3/.srv/.unifi-drive/forgejo_data/.data       /mnt/unas/forgejo_data       nfs vers=3,noatime,nofail,_netdev,x-systemd.automount,x-systemd.mount-timeout=10s 0 0
10.0.10.25:/volume/b69055de-0b30-4e8c-b7ef-b533d92733c3/.srv/.unifi-drive/gramps_data/.data        /mnt/unas/gramps_data        nfs vers=3,noatime,nofail,_netdev,x-systemd.automount,x-systemd.mount-timeout=10s 0 0
10.0.10.25:/volume/b69055de-0b30-4e8c-b7ef-b533d92733c3/.srv/.unifi-drive/immich_data/.data        /mnt/unas/immich_data        nfs vers=3,noatime,nofail,_netdev,x-systemd.automount,x-systemd.mount-timeout=10s 0 0
10.0.10.25:/volume/b69055de-0b30-4e8c-b7ef-b533d92733c3/.srv/.unifi-drive/paperless_data/.data     /mnt/unas/paperless_data     nfs vers=3,noatime,nofail,_netdev,x-systemd.automount,x-systemd.mount-timeout=10s 0 0
10.0.10.25:/volume/b69055de-0b30-4e8c-b7ef-b533d92733c3/.srv/.unifi-drive/pbs_backup/.data         /mnt/unas/pbs_backup         nfs vers=3,noatime,nofail,_netdev,x-systemd.automount,x-systemd.mount-timeout=10s 0 0

Create one root-only credential file for both SMB mounts:

# /etc/unas-smb-credentials
username=<unas-user>
password=<unas-password>
domain=WORKGROUP

chmod 600 /etc/unas-smb-credentials

Add the CIFS entries:

//10.0.10.25/mobile_photos  /mnt/unas/mobile_photos  cifs credentials=/etc/unas-smb-credentials,vers=3.0,iocharset=utf8,ro,nofail,_netdev,x-systemd.automount,x-systemd.mount-timeout=10s 0 0
//10.0.10.25/youtube_downloads /mnt/unas/youtube_downloads cifs credentials=/etc/unas-smb-credentials,vers=3.0,iocharset=utf8,rw,noperm,uid=0,gid=0,file_mode=0660,dir_mode=0770,nofail,_netdev,x-systemd.automount,x-systemd.mount-timeout=120s 0 0

6. Apply and Verify All Mounts

systemctl daemon-reload
mount -a

Confirm each share is mounted:

for share in arr_data forgejo_data gramps_data immich_data paperless_data pbs_backup; do
  findmnt /mnt/unas/$share || echo "MISSING: $share"
done

All NFS shares must show a source line. A MISSING line means the share is not mounted; check /etc/fstab for a typo in the export path or mountpoint, then confirm the UNAS IP is reachable.

Confirm the SMB-backed mounts separately:

findmnt /mnt/unas/mobile_photos
findmnt /mnt/unas/youtube_downloads

Quick write test for each share:

for share in arr_data forgejo_data gramps_data immich_data paperless_data pbs_backup; do
  touch /mnt/unas/$share/.mount-test && rm /mnt/unas/$share/.mount-test \
    && echo "OK: $share" || echo "WRITE FAIL: $share"
done

mobile_photos is read-only on the Proxmox host, so no write test is needed for that mount.

Verify that the Youtarr SMB mount is writable:

touch /mnt/unas/youtube_downloads/.mount-test
rm /mnt/unas/youtube_downloads/.mount-test

7. Bind Mounts into LXCs

Stop each LXC before adding mountpoints. Replace the VMID placeholders with your actual container IDs.

arr-stack LXC

ARR_VMID=120
pct stop "$ARR_VMID"
pct set "$ARR_VMID" -mp0 /mnt/unas/arr_data,mp=/mnt/unas/arr_data
pct start "$ARR_VMID"

youtube_downloads is consumed by a separate downloader LXC, not the arr-stack. See that LXC's own deployment guide when it is set up.

forgejo LXC

FORGEJO_VMID=<vmid>
pct stop "$FORGEJO_VMID"
pct set "$FORGEJO_VMID" -mp0 /mnt/unas/forgejo_data,mp=/mnt/unas/forgejo_data
pct start "$FORGEJO_VMID"

The forgejo compose reads FORGEJO_DATA_ROOT=/mnt/unas/forgejo_data from the .env file. That path must match the mp= value above.

immich LXC

IMMICH_VMID=121
pct stop "$IMMICH_VMID"
pct set "$IMMICH_VMID" -mp0 /mnt/unas/immich_data,mp=/mnt/unas/immich_data
pct start "$IMMICH_VMID"

The immich compose reads IMMICH_UPLOAD_LOCATION=/mnt/unas/immich_data from the .env file. That path must match the mp= value above.

Add the SMB-backed mobile_photos mount to the same LXC so the Immich container can read it as /mnt/mobile:

pct set "$IMMICH_VMID" -mp1 /mnt/unas/mobile_photos,mp=/mnt/unas/mobile_photos

gramps-web LXC

The gramps-web compose binds /mnt/gramps_media from the LXC filesystem, so the NFS share is bind-mounted to that path inside the LXC — not to /mnt/unas/gramps_data.

GRAMPS_VMID=122
pct stop "$GRAMPS_VMID"
pct set "$GRAMPS_VMID" -mp0 /mnt/unas/gramps_data,mp=/mnt/gramps_media
pct start "$GRAMPS_VMID"

paperless LXC

PAPERLESS_VMID=123
pct stop "$PAPERLESS_VMID"
pct set "$PAPERLESS_VMID" -mp0 /mnt/unas/paperless_data,mp=/mnt/unas/paperless_data
pct start "$PAPERLESS_VMID"

pbs_backup — cold rsync target only

NFSv3 does not support extended attributes (xattr), which PBS requires for its chunk store. The pbs_backup share cannot be used as a live PBS datastore.

The PBS datastore lives on a dedicated local ext4 volume inside the PBS LXC (/mnt/datastore/pbs). The pbs_backup NFS share is mounted on the Proxmox host at /mnt/unas/pbs_backup for use as a periodic rsync cold copy of the local datastore — a second copy in case the Proxmox NVMe fails.

No LXC bind mount is needed for this share.

8. Verify Inside Each LXC

After starting each LXC, confirm the bind mount is present and writable.

# From inside the LXC (pct enter <VMID>)
ls /mnt/unas/arr_data
touch /mnt/unas/arr_data/.lxc-write-test && rm /mnt/unas/arr_data/.lxc-write-test && echo OK

Repeat for each share with its mount path. If the write test fails with Permission denied, the owning UID on the NFS share does not match the container user. Fix ownership from the Proxmox host:

chown -R 1000:1000 /mnt/unas/<share>

This only works if the share was configured with No Root Squash in step 1. UniFi Drive's default squash mode maps the Proxmox host root to an anonymous UID (977:988) that does not own the .data directory and cannot chown files. With No Root Squash the host root retains root privileges on the UNAS, allowing ownership to be set correctly before containers start.