From: Tao Cui <cuitao@kylinos.cn>

File locks and leases taken on files through the overlay mount are
only meaningful between tasks that access the files through the same
overlay mount; they do not conflict with anything that changes the
underlying filesystems directly.  Add a short note to "Changes to
underlying filesystems" stating this scope.

Signed-off-by: Tao Cui <cuitao@kylinos.cn>
---
Changes since v1:
- minimal note within "Changes to underlying filesystems" instead of a
  separate section, per review (Amir Goldstein)
---
 Documentation/filesystems/overlayfs.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst
index 16c35b491dad..11af5bc73e32 100644
--- a/Documentation/filesystems/overlayfs.rst
+++ b/Documentation/filesystems/overlayfs.rst
@@ -671,6 +671,15 @@ 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.
 
+Note that file locks and leases taken on files through the overlay
+mount only provide mutual exclusion between tasks that access the
+files through the same overlay mount, and a lease taken through the
+overlay is broken by opens through that overlay.  They do not
+conflict with locks taken on the same files by anything that changes
+the underlying filesystems directly, so file locking cannot be relied
+on for mutual exclusion between overlay users and such direct
+changes.
+
 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
 "metacopy", "index", "xino" and "redirect_dir" features
-- 
2.43.0

On Thu, Sep 3, 2026 at 3:26 PM Tao Cui <cui.tao@linux.dev> wrote:
>
> From: Tao Cui <cuitao@kylinos.cn>
>
> File locks and leases taken on files through the overlay mount are
> only meaningful between tasks that access the files through the same
> overlay mount; they do not conflict with anything that changes the
> underlying filesystems directly.  Add a short note to "Changes to
> underlying filesystems" stating this scope.
>
> Signed-off-by: Tao Cui <cuitao@kylinos.cn>
> ---
> Changes since v1:
> - minimal note within "Changes to underlying filesystems" instead of a
>   separate section, per review (Amir Goldstein)
> ---
>  Documentation/filesystems/overlayfs.rst | 9 +++++++++
>  1 file changed, 9 insertions(+)
>
> diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst
> index 16c35b491dad..11af5bc73e32 100644
> --- a/Documentation/filesystems/overlayfs.rst
> +++ b/Documentation/filesystems/overlayfs.rst
> @@ -671,6 +671,15 @@ 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.
>
> +Note that file locks and leases taken on files through the overlay
> +mount only provide mutual exclusion between tasks that access the
> +files through the same overlay mount, and a lease taken through the
> +overlay is broken by opens through that overlay.  They do not
> +conflict with locks taken on the same files by anything that changes
> +the underlying filesystems directly, so file locking cannot be relied
> +on for mutual exclusion between overlay users and such direct
> +changes.
> +
>  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
>  "metacopy", "index", "xino" and "redirect_dir" features
> --
> 2.43.0
>

Reviewed-by: Amir Goldstein <amir73il@gmail.com>

I'd like to wait for Miklos to comment before merging this.

Thanks,
Amir.