Documentation/filesystems/overlayfs.rst

1 .. SPDX-License-Identifier: GPL-2.0
10 overlay-filesystem functionality in Linux (sometimes referred to as
11 union-filesystems).  An overlay-filesystem tries to present a
17 ---------------
25 While directories will report an st_dev from the overlay-filesystem,
26 non-directory objects may report an st_dev from the lower filesystem or
29 over the lifetime of a non-directory object.  Many applications and
46 filesystem will fall back to the non xino behavior for that inode.
48 The "xino" feature can be enabled with the "-o xino=on" overlay mount option.
51 the lifetime of the filesystem.  The "-o xino=auto" overlay mount option
60 +--------------+------------+------------+-----------------+----------------+
65 +--------------+-----+------+-----+------+--------+--------+--------+-------+
68 +--------------+-----+------+-----+------+--------+--------+--------+-------+
72 +--------------+-----+------+-----+------+--------+--------+--------+-------+
74 +--------------+-----+------+-----+------+--------+--------+--------+-------+
77 +--------------+-----+------+-----+------+--------+--------+--------+-------+
84 ---------------
86 An overlay filesystem combines two filesystems - an 'upper' filesystem
106 A read-only overlay of two read-only filesystems may use any
110 -----------
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
120 At mount time, the two directories given as mount options "lowerdir" and
123   mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,\
141 --------------------------------
146 directories (non-directories are always opaque).
149 as a zero-size regular file with the xattr "trusted.overlay.whiteout".
167 -------
171 obvious way (upper is read first, then lower - entries that already
172 exist are not re-added).  This merged name list is cached in the
174 directory is opened and read by two processes at the same time, they
186  - read part of a directory
187  - remember an offset, and close the directory
188  - re-open the directory some time later
189  - seek to the remembered offset
199 --------------------
220 - OVERLAY_FS_REDIRECT_DIR:
222 - OVERLAY_FS_REDIRECT_ALWAYS_FOLLOW:
230 - "redirect_dir=BOOL":
232 - "redirect_always_follow=BOOL":
234 - "redirect_max=NUM":
239 - "redirect_dir=on":
241 - "redirect_dir=follow":
243 - "redirect_dir=nofollow":
245 - "redirect_dir=off":
263 Non-directories
264 ---------------
266 Objects that are not directories (files, symlinks, device-special
269 the requires write-access, such as opening for write access, changing
271 to the upper filesystem (copy_up).  Note that creating a hard-link
276 opened for read-write but the data is not modified.
279 exists in the upper filesystem - creating it and any parents as
281 mode, mtime, symlink-target etc.) and then if the object is a file, the
287 filesystem - future operations on the file are barely noticed by the
293 ----------------
301  3) non-mounting task MAY gain additional privileges through the overlay,
325   mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,... /merged
329   cp -a /lower /upper
330   mount --bind /upper /merged
333 the time of copy (on-demand vs. up-front).
337 ---------------------
342   mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged
345 that case the overlay will be read-only.
354   mount -t overlay overlay -olowerdir=/a\:lower\:\:dir /merged
366 ---------------------
378 by default. Or one can enable/disable it at module load time with module
396 Data-only lower layers
397 ----------------------
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
419   mount -t overlay overlay -olowerdir=/l1:/l2:/l3::/do1::/do2 /merged
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
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
440 fs-verity support
441 -----------------
444 fs-verity enabled and overlay verity support is enabled, then the
447 each the time the metacopy file is opened.
451 that was in the lower at the time of the copy-up. If at any time
455 digest check, or from a later read due to fs-verity) and a detailed
456 error is printed to the kernel logs. For more details of how fs-verity
463 layer is fully trusted (by using dm-verity or something similar), then
466 directories are specified as "Data-only", then they can only supply
473 - "off":
476 - "on":
481 - "require":
484     will only be used if the data file has fs-verity enabled,
485     otherwise a full copy-up is used.
488 --------------------------
498 If files are accessed from two overlayfs mounts which share or overlap the
507 With the "index" feature, on the first time mount, an NFS file
519 mount time. So if same upper is mounted with different set of lower, mount
528 ------------------------
540 repeating the prefix multiple time, as each instance only removes one prefix.
544 alternative form of whiteout is supported. This form is a regular, zero-size
552 Non-standard behavior
553 ---------------------
563  b) If a file residing on a lower layer is opened for read-only and then
580 will fail with EXDEV ("Invalid cross-device link").
611 ---------------------------------
637 match the origin file handle that was stored at copy_up time.  If a
644 ----------
652 non-directory object, the index entry is a hard link to the upper inode.
660  1. For a non-upper object, encode a lower file handle from lower inode
662  3. For a pure-upper object and for an existing non-indexed upper object,
667  - Header including path type information (e.g. lower/upper)
668  - UUID of the underlying filesystem
669  - Underlying filesystem encoding of underlying inode
681  5. For a non-directory, instantiate a disconnected overlay dentry from the
686 Decoding a non-directory file handle may return a disconnected dentry.
703 The overlay filesystem does not support non-directory connectable file
708 verified on mount time to check that upper file handles are not stale.
712 read-write mount and will result in an error.
722 -------------
727 - "null":
729 - "off":
732 - "on":
737 - "auto": (default)
739     Upgrade to "uuid=on" on first time mount of new overlay filesystem that
746 --------------
774 ----------
776 The "-o userxattr" mount option forces overlayfs to use the
782 ---------
787 https://github.com/amir73il/unionmount-testsuite.git
791   # cd unionmount-testsuite
792   # ./run --ov --verify