From 18a76ce66f3a862f16c73109cefe3cc0a6f1f214 Mon Sep 17 00:00:00 2001 From: Christian Brauner Date: Mon, 15 Jun 2026 15:19:56 +0200 Subject: [PATCH] docs: document idmapped overlay mounts Describe that the merged overlay mount itself can be turned into an idmapped mount with mount_setattr(2), how the overlay mount idmapping composes with any layer idmappings, and that the mounter's access to the underlying layers is unaffected. Link: https://patch.msgid.link/20260615-work-idmapped-overlayfs-v1-7-7381632aa402@kernel.org Reviewed-by: Amir Goldstein Signed-off-by: Christian Brauner (Amutable) --- Documentation/filesystems/overlayfs.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst index eb846518e6ac..1a29a5afabd7 100644 --- a/Documentation/filesystems/overlayfs.rst +++ b/Documentation/filesystems/overlayfs.rst @@ -347,6 +347,22 @@ The resulting access permissions should be the same. The difference is in the time of copy (on-demand vs. up-front). +Idmapped mounts +--------------- + +The overlay mount itself can be turned into an idmapped mount by applying an +idmapping to it with mount_setattr(2) and MOUNT_ATTR_IDMAP, just like for +other filesystems that support idmapped mounts. + +The mount idmapping only changes how ownership and permissions of the overlay +inodes are presented to and interpreted for the caller. It does not change +how overlayfs accesses the underlying layers: those are still accessed with +the stashed mounter's credentials through their own mounts, which may +themselves be idmapped. The overlay mount idmapping and any layer idmapping +compose, an underlying id is first mapped according to the relevant layer +idmapping and then according to the overlay mount idmapping. + + Multiple lower layers ---------------------