Documentation/filesystems/overlayfs.rst

10 overlay-filesystem functionality in Linux (sometimes referred to as
11 union-filesystems).  An overlay-filesystem tries to present a
12 filesystem which is the result over overlaying one filesystem on top
19 The overlay filesystem approach is 'hybrid', because the objects that
20 appear in the filesystem do not always appear to belong to that filesystem.
22 from accessing the corresponding object from the original filesystem.
25 While directories will report an st_dev from the overlay-filesystem,
26 non-directory objects may report an st_dev from the lower filesystem or
27 upper filesystem that is providing the object.  Similarly st_ino will
33 filesystem, all objects will report an st_dev from the overlay
34 filesystem and st_ino from the underlying filesystem.  This will
35 make the overlay mount more compliant with filesystem scanners and
37 objects in the original filesystem.
40 underlying filesystem, the same compliant behavior could be achieved
45 handles with 32bit inode number encoding (e.g. ext4), overlay filesystem
47 filesystem uses 64bit inode numbers, users can still enable the "xino"
52 filesystem will fall back to the non xino behavior for that inode.
88 An overlay filesystem combines two filesystems - an 'upper' filesystem
89 and a 'lower' filesystem.  When a name exists in both filesystems, the
90 object in the 'upper' filesystem is visible while the object in the
91 'lower' filesystem is either hidden or, in the case of directories,
95 tree' rather than 'filesystem' as it is quite possible for both
96 directory trees to be in the same filesystem and there is no
97 requirement that the root of a filesystem be given for either upper or
100 The lower filesystem can be any filesystem supported by Linux and does
101 not need to be writable.  The lower filesystem can even be another
102 overlayfs.  The upper filesystem will normally be writable and if it
107 filesystem type.
126 The "workdir" needs to be an empty directory on the same filesystem
131 is cached in the dentry belonging to the overlay filesystem.  If both
167 filesystem, an overlay filesystem needs to record in the upper filesystem
177 to "y".  Where the upper filesystem contains an opaque directory, any
178 directory in the lower filesystem with the same name is ignored.
220    move a file or directory across filesystem boundaries.  Hence
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
283 appropriate.  When a file in the lower filesystem is accessed in a way
285 some metadata etc., the file is first copied from the lower filesystem
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
300 Once the copy_up is complete, the overlay filesystem simply
302 filesystem - future operations on the file are barely noticed by the
303 overlay filesystem (though an operation on the name of the file such as
310 Permission checking in the overlay filesystem follows these principles:
325     upper layer based on underlying filesystem permissions, again including
419 filesystem, are encoded and stored in the "trusted.overlay.origin" extended
421 the lower root directory file handle and lower filesystem UUID are compared
424 "inodes index" enabled will fail with EOPNOTSUPP if the lower filesystem
425 does not support NFS export, lower filesystem does not have a valid UUID or
426 if the upper filesystem does not support extended attributes.
433 directory tree on the same or different underlying filesystem, and even
442 filesystem.
454 compliant filesystem:
478 underlying filesystem for all layers making up the overlay.
480 If this feature is disabled or the underlying filesystem doesn't have
483 value of d_ino returned by readdir(3) will act like on a normal filesystem.
485 overlay filesystem and the value of st_ino for directory objects may not be
486 persistent and could change even while the overlay filesystem is mounted, as
497 filesystem are not allowed.  If the underlying filesystem is changed,
506 UUID of the lower filesystem, are encoded and stored in an extended
512 that the found lower directory file handle and lower filesystem UUID
523 feature is enabled, an overlay filesystem may be exported to NFS.
533 When encoding a file handle from an overlay filesystem object, the
543  - UUID of the underlying filesystem
544  - Underlying filesystem encoding of underlying inode
552 2. Decode the underlying filesystem file handle to underlying dentry.
565 When overlay filesystem has multiple lower layers, a middle layer
574 On an overlay filesystem with no upper layer this mitigation cannot be
578 The overlay filesystem does not support non-directory connectable file
599 sync calls to the upper filesystem are omitted.
603 VFS.  If any writeback error occurs on the upperdir's filesystem after a
605 condition is reached, the filesystem will not recover, and every subsequent sync