Documentation/filesystems/overlayfs.rst

6 Overlay Filesystem
10 overlay-filesystem functionality in Linux (sometimes referred to as
11 union-filesystems).  An overlay-filesystem tries to present a
16 Overlay objects
19 The overlay filesystem approach is 'hybrid', because the objects that
25 While directories will report an st_dev from the overlay-filesystem,
32 In the special case of all overlay layers on the same underlying
33 filesystem, all objects will report an st_dev from the overlay
35 make the overlay mount more compliant with filesystem scanners and
36 overlay objects will be distinguishable from the corresponding
39 On 64bit systems, even if all overlay layers are not on the same
45 the underlying inode number does overflow into the high xino bits, overlay
48 The "xino" feature can be enabled with the "-o xino=on" overlay mount option.
50 for overlay filesystem objects is not only unique, but also persistent over
51 the lifetime of the filesystem.  The "-o xino=auto" overlay mount option
54 The following table summarizes what can be expected in different overlay
86 An overlay filesystem combines two filesystems - an 'upper' filesystem
106 A read-only overlay of two read-only filesystems may use any
123   mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,\
131 is cached in the dentry belonging to the overlay filesystem.  If both
144 filesystem, an overlay filesystem needs to record in the upper filesystem
153 A directory is made opaque by setting the xattr "trusted.overlay.opaque"
202    copied up (but not the contents).  Then the "trusted.overlay.redirect"
204    root of the overlay.  Finally the directory is moved to the new
219 Module options (can also be changed through /sys/module/overlay/parameters/):
242 upper directory is stored in a "trusted.overlay.upper" extended attribute
250 NFS export support on an overlay filesystem with no upper layer requires
276 Once the copy_up is complete, the overlay filesystem simply
279 overlay filesystem (though an operation on the name of the file such as
286 Permission checking in the overlay filesystem follows these principles:
290  2) task creating the overlay mount MUST NOT gain additional privileges
292  3) non-mounting task MAY gain additional privileges through the overlay,
316   mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,... /merged
333   mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged
336 that case the overlay will be read-only.
345   mount -t overlay overlay -olowerdir=/a\:lower\:\:dir /merged
410   mount -t overlay overlay -olowerdir=/l1:/l2:/l3::/do1::/do2 /merged
435 fs-verity enabled and overlay verity support is enabled, then the
436 digest of the lower file is added to the "trusted.overlay.metacopy"
481 Lower layers may be shared among several overlay mounts and that is indeed
482 a very common practice.  An overlay mount may use the same lower layer
483 path as another overlay mount and it may use a lower layer path that is
484 beneath or above the path of another overlay lower layer path.
487 another overlay mount is not allowed and may fail with EBUSY.  Using
490 upper layer and/or workdir path the behavior of the overlay is undefined,
493 Mounting an overlay using an upper layer path, where the upper layer path
494 was previously used by another mounted overlay in combination with a
500 filesystem, are encoded and stored in the "trusted.overlay.origin" extended
513 It is quite a common practice to copy overlay layers to a different
562 underlying filesystem for all layers making up the overlay.
569 overlay filesystem and the value of st_ino for filesystem objects may not be
570 persistent and could change even while the overlay filesystem is mounted, as
577 Changes to the underlying filesystems while part of a mounted overlay
579 the behavior of the overlay is undefined, though it will not result in
582 Offline changes, when the overlay is not mounted, are allowed to the
586 features has been used, the behavior of the overlay is undefined,
589 When the overlay NFS export feature is enabled, overlay filesystems
595 attribute "trusted.overlay.origin" on the upper inode.
599 to by the "trusted.overlay.redirect" extended attribute, will verify
611 feature is enabled, an overlay filesystem may be exported to NFS.
618 "trusted.overlay.upper" with an encoded file handle of the upper
621 When encoding a file handle from an overlay filesystem object, the
629 The encoded overlay file handle includes:
635 are stored in extended attribute "trusted.overlay.origin".
637 When decoding an overlay file handle, the following steps are followed:
643    overlay object that was deleted after its file handle was encoded.
644 5. For a non-directory, instantiate a disconnected overlay dentry from the
647    and index, to lookup a connected overlay dentry.
653 When overlay filesystem has multiple lower layers, a middle layer
659 reconstruct a connected overlay path.  To mitigate the cases of
662 On an overlay filesystem with no upper layer this mitigation cannot be
666 The overlay filesystem does not support non-directory connectable file
697     UUID is stored in xattr "trusted.overlay.uuid", making overlayfs fsid
701     UUID is taken from xattr "trusted.overlay.uuid" if it exists.
702     Upgrade to "uuid=on" on first time mount of new overlay filesystem that
704     Downgrade to "uuid=null" for existing overlay filesystems that were never
713 mounts are only used if data written to the overlay can be recreated
727 When overlay is mounted with "volatile" option, the directory
728 "$workdir/work/incompat/volatile" is created.  During next mount, overlay
740 "user.overlay." xattr namespace instead of "trusted.overlay.".  This is