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).
150 matching name in the lower level is ignored, and the whiteout itself
155 directory in the lower filesystem with the same name is ignored.
158 -------
161 lower directories are each read and the name lists merged in the
162 obvious way (upper is read first, then lower - entries that already
163 exist are not re-added). This merged name list is cached in the
177 - read part of a directory
178 - remember an offset, and close the directory
179 - re-open the directory some time later
180 - seek to the remembered offset
187 underlying directory (upper or lower).
190 --------------------
192 When renaming a directory that is on the lower layer or merged (i.e. the
211 - OVERLAY_FS_REDIRECT_DIR:
213 - OVERLAY_FS_REDIRECT_ALWAYS_FOLLOW:
221 - "redirect_dir=BOOL":
223 - "redirect_always_follow=BOOL":
225 - "redirect_max=NUM":
230 - "redirect_dir=on":
232 - "redirect_dir=follow":
234 - "redirect_dir=off":
237 - "redirect_dir=nofollow":
242 indexed by the file handle of the lower inode and a file handle of the
247 lower directory. In that case, lookup returns an error and warns about
250 Because lower layer redirects cannot be verified with the index, enabling
255 Non-directories
256 ---------------
258 Objects that are not directories (files, symlinks, device-special
259 files etc.) are presented either from the upper or lower filesystem as
260 appropriate. When a file in the lower filesystem is accessed in a way
261 the requires write-access, such as opening for write access, changing
262 some metadata etc., the file is first copied from the lower filesystem
263 to the upper filesystem (copy_up). Note that creating a hard-link
268 opened for read-write but the data is not modified.
271 exists in the upper filesystem - creating it and any parents as
273 mode, mtime, symlink-target etc.) and then if the object is a file, the
274 data is copied from the lower to the upper filesystem. Finally any
279 filesystem - future operations on the file are barely noticed by the
285 ----------------
293 3) non-mounting task MAY gain additional privileges through the overlay,
294 compared to direct access on underlying lower or upper filesystems
301 b) check if mounting task would be allowed real operation on lower or
317 mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,... /merged
321 cp -a /lower /upper
322 mount --bind /upper /merged
325 the time of copy (on-demand vs. up-front).
328 Multiple lower layers
329 ---------------------
331 Multiple lower layers can now be given using the colon (":") as a
334 mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged
337 that case the overlay will be read-only.
339 The specified lower directories will be stacked beginning from the
345 ---------------------
361 Do not use metacopy=on with untrusted upper/lower directories. Otherwise
363 appropriate REDIRECT and METACOPY xattrs, and gain access to file on lower
375 --------------------------
377 Lower layers may be shared among several overlay mounts and that is indeed
378 a very common practice. An overlay mount may use the same lower layer
379 path as another overlay mount and it may use a lower layer path that is
380 beneath or above the path of another overlay lower layer path.
391 different lower layer path, is allowed, unless the "inodes index" feature
395 handle of the lower layer root directory, along with the UUID of the lower
398 the lower root directory file handle and lower filesystem UUID are compared
400 lower root origin, mount will fail with ESTALE. An overlayfs mount with
401 "inodes index" enabled will fail with EOPNOTSUPP if the lower filesystem
402 does not support NFS export, lower filesystem does not have a valid UUID or
406 mount time. So if same upper is mounted with different set of lower, mount
412 the copied layers will fail the verification of the lower root file handle.
415 Non-standard behavior
416 ---------------------
424 done in the case when the file resides on a lower layer.
426 b) If a file residing on a lower layer is opened for read-only and then
430 c) If a file residing on a lower layer is being executed, then opening that
441 If this feature is disabled, then rename(2) on a lower or merged directory
442 will fail with EXDEV ("Invalid cross-device link").
471 ---------------------------------
479 upper tree. Offline changes to the lower tree are only allowed if the
481 have not been used. If the lower tree is modified and any of these
486 behavior on offline changes of the underlying lower layer is different
489 On every copy_up, an NFS file handle of the lower inode, along with the
490 UUID of the lower filesystem, are encoded and stored in an extended
494 that found a lower directory at the lookup path or at the path pointed
496 that the found lower directory file handle and lower filesystem UUID
498 found lower directory does not match the stored origin, that directory
504 ----------
509 With the "nfs_export" feature, on copy_up of any lower object, an index
512 non-directory object, the index entry is a hard link to the upper inode.
520 1. For a non-upper object, encode a lower file handle from lower inode
521 2. For an indexed object, encode a lower file handle from copy_up origin
522 3. For a pure-upper object and for an existing non-indexed upper object,
526 - Header including path type information (e.g. lower/upper)
527 - UUID of the underlying filesystem
528 - Underlying filesystem encoding of underlying inode
537 3. For a lower file handle, lookup the handle in index directory by name.
540 5. For a non-directory, instantiate a disconnected overlay dentry from the
545 Decoding a non-directory file handle may return a disconnected dentry.
549 When overlay filesystem has multiple lower layers, a middle layer
550 directory may have a "redirect" to lower directory. Because middle layer
551 "redirects" are not indexed, a lower file handle that was encoded from the
553 layer directory. Similarly, a lower file handle that was encoded from a
556 directories that cannot be decoded from a lower file handle, these
562 The overlay filesystem does not support non-directory connectable file
571 read-write mount and will result in an error.
575 can be useful in case the underlying disk is copied and the UUID of this copy
576 is changed. This is only applicable if all lower/upper/work directories are on
580 --------------
608 ----------
610 The "-o userxattr" mount option forces overlayfs to use the
616 ---------
621 https://github.com/amir73il/unionmount-testsuite.git
625 # cd unionmount-testsuite
626 # ./run --ov --verify