On Wed, Dec 13, 2023 at 02:34:21PM +0200, Amir Goldstein wrote:
> Use the feature names "metacopy" and "index" consistently throughout
> the document.
>
> Covert the numbered list of features "redirect_dir", "index", "xino"
> to section headings, so that those features could be referenced in the
> document by their name.
>
> Signed-off-by: Amir Goldstein <amir73il@xxxxxxxxx>
> ---
> Documentation/filesystems/overlayfs.rst | 27 ++++++++++++++-----------
> 1 file changed, 15 insertions(+), 12 deletions(-)
>
> diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst
> index 0407f361f32a..926396fdc5eb 100644
> --- a/Documentation/filesystems/overlayfs.rst
> +++ b/Documentation/filesystems/overlayfs.rst
> @@ -39,7 +39,7 @@ objects in the original filesystem.
> On 64bit systems, even if all overlay layers are not on the same
> underlying filesystem, the same compliant behavior could be achieved
> with the "xino" feature. The "xino" feature composes a unique object
> -identifier from the real object st_ino and an underlying fsid index.
> +identifier from the real object st_ino and an underlying fsid number.
> 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
> @@ -356,7 +356,7 @@ as an octal characters (\072) when displayed in /proc/self/mountinfo.
> Metadata only copy up
> ---------------------
>
> -When metadata only copy up feature is enabled, overlayfs will only copy
> +When the "metacopy" 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.
> @@ -492,27 +492,27 @@ though it will not result in a crash or deadlock.
>
> 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 "inodes index" feature
> -or "metadata only copy up" feature is enabled.
> +different lower layer path, is allowed, unless the "index" or "metacopy"
> +features are enabled.
>
> -With the "inodes index" feature, on the first time mount, an NFS file
> +With the "index" 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. An overlayfs mount with
> -"inodes index" enabled will fail with EOPNOTSUPP if the lower filesystem
> +"index" enabled 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.
>
> -For "metadata only copy up" feature there is no verification mechanism at
> +For the "metacopy" feature, there is no verification mechanism at
> mount time. So if same upper is mounted with different set of lower, mount
> probably will succeed but expect the unexpected later on. So don't do it.
>
> 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 "inodes index" feature, trying to mount
> +to a different machine. With the "index" feature, trying to mount
> the copied layers will fail the verification of the lower root file handle.
>
> Nesting overlayfs mounts
> @@ -560,7 +560,8 @@ file for write or truncating the file will not be denied with ETXTBSY.
> The following options allow overlayfs to act more like a standards
> compliant filesystem:
>
> -1) "redirect_dir"
> +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.
> @@ -568,7 +569,8 @@ 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"
> +index
> +`````
>
> Enabled with the mount option or module option "index=on" or with the
> kernel config option CONFIG_OVERLAY_FS_INDEX=y.
> @@ -577,7 +579,8 @@ 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"
> +xino
> +````
>
> Enabled with the mount option "xino=auto" or "xino=on", with the module
> option "xino_auto=on" or with the kernel config option
> @@ -604,7 +607,7 @@ a crash or deadlock.
>
> Offline changes, when the overlay is not mounted, are allowed to the
> upper tree. Offline changes to the lower tree are only allowed if the
> -"metadata only copy up", "inode index", "xino" and "redirect_dir" features
> +"metacopy", "index", "xino" and "redirect_dir" features
> have not been used. If the lower tree is modified and any of these
> features has been used, the behavior of the overlay is undefined,
> though it will not result in a crash or deadlock.
LGTM, thanks!
Reviewed-by: Bagas Sanjaya <bagasdotme@xxxxxxxxx>
--
An old man doll... just what I always wanted! - Clara
Attachment:
signature.asc
Description: PGP signature
