Re: [PATCH] overlayfs.rst: document cross-layer file lock and lease semantics

[Amir Goldstein]

On Thu, Sep 3, 2026 at 5:34 AM Tao Cui <cui.tao@xxxxxxxxx> wrote:
>
> From: Tao Cui <cuitao@xxxxxxxxxx>
>
> Locks and leases taken through an overlay attach to the overlay inode,
> while opens of the same on-disk file through its real upper/lower path
> operate on the underlying inode.  The two do not conflict, so an
> "exclusive" flock/POSIX/OFD lock or a write lease held via the overlay
> is silently bypassed by anyone reaching the file through the layers
> directly, e.g. backup tools walking a container's upperdir or another
> overlay mount over the same layers.
>
> Locking through the overlay succeeds and appears to work, so the lack
> of mutual exclusion only shows up as data corruption when the two
> sides write concurrently.  Document the semantics, the affected
> scenarios and the recommended practice.
>
> Signed-off-by: Tao Cui <cuitao@xxxxxxxxxx>
> ---
>  Documentation/filesystems/overlayfs.rst | 27 +++++++++++++++++++++++++
>  1 file changed, 27 insertions(+)
>
> diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst
> index 16c35b491dad..546b77e66016 100644
> --- a/Documentation/filesystems/overlayfs.rst
> +++ b/Documentation/filesystems/overlayfs.rst
> @@ -884,6 +884,33 @@ The "-o userxattr" mount option forces overlayfs to use the
>  useful for unprivileged mounting of overlayfs.
>
>
> +File locks and leases
> +---------------------
> +
> +File locks (flock, POSIX record locks and OFD locks) and file leases
> +taken on a file through the overlay attach to the overlay inode.  The
> +same on-disk file opened through its real upper or lower path is a
> +different inode object, so locks and leases acquired through one path
> +do not conflict with locks and leases acquired through the other.
> +

Hi Tao,

Thanks for your contribution, but it is not acceptable as it is.

Everything written above may be true, but a document needs to be coherent
and this text was written without regard to the context of the document.

The most relevant context is:

  Changes to underlying filesystems
  ---------------------------------

  Changes to the underlying filesystems while part of a mounted overlay
  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.

TBH I am not enthusiastic about documenting what may happen
on changes of the underlying layer beyond this statement.

I am fine with clarifying a bit about the lock scope, but not as much
as you did -
keep it to bare minimum which is useful.

Also when writing text in this document you need to use terminology of
the document, for example, "same on-disk file" is incoherent with how
this document refers to underlying layers.

> +An "exclusive" lock or a write lease held by a task that opened the
> +file through the overlay does not prevent another task from acquiring
> +the same lock or opening the file if the latter reaches the file
> +through the underlying layer directly, e.g.:
> +
> +- a tool running outside the container accesses the container's
> +  upperdir/workdir or the image layers below it directly,
> +- a second overlay mount is stacked over the same upperdir,

This is really a disaster setup. I won't even discuss what could go
wrong with sharing an uperdir

> +- the same layers are shared between different overlay mounts.

This is obviously normal so not sure why it is relevant

> +
> +Locks and leases do provide mutual exclusion between tasks that all
> +reach the file through the same overlay mount, and a lease taken
> +through the overlay is broken by opens through that overlay.
> +
> +Do not rely on file locking for mutual exclusion between overlay
> +users and anything that may touch the underlying layers directly.
> +
> +

These two statements are the only ones that seem relevant to me
and I would add them in the context of
"Changes to underlying filesystems" not as a separate section.

Thanks,
Amir.