From a6c6d77b7b8656e6ccc4db2a784a31f17b5359ee Mon Sep 17 00:00:00 2001 From: Ian Pilcher Date: Fri, 3 Apr 2026 11:37:07 -0500 Subject: [PATCH 1/2] storage: Document force_mask UID 0 mapping requirement Signed-off-by: Ian Pilcher --- storage/docs/containers-storage.conf.5.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/storage/docs/containers-storage.conf.5.md b/storage/docs/containers-storage.conf.5.md index 49cca177e7..c61b824dc3 100644 --- a/storage/docs/containers-storage.conf.5.md +++ b/storage/docs/containers-storage.conf.5.md @@ -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. fuse-overlayfs (see "mount_program" below) creates a FUSE mount that that is only accessible 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 From 526cbe99920457b80993f22f8c2b4fac40c1ca64 Mon Sep 17 00:00:00 2001 From: Ian Pilcher Date: Sat, 4 Apr 2026 08:46:52 -0500 Subject: [PATCH 2/2] Update storage/docs/containers-storage.conf.5.md Signed-off-by: Ian Pilcher Co-authored-by: Tom Sweeney --- storage/docs/containers-storage.conf.5.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/storage/docs/containers-storage.conf.5.md b/storage/docs/containers-storage.conf.5.md index c61b824dc3..9ba4e7d4eb 100644 --- a/storage/docs/containers-storage.conf.5.md +++ b/storage/docs/containers-storage.conf.5.md @@ -194,7 +194,7 @@ 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. fuse-overlayfs (see "mount_program" below) creates a FUSE mount that that is only accessible 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. +- 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