Lines Matching +full:layer +full:- +full:depth
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
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
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
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 --------------------
201 When renaming a directory that is on the lower layer or merged (i.e. the
202 directory was not created on the upper layer to start with) overlayfs can
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":
258 Because lower layer redirects cannot be verified with the index, enabling
259 NFS export support on an overlay filesystem with no upper layer requires
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,
310 upper layer based on underlying filesystem permissions, again including
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.
349 top, lower2 the middle and lower3 the bottom layer.
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
362 In the latter case, colons in lower layer directory names will be escaped
366 ---------------------
399 Data-only lower layers
400 ----------------------
405 1) metadata from a file in the upper layer
407 2) st_ino and st_dev object identifier from a file in a lower layer
409 3) data from a file in another lower layer (further below)
411 The "lower data" file can be on any lower layer, except from the top most
412 lower layer.
414 Below the top most lower layer, any number of lower most layers may be defined
415 as "data-only" lower layers, using double colon ("::") separators.
416 A normal lower layer is not allowed to be below a data-only layer, so single
422 mount -t overlay overlay -olowerdir=/l1:/l2:/l3::/do1::/do2 /merged
424 The paths of files in the "data-only" lower layers are not visible in the
426 in the "data-only" lower layers are not visible in overlayfs inodes.
428 Only the data of the files in the "data-only" lower layers may be visible
430 to the absolute path of the "lower data" file in the "data-only" lower layer.
432 Since kernel version v6.8, "data-only" lower layers can also be added using
443 fs-verity support
444 -----------------
447 fs-verity enabled and overlay verity support is enabled, then the
452 When a layer containing verity xattrs is used, it means that any such
453 metacopy file in the upper layer is guaranteed to match the content
454 that was in the lower at the time of the copy-up. If at any time
458 digest check, or from a later read due to fs-verity) and a detailed
459 error is printed to the kernel logs. For more details of how fs-verity
466 layer is fully trusted (by using dm-verity or something similar), then
467 an untrusted lower layer can be used to supply validated file content
469 directories are specified as "Data-only", then they can only supply
471 upper layer.
476 - "off":
479 - "on":
484 - "require":
487 will only be used if the data file has fs-verity enabled,
488 otherwise a full copy-up is used.
491 --------------------------
494 a very common practice. An overlay mount may use the same lower layer
495 path as another overlay mount and it may use a lower layer path that is
496 beneath or above the path of another overlay lower layer path.
498 Using an upper layer path and/or a workdir path that are already used by
502 upper layer and/or workdir path the behavior of the overlay is undefined,
505 Mounting an overlay using an upper layer path, where the upper layer path
507 different lower layer path, is allowed, unless the "index" or "metacopy"
511 handle of the lower layer root directory, along with the UUID of the lower
513 attribute on the upper layer root directory. On subsequent mount attempts,
531 ------------------------
547 alternative form of whiteout is supported. This form is a regular, zero-size
553 mechanism in order to properly nest to any depth.
555 Non-standard behavior
556 ---------------------
564 done in the case when the file resides on a lower layer.
566 b) If a file residing on a lower layer is opened for read-only and then
570 c) If a file residing on a lower layer is being executed, then opening that
583 will fail with EXDEV ("Invalid cross-device link").
614 ---------------------------------
629 behavior on offline changes of the underlying lower layer is different
647 ----------
655 non-directory object, the index entry is a hard link to the upper inode.
663 1. For a non-upper object, encode a lower file handle from lower inode
665 3. For a pure-upper object and for an existing non-indexed upper object,
670 - Header including path type information (e.g. lower/upper)
671 - UUID of the underlying filesystem
672 - Underlying filesystem encoding of underlying inode
679 1. Find underlying layer by UUID and path type information.
684 5. For a non-directory, instantiate a disconnected overlay dentry from the
689 Decoding a non-directory file handle may return a disconnected dentry.
693 When overlay filesystem has multiple lower layers, a middle layer
694 directory may have a "redirect" to lower directory. Because middle layer
697 layer directory. Similarly, a lower file handle that was encoded from a
702 On an overlay filesystem with no upper layer this mitigation cannot be
706 The overlay filesystem does not support non-directory connectable file
715 read-write mount and will result in an error.
725 -------------
730 - "null":
732 - "off":
735 - "on":
740 - "auto": (default)
749 --------------
777 ----------
779 The "-o userxattr" mount option forces overlayfs to use the
785 ---------
790 https://github.com/amir73il/unionmount-testsuite.git
794 # cd unionmount-testsuite
795 # ./run --ov --verify