Lines Matching +full:y +full:- +full:origin
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 +--------------+-----+------+-----+------+--------+--------+--------+-------+
66 | All layers | Y | Y | Y | Y | Y | Y | Y | Y |
68 +--------------+-----+------+-----+------+--------+--------+--------+-------+
69 | Layers not | N | N | Y | N | N | Y | N | Y |
72 +--------------+-----+------+-----+------+--------+--------+--------+-------+
73 | xino=on/auto | Y | Y | Y | Y | Y | Y | Y | Y |
74 +--------------+-----+------+-----+------+--------+--------+--------+-------+
75 | xino=on/auto,| N | N | Y | N | N | Y | N | Y |
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".
156 to "y". Where the upper filesystem contains an opaque directory, any
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 --------------------
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 that 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 ----------------
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).
351 ---------------------
356 mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged
359 that case the overlay will be read-only.
368 mount -t overlay overlay -olowerdir=/a\:lower\:\:dir /merged
380 ---------------------
413 Data-only lower layers
414 ----------------------
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
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
453 Since kernel version v6.8, "data-only" lower layers can also be added using
465 --------------------------------------
481 fs-verity support
482 -----------------
485 fs-verity enabled and overlay verity support is enabled, then the
492 that was in the lower at the time of the copy-up. If at any time
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
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 --------------------------
550 filesystem, are encoded and stored in the "trusted.overlay.origin" extended
553 to the stored origin in upper root directory. On failure to verify the
554 lower root origin, mount will fail with ESTALE. An overlayfs mount with
569 ------------------------
585 alternative form of whiteout is supported. This form is a regular, zero-size
593 Non-standard behavior
594 ---------------------
604 b) If a file residing on a lower layer is opened for read-only and then
618 the kernel config option CONFIG_OVERLAY_FS_REDIRECT_DIR=y.
621 will fail with EXDEV ("Invalid cross-device link").
627 kernel config option CONFIG_OVERLAY_FS_INDEX=y.
638 CONFIG_OVERLAY_FS_XINO_AUTO=y. Also implicitly enabled by using the same
652 ---------------------------------
672 attribute "trusted.overlay.origin" on the upper inode.
678 match the origin file handle that was stored at copy_up time. If a
679 found lower directory does not match the stored origin, that directory
685 ----------
692 hexadecimal representation of the copy up origin file handle. For a
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
713 are stored in extended attribute "trusted.overlay.origin".
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.
734 "redirect" origin directory, cannot be used to find the middle or upper
736 descendant of the "redirect" origin directory, cannot be used to
744 The overlay filesystem does not support non-directory connectable file
753 read-write mount and will result in an error.
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