Overlayfs Details Continued: NFS Export Caveats, Xino, Metacopy, and Volatile Mounts

lookup the handle in index directory by name. • If a whiteout is found in index, return ESTALE. This represents an overlay object that was deleted after its file handle was encoded. • For a non-directory, instantiate a disconnected overlay dentry from the decoded underlying dentry, the path type and index inode, if found. • For a directory, use the connected underlying decoded dentry, path type and index, to lookup a connected overlay dentry. Decoding a non-directory file handle may return a disconnected dentry. copy_up of that disconnected dentry will create an upper index entry with no upper alias. When overlay filesystem has multiple lower layers, a middle layer directory may have a "redirect" to lower directory. Because middle layer "redirects" are not indexed, a lower file handle that was encoded from the "redirect" origin directory, cannot be used to find the middle or upper layer directory. Similarly, a lower file handle that was encoded from a descendant of the "redirect" origin directory, cannot be used to reconstruct a connected overlay path. To mitigate the cases of directories that cannot be decoded from a lower file handle, these directories are copied up on encode and encoded as an upper file handle. On an overlay filesystem with no upper layer this mitigation cannot be used NFS export in this setup requires turning off redirect follow (e.g. "redirect_dir=nofollow"). The overlay filesystem does not support non-directory connectable file handles, so exporting with the subtree_check exportfs configuration will cause failures to lookup files over NFS. When the NFS export feature is enabled, all directory index entries are verified on mount time to check that upper file handles are not stale. This verification may cause significant overhead in some cases. Note: the mount options index=off,nfs_export=on are conflicting for a read-write mount and will result in an error. xino={on|off|auto} The "xino" feature composes a unique object identifier from the real object st_ino and an underlying fsid index. The "xino" feature uses the high inode number bits for fsid, because the underlying filesystems rarely use the high inode number bits. In case the underlying inode number does overflow into the high xino bits, overlay filesystem will fall back to the non xino behavior for that inode. For a detailed description of the effect of this option please refer to https://docs.kernel.org/filesystems/overlayfs.html metacopy={on|off} When metadata only copy up feature is enabled, overlayfs will only copy up metadata (as opposed to whole file), when a metadata specific operation like chown/chmod is performed. Full file will be copied up later when file is opened for WRITE operation. In other words, this is delayed data copy up operation and data is copied up when there is a need to actually modify data. volatile Volatile mounts are not guaranteed to survive a crash. It is strongly recommended that volatile mounts are only used if data written to the overlay can be recreated without significant effort. The advantage of mounting with the "volatile" option is that all forms of sync calls to the upper filesystem are omitted. In order to avoid a giving a false sense of safety, the syncfs (and fsync) semantics of volatile mounts

This section continues to elaborate on the NFS export feature, addressing potential issues with 'redirect' handling in multi-layer configurations and recommending disabling redirect following in such scenarios. It highlights the incompatibility of non-directory connectable file handles with subtree_check in exportfs. It also touches on mount-time verification of directory index entries and the conflict between `index=off` and `nfs_export=on` for read-write mounts. Furthermore, it explains the 'xino' feature which creates unique object identifiers, 'metacopy' for delayed data copy-up, and the implications of using 'volatile' mounts which omit sync calls for performance, but at the risk of data loss on crashes.