diff mbox series

[man-pages,v1] flock.2: add CIFS details

Message ID 20210302154831.17000-1-aaptel@suse.com (mailing list archive)
State New, archived
Headers show
Series [man-pages,v1] flock.2: add CIFS details | expand

Commit Message

Aurélien Aptel March 2, 2021, 3:48 p.m. UTC
From: Aurelien Aptel <aaptel@suse.com>

Similarly to NFS, CIFS flock() locks behave differently than the
standard. Document those differences.

Signed-off-by: Aurelien Aptel <aaptel@suse.com>
---
 man2/flock.2 | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

Comments

Tom Talpey March 3, 2021, 3:37 p.m. UTC | #1
On 3/2/2021 10:48 AM, Aurélien Aptel wrote:
> From: Aurelien Aptel <aaptel@suse.com>
> 
> Similarly to NFS, CIFS flock() locks behave differently than the
> standard. Document those differences.
> 
> Signed-off-by: Aurelien Aptel <aaptel@suse.com>
> ---
>   man2/flock.2 | 22 ++++++++++++++++++++++
>   1 file changed, 22 insertions(+)
> 
> diff --git a/man2/flock.2 b/man2/flock.2
> index 61d4b5396..9271b8fef 100644
> --- a/man2/flock.2
> +++ b/man2/flock.2
> @@ -239,6 +239,28 @@ see the discussion of the
>   .I "local_lock"
>   option in
>   .BR nfs (5).
> +.SS CIFS details
> +CIFS mounts share similar limitations with NFS.

I'd suggest removing this sentence. It doesn't really add anything to
the definition.

> +.PP
> +In Linux kernels up to 5.4,
> +.BR flock ()
> +locks files on the local system,
> +not over SMB. A locked file won't appear locked for other SMB clients
> +accessing the same share.

This is discussing the scenario where a process on the server performs
an flock(), right? That's perhaps confusingly special. How about

"In Linux kernels up to 5.4, flock() is not propagated over SMB. A file
with such locks will not appear locked for remote clients."

> +.PP
> +Since Linux 5.5,
> +.BR flock ()
> +are emulated with SMB byte-range locks on the
> +entire file. Similarly to NFS, this means that
> +.BR fcntl (2)
> +and
> +.BR flock ()
> +locks interact with one another over SMB. Another important
> +side-effect is that the locks are not advisory anymore: a write on a
> +locked file will always fail with
> +.BR EACCESS .
> +This difference originates from the design of locks in the SMB
> +protocol and cannot be worked around.

"protocol, which provides mandatory locking semantics."

>   .SH SEE ALSO
>   .BR flock (1),
>   .BR close (2),
>
Aurélien Aptel March 3, 2021, 4:28 p.m. UTC | #2
Hi Tom,

Thanks for taking a look.

Tom Talpey <tom@talpey.com> writes:
> On 3/2/2021 10:48 AM, Aurélien Aptel wrote:
> I'd suggest removing this sentence. It doesn't really add anything to
> the definition.

OK.

> This is discussing the scenario where a process on the server performs
> an flock(), right? That's perhaps confusingly special. How about

This is about clients. Let's say the same app is running on 2 different
Linux system that have the same Windows Server share mounted.

The scenario is those 2 app instances use the same file on the share and
are trying to synchronize access using flock().

Pre-5.5, CIFS flock() is using the generic flock() implementation from
the Linux VFS layer which only knows about syscall made by local apps
and isn't aware that the file can be accessed under its feet from the
network.

In 5.5 and above, CIFS flock() is implemented using SMB locks, which
have different semantics than what POSIX defines, i.e. you cannot ignore
the locks and write, write() will fail with EPERM. So this version can
be used for file sync with other clients but works slightly
differently. It is a best-effort attempt.

Does this clarification changes anything to your suggestions?

> "In Linux kernels up to 5.4, flock() is not propagated over SMB. A file
> with such locks will not appear locked for remote clients."


> "protocol, which provides mandatory locking semantics."

OK. As it turns out, there is actually a 'nobrl' mount option to get back
pre-5.5 behavior. I'll mention it and use your suggestions in v2.

