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.
149 When a whiteout is found in the upper level of a merged directory, any
153 A directory is made opaque by setting the xattr "trusted.overlay.opaque"
154 to "y".  Where the upper filesystem contains an opaque directory, any
155 directory in the lower filesystem with the same name is ignored.
160 When a 'readdir' request is made on a merged directory, the upper and
165 directory is opened and read by two processes at the same time, they
167 directory (offset 0) followed by a readdir will cause the cache to be
170 This means that changes to the merged directory do not appear while a
171 directory is being read.  This is unlikely to be noticed by many
177   - read part of a directory
178   - remember an offset, and close the directory
179   - re-open the directory some time later
184 directory.
187 underlying directory (upper or lower).
192 When renaming a directory that is on the lower layer or merged (i.e. the
193 directory was not created on the upper layer to start with) overlayfs can
197    move a file or directory across filesystem boundaries.  Hence
199    recursively copies the directory tree).  This is the default behavior.
201 2. If the "redirect_dir" feature is enabled, then the directory will be
204    root of the overlay.  Finally the directory is moved to the new
240 When the NFS export feature is enabled, every copied up directory is
242 upper directory is stored in a "trusted.overlay.upper" extended attribute
243 on the index entry.  On lookup of a merged directory, if the upper
244 directory does not match the file handle stores in the index, that is an
246 lower directory.  In that case, lookup returns an error and warns about
269 The copy_up process first makes sure that the containing directory
331 separator character between the directory names.  For example:
342 Note: directory names containing colons can be provided as lower layer by
347 Since kernel version v6.8, directory names containing colons can also
353 In the latter case, colons in lower layer directory names will be escaped
499 handle of the lower layer root directory, along with the UUID of the lower
501 attribute on the upper layer root directory.  On subsequent mount attempts,
502 the lower root directory file handle and lower filesystem UUID are compared
503 to the stored origin in upper root directory.  On failure to verify the
514 directory tree on the same or different underlying filesystem, and even
545 If this feature is disabled, then rename(2) on a lower or merged directory
597 When the NFS export feature is enabled, a lookup of a merged directory,
598 that found a lower directory at the lookup path or at the path pointed
600 that the found lower directory file handle and lower filesystem UUID
602 found lower directory does not match the stored origin, that directory
603 will not be merged with the upper directory.
614 entry is created under the index directory.  The index entry name is the
616 non-directory object, the index entry is a hard link to the upper inode.
617 For a directory object, the index entry has an extended attribute
619 directory inode.
641 3. For a lower file handle, lookup the handle in index directory by name.
644 5. For a non-directory, instantiate a disconnected overlay dentry from the
646 6. For a directory, use the connected underlying decoded dentry, path type
649 Decoding a non-directory file handle may return a disconnected dentry.
654 directory may have a "redirect" to lower directory.  Because middle layer
656 "redirect" origin directory, cannot be used to find the middle or upper
657 layer directory.  Similarly, a lower file handle that was encoded from a
658 descendant of the "redirect" origin directory, cannot be used to
666 The overlay filesystem does not support non-directory connectable file
670 When the NFS export feature is enabled, all directory index entries are
727 When overlay is mounted with "volatile" option, the directory
729 checks for this directory and refuses to mount if present. This is a strong
732 not crashed and contents of upperdir are intact, The "volatile" directory