Documentation/filesystems/overlayfs.rst

27 upper filesystem that is providing the object.  Similarly st_ino will
83 Upper and Lower
86 An overlay filesystem combines two filesystems - an 'upper' filesystem
88 object in the 'upper' filesystem is visible while the object in the
90 merged with the 'upper' object.
92 It would be more correct to refer to an upper and lower 'directory
95 requirement that the root of a filesystem be given for either upper or
101 writable.  The lower filesystem can even be another overlayfs.  The upper
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
144 filesystem, an overlay filesystem needs to record in the upper filesystem
151 When a whiteout is found in the upper level of a merged directory, any
156 to "y".  Where the upper filesystem contains an opaque directory, any
169 When a 'readdir' request is made on a merged directory, the upper and
171 obvious way (upper is read first, then lower - entries that already
196 underlying directory (upper or lower).
202 directory was not created on the upper layer to start with) overlayfs can
251 upper directory is stored in a "trusted.overlay.upper" extended attribute
252 on the index entry.  On lookup of a merged directory, if the upper
254 indication that multiple upper directories may be redirected to the same
259 NFS export support on an overlay filesystem with no upper layer requires
267 files etc.) are presented either from the upper or lower filesystem as
271 to the upper filesystem (copy_up).  Note that creating a hard-link
279 exists in the upper filesystem - creating it and any parents as
282 data is copied from the lower to the upper filesystem.  Finally any
286 provides direct access to the newly created file in the upper
302     compared to direct access on underlying lower or upper filesystems
310     upper layer based on underlying filesystem permissions, again including
325   mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,... /merged
329   cp -a /lower /upper
330   mount --bind /upper /merged
370 like chown/chmod is performed. An upper file in this state is marked with
371 "trusted.overlayfs.metacopy" xattr which indicates that the upper file
374 the "trusted.overlayfs.metacopy" xattr is removed from the upper file.
385 Do not use metacopy=on with untrusted upper/lower directories. Otherwise
405  1) metadata from a file in the upper layer
453 metacopy file in the upper layer is guaranteed to match the content
465 it can also give more powerful guarantees. For example, if the upper
471 upper layer.
498 Using an upper layer path and/or a workdir path that are already used by
502 upper layer and/or workdir path the behavior of the overlay is undefined,
505 Mounting an overlay using an upper layer path, where the upper layer path
513 attribute on the upper layer root directory.  On subsequent mount attempts,
515 to the stored origin in upper root directory.  On failure to verify the
519 if the upper filesystem does not support extended attributes.
522 mount time. So if same upper is mounted with different set of lower, mount
622 upper tree.  Offline changes to the lower tree are only allowed if the
634 attribute "trusted.overlay.origin" on the upper inode.
642 will not be merged with the upper directory.
655 non-directory object, the index entry is a hard link to the upper inode.
657 "trusted.overlay.upper" with an encoded file handle of the upper
663  1. For a non-upper object, encode a lower file handle from lower inode
665  3. For a pure-upper object and for an existing non-indexed upper object,
666     encode an upper file handle from upper inode
670  - Header including path type information (e.g. lower/upper)
690 copy_up of that disconnected dentry will create an upper index entry with
691 no upper alias.
696 "redirect" origin directory, cannot be used to find the middle or upper
701 directories are copied up on encode and encoded as an upper file handle.
702 On an overlay filesystem with no upper layer this mitigation cannot be
711 verified on mount time to check that upper file handles are not stale.
720 is changed. This is only applicable if all lower/upper/work directories are on
731     UUID of overlayfs is null. fsid is taken from upper most filesystem.
733     UUID of overlayfs is null. fsid is taken from upper most filesystem.
738     unique and persistent.  This option requires an overlayfs with upper
757 sync calls to the upper filesystem are omitted.
770 indicator that user should throw away upper and work directories and create