Re: [RFC PATCH 35/35] ovl: fix documentation of non-standard behavior

[Amir Goldstein]

On Thu, Apr 12, 2018 at 6:08 PM, Miklos Szeredi  wrote:
> We can now drop description of the ro/rw inconsistency from the
> documentation.
>
> Also clarify, that now fully standard compliant behavior can be enabled
> with kernel/module/mount options.
>

Very nice!

Is it maybe a good time to tone down this expectation-lowering
phrase from the introduction:

"The result will inevitably fail to look exactly like a normal
filesystem for various technical reasons.  The expectation is that
many use cases will be able to ignore these differences."

> Signed-off-by: Miklos Szeredi 
> ---
>  Documentation/filesystems/overlayfs.txt | 64 
> ++---
>  1 file changed, 43 insertions(+), 21 deletions(-)
>
> diff --git a/Documentation/filesystems/overlayfs.txt 
> b/Documentation/filesystems/overlayfs.txt
> index 961b287ef323..095186080d23 100644
> --- a/Documentation/filesystems/overlayfs.txt
> +++ b/Documentation/filesystems/overlayfs.txt
> @@ -306,27 +306,49 @@ the copied layers will fail the verification of the 
> lower root file handle.
>  Non-standard behavior
>  -
>
> -The copy_up operation essentially creates a new, identical file and
> -moves it over to the old name.  Any open files referring to this inode
> -will access the old data.
> -
> -The new file may be on a different filesystem, so both st_dev and st_ino
> -of the real file may change.  The values of st_dev and st_ino returned by
> -stat(2) on an overlay object are often not the same as the real file
> -stat(2) values to prevent the values from changing on copy_up.
> -
> -Unless "xino" feature is enabled, when overlay layers are not all on the
> -same underlying filesystem, the value of st_dev may be different for two
> -non-directory objects in the same overlay filesystem and the value of
> -st_ino for directory objects may be non persistent and could change even
> -while the overlay filesystem is still mounted.
> -
> -Unless "inode index" feature is enabled, if a file with multiple hard
> -links is copied up, then this will "break" the link.  Changes will not be
> -propagated to other names referring to the same inode.
> -
> -Unless "redirect_dir" feature is enabled, rename(2) on a lower or merged
> -directory will fail with EXDEV.
> +Overlayfs can now act as a POSIX compliant filesystem with the following
> +features turned on:
> +
> +1) "redirect_dir"
> +
> +Enabled with the mount option or module option: "redirect_dir=on" or with
> +the kernel config option CONFIG_OVERLAY_FS_REDIRECT_DIR=y.
> +
> +If this feature is disabled, then rename(2) on a lower or merged directory
> +will fail with EXDEV ("Invalid cross-device link").
> +
> +2) "inode index"
> +
> +Enabled with the mount option or module option "index=on" or with the
> +kernel config option CONFIG_OVERLAY_FS_INDEX=y.
> +
> +If this feature is disabled and a file with multiple hard links is copied
> +up, then this will "break" the link.  Changes will not be propagated to
> +other names referring to the same inode.
> +
> +3) "xino"
> +
> +Enabled with the mount option "xino=auto" or "xino=on", with the module
> +option "xino_auto=on" or with the kernel config option
> +CONFIG_OVERLAY_FS_XINO_AUTO=y.  Also implicitly enabled by using the same
> +underlying filesystem for all layers making up the overlay.
> +
> +If this feature is disabled or the underlying filesystem doesn't have
> +enough free bits in the inode number, then overlayfs will not be able to
> +guarantee that the values of st_ino and st_dev returned by stat(2) and the
> +value of d_ino returned by readdir(3) will act like on a normal filesystem.
> +E.g. the value of st_dev may be different for two objects in the same
> +overlay filesystem and the value of st_ino for directory objects may not be
> +persistent and could change even while the overlay filesystem is mounted.
> +
> +4) "copy_up_shared"
> +
> +Enabled with the mount option or module option "copy_up_shared=on" or with
> +the kernel config option CONFIG_OVERLAY_FS_COPY_UP_SHARED=y.
> +
> +If this feature is disabled, then a memory mapping created with MAP_SHARED
> +might contain stale data if the file has been copied up and modified in the
> +meantime.
>
>
>  Changes to underlying filesystems
> --
> 2.14.3
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-unionfs" in
> the body of a message to majord...@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH 35/35] ovl: fix documentation of non-standard behavior

