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
35 make the overlay mount more compliant with filesystem scanners and
40 underlying filesystem, the same compliant behavior could be achieved
48 feature with the "-o xino=on" overlay mount option.  That is useful for the
52 filesystem will fall back to the non xino behavior for that inode.
60 +--------------+------------+------------+-----------------+----------------+
65 +--------------+-----+------+-----+------+--------+--------+--------+-------+
68 +--------------+-----+------+-----+------+--------+--------+--------+-------+
72 +--------------+-----+------+-----+------+--------+--------+--------+-------+
75 +--------------+-----+------+-----+------+--------+--------+--------+-------+
78 +--------------+-----+------+-----+------+--------+--------+--------+-------+
86 ---------------
88 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 -----------
164 --------------------------------
169 directories (non-directories are always opaque).
181 -------
185 obvious way (upper is read first, then lower - entries that already
186 exist are not re-added).  This merged name list is cached in the
200   - read part of a directory
201   - remember an offset, and close the directory
202   - re-open the directory some time later
203   - seek to the remembered offset
213 --------------------
234 - OVERLAY_FS_REDIRECT_DIR:
236 - OVERLAY_FS_REDIRECT_ALWAYS_FOLLOW:
244 - "redirect_dir=BOOL":
246 - "redirect_always_follow=BOOL":
248 - "redirect_max=NUM":
253 - "redirect_dir=on":
255 - "redirect_dir=follow":
257 - "redirect_dir=off":
260 - "redirect_dir=nofollow":
278 Non-directories
279 ---------------
281 Objects that are not directories (files, symlinks, device-special
284 the requires write-access, such as opening for write access, changing
286 to the upper filesystem (copy_up).  Note that creating a hard-link
291 opened for read-write but the data is not modified.
294 exists in the upper filesystem - creating it and any parents as
296 mode, mtime, symlink-target etc.) and then if the object is a file, the
302 filesystem - future operations on the file are barely noticed by the
308 ----------------
316  3) non-mounting task MAY gain additional privileges through the overlay,
340   mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,... /merged
344   cp -a /lower /upper
345   mount --bind /upper /merged
348 the time of copy (on-demand vs. up-front).
352 ---------------------
357   mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged
360 that case the overlay will be read-only.
368 ---------------------
398 --------------------------
438 Non-standard behavior
439 ---------------------
441 Current version of overlayfs can act as a mostly POSIX compliant
449 b) If a file residing on a lower layer is opened for read-only and then
454 compliant filesystem:
462 will fail with EXDEV ("Invalid cross-device link").
491 ---------------------------------
520 ----------
528 non-directory object, the index entry is a hard link to the upper inode.
536 1. For a non-upper object, encode a lower file handle from lower inode
538 3. For a pure-upper object and for an existing non-indexed upper object,
542  - Header including path type information (e.g. lower/upper)
543  - UUID of the underlying filesystem
544  - Underlying filesystem encoding of underlying inode
556 5. For a non-directory, instantiate a disconnected overlay dentry from the
561 Decoding a non-directory file handle may return a disconnected dentry.
578 The overlay filesystem does not support non-directory connectable file
587 read-write mount and will result in an error.
591 --------------
618 ---------
623   https://github.com/amir73il/unionmount-testsuite.git
627   # cd unionmount-testsuite
628   # ./run --ov --verify