Lines Matching +full:lower +full:- +full:case
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
32 In the special case of all overlay layers on the same underlying
44 underlying filesystems rarely use the high inode number bits. In case
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 +--------------+-----+------+-----+------+--------+--------+--------+-------+
83 Upper and Lower
84 ---------------
86 An overlay filesystem combines two filesystems - an 'upper' filesystem
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
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
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.
141 --------------------------------
143 In order to support rm and rmdir without changing the lower
146 directories (non-directories are always opaque).
149 as a zero-size regular file with the xattr "trusted.overlay.whiteout".
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.
164 on all entries during readdir in the common case.
167 -------
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
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
196 underlying directory (upper or lower).
199 --------------------
201 When renaming a directory that is on the lower layer or merged (i.e. the
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":
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
263 Non-directories
264 ---------------
266 Objects that are not directories (files, symlinks, device-special
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
269 that requires write-access, such as opening for write access, changing
270 some metadata etc., the file is first copied from the lower filesystem
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
282 data is copied from the lower to the upper filesystem. Finally any
287 filesystem - future operations on the file are barely noticed by the
293 ----------------
296 accessing lower or upper filesystems.
316 compared to direct access on underlying lower or upper filesystems
323 b) check if stashed credentials would be allowed real operation on lower or
339 mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,... /merged
343 cp -a /lower /upper
344 mount --bind /upper /merged
347 the time of copy (on-demand vs. up-front).
350 Multiple lower layers
351 ---------------------
353 Multiple lower layers can now be given using the colon (":") as a
356 mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged
359 that case the overlay will be read-only.
361 The specified lower directories will be stacked beginning from the
365 Note: directory names containing colons can be provided as lower layer by
368 mount -t overlay overlay -olowerdir=/a\:lower\:\:dir /merged
371 be configured as lower layer using the "lowerdir+" mount options and the
374 fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir+", "/a:lower::dir", 0);
376 In the latter case, colons in lower layer directory names will be escaped
380 ---------------------
387 WRITE operation. After the lower file's data is copied up,
399 Do not use metacopy=on with untrusted upper/lower directories. Otherwise
401 appropriate REDIRECT and METACOPY xattrs, and gain access to file on lower
413 Data-only lower layers
414 ----------------------
421 2) st_ino and st_dev object identifier from a file in a lower layer
423 3) data from a file in another lower layer (further below)
425 The "lower data" file can be on any lower layer, except from the top most
426 lower layer.
428 Below the topmost lower layer, any number of lowermost layers may be defined
429 as "data-only" lower layers, using double colon ("::") separators.
430 A normal lower layer is not allowed to be below a data-only layer, so single
436 mount -t overlay overlay -olowerdir=/l1:/l2:/l3::/do1::/do2 /merged
438 The paths of files in the "data-only" lower layers are not visible in the
440 in the "data-only" lower layers are not visible in overlayfs inodes.
442 Only the data of the files in the "data-only" lower layers may be visible
443 when a "metacopy" file in one of the lower layers above it, has a "redirect"
444 to the absolute path of the "lower data" file in the "data-only" lower layer.
447 least one data-only layer to enable redirection of data to a data-only layer.
448 In this case other forms of metacopy are rejected. Note: this way, data-only
449 layers may be used together with "userxattr", in which case careful attention
453 Since kernel version v6.8, "data-only" lower layers can also be added using
465 --------------------------------------
481 fs-verity support
482 -----------------
484 During metadata copy up of a lower file, if the source file has
485 fs-verity enabled and overlay verity support is enabled, then the
486 digest of the lower file is added to the "trusted.overlay.metacopy"
487 xattr. This is then used to verify the content of the lower file
492 that was in the lower at the time of the copy-up. If at any time
493 (during a mount, after a remount, etc) such a file in the lower is
496 digest check, or from a later read due to fs-verity) and a detailed
497 error is printed to the kernel logs. For more details of how fs-verity
504 layer is fully trusted (by using dm-verity or something similar), then
505 an untrusted lower layer can be used to supply validated file content
506 for all metacopy files. If additionally the untrusted lower
507 directories are specified as "Data-only", then they can only supply
514 - "off":
517 - "on":
522 - "require":
525 will only be used if the data file has fs-verity enabled,
526 otherwise a full copy-up is used.
529 --------------------------
531 Lower layers may be shared among several overlay mounts and that is indeed
532 a very common practice. An overlay mount may use the same lower layer
533 path as another overlay mount and it may use a lower layer path that is
534 beneath or above the path of another overlay lower layer path.
545 different lower layer path, is allowed, unless the "index" or "metacopy"
549 handle of the lower layer root directory, along with the UUID of the lower
552 the lower root directory file handle and lower filesystem UUID are compared
554 lower root origin, mount will fail with ESTALE. An overlayfs mount with
555 "index" enabled will fail with EOPNOTSUPP if the lower filesystem
556 does not support NFS export, lower filesystem does not have a valid UUID or
560 mount time. So if same upper is mounted with different set of lower, mount
566 the copied layers will fail the verification of the lower root file handle.
569 ------------------------
571 It is possible to use a lower directory that is stored on an overlayfs
579 in the lower dir will be exposed as a regular file with a
583 A lower dir with a regular whiteout will always be handled by the overlayfs
585 alternative form of whiteout is supported. This form is a regular, zero-size
589 userspace tools (like containers) that generate lower layers.
593 Non-standard behavior
594 ---------------------
602 done in the case when the file resides on a lower layer.
604 b) If a file residing on a lower layer is opened for read-only and then
608 c) If a file residing on a lower layer is being executed, then opening that
620 If this feature is disabled, then rename(2) on a lower or merged directory
621 will fail with EXDEV ("Invalid cross-device link").
652 ---------------------------------
660 upper tree. Offline changes to the lower tree are only allowed if the
662 have not been used. If the lower tree is modified and any of these
667 behavior on offline changes of the underlying lower layer is different
670 On every copy_up, an NFS file handle of the lower inode, along with the
671 UUID of the lower filesystem, are encoded and stored in an extended
675 that found a lower directory at the lookup path or at the path pointed
677 that the found lower directory file handle and lower filesystem UUID
679 found lower directory does not match the stored origin, that directory
685 ----------
690 With the "nfs_export" feature, on copy_up of any lower object, an index
693 non-directory object, the index entry is a hard link to the upper inode.
701 1. For a non-upper object, encode a lower file handle from lower inode
702 2. For an indexed object, encode a lower file handle from copy_up origin
703 3. For a pure-upper object and for an existing non-indexed upper object,
708 - Header including path type information (e.g. lower/upper)
709 - UUID of the underlying filesystem
710 - Underlying filesystem encoding of underlying inode
719 3. For a lower file handle, lookup the handle in index directory by name.
722 5. For a non-directory, instantiate a disconnected overlay dentry from the
727 Decoding a non-directory file handle may return a disconnected dentry.
731 When overlay filesystem has multiple lower layers, a middle layer
732 directory may have a "redirect" to lower directory. Because middle layer
733 "redirects" are not indexed, a lower file handle that was encoded from the
735 layer directory. Similarly, a lower file handle that was encoded from a
738 directories that cannot be decoded from a lower file handle, these
744 The overlay filesystem does not support non-directory connectable file
753 read-write mount and will result in an error.
757 can be useful in case the underlying disk is copied and the UUID of this copy
758 is changed. This is only applicable if all lower/upper/work directories are on
763 -------------
768 - "null":
770 - "off":
773 - "on":
778 - "auto": (default)
787 --------------
815 ----------
817 The "-o userxattr" mount option forces overlayfs to use the
823 ---------
828 https://github.com/amir73il/unionmount-testsuite.git
832 # cd unionmount-testsuite
833 # ./run --ov --verify