Signed-off-by: Alexander Larsson <alexl@xxxxxxxxxx> --- Documentation/filesystems/overlayfs.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst index 35853906accb..e38b2f5fadaf 100644 --- a/Documentation/filesystems/overlayfs.rst +++ b/Documentation/filesystems/overlayfs.rst @@ -492,6 +492,28 @@ directory tree on the same or different underlying filesystem, and even to a different machine. With the "inodes index" feature, trying to mount the copied layers will fail the verification of the lower root file handle. +Nesting overlayfs mounts +------------------------ + +It is possible to use a lower directory that is stored on an overlayfs +mount. For regular files this does not need any special care. However, files +that have overlayfs attributes, such as whiteouts or `overlay.*` xattrs will +be interpreted by the underlying overlayfs mount and stripped out. In order to +allow the second overlayfs mount to see the attributes they must be escaped. + +Overlayfs specific xattrs are escaped by using a special prefix of +`overlay.overlay.`. So, a file with a `trusted.overlay.overlay.metacopy` xattr +in the lower dir will be exposed as a regular file with a +`trusted.overlay.metacopy` xattr in the overlayfs mount. This can be nested +by repeating the prefix multiple time, as each instance only removes one +prefix. + +Whiteouts files marked with a `overlay.nowhiteout` xattr will cause overlayfs +not to treat them as a whiteout. Since this xattr is then stripped out, the +next layer will instead apply the whiteout. + +Files created via overlayfs will automatically be created with the right +escapes in the upper directory. Non-standard behavior --------------------- -- 2.41.0