[Amir Goldstein]

On Thu, Apr 12, 2018 at 6:08 PM, Miklos Szeredi  wrote:
> We can now drop description of the ro/rw inconsistency from the
> documentation.
>
> Also clarify, that now fully standard compliant behavior can be enabled
> with kernel/module/mount options.
>

Very nice!

Is it maybe a good time to tone down this expectation-lowering
phrase from the introduction:

"The result will inevitably fail to look exactly like a normal
filesystem for various technical reasons.  The expectation is that
many use cases will be able to ignore these differences."

> Signed-off-by: Miklos Szeredi 
> ---
>  Documentation/filesystems/overlayfs.txt | 64 
> ++---
>  1 file changed, 43 insertions(+), 21 deletions(-)
>
> diff --git a/Documentation/filesystems/overlayfs.txt 
> b/Documentation/filesystems/overlayfs.txt
> index 961b287ef323..095186080d23 100644
> --- a/Documentation/filesystems/overlayfs.txt
> +++ b/Documentation/filesystems/overlayfs.txt
> @@ -306,27 +306,49 @@ the copied layers will fail the verification of the 
> lower root file handle.
>  Non-standard behavior
>  -
>
> -The copy_up operation essentially creates a new, identical file and
> -moves it over to the old name.  Any open files referring to this inode
> -will access the old data.
> -
> -The new file may be on a different filesystem, so both st_dev and st_ino
> -of the real file may change.  The values of st_dev and st_ino returned by
> -stat(2) on an overlay object are often not the same as the real file
> -stat(2) values to prevent the values from changing on copy_up.
> -
> -Unless "xino" feature is enabled, when overlay layers are not all on the
> -same underlying filesystem, the value of st_dev may be different for two
> -non-directory objects in the same overlay filesystem and the value of
> -st_ino for directory objects may be non persistent and could change even
> -while the overlay filesystem is still mounted.
> -
> -Unless "inode index" feature is enabled, if a file with multiple hard
> -links is copied up, then this will "break" the link.  Changes will not be
> -propagated to other names referring to the same inode.
> -
> -Unless "redirect_dir" feature is enabled, rename(2) on a lower or merged
> -directory will fail with EXDEV.
> +Overlayfs can now act as a POSIX compliant filesystem with the following
> +features turned on:
> +
> +1) "redirect_dir"
> +
> +Enabled with the mount option or module option: "redirect_dir=on" or with
> +the kernel config option CONFIG_OVERLAY_FS_REDIRECT_DIR=y.
> +
> +If this feature is disabled, then rename(2) on a lower or merged directory
> +will fail with EXDEV ("Invalid cross-device link").
> +
> +2) "inode index"
> +
> +Enabled with the mount option or module option "index=on" or with the
> +kernel config option CONFIG_OVERLAY_FS_INDEX=y.
> +
> +If this feature is disabled and a file with multiple hard links is copied
> +up, then this will "break" the link.  Changes will not be propagated to
> +other names referring to the same inode.
> +
> +3) "xino"
> +
> +Enabled with the mount option "xino=auto" or "xino=on", with the module
> +option "xino_auto=on" or with the kernel config option
> +CONFIG_OVERLAY_FS_XINO_AUTO=y.  Also implicitly enabled by using the same
> +underlying filesystem for all layers making up the overlay.
> +
> +If this feature is disabled or the underlying filesystem doesn't have
> +enough free bits in the inode number, then overlayfs will not be able to
> +guarantee that the values of st_ino and st_dev returned by stat(2) and the
> +value of d_ino returned by readdir(3) will act like on a normal filesystem.
> +E.g. the value of st_dev may be different for two objects in the same
> +overlay filesystem and the value of st_ino for directory objects may not be
> +persistent and could change even while the overlay filesystem is mounted.
> +
> +4) "copy_up_shared"
> +
> +Enabled with the mount option or module option "copy_up_shared=on" or with
> +the kernel config option CONFIG_OVERLAY_FS_COPY_UP_SHARED=y.
> +
> +If this feature is disabled, then a memory mapping created with MAP_SHARED
> +might contain stale data if the file has been copied up and modified in the
> +meantime.
>
>
>  Changes to underlying filesystems
> --
> 2.14.3
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-unionfs" in
> the body of a message to majord...@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC PATCH 35/35] ovl: fix documentation of non-standard behavior

