Back to home page

OSCL-LXR

 
 

    


0001 .. SPDX-License-Identifier: GPL-2.0
0002 
0003 Written by: Neil Brown
0004 Please see MAINTAINERS file for where to send questions.
0005 
0006 Overlay Filesystem
0007 ==================
0008 
0009 This document describes a prototype for a new approach to providing
0010 overlay-filesystem functionality in Linux (sometimes referred to as
0011 union-filesystems).  An overlay-filesystem tries to present a
0012 filesystem which is the result over overlaying one filesystem on top
0013 of the other.
0014 
0015 
0016 Overlay objects
0017 ---------------
0018 
0019 The overlay filesystem approach is 'hybrid', because the objects that
0020 appear in the filesystem do not always appear to belong to that filesystem.
0021 In many cases, an object accessed in the union will be indistinguishable
0022 from accessing the corresponding object from the original filesystem.
0023 This is most obvious from the 'st_dev' field returned by stat(2).
0024 
0025 While directories will report an st_dev from the overlay-filesystem,
0026 non-directory objects may report an st_dev from the lower filesystem or
0027 upper filesystem that is providing the object.  Similarly st_ino will
0028 only be unique when combined with st_dev, and both of these can change
0029 over the lifetime of a non-directory object.  Many applications and
0030 tools ignore these values and will not be affected.
0031 
0032 In the special case of all overlay layers on the same underlying
0033 filesystem, all objects will report an st_dev from the overlay
0034 filesystem and st_ino from the underlying filesystem.  This will
0035 make the overlay mount more compliant with filesystem scanners and
0036 overlay objects will be distinguishable from the corresponding
0037 objects in the original filesystem.
0038 
0039 On 64bit systems, even if all overlay layers are not on the same
0040 underlying filesystem, the same compliant behavior could be achieved
0041 with the "xino" feature.  The "xino" feature composes a unique object
0042 identifier from the real object st_ino and an underlying fsid index.
0043 The "xino" feature uses the high inode number bits for fsid, because the
0044 underlying filesystems rarely use the high inode number bits.  In case
0045 the underlying inode number does overflow into the high xino bits, overlay
0046 filesystem will fall back to the non xino behavior for that inode.
0047 
0048 The "xino" feature can be enabled with the "-o xino=on" overlay mount option.
0049 If all underlying filesystems support NFS file handles, the value of st_ino
0050 for overlay filesystem objects is not only unique, but also persistent over
0051 the lifetime of the filesystem.  The "-o xino=auto" overlay mount option
0052 enables the "xino" feature only if the persistent st_ino requirement is met.
0053 
0054 The following table summarizes what can be expected in different overlay
0055 configurations.
0056 
0057 Inode properties
0058 ````````````````
0059 
0060 +--------------+------------+------------+-----------------+----------------+
0061 |Configuration | Persistent | Uniform    | st_ino == d_ino | d_ino == i_ino |
0062 |              | st_ino     | st_dev     |                 | [*]            |
0063 +==============+=====+======+=====+======+========+========+========+=======+
0064 |              | dir | !dir | dir | !dir |  dir   +  !dir  |  dir   | !dir  |
0065 +--------------+-----+------+-----+------+--------+--------+--------+-------+
0066 | All layers   |  Y  |  Y   |  Y  |  Y   |  Y     |   Y    |  Y     |  Y    |
0067 | on same fs   |     |      |     |      |        |        |        |       |
0068 +--------------+-----+------+-----+------+--------+--------+--------+-------+
0069 | Layers not   |  N  |  N   |  Y  |  N   |  N     |   Y    |  N     |  Y    |
0070 | on same fs,  |     |      |     |      |        |        |        |       |
0071 | xino=off     |     |      |     |      |        |        |        |       |
0072 +--------------+-----+------+-----+------+--------+--------+--------+-------+
0073 | xino=on/auto |  Y  |  Y   |  Y  |  Y   |  Y     |   Y    |  Y     |  Y    |
0074 +--------------+-----+------+-----+------+--------+--------+--------+-------+
0075 | xino=on/auto,|  N  |  N   |  Y  |  N   |  N     |   Y    |  N     |  Y    |
0076 | ino overflow |     |      |     |      |        |        |        |       |
0077 +--------------+-----+------+-----+------+--------+--------+--------+-------+
0078 
0079 [*] nfsd v3 readdirplus verifies d_ino == i_ino. i_ino is exposed via several
0080 /proc files, such as /proc/locks and /proc/self/fdinfo/<fd> of an inotify
0081 file descriptor.
0082 
0083 Upper and Lower
0084 ---------------
0085 
0086 An overlay filesystem combines two filesystems - an 'upper' filesystem
0087 and a 'lower' filesystem.  When a name exists in both filesystems, the
0088 object in the 'upper' filesystem is visible while the object in the
0089 'lower' filesystem is either hidden or, in the case of directories,
0090 merged with the 'upper' object.
0091 
0092 It would be more correct to refer to an upper and lower 'directory
0093 tree' rather than 'filesystem' as it is quite possible for both
0094 directory trees to be in the same filesystem and there is no
0095 requirement that the root of a filesystem be given for either upper or
0096 lower.
0097 
0098 A wide range of filesystems supported by Linux can be the lower filesystem,
0099 but not all filesystems that are mountable by Linux have the features
0100 needed for OverlayFS to work.  The lower filesystem does not need to be
0101 writable.  The lower filesystem can even be another overlayfs.  The upper
0102 filesystem will normally be writable and if it is it must support the
0103 creation of trusted.* and/or user.* extended attributes, and must provide
0104 valid d_type in readdir responses, so NFS is not suitable.
0105 
0106 A read-only overlay of two read-only filesystems may use any
0107 filesystem type.
0108 
0109 Directories
0110 -----------
0111 
0112 Overlaying mainly involves directories.  If a given name appears in both
0113 upper and lower filesystems and refers to a non-directory in either,
0114 then the lower object is hidden - the name refers only to the upper
0115 object.
0116 
0117 Where both upper and lower objects are directories, a merged directory
0118 is formed.
0119 
0120 At mount time, the two directories given as mount options "lowerdir" and
0121 "upperdir" are combined into a merged directory:
0122 
0123   mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,\
0124   workdir=/work /merged
0125 
0126 The "workdir" needs to be an empty directory on the same filesystem
0127 as upperdir.
0128 
0129 Then whenever a lookup is requested in such a merged directory, the
0130 lookup is performed in each actual directory and the combined result
0131 is cached in the dentry belonging to the overlay filesystem.  If both
0132 actual lookups find directories, both are stored and a merged
0133 directory is created, otherwise only one is stored: the upper if it
0134 exists, else the lower.
0135 
0136 Only the lists of names from directories are merged.  Other content
0137 such as metadata and extended attributes are reported for the upper
0138 directory only.  These attributes of the lower directory are hidden.
0139 
0140 whiteouts and opaque directories
0141 --------------------------------
0142 
0143 In order to support rm and rmdir without changing the lower
0144 filesystem, an overlay filesystem needs to record in the upper filesystem
0145 that files have been removed.  This is done using whiteouts and opaque
0146 directories (non-directories are always opaque).
0147 
0148 A whiteout is created as a character device with 0/0 device number.
0149 When a whiteout is found in the upper level of a merged directory, any
0150 matching name in the lower level is ignored, and the whiteout itself
0151 is also hidden.
0152 
0153 A directory is made opaque by setting the xattr "trusted.overlay.opaque"
0154 to "y".  Where the upper filesystem contains an opaque directory, any
0155 directory in the lower filesystem with the same name is ignored.
0156 
0157 readdir
0158 -------
0159 
0160 When a 'readdir' request is made on a merged directory, the upper and
0161 lower directories are each read and the name lists merged in the
0162 obvious way (upper is read first, then lower - entries that already
0163 exist are not re-added).  This merged name list is cached in the
0164 'struct file' and so remains as long as the file is kept open.  If the
0165 directory is opened and read by two processes at the same time, they
0166 will each have separate caches.  A seekdir to the start of the
0167 directory (offset 0) followed by a readdir will cause the cache to be
0168 discarded and rebuilt.
0169 
0170 This means that changes to the merged directory do not appear while a
0171 directory is being read.  This is unlikely to be noticed by many
0172 programs.
0173 
0174 seek offsets are assigned sequentially when the directories are read.
0175 Thus if
0176 
0177   - read part of a directory
0178   - remember an offset, and close the directory
0179   - re-open the directory some time later
0180   - seek to the remembered offset
0181 
0182 there may be little correlation between the old and new locations in
0183 the list of filenames, particularly if anything has changed in the
0184 directory.
0185 
0186 Readdir on directories that are not merged is simply handled by the
0187 underlying directory (upper or lower).
0188 
0189 renaming directories
0190 --------------------
0191 
0192 When renaming a directory that is on the lower layer or merged (i.e. the
0193 directory was not created on the upper layer to start with) overlayfs can
0194 handle it in two different ways:
0195 
0196 1. return EXDEV error: this error is returned by rename(2) when trying to
0197    move a file or directory across filesystem boundaries.  Hence
0198    applications are usually prepared to hande this error (mv(1) for example
0199    recursively copies the directory tree).  This is the default behavior.
0200 
0201 2. If the "redirect_dir" feature is enabled, then the directory will be
0202    copied up (but not the contents).  Then the "trusted.overlay.redirect"
0203    extended attribute is set to the path of the original location from the
0204    root of the overlay.  Finally the directory is moved to the new
0205    location.
0206 
0207 There are several ways to tune the "redirect_dir" feature.
0208 
0209 Kernel config options:
0210 
0211 - OVERLAY_FS_REDIRECT_DIR:
0212     If this is enabled, then redirect_dir is turned on by  default.
0213 - OVERLAY_FS_REDIRECT_ALWAYS_FOLLOW:
0214     If this is enabled, then redirects are always followed by default. Enabling
0215     this results in a less secure configuration.  Enable this option only when
0216     worried about backward compatibility with kernels that have the redirect_dir
0217     feature and follow redirects even if turned off.
0218 
0219 Module options (can also be changed through /sys/module/overlay/parameters/):
0220 
0221 - "redirect_dir=BOOL":
0222     See OVERLAY_FS_REDIRECT_DIR kernel config option above.
0223 - "redirect_always_follow=BOOL":
0224     See OVERLAY_FS_REDIRECT_ALWAYS_FOLLOW kernel config option above.
0225 - "redirect_max=NUM":
0226     The maximum number of bytes in an absolute redirect (default is 256).
0227 
0228 Mount options:
0229 
0230 - "redirect_dir=on":
0231     Redirects are enabled.
0232 - "redirect_dir=follow":
0233     Redirects are not created, but followed.
0234 - "redirect_dir=off":
0235     Redirects are not created and only followed if "redirect_always_follow"
0236     feature is enabled in the kernel/module config.
0237 - "redirect_dir=nofollow":
0238     Redirects are not created and not followed (equivalent to "redirect_dir=off"
0239     if "redirect_always_follow" feature is not enabled).
0240 
0241 When the NFS export feature is enabled, every copied up directory is
0242 indexed by the file handle of the lower inode and a file handle of the
0243 upper directory is stored in a "trusted.overlay.upper" extended attribute
0244 on the index entry.  On lookup of a merged directory, if the upper
0245 directory does not match the file handle stores in the index, that is an
0246 indication that multiple upper directories may be redirected to the same
0247 lower directory.  In that case, lookup returns an error and warns about
0248 a possible inconsistency.
0249 
0250 Because lower layer redirects cannot be verified with the index, enabling
0251 NFS export support on an overlay filesystem with no upper layer requires
0252 turning off redirect follow (e.g. "redirect_dir=nofollow").
0253 
0254 
0255 Non-directories
0256 ---------------
0257 
0258 Objects that are not directories (files, symlinks, device-special
0259 files etc.) are presented either from the upper or lower filesystem as
0260 appropriate.  When a file in the lower filesystem is accessed in a way
0261 the requires write-access, such as opening for write access, changing
0262 some metadata etc., the file is first copied from the lower filesystem
0263 to the upper filesystem (copy_up).  Note that creating a hard-link
0264 also requires copy_up, though of course creation of a symlink does
0265 not.
0266 
0267 The copy_up may turn out to be unnecessary, for example if the file is
0268 opened for read-write but the data is not modified.
0269 
0270 The copy_up process first makes sure that the containing directory
0271 exists in the upper filesystem - creating it and any parents as
0272 necessary.  It then creates the object with the same metadata (owner,
0273 mode, mtime, symlink-target etc.) and then if the object is a file, the
0274 data is copied from the lower to the upper filesystem.  Finally any
0275 extended attributes are copied up.
0276 
0277 Once the copy_up is complete, the overlay filesystem simply
0278 provides direct access to the newly created file in the upper
0279 filesystem - future operations on the file are barely noticed by the
0280 overlay filesystem (though an operation on the name of the file such as
0281 rename or unlink will of course be noticed and handled).
0282 
0283 
0284 Permission model
0285 ----------------
0286 
0287 Permission checking in the overlay filesystem follows these principles:
0288 
0289  1) permission check SHOULD return the same result before and after copy up
0290 
0291  2) task creating the overlay mount MUST NOT gain additional privileges
0292 
0293  3) non-mounting task MAY gain additional privileges through the overlay,
0294  compared to direct access on underlying lower or upper filesystems
0295 
0296 This is achieved by performing two permission checks on each access
0297 
0298  a) check if current task is allowed access based on local DAC (owner,
0299     group, mode and posix acl), as well as MAC checks
0300 
0301  b) check if mounting task would be allowed real operation on lower or
0302     upper layer based on underlying filesystem permissions, again including
0303     MAC checks
0304 
0305 Check (a) ensures consistency (1) since owner, group, mode and posix acls
0306 are copied up.  On the other hand it can result in server enforced
0307 permissions (used by NFS, for example) being ignored (3).
0308 
0309 Check (b) ensures that no task gains permissions to underlying layers that
0310 the mounting task does not have (2).  This also means that it is possible
0311 to create setups where the consistency rule (1) does not hold; normally,
0312 however, the mounting task will have sufficient privileges to perform all
0313 operations.
0314 
0315 Another way to demonstrate this model is drawing parallels between
0316 
0317   mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,... /merged
0318 
0319 and
0320 
0321   cp -a /lower /upper
0322   mount --bind /upper /merged
0323 
0324 The resulting access permissions should be the same.  The difference is in
0325 the time of copy (on-demand vs. up-front).
0326 
0327 
0328 Multiple lower layers
0329 ---------------------
0330 
0331 Multiple lower layers can now be given using the colon (":") as a
0332 separator character between the directory names.  For example:
0333 
0334   mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged
0335 
0336 As the example shows, "upperdir=" and "workdir=" may be omitted.  In
0337 that case the overlay will be read-only.
0338 
0339 The specified lower directories will be stacked beginning from the
0340 rightmost one and going left.  In the above example lower1 will be the
0341 top, lower2 the middle and lower3 the bottom layer.
0342 
0343 
0344 Metadata only copy up
0345 ---------------------
0346 
0347 When metadata only copy up feature is enabled, overlayfs will only copy
0348 up metadata (as opposed to whole file), when a metadata specific operation
0349 like chown/chmod is performed. Full file will be copied up later when
0350 file is opened for WRITE operation.
0351 
0352 In other words, this is delayed data copy up operation and data is copied
0353 up when there is a need to actually modify data.
0354 
0355 There are multiple ways to enable/disable this feature. A config option
0356 CONFIG_OVERLAY_FS_METACOPY can be set/unset to enable/disable this feature
0357 by default. Or one can enable/disable it at module load time with module
0358 parameter metacopy=on/off. Lastly, there is also a per mount option
0359 metacopy=on/off to enable/disable this feature per mount.
0360 
0361 Do not use metacopy=on with untrusted upper/lower directories. Otherwise
0362 it is possible that an attacker can create a handcrafted file with
0363 appropriate REDIRECT and METACOPY xattrs, and gain access to file on lower
0364 pointed by REDIRECT. This should not be possible on local system as setting
0365 "trusted." xattrs will require CAP_SYS_ADMIN. But it should be possible
0366 for untrusted layers like from a pen drive.
0367 
0368 Note: redirect_dir={off|nofollow|follow[*]} and nfs_export=on mount options
0369 conflict with metacopy=on, and will result in an error.
0370 
0371 [*] redirect_dir=follow only conflicts with metacopy=on if upperdir=... is
0372 given.
0373 
0374 Sharing and copying layers
0375 --------------------------
0376 
0377 Lower layers may be shared among several overlay mounts and that is indeed
0378 a very common practice.  An overlay mount may use the same lower layer
0379 path as another overlay mount and it may use a lower layer path that is
0380 beneath or above the path of another overlay lower layer path.
0381 
0382 Using an upper layer path and/or a workdir path that are already used by
0383 another overlay mount is not allowed and may fail with EBUSY.  Using
0384 partially overlapping paths is not allowed and may fail with EBUSY.
0385 If files are accessed from two overlayfs mounts which share or overlap the
0386 upper layer and/or workdir path the behavior of the overlay is undefined,
0387 though it will not result in a crash or deadlock.
0388 
0389 Mounting an overlay using an upper layer path, where the upper layer path
0390 was previously used by another mounted overlay in combination with a
0391 different lower layer path, is allowed, unless the "inodes index" feature
0392 or "metadata only copy up" feature is enabled.
0393 
0394 With the "inodes index" feature, on the first time mount, an NFS file
0395 handle of the lower layer root directory, along with the UUID of the lower
0396 filesystem, are encoded and stored in the "trusted.overlay.origin" extended
0397 attribute on the upper layer root directory.  On subsequent mount attempts,
0398 the lower root directory file handle and lower filesystem UUID are compared
0399 to the stored origin in upper root directory.  On failure to verify the
0400 lower root origin, mount will fail with ESTALE.  An overlayfs mount with
0401 "inodes index" enabled will fail with EOPNOTSUPP if the lower filesystem
0402 does not support NFS export, lower filesystem does not have a valid UUID or
0403 if the upper filesystem does not support extended attributes.
0404 
0405 For "metadata only copy up" feature there is no verification mechanism at
0406 mount time. So if same upper is mounted with different set of lower, mount
0407 probably will succeed but expect the unexpected later on. So don't do it.
0408 
0409 It is quite a common practice to copy overlay layers to a different
0410 directory tree on the same or different underlying filesystem, and even
0411 to a different machine.  With the "inodes index" feature, trying to mount
0412 the copied layers will fail the verification of the lower root file handle.
0413 
0414 
0415 Non-standard behavior
0416 ---------------------
0417 
0418 Current version of overlayfs can act as a mostly POSIX compliant
0419 filesystem.
0420 
0421 This is the list of cases that overlayfs doesn't currently handle:
0422 
0423 a) POSIX mandates updating st_atime for reads.  This is currently not
0424 done in the case when the file resides on a lower layer.
0425 
0426 b) If a file residing on a lower layer is opened for read-only and then
0427 memory mapped with MAP_SHARED, then subsequent changes to the file are not
0428 reflected in the memory mapping.
0429 
0430 c) If a file residing on a lower layer is being executed, then opening that
0431 file for write or truncating the file will not be denied with ETXTBSY.
0432 
0433 The following options allow overlayfs to act more like a standards
0434 compliant filesystem:
0435 
0436 1) "redirect_dir"
0437 
0438 Enabled with the mount option or module option: "redirect_dir=on" or with
0439 the kernel config option CONFIG_OVERLAY_FS_REDIRECT_DIR=y.
0440 
0441 If this feature is disabled, then rename(2) on a lower or merged directory
0442 will fail with EXDEV ("Invalid cross-device link").
0443 
0444 2) "inode index"
0445 
0446 Enabled with the mount option or module option "index=on" or with the
0447 kernel config option CONFIG_OVERLAY_FS_INDEX=y.
0448 
0449 If this feature is disabled and a file with multiple hard links is copied
0450 up, then this will "break" the link.  Changes will not be propagated to
0451 other names referring to the same inode.
0452 
0453 3) "xino"
0454 
0455 Enabled with the mount option "xino=auto" or "xino=on", with the module
0456 option "xino_auto=on" or with the kernel config option
0457 CONFIG_OVERLAY_FS_XINO_AUTO=y.  Also implicitly enabled by using the same
0458 underlying filesystem for all layers making up the overlay.
0459 
0460 If this feature is disabled or the underlying filesystem doesn't have
0461 enough free bits in the inode number, then overlayfs will not be able to
0462 guarantee that the values of st_ino and st_dev returned by stat(2) and the
0463 value of d_ino returned by readdir(3) will act like on a normal filesystem.
0464 E.g. the value of st_dev may be different for two objects in the same
0465 overlay filesystem and the value of st_ino for filesystem objects may not be
0466 persistent and could change even while the overlay filesystem is mounted, as
0467 summarized in the `Inode properties`_ table above.
0468 
0469 
0470 Changes to underlying filesystems
0471 ---------------------------------
0472 
0473 Changes to the underlying filesystems while part of a mounted overlay
0474 filesystem are not allowed.  If the underlying filesystem is changed,
0475 the behavior of the overlay is undefined, though it will not result in
0476 a crash or deadlock.
0477 
0478 Offline changes, when the overlay is not mounted, are allowed to the
0479 upper tree.  Offline changes to the lower tree are only allowed if the
0480 "metadata only copy up", "inode index", "xino" and "redirect_dir" features
0481 have not been used.  If the lower tree is modified and any of these
0482 features has been used, the behavior of the overlay is undefined,
0483 though it will not result in a crash or deadlock.
0484 
0485 When the overlay NFS export feature is enabled, overlay filesystems
0486 behavior on offline changes of the underlying lower layer is different
0487 than the behavior when NFS export is disabled.
0488 
0489 On every copy_up, an NFS file handle of the lower inode, along with the
0490 UUID of the lower filesystem, are encoded and stored in an extended
0491 attribute "trusted.overlay.origin" on the upper inode.
0492 
0493 When the NFS export feature is enabled, a lookup of a merged directory,
0494 that found a lower directory at the lookup path or at the path pointed
0495 to by the "trusted.overlay.redirect" extended attribute, will verify
0496 that the found lower directory file handle and lower filesystem UUID
0497 match the origin file handle that was stored at copy_up time.  If a
0498 found lower directory does not match the stored origin, that directory
0499 will not be merged with the upper directory.
0500 
0501 
0502 
0503 NFS export
0504 ----------
0505 
0506 When the underlying filesystems supports NFS export and the "nfs_export"
0507 feature is enabled, an overlay filesystem may be exported to NFS.
0508 
0509 With the "nfs_export" feature, on copy_up of any lower object, an index
0510 entry is created under the index directory.  The index entry name is the
0511 hexadecimal representation of the copy up origin file handle.  For a
0512 non-directory object, the index entry is a hard link to the upper inode.
0513 For a directory object, the index entry has an extended attribute
0514 "trusted.overlay.upper" with an encoded file handle of the upper
0515 directory inode.
0516 
0517 When encoding a file handle from an overlay filesystem object, the
0518 following rules apply:
0519 
0520 1. For a non-upper object, encode a lower file handle from lower inode
0521 2. For an indexed object, encode a lower file handle from copy_up origin
0522 3. For a pure-upper object and for an existing non-indexed upper object,
0523    encode an upper file handle from upper inode
0524 
0525 The encoded overlay file handle includes:
0526  - Header including path type information (e.g. lower/upper)
0527  - UUID of the underlying filesystem
0528  - Underlying filesystem encoding of underlying inode
0529 
0530 This encoding format is identical to the encoding format file handles that
0531 are stored in extended attribute "trusted.overlay.origin".
0532 
0533 When decoding an overlay file handle, the following steps are followed:
0534 
0535 1. Find underlying layer by UUID and path type information.
0536 2. Decode the underlying filesystem file handle to underlying dentry.
0537 3. For a lower file handle, lookup the handle in index directory by name.
0538 4. If a whiteout is found in index, return ESTALE. This represents an
0539    overlay object that was deleted after its file handle was encoded.
0540 5. For a non-directory, instantiate a disconnected overlay dentry from the
0541    decoded underlying dentry, the path type and index inode, if found.
0542 6. For a directory, use the connected underlying decoded dentry, path type
0543    and index, to lookup a connected overlay dentry.
0544 
0545 Decoding a non-directory file handle may return a disconnected dentry.
0546 copy_up of that disconnected dentry will create an upper index entry with
0547 no upper alias.
0548 
0549 When overlay filesystem has multiple lower layers, a middle layer
0550 directory may have a "redirect" to lower directory.  Because middle layer
0551 "redirects" are not indexed, a lower file handle that was encoded from the
0552 "redirect" origin directory, cannot be used to find the middle or upper
0553 layer directory.  Similarly, a lower file handle that was encoded from a
0554 descendant of the "redirect" origin directory, cannot be used to
0555 reconstruct a connected overlay path.  To mitigate the cases of
0556 directories that cannot be decoded from a lower file handle, these
0557 directories are copied up on encode and encoded as an upper file handle.
0558 On an overlay filesystem with no upper layer this mitigation cannot be
0559 used NFS export in this setup requires turning off redirect follow (e.g.
0560 "redirect_dir=nofollow").
0561 
0562 The overlay filesystem does not support non-directory connectable file
0563 handles, so exporting with the 'subtree_check' exportfs configuration will
0564 cause failures to lookup files over NFS.
0565 
0566 When the NFS export feature is enabled, all directory index entries are
0567 verified on mount time to check that upper file handles are not stale.
0568 This verification may cause significant overhead in some cases.
0569 
0570 Note: the mount options index=off,nfs_export=on are conflicting for a
0571 read-write mount and will result in an error.
0572 
0573 Note: the mount option uuid=off can be used to replace UUID of the underlying
0574 filesystem in file handles with null, and effectively disable UUID checks. This
0575 can be useful in case the underlying disk is copied and the UUID of this copy
0576 is changed. This is only applicable if all lower/upper/work directories are on
0577 the same filesystem, otherwise it will fallback to normal behaviour.
0578 
0579 Volatile mount
0580 --------------
0581 
0582 This is enabled with the "volatile" mount option.  Volatile mounts are not
0583 guaranteed to survive a crash.  It is strongly recommended that volatile
0584 mounts are only used if data written to the overlay can be recreated
0585 without significant effort.
0586 
0587 The advantage of mounting with the "volatile" option is that all forms of
0588 sync calls to the upper filesystem are omitted.
0589 
0590 In order to avoid a giving a false sense of safety, the syncfs (and fsync)
0591 semantics of volatile mounts are slightly different than that of the rest of
0592 VFS.  If any writeback error occurs on the upperdir's filesystem after a
0593 volatile mount takes place, all sync functions will return an error.  Once this
0594 condition is reached, the filesystem will not recover, and every subsequent sync
0595 call will return an error, even if the upperdir has not experience a new error
0596 since the last sync call.
0597 
0598 When overlay is mounted with "volatile" option, the directory
0599 "$workdir/work/incompat/volatile" is created.  During next mount, overlay
0600 checks for this directory and refuses to mount if present. This is a strong
0601 indicator that user should throw away upper and work directories and create
0602 fresh one. In very limited cases where the user knows that the system has
0603 not crashed and contents of upperdir are intact, The "volatile" directory
0604 can be removed.
0605 
0606 
0607 User xattr
0608 ----------
0609 
0610 The "-o userxattr" mount option forces overlayfs to use the
0611 "user.overlay." xattr namespace instead of "trusted.overlay.".  This is
0612 useful for unprivileged mounting of overlayfs.
0613 
0614 
0615 Testsuite
0616 ---------
0617 
0618 There's a testsuite originally developed by David Howells and currently
0619 maintained by Amir Goldstein at:
0620 
0621   https://github.com/amir73il/unionmount-testsuite.git
0622 
0623 Run as root:
0624 
0625   # cd unionmount-testsuite
0626   # ./run --ov --verify