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
32 In the special case of all overlay layers on the same underlying
48 feature with the "-o xino=on" overlay mount option.  That is useful for the
49 case of underlying filesystems like xfs and tmpfs, which use 64bit inode
50 numbers, but are very unlikely to use the high inode number bits.  In case
60 +--------------+------------+------------+-----------------+----------------+
65 +--------------+-----+------+-----+------+--------+--------+--------+-------+
68 +--------------+-----+------+-----+------+--------+--------+--------+-------+
72 +--------------+-----+------+-----+------+--------+--------+--------+-------+
75 +--------------+-----+------+-----+------+--------+--------+--------+-------+
78 +--------------+-----+------+-----+------+--------+--------+--------+-------+
85 Upper and Lower
86 ---------------
88 An overlay filesystem combines two filesystems - an 'upper' filesystem
89 and a 'lower' filesystem.  When a name exists in both filesystems, the
91 'lower' filesystem is either hidden or, in the case of directories,
94 It would be more correct to refer to an upper and lower 'directory
98 lower.
100 The lower filesystem can be any filesystem supported by Linux and does
101 not need to be writable.  The lower filesystem can even be another
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 By default, all access to the upper, lower and work directories is the
147 In the case where caller MAC or DAC credentials do not overlap, a
148 use case available in older versions of the driver, the
152 caller without certain key capabilities or lower privilege will not
157 caller can fill cache, then a lower privilege can read the directory
164 --------------------------------
166 In order to support rm and rmdir without changing the lower
169 directories (non-directories are always opaque).
173 matching name in the lower level is ignored, and the whiteout itself
178 directory in the lower filesystem with the same name is ignored.
181 -------
184 lower directories are each read and the name lists merged in the
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
210 underlying directory (upper or lower).
213 --------------------
215 When renaming a directory that is on the lower layer or merged (i.e. the
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":
265 indexed by the file handle of the lower inode and a file handle of the
270 lower directory.  In that case, lookup returns an error and warns about
273 Because lower layer redirects cannot be verified with the index, enabling
278 Non-directories
279 ---------------
281 Objects that are not directories (files, symlinks, device-special
282 files etc.) are presented either from the upper or lower filesystem as
283 appropriate.  When a file in the lower filesystem is accessed in a way
284 the requires write-access, such as opening for write access, changing
285 some metadata etc., the file is first copied from the lower filesystem
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
297 data is copied from the lower to the upper filesystem.  Finally any
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,
317  compared to direct access on underlying lower or upper filesystems
324  b) check if mounting task would be allowed real operation on lower or
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).
351 Multiple lower layers
352 ---------------------
354 Multiple lower layers can now be given using the colon (":") as a
357   mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged
360 that case the overlay will be read-only.
362 The specified lower directories will be stacked beginning from the
368 ---------------------
384 Do not use metacopy=on with untrusted upper/lower directories. Otherwise
386 appropriate REDIRECT and METACOPY xattrs, and gain access to file on lower
398 --------------------------
400 Lower layers may be shared among several overlay mounts and that is indeed
401 a very common practice.  An overlay mount may use the same lower layer
402 path as another overlay mount and it may use a lower layer path that is
403 beneath or above the path of another overlay lower layer path.
414 different lower layer path, is allowed, unless the "inodes index" feature
418 handle of the lower layer root directory, along with the UUID of the lower
421 the lower root directory file handle and lower filesystem UUID are compared
423 lower root origin, mount will fail with ESTALE.  An overlayfs mount with
424 "inodes index" enabled will fail with EOPNOTSUPP if the lower filesystem
425 does not support NFS export, lower filesystem does not have a valid UUID or
429 mount time. So if same upper is mounted with different set of lower, mount
435 the copied layers will fail the verification of the lower root file handle.
438 Non-standard behavior
439 ---------------------
447 done in the case when the file resides on a lower layer.
449 b) If a file residing on a lower layer is opened for read-only and then
461 If this feature is disabled, then rename(2) on a lower or merged directory
462 will fail with EXDEV ("Invalid cross-device link").
491 ---------------------------------
494 the upper or the lower trees.
502 behavior on offline changes of the underlying lower layer is different
505 On every copy_up, an NFS file handle of the lower inode, along with the
506 UUID of the lower filesystem, are encoded and stored in an extended
510 that found a lower directory at the lookup path or at the path pointed
512 that the found lower directory file handle and lower filesystem UUID
514 found lower directory does not match the stored origin, that directory
520 ----------
525 With the "nfs_export" feature, on copy_up of any lower object, an index
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
537 2. For an indexed object, encode a lower file handle from copy_up origin
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
553 3. For a lower file handle, lookup the handle in index directory by name.
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.
565 When overlay filesystem has multiple lower layers, a middle layer
566 directory may have a "redirect" to lower directory.  Because middle layer
567 "redirects" are not indexed, a lower file handle that was encoded from the
569 layer directory.  Similarly, a lower file handle that was encoded from a
572 directories that cannot be decoded from a lower file handle, these
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