On Thu, Sep 7, 2023 at 11:44 AM Alexander Larsson <alexl@xxxxxxxxxx> wrote: > > Signed-off-by: Alexander Larsson <alexl@xxxxxxxxxx> Reviewed-by: Amir Goldstein <amir73il@xxxxxxxxx> > --- > Documentation/filesystems/overlayfs.rst | 23 +++++++++++++++++++++++ > 1 file changed, 23 insertions(+) > > diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst > index cdefbe73d85c..ae194543dbda 100644 > --- a/Documentation/filesystems/overlayfs.rst > +++ b/Documentation/filesystems/overlayfs.rst > @@ -492,6 +492,29 @@ 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. > + > +A lower dir with a regular whiteout will always be handled by the overlayfs > +mount, so to support storing an effective whiteout file in an overlayfs mount an > +alternative form of whiteout is supported. This form is a regular, zero-size > +file with the "overlay.whiteout" xattr set, inside a directory with the > +"overlay.whiteouts" xattr set. Such whiteouts are never created by overlayfs, > +but can be used by userspace tools (like containers) that generate lower layers. > +These alternative whiteouts can be escaped using the standard xattr escape > +mechanism in order to properly nest to any depth. > > Non-standard behavior > --------------------- > -- > 2.41.0 >
