Bind mounts and mount points: sharing host storage with a container · Proxmox VE

A container with 8 GiB of rootfs and 40 TiB of media on the host is the normal shape of an LXC deployment. Getting the media into the container is one line of configuration. Getting it in correctly involves two things that are not visible in that line: who owns the files once they are inside, and whether they are in the backup.

Both are decided by choices you make when you write the mount point, and both fail quietly.

Three kinds of mount point, and the one difference that matters

mp0 through mp255 all use the same option syntax, but the value in the volume position selects between three quite different things.

Kind	Written as	Managed by PVE storage?	In `vzdump`?
Volume mount point	`mp0: local-zfs:32,mp=/data`	Yes - PVE allocates it	Yes, unless `backup=0`
Bind mount point	`mp0: /srv/ct-media,mp=/media`	No - a host path	No
Device mount point	`mp0: /dev/disk/by-id/…,mp=/data`	No - a host block device	No

The documentation is explicit that the contents of bind and device mount points are not backed up with vzdump, and that the backup option applies to volume mount points only. There is no flag that changes this.

The restore that comes back empty

This is the failure that costs a night, and it is entirely predictable.

A container is backed up nightly, the job is green for a year, and then the container is destroyed by an operator error. You restore it. It boots. The application starts. /media is an empty directory.

The backup was always a backup of the 8 GiB rootfs. The 40 TiB behind the bind mount was never in it, because bind-mounted content is out of scope for vzdump by design - PVE does not own that data and cannot reason about its consistency.

The first diagnosis is usually “the restore failed” or “we restored the wrong snapshot”, and people spend an hour restoring other snapshots to compare. The restore was correct. The backup design was wrong.

What to do instead: every bind mount is a declaration that something else protects this data. Write down what that something else is - a host-level PBS proxmox-backup-client job, a ZFS snapshot and replication schedule, a NAS with its own backup - before you add the mount point, not after. If the answer is “nothing”, use a volume mount point instead and let vzdump do it.

Adding a bind mount

Configuration changebind a host directory into a stopped container— Changes the container config. The container must be restarted for a new mount point to appear. Nothing is written to the host directory.

set -euo pipefail
CTID=200
HOSTDIR=/srv/ct-media

# The source must exist and must not contain symlinks anywhere in its path.
mkdir -p "$HOSTDIR"

pct set "$CTID" --mp0 "$HOSTDIR,mp=/media"

pct config "$CTID" | grep -E '^(rootfs|mp[0-9]+):'

Options worth knowing, all documented on mp[n]:

Option	Effect
`mp=`	Path inside the container. Required.
`ro=1`	Mount read-only. The cheapest real safety control on this page.
`backup=1`	Volume mount points only. Silently irrelevant on a bind mount.
`shared=1`	Marks a non-volume mount point as “available on all nodes”.
`replicate=0`	Exclude a volume from storage replication jobs. Default is 1.
`mountoptions=`	Extra mount options, semicolon-separated.
`idmap=`	Per-mount UID/GID remapping. The subject of the next section.
`keepattrs=1`	Inherit UID, GID and mode from the mount point directory if it already exists.

Why the files show up as `nobody:nogroup`

Here is the moment every operator meets once.

Read-only / Safethe same directory, from the host and from inside the container

# stat -c '%U:%G %u:%g %n' /srv/ct-media
pct exec 200 -- stat -c '%U:%G %u:%g %n' /media

root:root 0:0 /srv/ct-media
nobody:nogroup 65534:65534 /media

Illustrative output

Nothing is broken. This is the user namespace working exactly as designed.

An unprivileged container runs inside a user namespace whose mapping is, by default, container UID 0..65535 onto host UID 100000..165535. That mapping is declared for the root user in /etc/subuid and /etc/subgid:

Read-only / Safethe subordinate ID delegation that makes the default mapping legal

# cat /etc/subuid /etc/subgid

root:100000:65536
root:100000:65536

Illustrative output

So the arithmetic runs in both directions:

A file that a container process creates as container UID 0 is written to disk as host UID 100000.
A file on disk owned by host UID 0 has no container-side ID, because 0 is outside the mapped range 100000..165535. The kernel reports it as the overflow UID, 65534, which /etc/passwd renders as nobody.

