Technical

How to handle unprivileged containers and large UIDs/GIDs in Proxmox

How to handle unprivileged containers and large UIDs/GIDs in Proxmox

Unprivileged containers in Proxmox map UIDs starting at 100000, so any file owned by a UID above 65536 inside the container ends up unmapped on the host. That’s why your bind mounts show nobody:nogroup or just fail. Fix is to remap the container’s ID range to cover those large UIDs — and, if you need it, to carve a hole in that range so part of it is never mapped at all.

Detailed view of fiber optic cables connected to a server rack, showcasing modern technology.

The problem with large UIDs

Proxmox gives each unprivileged container a default mapping of 65536 UIDs/GIDs, starting at 100000 on the host. Inside the container, those appear as 0-65535. If your data was created on a different system with UIDs like 100000 or 200000, they don’t fit in that range. The container sees them as unmapped, and you get permission errors even as root.

Remap the container’s ID range

You can change the mapping so the container’s internal UID 0 maps to a host UID that aligns with your data. Say your files are owned by UID 100000 on the host. You’d set the container to map its root to host UID 100000, giving you 65536 IDs starting there.

Edit the container config:

nano /etc/pve/lxc/<CTID>.conf

Add or modify the mapping lines. For a container that should start at host UID 100000:

lxc.idmap: u 0 100000 65536
lxc.idmap: g 0 100000 65536

That maps container UID 0 to host UID 100000, container UID 1 to host 100001, and so on. If you need more than 65536 IDs, you can add additional ranges, but be careful — the host UIDs must not overlap with other containers or the host itself.

Close-up image of ethernet cables plugged into a network switch, showcasing IT infrastructure.

Excluding a UID range from the mapping

The other question that comes up constantly: can you ask a UID range not to be mapped into an unprivileged container? Yes. Sometimes a host range is used by a service, or you want to reserve it for another container, and the default mapping grabs everything — so you have to carve out a hole.

You do it by splitting the mapping into two lxc.idmap entries with a gap between them. Here’s an example that leaves host UIDs 102000-102999 untouched:

# Map container UIDs 0-1999 to host 100000-101999
lxc.idmap: u 0 100000 2000
# Resume at container UID 2000 -> host 103000, skipping 102000-102999
lxc.idmap: u 2000 103000 63036
# Same shape for GIDs
lxc.idmap: g 0 100000 2000
lxc.idmap: g 2000 103000 63036

The first line maps container UIDs 0-1999 to host UIDs 100000-101999. The second picks up at container UID 2000 and maps to host 103000 onward, which means host UIDs 102000-102999 are never reachable from inside the container. Same pattern for GIDs — and they have to match, or you get files owned by a user that exists and a group that doesn’t.

The part that makes it fail to start

Proxmox will not let you just add idmap entries. The host has to allow the ranges too, in /etc/subuid and /etc/subgid, for the user running the container (usually root):

root:100000:65536

If you skip this, the container simply won’t start and you get a permission error that says nothing useful about the real cause. Annoying, but at least it fails fast rather than booting into something half-mapped.

Apply the mapping and fix ownership

After changing the config, restart the container. Then inside the container, you may need to chown the files to match the new internal UIDs. If your data was previously owned by UID 100000 on the host, that’s now UID 0 inside the container, so root owns it — which is usually fine. But if you had other UIDs, you’ll need to adjust.

Check ownership with ls -n inside the container. If files show as nobody, chown them to the appropriate internal UID. For example, if a file was host UID 100100, that’s container UID 100 now:

chown -R 100:100 /path/to/data

Why this happens and a simpler alternative

This is a pain because the default mapping assumes small UIDs. If you’re setting up a new container, it’s easier to create a privileged container and skip the mapping headache — but that’s less secure. For unprivileged, you have to plan the ID ranges ahead. Honestly, for a homelab, I’d just use a privileged container if I need to bind mount data with arbitrary UIDs. But if you want the security, remapping works.

If what you are actually trying to do is share a NAS dataset into a container, the ownership side of this is where it gets genuinely confusing — I worked through that one in sharing TrueNAS datasets with unprivileged LXC containers.

Leave a comment

Comments are reviewed before they appear. Your email is never published.