spiegel_podman/docs/tutorials
José M. Requena Plens a014988113
Document rootless bind-mount access through an unmapped parent
A rootless user can bind-mount a directory whose parent is mode 700 when
that parent is owned by a UID inside their /etc/subuid range, and gets
"statfs ...: permission denied" when the same parent is owned by root.
The user has no access to the parent in either case, and nothing in the
docs explains the difference.

The reason is the user namespace. CAP_DAC_OVERRIDE bypasses a file's
mode only when that file's UID and GID are both mapped in the namespace,
which is "Operation of file-related capabilities" in user_namespaces(7).
A parent whose owner is not mapped is reported with the overflow ID
65534, so root gets no DAC override and the parent's mode is enforced.
An owner inside the subordinate range is mapped, the override applies,
and mode 700 is bypassed. --userns=keep-id changes none of the outcomes.

The report that prompted this was a rootless bind mount of a directory
under /etc/letsencrypt, owned by certbot:certbot with mode 750, by a
user who is not in that group, and a question about whether that is
intentional. The "Using volumes" section explains the ID shift for files
created inside the container and says nothing about whether the mount
source can be traversed, which is the part the reporter hit.

Add a short subsection there that opens with the capability rule and
shows three cases as one rule: mode 755 owned by root mounts fine
because world permissions already allow it, mode 700 owned by root
fails, and mode 700 owned by an ID inside the range succeeds. It also
gives the podman unshare check for whether a UID is mapped, and the
consequence for subordinate ranges that overlap real accounts.

Behavior checked on Debian with podman 5.4.2 and a 100000:65536 range.

Discussion: https://github.com/podman-container-tools/podman/discussions/29443
Signed-off-by: José M. Requena Plens <jmrplens@gmail.com>
2026-09-11 10:30:06 +02:00
..
basic_networking.md Document pasta forwarding mode for rootless bridge networks 2026-05-20 14:24:48 +02:00
image_signing.md source code comments and docs: fix typos, language, Markdown layout 2023-05-22 07:52:16 +02:00
mac_client.md [CI:DOCS] fix default branch links 2022-01-15 20:56:19 +01:00
mac_win_client.md Improve mac_win_client tutorial structure and links 2026-03-12 11:14:34 +01:00
macos_autostart.md Add tutorial for running podman machine on macOS startup 2026-03-12 11:13:27 +01:00
performance.md docs: clarify partial vs lazy image pulling 2026-06-19 12:17:05 +02:00
podman-derivative-api.md docs: update the podman logo 2022-08-07 09:11:53 +08:00
podman-for-windows.md Add command podman system hyperv-prep 2026-04-29 23:00:29 +02:00
podman-install-certificate-authority.md Import local certificates to machines on macOS and Linux 2026-05-01 00:42:52 +02:00
podman-win-install.jpg Update the Podman on Windows tutorial for 6.0.x 2026-01-16 11:48:57 +01:00
podman-wsl-term.jpg Update the Podman on Windows tutorial for 5.7.x 2026-01-13 12:49:33 +01:00
podman_bridge.png [CI:DOCS]basic networking guide 2021-02-18 13:21:33 -06:00
podman_macvlan.png [CI:DOCS]basic networking guide 2021-02-18 13:21:33 -06:00
podman_pod.png [CI:DOCS]basic networking guide 2021-02-18 13:21:33 -06:00
podman_rootless_default.png [CI:DOCS]basic networking guide 2021-02-18 13:21:33 -06:00
podman_tutorial.md Clarify inspect example in basic setup tutorial 2026-05-25 10:58:07 +02:00
podman_tutorial_cn.md Clarify inspect example in basic setup tutorial 2026-05-25 10:58:07 +02:00
qemu-remote-tutorial.md Fix language, typos and markdown layout 2023-07-24 11:18:25 +02:00
README.md Add tutorial for running podman machine on macOS startup 2026-03-12 11:13:27 +01:00
remote_client.md Update remote_client.md 2023-02-18 23:54:41 +08:00
rootless_tutorial.md Document rootless bind-mount access through an unmapped parent 2026-09-11 10:30:06 +02:00
socket_activation.md Remove slirp4netns from documentation 2026-04-13 09:04:41 -04:00

PODMAN logo

Podman Tutorials

Introduction Tutorial

Learn how to set up Podman and perform some basic commands with the utility.

Basic Setup and Use of Podman in a Rootless environment

The steps required to set up rootless Podman are enumerated.

Setup Mac/Windows

Special setup for running the Podman remote client on a Mac or Windows PC and connecting to Podman running on a Linux VM are documented.

Running Podman on macOS startup with launchd

How to automatically start a Podman machine at login on macOS using launchd LaunchAgents.

Remote Client

A brief how-to on using the Podman remote-client.

How to use libpod for custom/derivative projects

How the libpod API can be used within your own project.

Image Signing

Learn how to set up and use image signing with Podman.

Basic Networking

A basic guide to common network setups with Podman

Socket activation

Learn how to run containers that support socket activation.

Performance

Performance guide regarding Podman configuration and usage.