Rootless Podman Bind‑Mount Permission Issues: Diagnostic & Fix

Rootless Podman containers often fail to write to bind‑mounted directories due to UID/GID mapping or SELinux context mismatches. This guide walks through the symptoms, diagnostic steps, targeted fixes, and when to seek escalation, complete with command snippets and risk notes.

Recognizing the Symptom

When a rootless Podman container cannot write to a bind‑mounted directory, or when files created inside the container appear on the host with an owner the invoking user cannot read, you’re dealing with a UID/GID mapping or SELinux context mismatch. The error message usually looks like touch: cannot create file: Permission denied or open: Permission denied inside the container, while ls -l on the host shows the file owned by root or another UID.

Cause‑Diagnostic Mapping

Cause	Typical Symptom
UID/GID mapping mismatch	Files owned by root on host; container runs as UID 0 but host user has no write permission.
SELinux context mismatch	Permission denied even when UID/GID is correct; `ls -Z` shows a context that does not allow svirt_sandbox_file_t.
Incorrect mount options	Mount appears read‑only or the container cannot see the directory at all.
Missing subuid/subgid range	Podman refuses to start or silently maps to a different UID.

Ordered Checks

Verify UID/GID mapping
```
# Inside the container
podman exec -it mycontainer id
# On the host
ls -n /path/to/mount | head -n 1
```
Compare the numeric UID/GID from the container with the host's subuid/subgid range (see /etc/subuid and /etc/subgid). If the container shows uid=0 but the host path is owned by a different UID, mapping is the culprit.
Check SELinux context
```
ls -Z /path/to/mount
```
The context should be svirt_sandbox_file_t (or a variant that allows the container). If it’s unconfined_u:object_r:user_home_t:s0, SELinux is blocking access.
Inspect mount options in the run command or unit file
```
podman inspect --format '{{.Mounts}}' mycontainer
```
Look for --userns, --user, or volume suffixes like :z or :Z. A missing :z on a shared volume can cause permission errors.
Validate subuid/subgid ranges
```
cat /etc/subuid | grep $(whoami)
cat /etc/subgid | grep $(whoami)
```
Ensure there is a range allocated; otherwise Podman may silently map to an unexpected UID.
Confirm rootless mode and Podman version
```
podman info --format '{{.Host.Security.Rootless}}'
podman version
```
Some behaviors differ between Podman 4.x and 5.x, especially around --userns=keep-id support.

Targeted Fixes

1. Align UID/GID Mapping

If the container’s UID 0 does not match the host user, use one of the following options when starting the container:

--userns=keep-id – keeps the host UID/GID inside the container. Requires a valid subuid/subgid range.
```
podman run --rm -v $(pwd):/data --userns=keep-id alpine sh -c 'touch /data/hello'
```

Explicitly set the user: --user $(id -u):$(id -g).

podman run --rm -v $(pwd):/data --user $(id -u):$(id -g) alpine sh -c 'touch /data/hello'

Change host directory ownership to match the container UID.
```
sudo chown $(id -u):$(id -g) /path/to/mount
```

2. Resolve SELinux Context Issues

For a shared host directory, append :z to the volume spec or relabel the directory:

--volume /host/path:/data:z – allows multiple containers to share the same context.

Relabel with chcon:

chcon -Rt svirt_sandbox_file_t /path/to/mount
ls -Z /path/to/mount

For private access, use :Z but ensure only one container uses the volume.

3. Correct Mount Options

Ensure the --userns flag is present if you want the container to inherit the host UID. If you omit it, the container will map UID 0 to a random subuid, leading to mismatches.

Escalation Criteria

After applying the above fixes, the container still reports permission denied.
Multiple containers (rootful and rootless) share the same host volume and interfere with each other.
The host’s /etc/subuid or /etc/subgid files are missing or incorrectly configured.
SELinux is disabled or in permissive mode, yet errors persist, indicating a deeper namespace misconfiguration.

At this point, consult the Podman release notes for your version, verify the podman info output for any warnings, and consider raising an issue on the Podman GitHub repository with detailed logs.

Practical Verification Example

Reproduce the minimal failure scenario:

# Host
mkdir -p /tmp/demo
# Run container
podman run --rm -v /tmp/demo:/data alpine sh -c 'touch /data/inside; ls -ln /data/inside'
# Inspect host file
ls -ln /tmp/demo/inside

Expected outcome: the file is owned by the host user. If it appears as root, you have a mapping issue. Apply --userns=keep-id or adjust ownership accordingly.

Risk Mitigation

Never run chown -R on system directories; restrict changes to the exact mount target.
Use :z for shared volumes; :Z only when a single container exclusively uses the path.
Test --userns=keep-id in a non‑production environment first, as older Podman releases may not support it fully.

Rootless Podman Bind‑Mount Permission Failures: A Diagnostic Guide