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

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

[Tao Cui]

From: Tao Cui <cuitao@kylinos.cn>

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@kylinos.cn>
---
 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.
+
+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,
+- the same layers are shared between different overlay mounts.
+
+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.
+
+
 Testsuite
 ---------
 
-- 
2.43.0

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@linux.dev> wrote:
>
> From: Tao Cui <cuitao@kylinos.cn>
>
> 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@kylinos.cn>
> ---
>  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.

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

[Tao Cui]

Hi Amir,

在 2026/9/3 16:34, Amir Goldstein 写道:
> On Thu, Sep 3, 2026 at 5:34 AM Tao Cui <cui.tao@linux.dev> wrote:
>>
>> From: Tao Cui <cuitao@kylinos.cn>
>>
>> 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@kylinos.cn>
>> ---
>>  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 for the review.  Understood - the note belongs in the context
of "Changes to underlying filesystems" and should stay minimal, in
the document's terminology.  I'll follow up with a v2.

Thanks,
Tao

> Thanks,
> Amir.