Documentation/filesystems/overlayfs.rst

26 non-directory objects may report an st_dev from the lower filesystem or
83 Upper and Lower
87 and a 'lower' filesystem.  When a name exists in both filesystems, the
89 'lower' filesystem is either hidden or, in the case of directories,
92 It would be more correct to refer to an upper and lower 'directory
96 lower.
98 A wide range of filesystems supported by Linux can be the lower filesystem,
100 needed for OverlayFS to work.  The lower filesystem does not need to be
101 writable.  The lower filesystem can even be another overlayfs.  The upper
113 upper and lower filesystems and refers to a non-directory in either,
114 then the lower object is hidden - the name refers only to the upper
117 Where both upper and lower objects are directories, a merged directory
123   mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,\
134 exists, else the lower.
138 directory only.  These attributes of the lower directory are hidden.
143 In order to support rm and rmdir without changing the lower
152 matching name in the lower level is ignored, and the whiteout itself
157 directory in the lower filesystem with the same name is ignored.
170 lower directories are each read and the name lists merged in the
171 obvious way (upper is read first, then lower - entries that already
196 underlying directory (upper or lower).
201 When renaming a directory that is on the lower layer or merged (i.e. the
250 indexed by the file handle of the lower inode and a file handle of the
255 lower directory.  In that case, lookup returns an error and warns about
258 Because lower layer redirects cannot be verified with the index, enabling
267 files etc.) are presented either from the upper or lower filesystem as
268 appropriate.  When a file in the lower filesystem is accessed in a way
270 some metadata etc., the file is first copied from the lower filesystem
282 data is copied from the lower to the upper filesystem.  Finally any
302     compared to direct access on underlying lower or upper filesystems
309  b) check if mounting task would be allowed real operation on lower or
325   mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,... /merged
329   cp -a /lower /upper
336 Multiple lower layers
339 Multiple lower layers can now be given using the colon (":") as a
347 The specified lower directories will be stacked beginning from the
351 Note: directory names containing colons can be provided as lower layer by
354   mount -t overlay overlay -olowerdir=/a\:lower\:\:dir /merged
357 be configured as lower layer using the "lowerdir+" mount options and the
360   fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir+", "/a:lower::dir", 0);
362 In the latter case, colons in lower layer directory names will be escaped
382 Do not use metacopy=on with untrusted upper/lower directories. Otherwise
384 appropriate REDIRECT and METACOPY xattrs, and gain access to file on lower
396 Data-only lower layers
404  2) st_ino and st_dev object identifier from a file in a lower layer
406  3) data from a file in another lower layer (further below)
408 The "lower data" file can be on any lower layer, except from the top most
409 lower layer.
411 Below the top most lower layer, any number of lower most layers may be defined
412 as "data-only" lower layers, using double colon ("::") separators.
413 A normal lower layer is not allowed to be below a data-only layer, so single
421 The paths of files in the "data-only" lower layers are not visible in the
423 in the "data-only" lower layers are not visible in overlayfs inodes.
425 Only the data of the files in the "data-only" lower layers may be visible
426 when a "metacopy" file in one of the lower layers above it, has a "redirect"
427 to the absolute path of the "lower data" file in the "data-only" lower layer.
429 Since kernel version v6.8, "data-only" lower layers can also be added using
443 During metadata copy up of a lower file, if the source file has
445 digest of the lower file is added to the "trusted.overlay.metacopy"
446 xattr. This is then used to verify the content of the lower file
451 that was in the lower at the time of the copy-up. If at any time
452 (during a mount, after a remount, etc) such a file in the lower is
464 an untrusted lower layer can be used to supply validated file content
465 for all metacopy files.  If additionally the untrusted lower
490 Lower layers may be shared among several overlay mounts and that is indeed
491 a very common practice.  An overlay mount may use the same lower layer
492 path as another overlay mount and it may use a lower layer path that is
493 beneath or above the path of another overlay lower layer path.
504 different lower layer path, is allowed, unless the "index" or "metacopy"
508 handle of the lower layer root directory, along with the UUID of the lower
511 the lower root directory file handle and lower filesystem UUID are compared
513 lower root origin, mount will fail with ESTALE.  An overlayfs mount with
514 "index" enabled will fail with EOPNOTSUPP if the lower filesystem
515 does not support NFS export, lower filesystem does not have a valid UUID or
519 mount time. So if same upper is mounted with different set of lower, mount
525 the copied layers will fail the verification of the lower root file handle.
530 It is possible to use a lower directory that is stored on an overlayfs
538 in the lower dir will be exposed as a regular file with a
542 A lower dir with a regular whiteout will always be handled by the overlayfs
548 userspace tools (like containers) that generate lower layers.
561     done in the case when the file resides on a lower layer.
563  b) If a file residing on a lower layer is opened for read-only and then
567  c) If a file residing on a lower layer is being executed, then opening that
579 If this feature is disabled, then rename(2) on a lower or merged directory
619 upper tree.  Offline changes to the lower tree are only allowed if the
621 have not been used.  If the lower tree is modified and any of these
626 behavior on offline changes of the underlying lower layer is different
629 On every copy_up, an NFS file handle of the lower inode, along with the
630 UUID of the lower filesystem, are encoded and stored in an extended
634 that found a lower directory at the lookup path or at the path pointed
636 that the found lower directory file handle and lower filesystem UUID
638 found lower directory does not match the stored origin, that directory
649 With the "nfs_export" feature, on copy_up of any lower object, an index
660  1. For a non-upper object, encode a lower file handle from lower inode
661  2. For an indexed object, encode a lower file handle from copy_up origin
667  - Header including path type information (e.g. lower/upper)
678  3. For a lower file handle, lookup the handle in index directory by name.
690 When overlay filesystem has multiple lower layers, a middle layer
691 directory may have a "redirect" to lower directory.  Because middle layer
692 "redirects" are not indexed, a lower file handle that was encoded from the
694 layer directory.  Similarly, a lower file handle that was encoded from a
697 directories that cannot be decoded from a lower file handle, these
717 is changed. This is only applicable if all lower/upper/work directories are on