Documentation/filesystems/overlayfs.rst

6 Overlay Filesystem
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
46 filesystem will fall back to the non xino behavior for that inode.
50 for overlay filesystem objects is not only unique, but also persistent over
51 the lifetime of the filesystem.  The "-o xino=auto" overlay mount option
86 An overlay filesystem combines two filesystems - an 'upper' filesystem
87 and a 'lower' filesystem.  When a name exists in both filesystems, the
88 object in the 'upper' filesystem is visible while the object in the
89 'lower' filesystem is either hidden or, in the case of directories,
93 tree' rather than 'filesystem' as it is quite possible for both
94 directory trees to be in the same filesystem and there is no
95 requirement that the root of a filesystem be given for either upper or
98 A wide range of filesystems supported by Linux can be the lower filesystem,
100 needed for OverlayFS to work.  The lower filesystem does not need to be
101 writable.  The lower filesystem can even be another overlayfs.  The upper
102 filesystem will normally be writable and if it is it must support the
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
144 filesystem, an overlay filesystem needs to record in the upper filesystem
156 to "y".  Where the upper filesystem contains an opaque directory, any
157 directory in the lower filesystem with the same name is ignored.
206    move a file or directory across filesystem boundaries.  Hence
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
268 appropriate.  When a file in the lower filesystem is accessed in a way
270 some metadata etc., the file is first copied from the lower filesystem
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
285 Once the copy_up is complete, the overlay filesystem simply
287 filesystem - future operations on the file are barely noticed by the
288 overlay filesystem (though an operation on the name of the file such as
295 Permission checking in the overlay filesystem follows these principles:
310     upper layer based on underlying filesystem permissions, again including
512 filesystem, are encoded and stored in the "trusted.overlay.origin" extended
514 the lower root directory file handle and lower filesystem UUID are compared
517 "index" enabled will fail with EOPNOTSUPP if the lower filesystem
518 does not support NFS export, lower filesystem does not have a valid UUID or
519 if the upper filesystem does not support extended attributes.
526 directory tree on the same or different underlying filesystem, and even
559 filesystem.
574 compliant filesystem:
601 underlying filesystem for all layers making up the overlay.
603 If this feature is disabled or the underlying filesystem doesn't have
606 value of d_ino returned by readdir(3) will act like on a normal filesystem.
608 overlay filesystem and the value of st_ino for filesystem objects may not be
609 persistent and could change even while the overlay filesystem is mounted, as
617 filesystem are not allowed.  If the underlying filesystem is changed,
633 UUID of the lower filesystem, are encoded and stored in an extended
639 that the found lower directory file handle and lower filesystem UUID
650 feature is enabled, an overlay filesystem may be exported to NFS.
660 When encoding a file handle from an overlay filesystem object, the
671  - UUID of the underlying filesystem
672  - Underlying filesystem encoding of underlying inode
680  2. Decode the underlying filesystem file handle to underlying dentry.
693 When overlay filesystem has multiple lower layers, a middle layer
702 On an overlay filesystem with no upper layer this mitigation cannot be
706 The overlay filesystem does not support non-directory connectable file
718 filesystem in file handles with null, and effectively disable UUID checks. This
721 the same filesystem, otherwise it will fallback to normal behaviour.
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.
739     filesystem that supports xattrs.
742     Upgrade to "uuid=on" on first time mount of new overlay filesystem that
757 sync calls to the upper filesystem are omitted.
761 VFS.  If any writeback error occurs on the upperdir's filesystem after a
763 condition is reached, the filesystem will not recover, and every subsequent sync