Documentation/filesystems/overlayfs.rst

27 upper filesystem that is providing the object.  Similarly st_ino will
85 Upper and Lower
88 An overlay filesystem combines two filesystems - an 'upper' filesystem
90 object in the 'upper' filesystem is visible while the object in the
92 merged with the 'upper' object.
94 It would be more correct to refer to an upper and lower 'directory
97 requirement that the root of a filesystem be given for either upper or
102 overlayfs.  The upper filesystem will normally be writable and if it
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,\
133 directory is created, otherwise only one is stored: the upper if it
137 such as metadata and extended attributes are reported for the upper
143 By default, all access to the upper, lower and work directories is the
167 filesystem, an overlay filesystem needs to record in the upper filesystem
172 When a whiteout is found in the upper level of a merged directory, any
177 to "y".  Where the upper filesystem contains an opaque directory, any
183 When a 'readdir' request is made on a merged directory, the upper and
185 obvious way (upper is read first, then lower - entries that already
210 underlying directory (upper or lower).
216 directory was not created on the upper layer to start with) overlayfs can
266 upper directory is stored in a "trusted.overlay.upper" extended attribute
267 on the index entry.  On lookup of a merged directory, if the upper
269 indication that multiple upper directories may be redirected to the same
274 NFS export support on an overlay filesystem with no upper layer requires
282 files etc.) are presented either from the upper or lower filesystem as
286 to the upper filesystem (copy_up).  Note that creating a hard-link
294 exists in the upper filesystem - creating it and any parents as
297 data is copied from the lower to the upper filesystem.  Finally any
301 provides direct access to the newly created file in the upper
317  compared to direct access on underlying lower or upper filesystems
325     upper layer based on underlying filesystem permissions, again including
340   mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,... /merged
344   cp -a /lower /upper
345   mount --bind /upper /merged
384 Do not use metacopy=on with untrusted upper/lower directories. Otherwise
405 Using an upper layer path and/or a workdir path that are already used by
409 upper layer and/or workdir path the behavior of the overlay is undefined,
412 Mounting an overlay using an upper layer path, where the upper layer path
420 attribute on the upper layer root directory.  On subsequent mount attempts,
422 to the stored origin in upper root directory.  On failure to verify the
426 if the upper filesystem does not support extended attributes.
429 mount time. So if same upper is mounted with different set of lower, mount
494 the upper or the lower trees.
507 attribute "trusted.overlay.origin" on the upper inode.
515 will not be merged with the upper directory.
528 non-directory object, the index entry is a hard link to the upper inode.
530 "trusted.overlay.upper" with an encoded file handle of the upper
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,
539    encode an upper file handle from upper inode
542  - Header including path type information (e.g. lower/upper)
562 copy_up of that disconnected dentry will create an upper index entry with
563 no upper alias.
568 "redirect" origin directory, cannot be used to find the middle or upper
573 directories are copied up on encode and encoded as an upper file handle.
574 On an overlay filesystem with no upper layer this mitigation cannot be
583 verified on mount time to check that upper file handles are not stale.
599 sync calls to the upper filesystem are omitted.
612 indicator that user should throw away upper and work directories and create