nobody:nogroup is not an error message. It is the kernel saying “this ownership does not exist in your namespace.”

Where the mapping actually lives

Two places, and they answer different questions.

/etc/subuid and /etc/subgid are a delegation policy: they say which ranges of host IDs the user root is permitted to hand to a child namespace. They are read by the tooling, not by the container. Editing them alone changes nothing about a running container.

/proc/<pid>/uid_map and /proc/<pid>/gid_map are the mapping itself, for one live namespace. Each line is three numbers - first ID inside the namespace, first ID outside it, and the length of the range - and they are written once, at namespace creation, and are read-only thereafter.

That “written once” is why you cannot re-map a running container, and it is the same kernel property that makes unprivileged unchangeable after creation. The rootfs was laid down with one arithmetic; changing the arithmetic afterwards would leave every file on it owned by an ID that no longer maps to anything.

You can read the live mapping from inside the container itself:

CTID=200
pct exec "$CTID" -- cat /proc/self/uid_map

The output 0 100000 65536 is the default mapping stated in the kernel’s own three-column form: container ID 0 maps to host ID 100000, for 65536 IDs. A privileged container reports 0 0 4294967295 instead - the whole ID space, identity-mapped, which is the mechanical statement of what “privileged” means.

Two ways to fix ownership, and when to use each

Option 1: chown on the host to the mapped ID

The blunt, portable fix. Decide what the container-side owner should be, add 100000, and set that on the host.

Configuration changegive container root ownership of a bind-mounted tree— Rewrites ownership on the host directory. Run it on a directory reserved for this container; do not run it on shared or system paths.

set -euo pipefail
HOSTDIR=/srv/ct-media
BASE=100000            # first host UID of the container's default map

# container root (0) -> host 100000
chown -R "$BASE:$BASE" "$HOSTDIR"

# container uid 1000 (a service account inside) -> host 101000
# chown -R "$((BASE + 1000)):$((BASE + 1000))" "$HOSTDIR/app"

stat -c '%u:%g %n' "$HOSTDIR"

This works, and it is what most estates do. Its limitation is that the data now belongs to one container’s namespace. A host process, or a second container with a different offset, sees 100000 and has no idea what it is.

Option 2: a per-mount-point `idmap`

PVE supports a custom mapping on the mount point itself, overriding the container’s default for that mount only. The syntax is type:container:disk:range-size, semicolon-separated, where type is u for UIDs or g for GIDs.

Configuration changemap one on-disk owner to one in-container owner— Changes the container config. Requires a container restart to take effect. The on-disk ownership is not modified.

set -euo pipefail
CTID=200

# On disk the tree is owned by 1000:1000 (a host service account).
# Inside the container it should appear as 1000:1000 as well.
pct set "$CTID" --mp0 '/srv/ct-media,mp=/media,idmap=u:1000:1000:1;g:1000:1000:1'

pct reboot "$CTID"
pct exec "$CTID" -- stat -c '%u:%g %n' /media

The documented special value passthrough identity-maps every ID on that mount, so the container sees exactly the on-disk ownership.

Situation	Use
Directory exists only to serve this container	`chown` to `100000`-relative IDs
Host and container both read and write the tree	`idmap=` for the specific IDs involved
Two containers share the same tree	`idmap=` in both, mapping to the same on-disk IDs
Container is untrusted	`ro=1`, and neither of the above
You are reaching for `passthrough`	Ask whether a volume mount point solves it instead

Migration, and what `shared=1` really claims

A volume mount point on shared storage migrates because PVE knows where the data is and that the target node can reach it. A bind mount is a host path, and PVE has no way to know whether /srv/ct-media on pve-02 is the same data as /srv/ct-media on pve-01, a different NFS export, or an empty directory.

shared=1 is documented as marking the mount point “as available on all nodes”. Read that as an assertion you are making, which PVE then trusts.

The container that migrates successfully and comes up empty

Someone sets shared=1 on a bind mount because migration refused without it and the flag made the error go away. The underlying path is a local ZFS dataset that exists on both nodes with the same name and different contents.

