Mount a NAS Share in a Proxmox LXC (NFS or SMB)
Mount an NFS or SMB share from your NAS into an unprivileged Proxmox LXC: host-side mounts, bind mount points, UID mapping, and the permission fixes that work.
You have a NAS full of media or documents, and a Proxmox LXC running Jellyfin, Immich or Paperless-ngx that needs to read it. The obvious move is to mount the share inside the container. In an unprivileged container that fails, and the workarounds people paste into forums range from fine to “just make it privileged”, which throws away the main safety feature of the container.
This guide covers the approach that holds up: mount the share once on the Proxmox host, bind-mount it into the container, and line up the user IDs so permissions work. It assumes you already have a Proxmox host and at least one container running, per the Proxmox beginner’s guide. If you are still deciding whether the service belongs in a container at all, read LXC vs VM in Proxmox first: a VM can mount NFS or SMB directly with none of this, at the cost of more RAM.
Quick Answer: Mounting a NAS Share in a Proxmox LXC
- Mount the share on the host under
/mnt/lxc_shares/<name>with an/etc/fstabline - Own it as the container’s mapped IDs:
uid=100000,gid=110000for SMB, or the same IDs set on the NAS for NFS - Create group
lxc_shareswith GID 10000 inside the container and add your service user to it - Add the bind mount:
pct set <CTID> -mp0 /mnt/lxc_shares/media,mp=/mnt/media - Start the container and check ownership with
ls -ln - Back up the share on the NAS, because Proxmox backups skip bind mounts
Why You Can’t Mount It Inside the Container
Two things get in the way.
Mounting is blocked. The Proxmox container docs list mount among the system calls the default AppArmor profile prohibits. There is a per-container feature flag (features: mount=nfs or mount=cifs) that lifts this, but the same docs warn that an NFS mount inside a container can block the host’s I/O completely and stop it from rebooting. That is a bad trade on the machine that runs everything else.
The user IDs don’t line up. An unprivileged container runs with shifted IDs. The Proxmox wiki on unprivileged containers puts it plainly: root (UID 0) inside the container is UID 100000 on the host, UID 1 is 100001, and so on. Anything on the host owned by an ID outside that range shows up inside the container as nobody (65534), and the container can’t write to it.
The fix for both is the same pattern: the host does the mounting, and you choose ownership so the IDs land inside the container’s range.
How the ID Mapping Works
The default mapping shifts every ID by 100000. The ones that matter for this guide:
| Inside the container | On the Proxmox host | Used for |
|---|---|---|
| UID 0 (root) | UID 100000 | Owner of the share |
| UID 1000 (first regular user) | UID 101000 | A service user, if you use one |
GID 10000 (lxc_shares) | GID 110000 | Group that gets read/write access |
The group is the trick. Instead of chasing whichever UID each app runs as, you give a single group read/write access on the host side (GID 110000), then add each service user to the matching group (GID 10000) inside the container. One share can then serve several containers, as long as each has the same group.
Step 1: Pick NFS or SMB
Use whatever your NAS already serves well. The differences that matter here:
| NFS | SMB (CIFS) | |
|---|---|---|
| How ownership reaches the host | Numeric UIDs and GIDs pass through from the NAS | Set at mount time with uid= and gid= options |
| Where you fix permissions | On the NAS (folder ownership or squash settings) | In the host’s mount line |
| Best fit | Linux NAS (TrueNAS, OpenMediaVault, Unraid) talking to Linux hosts | A NAS that also serves Windows or Mac clients |
| Credentials | Export access by host IP | Username and password, kept in a root-only file |
My read: if the share only feeds Linux machines, NFS is the cleaner choice. If you already have SMB set up for laptops, there is no need to add a second protocol just for Proxmox.
The examples below use nas.example.lan as the NAS hostname and a share called media. Replace both with your own.
Step 2: Prepare the Share on the NAS
For NFS: export the share to the Proxmox host’s address, not the container’s. The container never talks to the NAS directly; the host does. Then handle ownership in one of two ways:
- Set the shared folder’s owner to UID 100000 and group to GID 110000, with group read/write (mode
0770or2770). - Or use your NAS’s squash option, usually labelled
all_squashwithanonuid/anongid, or “Mapall User/Group” on TrueNAS. Squash every client to 100000/110000 so all writes from the host land as those IDs.
Squashing is simpler for a share that only Proxmox uses. Explicit ownership is better when other machines also write to the share with their own user IDs.
For SMB: create a dedicated NAS user for Proxmox with read/write access to the share. Ownership on the NAS side doesn’t matter for the container, because the host’s mount line decides what the container sees.
If you are building the NAS side from scratch, the TrueNAS SCALE setup guide covers creating datasets and shares.
Step 3: Mount the Share on the Proxmox Host
Open a shell on the Proxmox host (the web UI’s node Shell works) and create the mount directory:
mkdir -p /mnt/lxc_shares/media
NFS
Install the client tools if they aren’t already present, then add a line to /etc/fstab:
apt install nfs-common
# NAS media share for LXC containers
nas.example.lan:/export/media /mnt/lxc_shares/media nfs defaults,_netdev,x-systemd.automount 0 0
The export path (/export/media here) depends on your NAS. Some show it as /mnt/pool/media; copy it exactly. pvesm scan nfs nas.example.lan lists what the NAS exports.
SMB
Keep the password out of /etc/fstab with a credentials file that only root can read:
cat > /root/.smb-nas <<'EOF'
username=proxmox
password=your-share-password
EOF
chmod 600 /root/.smb-nas
Then the /etc/fstab line:
# NAS media share for LXC containers
//nas.example.lan/media /mnt/lxc_shares/media cifs _netdev,x-systemd.automount,noatime,uid=100000,gid=110000,dir_mode=0770,file_mode=0770,credentials=/root/.smb-nas 0 0
uid=100000,gid=110000 makes every file appear owned by container root and the lxc_shares group. 0770 gives both read/write and everyone else nothing. This layout comes from a long-running Proxmox forum tutorial on CIFS shares for unprivileged LXCs, which is worth reading for edge cases.
Mount it
systemctl daemon-reload
mount /mnt/lxc_shares/media
findmnt /mnt/lxc_shares/media
ls -ln /mnt/lxc_shares/media
findmnt should show the NAS as the source. If it prints nothing, the share isn’t mounted, and you are looking at an empty local directory. Fix that before going further (see the warning in Step 6).
A note on the web UI: Datacenter > Storage > Add > NFS or SMB/CIFS also mounts a share on every node, under /mnt/pve/<storage-id>. That’s built for storing ISOs, templates and backups. You can bind-mount from there, but a CIFS storage added that way mounts files as host root by default, so they show as nobody inside the container, and it also creates its own content folders on the share. The /etc/fstab route keeps ownership in one visible line.
Step 4: Create the Group Inside the Container
Start the container if it’s stopped, open its console (or run pct enter <CTID> from the host), and run:
groupadd -g 10000 lxc_shares
usermod -aG lxc_shares jellyfin
Swap jellyfin for whichever user your service runs as. For a Docker container running inside the LXC, the process’s user is whatever the image uses; images that take PUID/PGID variables can be pointed at the group by setting PGID=10000.
Then shut the container down:
pct shutdown <CTID>
Step 5: Add the Bind Mount Point
Back on the host. Bind mounts are added from the shell or by editing the container’s config file; the web UI’s “Add > Mount Point” dialog creates new storage volumes, not bind mounts.
pct set <CTID> -mp0 /mnt/lxc_shares/media,mp=/mnt/media
That writes this line to /etc/pve/lxc/<CTID>.conf:
mp0: /mnt/lxc_shares/media,mp=/mnt/media
mp= is the path inside the container. Use mp1, mp2 and so on for additional shares.
If the container only needs to read the share (a media server reading a library, for example), make it read-only:
pct set <CTID> -mp0 /mnt/lxc_shares/media,mp=/mnt/media,ro=1
Read-only is worth the extra four characters. A misconfigured app can’t delete what it can’t write.
Step 6: Start It and Check
pct start <CTID>
pct enter <CTID>
ls -ln /mnt/media
You want to see 0 10000 as the owner and group (container root, lxc_shares), not 65534 65534. Then confirm the service user can write, if the mount isn’t read-only:
su -s /bin/sh jellyfin -c 'touch /mnt/media/.write-test && rm /mnt/media/.write-test'
The empty-directory trap. If the NAS is down or slow at boot, the host directory can be empty but present, and the container starts anyway. An app with write access will then write into the host’s local disk, and you find out weeks later when files “vanish” once the share comes back on top of them. x-systemd.automount in the fstab line helps, because the share mounts on first access instead of racing the boot. For anything that writes, check findmnt after a reboot before trusting it.
The Advanced Option: Map a Container UID Straight Through
The group approach covers most setups. When an app must own files as a specific user (UID 1000, say) and you want that to be UID 1000 on the host and NAS as well, you can carve that one ID out of the shifted range. The pattern below follows the Proxmox wiki’s idmap example, adapted to UID and GID 1000.
Add to /etc/pve/lxc/<CTID>.conf:
lxc.idmap: u 0 100000 1000
lxc.idmap: g 0 100000 1000
lxc.idmap: u 1000 1000 1
lxc.idmap: g 1000 1000 1
lxc.idmap: u 1001 101001 64535
lxc.idmap: g 1001 101001 64535
Then allow root to map that ID by adding this line to both /etc/subuid and /etc/subgid on the host:
root:1000:1
Container UID 1000 is now host UID 1000; everything else keeps its shift. The three ranges must cover 0 to 65535 with no gaps or overlaps, which is where most broken configs go wrong. If the container won’t start after the change, lxc-start -F -n <CTID> runs it in the foreground and prints the actual error.
Treat this as a targeted fix. Every ID you map straight through is an ID where container and host are the same user.
What Bind Mounts Leave Out
Bind mounts are outside Proxmox’s storage system, which has three consequences:
- Backups skip them. The Proxmox docs state that bind mount contents are not backed up by
vzdump, and a restore brings back only the mount point line. The same is true for Proxmox Backup Server. Back up the share on the NAS side, for example with restic, as part of a wider backup strategy. - Snapshots skip them. A container snapshot (see Proxmox snapshots) rolls back the container’s own disk, not the share. Rolling back an app whose database is on local disk while its files sit on the share can leave the two out of step.
- Clusters need extra flags. If you migrate or replicate the container between nodes, every node needs the same share mounted at the same path. Mark the mount point
shared=1so Proxmox will migrate it, andreplicate=0so storage replication jobs skip it. The docs are clear thatshared=1does not share anything for you; it only tells Proxmox the path already exists everywhere.
mp0: /mnt/lxc_shares/media,mp=/mnt/media,shared=1,replicate=0
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Files show 65534 / nobody inside the container | Host-side owner is outside the 100000+ range | SMB: check uid=100000,gid=110000 in fstab. NFS: fix ownership or squash on the NAS |
Permission denied on write, ownership looks right | Service user isn’t in lxc_shares, or ro=1 is set | id <user> inside the container; check the mp0 line |
Container won’t start after adding mp0 | Host path doesn’t exist or isn’t mounted | findmnt on the host; lxc-start -F -n <CTID> for the real error |
| NFS mount hangs or times out | Export allows the container’s address, not the host’s | Allow the Proxmox host’s IP in the export |
| Share is empty after a reboot | Mounted after the container started | Use x-systemd.automount; check findmnt, then restart the container |
Where This Fits
This is the plumbing behind most media and document setups on Proxmox: a Jellyfin container reading a library off the NAS, or Paperless-ngx writing its archive somewhere with real redundancy. It also keeps the Proxmox host’s own disk small, which is why a cheap mini PC plus a NAS often beats one big box. If you haven’t picked the storage side yet, prebuilt vs DIY NAS covers the choice, and best hard drives for a budget homelab NAS covers what goes in it.