[Miklos Szeredi]

We can now drop description of the ro/rw inconsistency from the
documentation.

Also clarify, that now fully standard compliant behavior can be enabled
with kernel/module/mount options.

Signed-off-by: Miklos Szeredi 
---
 Documentation/filesystems/overlayfs.txt | 64 ++---
 1 file changed, 43 insertions(+), 21 deletions(-)

diff --git a/Documentation/filesystems/overlayfs.txt 
b/Documentation/filesystems/overlayfs.txt
index 961b287ef323..095186080d23 100644
--- a/Documentation/filesystems/overlayfs.txt
+++ b/Documentation/filesystems/overlayfs.txt
@@ -306,27 +306,49 @@ the copied layers will fail the verification of the lower 
root file handle.
 Non-standard behavior
 -
 
-The copy_up operation essentially creates a new, identical file and
-moves it over to the old name.  Any open files referring to this inode
-will access the old data.
-
-The new file may be on a different filesystem, so both st_dev and st_ino
-of the real file may change.  The values of st_dev and st_ino returned by
-stat(2) on an overlay object are often not the same as the real file
-stat(2) values to prevent the values from changing on copy_up.
-
-Unless "xino" feature is enabled, when overlay layers are not all on the
-same underlying filesystem, the value of st_dev may be different for two
-non-directory objects in the same overlay filesystem and the value of
-st_ino for directory objects may be non persistent and could change even
-while the overlay filesystem is still mounted.
-
-Unless "inode index" feature is enabled, if a file with multiple hard
-links is copied up, then this will "break" the link.  Changes will not be
-propagated to other names referring to the same inode.
-
-Unless "redirect_dir" feature is enabled, rename(2) on a lower or merged
-directory will fail with EXDEV.
+Overlayfs can now act as a POSIX compliant filesystem with the following
+features turned on:
+
+1) "redirect_dir"
+
+Enabled with the mount option or module option: "redirect_dir=on" or with
+the kernel config option CONFIG_OVERLAY_FS_REDIRECT_DIR=y.
+
+If this feature is disabled, then rename(2) on a lower or merged directory
+will fail with EXDEV ("Invalid cross-device link").
+
+2) "inode index"
+
+Enabled with the mount option or module option "index=on" or with the
+kernel config option CONFIG_OVERLAY_FS_INDEX=y.
+
+If this feature is disabled and a file with multiple hard links is copied
+up, then this will "break" the link.  Changes will not be propagated to
+other names referring to the same inode.
+
+3) "xino"
+
+Enabled with the mount option "xino=auto" or "xino=on", with the module
+option "xino_auto=on" or with the kernel config option
+CONFIG_OVERLAY_FS_XINO_AUTO=y.  Also implicitly enabled by using the same
+underlying filesystem for all layers making up the overlay.
+
+If this feature is disabled or the underlying filesystem doesn't have
+enough free bits in the inode number, then overlayfs will not be able to
+guarantee that the values of st_ino and st_dev returned by stat(2) and the
+value of d_ino returned by readdir(3) will act like on a normal filesystem.
+E.g. the value of st_dev may be different for two objects in the same
+overlay filesystem and the value of st_ino for directory objects may not be
+persistent and could change even while the overlay filesystem is mounted.
+
+4) "copy_up_shared"
+
+Enabled with the mount option or module option "copy_up_shared=on" or with
+the kernel config option CONFIG_OVERLAY_FS_COPY_UP_SHARED=y.
+
+If this feature is disabled, then a memory mapping created with MAP_SHARED
+might contain stale data if the file has been copied up and modified in the
+meantime.
 
 
 Changes to underlying filesystems
