Documentation/filesystems/overlayfs.rst

10 overlay-filesystem functionality in Linux (sometimes referred to as
11 union-filesystems).  An overlay-filesystem tries to present a
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 handles with 32bit inode number encoding (e.g. ext4), overlay filesystem
48 feature with the "-o xino=on" overlay mount option.  That is useful for the
51 the underlying inode number does overflow into the high xino bits, overlay
54 The following table summarizes what can be expected in different overlay
88 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
167 filesystem, an overlay filesystem needs to record in the upper filesystem
176 A directory is made opaque by setting the xattr "trusted.overlay.opaque"
225    copied up (but not the contents).  Then the "trusted.overlay.redirect"
227    root of the overlay.  Finally the directory is moved to the new
242 Module options (can also be changed through /sys/module/overlay/parameters/):
266 upper directory is stored in a "trusted.overlay.upper" extended attribute
274 NFS export support on an overlay filesystem with no upper layer requires
300 Once the copy_up is complete, the overlay filesystem simply
303 overlay filesystem (though an operation on the name of the file such as
310 Permission checking in the overlay filesystem follows these principles:
314  2) task creating the overlay mount MUST NOT gain additional privileges
316  3) non-mounting task MAY gain additional privileges through the overlay,
340   mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,... /merged
357   mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged
360 that case the overlay will be read-only.
400 Lower layers may be shared among several overlay mounts and that is indeed
401 a very common practice.  An overlay mount may use the same lower layer
402 path as another overlay mount and it may use a lower layer path that is
403 beneath or above the path of another overlay lower layer path.
406 another overlay mount is not allowed and may fail with EBUSY.  Using
409 upper layer and/or workdir path the behavior of the overlay is undefined,
412 Mounting an overlay using an upper layer path, where the upper layer path
413 was previously used by another mounted overlay in combination with a
419 filesystem, are encoded and stored in the "trusted.overlay.origin" extended
432 It is quite a common practice to copy overlay layers to a different
478 underlying filesystem for all layers making up the overlay.
485 overlay filesystem and the value of st_ino for directory objects may not be
486 persistent and could change even while the overlay filesystem is mounted, as
493 Offline changes, when the overlay is not mounted, are allowed to either
496 Changes to the underlying filesystems while part of a mounted overlay
498 the behavior of the overlay is undefined, though it will not result in
501 When the overlay NFS export feature is enabled, overlay filesystems
507 attribute "trusted.overlay.origin" on the upper inode.
511 to by the "trusted.overlay.redirect" extended attribute, will verify
523 feature is enabled, an overlay filesystem may be exported to NFS.
530 "trusted.overlay.upper" with an encoded file handle of the upper
533 When encoding a file handle from an overlay filesystem object, the
541 The encoded overlay file handle includes:
547 are stored in extended attribute "trusted.overlay.origin".
549 When decoding an overlay file handle, the following steps are followed:
555    overlay object that was deleted after its file handle was encoded.
556 5. For a non-directory, instantiate a disconnected overlay dentry from the
559    and index, to lookup a connected overlay dentry.
565 When overlay filesystem has multiple lower layers, a middle layer
571 reconstruct a connected overlay path.  To mitigate the cases of
574 On an overlay filesystem with no upper layer this mitigation cannot be
578 The overlay filesystem does not support non-directory connectable file
595 mounts are only used if data written to the overlay can be recreated
609 When overlay is mounted with "volatile" option, the directory
610 "$workdir/work/incompat/volatile" is created.  During next mount, overlay