Skip to content

storage: Document force_mask UID 0 mapping requirement #742

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ipilcher wants to merge 2 commits into
base: main
Choose a base branch
from
+5 −1
Open

storage: Document force_mask UID 0 mapping requirement #742

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a6c6d77
storage: Document force_mask UID 0 mapping requirement
ipilcher Apr 3, 2026
526cbe9
Update storage/docs/containers-storage.conf.5.md
ipilcher Apr 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion storage/docs/containers-storage.conf.5.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,13 +185,17 @@ any user.

`OCTAL`: Users can experiment with other OCTAL Permissions.

Note: The force_mask Flag is an experimental feature, it could change in the
Notes:

- The force_mask Flag is an experimental feature, it could change in the
future. When "force_mask" is set the original permission mask is stored in the
"user.containers.override_stat" xattr and the "mount_program" option must be
specified. Mount programs like "/usr/bin/fuse-overlayfs" present the extended
attribute permissions to processes within containers rather than the
"force_mask" permissions.

- When force_mask is used in rootless mode with explicit UID mappings (e.g., `--uidmap`), the container's UID 0 must map to the host user's UID. The fuse-overlayfs (see "mount_program" below) storage driver creates a FUSE mount accessible only to the user who created it (the user running podman in this case). If UID 0 within the container is mapped to a different host UID (such as a subordinate UID from /etc/subuid), the OCI runtime (which runs in the user namespace) will not be able to access the FUSE mount.

**mount_program**=""
Specifies the path to a custom program to use instead of using kernel defaults
for mounting the file system. In rootless mode, without the CAP_SYS_ADMIN
Expand Down