-- 
2.14.3

[RFC PATCH 35/35] ovl: fix documentation of non-standard behavior

[Miklos Szeredi]

We can now drop description of the ro/rw inconsistency from the
documentation.

Also clarify, that now fully standard compliant behavior can be enabled
with kernel/module/mount options.

Signed-off-by: Miklos Szeredi 
---
 Documentation/filesystems/overlayfs.txt | 64 ++---
 1 file changed, 43 insertions(+), 21 deletions(-)

diff --git a/Documentation/filesystems/overlayfs.txt 
b/Documentation/filesystems/overlayfs.txt
index 961b287ef323..095186080d23 100644
--- a/Documentation/filesystems/overlayfs.txt
+++ b/Documentation/filesystems/overlayfs.txt
@@ -306,27 +306,49 @@ the copied layers will fail the verification of the lower 
root file handle.
 Non-standard behavior
 -
 
-The copy_up operation essentially creates a new, identical file and
-moves it over to the old name.  Any open files referring to this inode
-will access the old data.
-
-The new file may be on a different filesystem, so both st_dev and st_ino
-of the real file may change.  The values of st_dev and st_ino returned by
-stat(2) on an overlay object are often not the same as the real file
-stat(2) values to prevent the values from changing on copy_up.
-
-Unless "xino" feature is enabled, when overlay layers are not all on the
-same underlying filesystem, the value of st_dev may be different for two
-non-directory objects in the same overlay filesystem and the value of
-st_ino for directory objects may be non persistent and could change even
-while the overlay filesystem is still mounted.
-
-Unless "inode index" feature is enabled, if a file with multiple hard
-links is copied up, then this will "break" the link.  Changes will not be
-propagated to other names referring to the same inode.
-
-Unless "redirect_dir" feature is enabled, rename(2) on a lower or merged
-directory will fail with EXDEV.
+Overlayfs can now act as a POSIX compliant filesystem with the following
+features turned on:
+
+1) "redirect_dir"
+
+Enabled with the mount option or module option: "redirect_dir=on" or with
+the kernel config option CONFIG_OVERLAY_FS_REDIRECT_DIR=y.
+
+If this feature is disabled, then rename(2) on a lower or merged directory
+will fail with EXDEV ("Invalid cross-device link").
+
+2) "inode index"
+
+Enabled with the mount option or module option "index=on" or with the
+kernel config option CONFIG_OVERLAY_FS_INDEX=y.
+
+If this feature is disabled and a file with multiple hard links is copied
+up, then this will "break" the link.  Changes will not be propagated to
+other names referring to the same inode.
+
+3) "xino"
+
+Enabled with the mount option "xino=auto" or "xino=on", with the module
+option "xino_auto=on" or with the kernel config option
+CONFIG_OVERLAY_FS_XINO_AUTO=y.  Also implicitly enabled by using the same
+underlying filesystem for all layers making up the overlay.
+
+If this feature is disabled or the underlying filesystem doesn't have
+enough free bits in the inode number, then overlayfs will not be able to
+guarantee that the values of st_ino and st_dev returned by stat(2) and the
+value of d_ino returned by readdir(3) will act like on a normal filesystem.
+E.g. the value of st_dev may be different for two objects in the same
+overlay filesystem and the value of st_ino for directory objects may not be
+persistent and could change even while the overlay filesystem is mounted.
+
+4) "copy_up_shared"
+
+Enabled with the mount option or module option "copy_up_shared=on" or with
+the kernel config option CONFIG_OVERLAY_FS_COPY_UP_SHARED=y.
+
+If this feature is disabled, then a memory mapping created with MAP_SHARED
+might contain stale data if the file has been copied up and modified in the
+meantime.
 
 
 Changes to underlying filesystems
-- 
2.14.3