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
94 It would be more correct to refer to an upper and lower 'directory
96 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.
155 a directory entry is spotty as a result of the cache mechanism not
157 caller can fill cache, then a lower privilege can read the directory
172 When a whiteout is found in the upper level of a merged directory, any
176 A directory is made opaque by setting the xattr "trusted.overlay.opaque"
177 to "y".  Where the upper filesystem contains an opaque directory, any
178 directory in the lower filesystem with the same name is ignored.
183 When a 'readdir' request is made on a merged directory, the upper and
188 directory is opened and read by two processes at the same time, they
190 directory (offset 0) followed by a readdir will cause the cache to be
193 This means that changes to the merged directory do not appear while a
194 directory is being read.  This is unlikely to be noticed by many
200   - read part of a directory
201   - remember an offset, and close the directory
202   - re-open the directory some time later
207 directory.
210 underlying directory (upper or lower).
215 When renaming a directory that is on the lower layer or merged (i.e. the
216 directory was not created on the upper layer to start with) overlayfs can
220    move a file or directory across filesystem boundaries.  Hence
222    recursively copies the directory tree).  This is the default behavior.
224 2. If the "redirect_dir" feature is enabled, then the directory will be
227    root of the overlay.  Finally the directory is moved to the new
264 When the NFS export feature is enabled, every copied up directory is
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
268 directory does not match the file handle stores in the index, that is an
270 lower directory.  In that case, lookup returns an error and warns about
293 The copy_up process first makes sure that the containing directory
355 separator character between the directory names.  For example:
418 handle of the lower layer root directory, along with the UUID of the lower
420 attribute on the upper layer root directory.  On subsequent mount attempts,
421 the lower root directory file handle and lower filesystem UUID are compared
422 to the stored origin in upper root directory.  On failure to verify the
433 directory tree on the same or different underlying filesystem, and even
461 If this feature is disabled, then rename(2) on a lower or merged directory
485 overlay filesystem and the value of st_ino for directory objects may not be
509 When the NFS export feature is enabled, a lookup of a merged directory,
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
515 will not be merged with the upper directory.
526 entry is created under the index directory.  The index entry name is the
528 non-directory object, the index entry is a hard link to the upper inode.
529 For a directory object, the index entry has an extended attribute
531 directory 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
558 6. For a directory, use the connected underlying decoded dentry, path type
561 Decoding a non-directory file handle may return a disconnected dentry.
566 directory may have a "redirect" to lower directory.  Because middle layer
568 "redirect" origin directory, cannot be used to find the middle or upper
569 layer directory.  Similarly, a lower file handle that was encoded from a
570 descendant of the "redirect" origin directory, cannot be used to
578 The overlay filesystem does not support non-directory connectable file
582 When the NFS export feature is enabled, all directory index entries are
609 When overlay is mounted with "volatile" option, the directory
611 checks for this directory and refuses to mount if present. This is a strong
614 not crashed and contents of upperdir are intact, The "volatile" directory