The migration now succeeds. The container starts on pve-02. The application finds an empty /media, decides it is a first run, and initialises. If it is a database, it initialises a new empty one. If it is a media indexer, it rewrites its library. Either way the container is healthy, the migration task is green, and monitoring says nothing.

Symptom: a service that is up and functioning but has lost all of its state, immediately after a routine migration or an HA failover.

Why the first diagnosis is wrong: everyone looks at the migration log, which is clean, and then at storage, which is online. Nothing failed. The config lied and PVE believed it.

The check that catches it, before you trust the flag:

CTID=200
MP=/srv/ct-media
for NODE in pve-01 pve-02 pve-03; do
  printf '%s: ' "$NODE"
  ssh "root@$NODE" "findmnt -no SOURCE,FSTYPE '$MP' || echo 'NOT A MOUNT'"
done

If that path is not the same network filesystem on every node in the migration target set, shared=1 is false and the mount point should be a volume mount point on shared storage instead.

What happens if you bind mount an NFS export into an unprivileged container?

It works, and then ownership behaves in a way that surprises people, because there are now two ID mappings stacked.

The NFS server exports files with its own UIDs. The host mounts the export and sees those UIDs directly - NFSv3 has no translation, and NFSv4 with sec=sys behaves the same unless idmapd is configured. The container then applies its namespace offset on top. A file owned by UID 1000 on the NFS server is UID 1000 on the host, and is outside the container’s mapped range, so it is nobody inside.

Three consequences that follow:

chown on the host now writes to the NFS server, changing ownership for every other client of that export. The chown -R 100000:100000 fix from earlier is not local. On a shared export it is an outage for someone else.
root_squash on the export means container root cannot write even after you get the mapping right, because the host’s request arrives at the server as an unprivileged user.
idmap= on the mount point is the right tool here, precisely because it changes what the container sees without touching what is on the server.

The general rule: when the storage has an owner outside your host, remap in the container, never on the disk.

Verification, and undo

A mount point that “looks right” in pct config proves only that the config parsed. These four checks can each fail.

Read-only / Safeverify a bind mount is real, writable and correctly owned— Read-only apart from a single test file, which is removed. Run it after adding a mount point and after any migration.

set -euo pipefail
CTID=200
INNER=/media

# 1. The container agrees it is a mount, not just a directory.
pct exec "$CTID" -- findmnt -no SOURCE,FSTYPE,OPTIONS "$INNER"

# 2. It is not empty when it should not be.
pct exec "$CTID" -- sh -c "ls -A '$INNER' | head -5"

# 3. The service account inside can actually write.
pct exec "$CTID" -- runuser -u www-data -- \
sh -c "touch '$INNER/.writetest' && rm '$INNER/.writetest'" \
&& echo 'write OK'

# 4. Ownership resolves to a name, not to nobody.
pct exec "$CTID" -- stat -c '%U:%G %n' "$INNER"

Check 3 is the one that matters. ls succeeding tells you the mount exists; only a write as the account the application actually runs as tells you the mapping is right.

Configuration changeremove a mount point— Removes the mount point from the container config. The host directory and its contents are untouched - PVE does not delete data it does not manage.

set -euo pipefail
CTID=200

pct set "$CTID" --delete mp0
pct reboot "$CTID"
pct config "$CTID" | grep -E '^mp[0-9]+:' || echo 'no mount points remain'

Removing a volume mount point behaves differently: the volume becomes an unused disk on the container config rather than disappearing, and you delete it deliberately afterwards. That asymmetry is a feature - PVE will not silently destroy storage it allocated.

Knowledge check

Why this matters

Bind mounts are where the container abstraction stops being an abstraction. Everything else about LXC - the config file, the pct verbs, the web interface - lets you think about a container as a small machine. A bind mount makes you think about inodes, UID arithmetic and which host actually holds the bytes.

That is why the two failures on this page are so common and so expensive. Both come from treating the mount point as a property of the container when it is really a property of the host, and both stay invisible until the day something moves: a restore, a migration, a failover.

The habit worth building is to answer two questions in writing every time you add a mount point, before you add it. What backs this data up, if not vzdump? And is this path the same data on every node this container could ever run on? Neither question has a default answer, and the config file has no space to record either one - so it belongs in the runbook.