Black Friday mini PC deals are live, checked daily through Cyber Monday. See the deals guide
← All Guides
intermediate

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.

Budget Homelab ·
proxmoxlxcstoragehow-to

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

  1. Mount the share on the host under /mnt/lxc_shares/<name> with an /etc/fstab line
  2. Own it as the container’s mapped IDs: uid=100000,gid=110000 for SMB, or the same IDs set on the NAS for NFS
  3. Create group lxc_shares with GID 10000 inside the container and add your service user to it
  4. Add the bind mount: pct set <CTID> -mp0 /mnt/lxc_shares/media,mp=/mnt/media
  5. Start the container and check ownership with ls -ln
  6. 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 containerOn the Proxmox hostUsed for
UID 0 (root)UID 100000Owner of the share
UID 1000 (first regular user)UID 101000A service user, if you use one
GID 10000 (lxc_shares)GID 110000Group 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:

NFSSMB (CIFS)
How ownership reaches the hostNumeric UIDs and GIDs pass through from the NASSet at mount time with uid= and gid= options
Where you fix permissionsOn the NAS (folder ownership or squash settings)In the host’s mount line
Best fitLinux NAS (TrueNAS, OpenMediaVault, Unraid) talking to Linux hostsA NAS that also serves Windows or Mac clients
CredentialsExport access by host IPUsername 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:

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:

mp0: /mnt/lxc_shares/media,mp=/mnt/media,shared=1,replicate=0

Troubleshooting

SymptomLikely causeFix
Files show 65534 / nobody inside the containerHost-side owner is outside the 100000+ rangeSMB: check uid=100000,gid=110000 in fstab. NFS: fix ownership or squash on the NAS
Permission denied on write, ownership looks rightService user isn’t in lxc_shares, or ro=1 is setid <user> inside the container; check the mp0 line
Container won’t start after adding mp0Host path doesn’t exist or isn’t mountedfindmnt on the host; lxc-start -F -n <CTID> for the real error
NFS mount hangs or times outExport allows the container’s address, not the host’sAllow the Proxmox host’s IP in the export
Share is empty after a rebootMounted after the container startedUse 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.