Sharing CIFS mount with unprivileged LXC in Proxmox

If you’re running unprivileged LXC containers in Proxmox and need to access a CIFS/SMB share from your NAS, you’ll quickly run into permission issues. Unprivileged containers use UID/GID mapping, which means the user IDs inside the container don’t match the ones on the host. This guide walks you through the correct way to share a CIFS mount with an unprivileged LXC.

Unprivileged vs Privileged

This guide is specifically for unprivileged LXC containers. Privileged containers don’t have the UID/GID mapping issue, so the setup is much simpler. If you’re unsure which type you’re running, check your container config at /etc/pve/lxc/<ID>.conf—if it contains unprivileged: 1, this guide is for you.

Overview

Step	What	Where
1	Create a shared group inside the LXC	LXC container
2	Add users to the shared group	LXC container
3	Mount the CIFS share on the host	Proxmox host
4	Bind mount the share into the LXC config	Proxmox host
5	Start the LXC and verify	Proxmox host

Inside the LXC

First, create the group lxc_shares with GID 10000 inside the LXC container:

root@lxc-container:~$ groupadd -g 10000 lxc_shares

Why GID 10000?

The GID 10000 inside the container maps to GID 110000 on the Proxmox host (due to the default +100000 offset for unprivileged containers). We’ll use this mapped GID when mounting the CIFS share on the host.

Add the user(s) from the LXC container that need access to the CIFS share to the group lxc_shares:

root@lxc-container:~$ usermod -aG lxc_shares USERNAME

You can verify the user was added correctly:

root@lxc-container:~$ id USERNAME
uid=1000(USERNAME) gid=1000(USERNAME) groups=1000(USERNAME),10000(lxc_shares)

Now shutdown the LXC before proceeding to the host configuration.

root@lxc-container:~$ poweroff

On the Proxmox host

Create the mount point on the PVE host:

root@pve:~$ mkdir -p /mnt/media

Credentials file

Instead of putting your SMB credentials directly in /etc/fstab, you can store them in a separate file for better security:

root@pve:~$ cat /etc/samba/credentials
username=smb_username
password=smb_password

root@pve:~$ chmod 600 /etc/samba/credentials

Then use credentials=/etc/samba/credentials in the fstab entry instead of user= and pass=.

Add the CIFS mount to /etc/fstab:

/etc/fstab

//NAS/media/ /mnt/media cifs _netdev,x-systemd.automount,noatime,uid=100000,gid=110000,dir_mode=0770,file_mode=0770,user=smb_username,pass=smb_password 0 0

option	description
_netdev	Forces systemd to consider this mount as a network mount
x-systemd.automount	Automatically remounts in case the NAS went offline for some time
noatime	Access timestamps will not be updated when a file/folder is read
uid=100000,gid=110000	Specify the user mapping ids
dir_mode=0770,file_mode=0770	Only the uid/gid will have rwx access to the share

Mount the share on the PVE host:

root@pve:~$ mount /mnt/media

You can verify the mount is working and permissions are correct:

root@pve:~$ ls -la /mnt/media
total 0
drwxrwx--- 2 100000 110000 0 Jul 18 12:00 .
drwxr-xr-x 3 root   root   0 Jul 18 11:00 ..

Bind mounting into the LXC

Add a bind mount of the share to your container config, e.g: /etc/pve/lxc/LXC_ID.conf:

/etc/pve/lxc/204.conf

mp0: /mnt/media/,mp=/mnt/nas

Snapshots with mp0

Using mp0 disables snapshotting for the LXC container. If you rely on snapshots, use the lxc.mount.entry approach below instead.

To preserve snapshot functionality, you can instead share the mount using lxc.mount.entry:

/etc/pve/lxc/204.conf

lxc.mount.entry: /mnt/media/ mnt/media none bind 0 0

Mount path inside the LXC

With mp0, you explicitly set the mount point inside the container (e.g. /mnt/nas). With lxc.mount.entry, the path is relative to the container’s root, so mnt/media becomes /mnt/media inside the LXC. Make sure the directory exists inside the container before starting it.

Now you just need to start the LXC. The share should be accessible at the configured mount point.

How does this work?

Unprivileged LXC containers in Proxmox use a UID/GID offset of 100000 by default. This means that root (UID 0) inside the container is actually UID 100000 on the host, and so on for all other users and groups.

We mount the CIFS share to the UID that belongs to the unprivileged LXC root user, which by default is always uid=100000. Then we create a group in our LXC (lxc_shares) with gid=10000 which refers to gid=110000 on the PVE host.

This is how the mapping will be done:

	UID	GID
PVE host	100000	110000
Unprivileged LXC	0	10000

Custom UID/GID mappings

If your container uses a custom ID mapping (check lxc.idmap in the container config), you’ll need to adjust the UIDs/GIDs accordingly. The formula is: host_id = container_id + offset.

Proxmox Backup Server

If you have any errors while trying this setup using a shared mount to your backups using PBS (like I did), you can just fix it by changing the uid/gid of the share to the backup user inside the PBS:

/etc/fstab

//NAS/media/ /mnt/media cifs _netdev,x-systemd.automount,noatime,uid=100034,gid=100034,dir_mode=0770,file_mode=0770,user=smb_username,pass=smb_password 0 0

Finding the backup user's UID

The backup user in PBS typically has UID/GID 34. You can verify this by running id backup on the PBS host. The mapped value on the PVE host would then be 100000 + 34 = 100034.

This will allow rwx access to the backup user from PBS and the mapping will be:

	UID	GID
PVE host	100034	100034
Unprivileged LXC	34	34

Troubleshooting

If you’re having issues, here are the most common things to check:

• Permission denied inside the LXC: Make sure the user is in the lxc_shares group (id USERNAME) and that you restarted the container after making changes.
• Mount fails on the host: Ensure the cifs-utils package is installed (apt install cifs-utils) and that the NAS is reachable from the host.
• Share is read-only: Double-check the dir_mode and file_mode values in your fstab entry. Also verify the SMB user has write permissions on the NAS side.
• Changes not taking effect: After modifying the container config, you must fully stop and start the LXC (not just reboot from inside).

Source

This article is adapted from https://forum.proxmox.com/threads/tutorial-unprivileged-lxcs-mount-cifs-shares.101795/, many thanks to TheHellSite for the original tutorial!