Documentation/filesystems/overlayfs.rst

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
92 It would be more correct to refer to an upper and lower 'directory
94 directory trees to be in the same filesystem and there is no
113 upper and lower filesystems and refers to a non-directory in either,
117 Where both upper and lower objects are directories, a merged directory
121 "upperdir" are combined into a merged directory::
126 The "workdir" needs to be an empty directory on the same filesystem
129 Then whenever a lookup is requested in such a merged directory, the
130 lookup is performed in each actual directory and the combined result
133 directory is created, otherwise only one is stored: the upper if it
138 directory only.  These attributes of the lower directory are hidden.
151 When a whiteout is found in the upper level of a merged directory, any
155 A directory is made opaque by setting the xattr "trusted.overlay.opaque"
156 to "y".  Where the upper filesystem contains an opaque directory, any
157 directory in the lower filesystem with the same name is ignored.
159 An opaque directory should not conntain any whiteouts, because they do not
160 serve any purpose.  A merge directory containing regular files with the xattr
162 "trusted.overlay.opaque" to "x" on the merge directory itself.
169 When a 'readdir' request is made on a merged directory, the upper and
174 directory is opened and read by two processes at the same time, they
176 directory (offset 0) followed by a readdir will cause the cache to be
179 This means that changes to the merged directory do not appear while a
180 directory is being read.  This is unlikely to be noticed by many
186  - read part of a directory
187  - remember an offset, and close the directory
188  - re-open the directory some time later
193 directory.
196 underlying directory (upper or lower).
201 When renaming a directory that is on the lower layer or merged (i.e. the
202 directory was not created on the upper layer to start with) overlayfs can
206    move a file or directory across filesystem boundaries.  Hence
208    recursively copies the directory tree).  This is the default behavior.
210 2. If the "redirect_dir" feature is enabled, then the directory will be
213    root of the overlay.  Finally the directory is moved to the new
249 When the NFS export feature is enabled, every copied up directory is
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
253 directory does not match the file handle stores in the index, that is an
255 lower directory.  In that case, lookup returns an error and warns about
278 The copy_up process first makes sure that the containing directory
340 separator character between the directory names.  For example::
351 Note: directory names containing colons can be provided as lower layer by
356 Since kernel version v6.8, directory names containing colons can also
362 In the latter case, colons in lower layer directory names will be escaped
508 handle of the lower layer root directory, along with the UUID of the lower
510 attribute on the upper layer root directory.  On subsequent mount attempts,
511 the lower root directory file handle and lower filesystem UUID are compared
512 to the stored origin in upper root directory.  On failure to verify the
523 directory tree on the same or different underlying filesystem, and even
530 It is possible to use a lower directory that is stored on an overlayfs
545 file with the "overlay.whiteout" xattr set, inside a directory with the
579 If this feature is disabled, then rename(2) on a lower or merged directory
633 When the NFS export feature is enabled, a lookup of a merged directory,
634 that found a lower directory at the lookup path or at the path pointed
636 that the found lower directory file handle and lower filesystem UUID
638 found lower directory does not match the stored origin, that directory
639 will not be merged with the upper directory.
650 entry is created under the index directory.  The index entry name is the
652 non-directory object, the index entry is a hard link to the upper inode.
653 For a directory object, the index entry has an extended attribute
655 directory inode.
678  3. For a lower file handle, lookup the handle in index directory by name.
681  5. For a non-directory, instantiate a disconnected overlay dentry from the
683  6. For a directory, use the connected underlying decoded dentry, path type
686 Decoding a non-directory file handle may return a disconnected dentry.
691 directory may have a "redirect" to lower directory.  Because middle layer
693 "redirect" origin directory, cannot be used to find the middle or upper
694 layer directory.  Similarly, a lower file handle that was encoded from a
695 descendant of the "redirect" origin directory, cannot be used to
703 The overlay filesystem does not support non-directory connectable file
707 When the NFS export feature is enabled, all directory index entries are
764 When overlay is mounted with "volatile" option, the directory
766 checks for this directory and refuses to mount if present. This is a strong
769 not crashed and contents of upperdir are intact, The "volatile" directory