Cheers,
Tom Talpey March 3, 2021, 4:48 p.m. UTC | #3
On 3/3/2021 11:28 AM, Aurélien Aptel wrote:
> Hi Tom,
> 
> Thanks for taking a look.
> 
> Tom Talpey <tom@talpey.com> writes:
>> On 3/2/2021 10:48 AM, Aurélien Aptel wrote:
>> I'd suggest removing this sentence. It doesn't really add anything to
>> the definition.
> 
> OK.
> 
>> This is discussing the scenario where a process on the server performs
>> an flock(), right? That's perhaps confusingly special. How about
> 
> This is about clients. Let's say the same app is running on 2 different
> Linux system that have the same Windows Server share mounted.
> 
> The scenario is those 2 app instances use the same file on the share and
> are trying to synchronize access using flock().
> 
> Pre-5.5, CIFS flock() is using the generic flock() implementation from
> the Linux VFS layer which only knows about syscall made by local apps
> and isn't aware that the file can be accessed under its feet from the
> network.

I don't fully understand your response. What does "knows about syscall
from local apps" mean, from a practical perspective? That it never
forwards any flock() call to the server? Or that it somehow caches
the flock() results, and never checks if the server has a conflict
from another client?

> In 5.5 and above, CIFS flock() is implemented using SMB locks, which
> have different semantics than what POSIX defines, i.e. you cannot ignore
> the locks and write, write() will fail with EPERM. So this version can
> be used for file sync with other clients but works slightly
> differently. It is a best-effort attempt.

I think we're agreeing here. Let's figure out the other question before
deciding.

Bottom line, I think it's important to avoid statements like "same" or
"different". Say what it does or does not do, and leave such questions
to other sources.

Tom.


> Does this clarification changes anything to your suggestions?
> 
>> "In Linux kernels up to 5.4, flock() is not propagated over SMB. A file
>> with such locks will not appear locked for remote clients."
> 
> 
>> "protocol, which provides mandatory locking semantics."
> 
> OK. As it turns out, there is actually a 'nobrl' mount option to get back
> pre-5.5 behavior. I'll mention it and use your suggestions in v2.
> 
> Cheers,
>
Aurélien Aptel March 3, 2021, 4:57 p.m. UTC | #4
Tom Talpey <tom@talpey.com> writes:
> I don't fully understand your response. What does "knows about syscall
> from local apps" mean, from a practical perspective? That it never
> forwards any flock() call to the server? Or that it somehow caches
> the flock() results, and never checks if the server has a conflict
> from another client?

Yes that's what I'm trying to say. Locking never goes on the
wire. Server is not aware of locking, and thus neither are any other
clients.

Cheers,
Tom Talpey March 3, 2021, 5:41 p.m. UTC | #5
On 3/3/2021 11:57 AM, Aurélien Aptel wrote:
> Tom Talpey <tom@talpey.com> writes:
>> I don't fully understand your response. What does "knows about syscall
>> from local apps" mean, from a practical perspective? That it never
>> forwards any flock() call to the server? Or that it somehow caches
>> the flock() results, and never checks if the server has a conflict
>> from another client?
> 
> Yes that's what I'm trying to say. Locking never goes on the
> wire. Server is not aware of locking, and thus neither are any other
> clients.

Ok, but that's what I wrote in the earlier suggestion:

"In Linux kernels up to 5.4, flock() is not propagated over SMB. A file
with such locks will not appear locked for remote clients."

So I'm still confused what to suggest, but I'll respond on the
other fork of the thread.

Tom.
diff mbox series

Patch

diff --git a/man2/flock.2 b/man2/flock.2
index 61d4b5396..9271b8fef 100644
--- a/man2/flock.2
+++ b/man2/flock.2
@@ -239,6 +239,28 @@  see the discussion of the
 .I "local_lock"
 option in
 .BR nfs (5).
+.SS CIFS details
+CIFS mounts share similar limitations with NFS.
+.PP
+In Linux kernels up to 5.4,
+.BR flock ()
+locks files on the local system,
+not over SMB. A locked file won't appear locked for other SMB clients
+accessing the same share.
+.PP
+Since Linux 5.5,
+.BR flock ()
+are emulated with SMB byte-range locks on the
+entire file. Similarly to NFS, this means that
+.BR fcntl (2)
+and
+.BR flock ()
+locks interact with one another over SMB. Another important
+side-effect is that the locks are not advisory anymore: a write on a
+locked file will always fail with
+.BR EACCESS .
+This difference originates from the design of locks in the SMB
+protocol and cannot be worked around.
 .SH SEE ALSO
 .BR flock (1),
 .BR close (2),