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