The 'verify_lower' feature provides the following: 1. Verify on mount that upper root origin matches lower root 2. Verify on lookup that upper dir origin matches lower dir The feature is needed for upcoming overlayfs features: - Prevent breaking hardlinks on copy up - NFS export support - Overlayfs snapshots Signed-off-by: Amir Goldstein <amir73il@xxxxxxxxx> --- Documentation/filesystems/overlayfs.txt | 48 +++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/Documentation/filesystems/overlayfs.txt b/Documentation/filesystems/overlayfs.txt index c9e884b52698..e82c4fb4871d 100644 --- a/Documentation/filesystems/overlayfs.txt +++ b/Documentation/filesystems/overlayfs.txt @@ -201,6 +201,40 @@ rightmost one and going left. In the above example lower1 will be the top, lower2 the middle and lower3 the bottom layer. +Sharing and copying layers +-------------------------- + +Lower layers may be shared among several overlay mounts and that is indeed +a very common practice. An overlay mounts may use the same lower layer +path as another overlay mount and it may use a lower layer path that is +beneath or above the path of another overlay lower layer path. + +Using an upper layer path and/or a workdir path that are already used by +another overlay mount is not allowed and will fail with EBUSY. Using +partially overlapping paths is not allowed but will not fail with EBUSY. + +Mounting an overlay using an upper layer path, where the upper layer path +was previously used by another mounted overlay in combination with a +different lower layer path, is allowed, unless the "verify_lower" mount +option is used. + +With the "verify_lower" feature, on the first time mount, an NFS file +handle of the lower layer root directory, along with the UUID of the lower +filesystem, are encoded and stored in the "trusted.overlay.origin" extended +attribute on the upper layer root directory. On subsequent mount attempts, +the lower root directory file handle and lower filesystem UUID are compared +to the stored origin in upper root directory. On failure to verify the +lower root origin, mount will fail with ESTALE. A "verify_lower" mount +will fail with EOPNOTSUPP if the lower filesystem does not support NFS +export, lower filesystem does not have a valid UUID or if the upper +filesystem does not support extended attributes. + +It is quite a common practice to copy overlay layers to a different +directory tree on the same or different underlying filesystem, and even +to a different machine. With the "verify_lower" feature, trying to mount +the copied layers will fail the verification of the lower root file handle. + + Non-standard behavior --------------------- @@ -228,6 +262,20 @@ filesystem are not allowed. If the underlying filesystem is changed, the behavior of the overlay is undefined, though it will not result in a crash or deadlock. +When the lower filesystem supports NFS export, overlay mount can be made +more resilient to offline and online changes of the underlying lower layer. +On every copy_up, an NFS file handle of the lower inode, along with the +UUID of the lower filesystem, are encoded and stored in an extended +attribute "trusted.overlay.origin" on the upper inode. + +With the "verify_lower" feature, a lookup of a merged directory, that found +a lower directory at the lookup path or at the path pointed to by the +"trusted.overlay.redirect" extended attribute, will verify that the found +lower directory file handle and lower filesystem UUID match the origin +that was stored at copy_up time. If a found lower directory does not match +the stored origin, that directory will be not be merged with the upper +directory. + Testsuite --------- -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-unionfs" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
