Re: [PATCH v2 1/2] overlayfs.rst: use consistent feature names

[Bagas Sanjaya <bagasdotme@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 5858 bytes --]

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@gmail.com>
> ---
>  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@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]