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

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

[Aurélien Aptel]

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.
+.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),
-- 
2.30.0

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

[Tom Talpey]

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),
> 

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

[Aurélien Aptel]

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,
-- 
Aurélien Aptel / SUSE Labs Samba Team
GPG: 1839 CB5F 9F5B FB9B AA97  8C99 03C8 A49B 521B D5D3
SUSE Software Solutions Germany GmbH, Maxfeldstr. 5, 90409 Nürnberg, DE
GF: Felix Imendörffer, Mary Higgins, Sri Rasiah HRB 247165 (AG München)

[PATCH v2] flock.2: add CIFS details

[Aurélien Aptel]

From: Aurelien Aptel <aaptel@suse.com>

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

Here is the rendered text:

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

  Since Linux 5.5, flock() are emulated with SMB byte-range locks on  the
  entire  file.  Similarly  to  NFS, this means that fcntl(2) and 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 EACCESS.  This difference originates from the de-
  sign of locks in the SMB protocol, which provides mandatory locking se-
  mantics. The nobrl mount option can be used switch back to pre-5.5 ker-
  nel behavior.

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

diff --git a/man2/flock.2 b/man2/flock.2
index 61d4b5396..7c4e7e8c9 100644
--- a/man2/flock.2
+++ b/man2/flock.2
@@ -239,6 +239,27 @@ see the discussion of the
 .I "local_lock"
 option in
 .BR nfs (5).
+.SS CIFS details
+In Linux kernels up to 5.4,
+.BR flock ()
+is not propagated over SMB. A file with such locks will not appear
+locked for other SMB 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, which provides mandatory locking semantics. The
+.BR nobrl
+mount option can be used switch back to pre-5.5 kernel behavior.
 .SH SEE ALSO
 .BR flock (1),
 .BR close (2),
-- 
2.30.0

Re: [PATCH v2] flock.2: add CIFS details

[Tom Talpey]

Definitely better! Couple of suggestions:

On 3/3/2021 11:37 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.
> 
> Here is the rendered text:
> 
> CIFS details
>    In  Linux kernels up to 5.4, flock() is not propagated over SMB. A file
>    with such locks will not appear locked for other SMB clients.
> 
>    Since Linux 5.5, flock() are emulated with SMB byte-range locks on  the
>    entire  file.  Similarly  to  NFS, this means that fcntl(2) and 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 EACCESS.  This difference originates from the de-
>    sign of locks in the SMB protocol, which provides mandatory locking se-
>    mantics. The nobrl mount option can be used switch back to pre-5.5 ker-
>    nel behavior.
> 
> Signed-off-by: Aurelien Aptel <aaptel@suse.com>
> ---
>   man2/flock.2 | 21 +++++++++++++++++++++
>   1 file changed, 21 insertions(+)
> 
> diff --git a/man2/flock.2 b/man2/flock.2
> index 61d4b5396..7c4e7e8c9 100644
> --- a/man2/flock.2
> +++ b/man2/flock.2
> @@ -239,6 +239,27 @@ see the discussion of the
>   .I "local_lock"
>   option in
>   .BR nfs (5).
> +.SS CIFS details
> +In Linux kernels up to 5.4,
> +.BR flock ()
> +is not propagated over SMB. A file with such locks will not appear
> +locked for other SMB clients.

Other "remote" clients, right? It's not limited to SMB, if the server
is also managing other protocols which might support flock'ing.

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

There's a subtlety here. If the server implements these SMB byte-range
locks in certain ways, the locks may interact with other protocols too.
So constraining the statement to "over SMB" may be incomplete.

Wy not simply say "this means that fcntl() and flock() locks interact
with one another", and preserve the generality?

> +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, which provides mandatory locking semantics. The
> +.BR nobrl
> +mount option can be used switch back to pre-5.5 kernel behavior.

Wait, the page just said that pre-5.5 was local only. Wouldn't it
be better to just say that "nobrl" turns off the entire behavior of
forwarding locks to the server, like before? Or are there other
side effects...

Tom.

>   .SH SEE ALSO
>   .BR flock (1),
>   .BR close (2),
> 

[PATCH v3] flock.2: add CIFS details

[Aurélien Aptel]

From: Aurelien Aptel <aaptel@suse.com>

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

Here is the rendered text:

CIFS details
  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.

  Since Linux 5.5, flock() locks are emulated with SMB  byte-range  locks
  on  the  entire  file.  Similarly  to NFS, this means that fcntl(2) and
  flock() locks interact with one another. Another important  side-effect
  is  that  the  locks are not advisory anymore: a write on a locked file
  will always fail with EACCESS.  This difference originates from the de-
  sign of locks in the SMB protocol, which provides mandatory locking se-
  mantics. The nobrl mount option (see mount.cifs(8)) turns off  fnctl(2)
  and  flock() lock propagation to remote clients and makes flock() locks
  advisory again.

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

diff --git a/man2/flock.2 b/man2/flock.2
index 61d4b5396..4b6e5cc24 100644
--- a/man2/flock.2
+++ b/man2/flock.2
@@ -239,6 +239,35 @@ see the discussion of the
 .I "local_lock"
 option in
 .BR nfs (5).
+.SS CIFS details
+In Linux kernels up to 5.4,
+.BR 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 ()
+locks 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. 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, which provides mandatory locking semantics. The
+.I nobrl
+mount option (see
+.BR mount.cifs (8))
+turns off
+.BR fnctl (2)
+and
+.BR flock ()
+lock propagation to remote clients and makes
+.BR flock ()
+locks advisory again.
 .SH SEE ALSO
 .BR flock (1),
 .BR close (2),
-- 
2.30.0

Re: [PATCH v3] flock.2: add CIFS details

[Tom Talpey]

It looks great, and sorry to be a pest, but I just noticed - it's
EACCES (not EACCESS).

Reviewed-By: Tom Talpey <tom@talpey.com>

On 3/3/2021 2:03 PM, Aurélien Aptel wrote:
> From: Aurelien Aptel <aaptel@suse.com>
> 
> Similarly to NFS, CIFS flock() locks behave differently than the
> standard. Document those differences.
> 
> Here is the rendered text:
> 
> CIFS details
>    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.
> 
>    Since Linux 5.5, flock() locks are emulated with SMB  byte-range  locks
>    on  the  entire  file.  Similarly  to NFS, this means that fcntl(2) and
>    flock() locks interact with one another. Another important  side-effect
>    is  that  the  locks are not advisory anymore: a write on a locked file
>    will always fail with EACCESS.  This difference originates from the de-
>    sign of locks in the SMB protocol, which provides mandatory locking se-
>    mantics. The nobrl mount option (see mount.cifs(8)) turns off  fnctl(2)
>    and  flock() lock propagation to remote clients and makes flock() locks
>    advisory again.
> 
> Signed-off-by: Aurelien Aptel <aaptel@suse.com>
> ---
>   man2/flock.2 | 29 +++++++++++++++++++++++++++++
>   1 file changed, 29 insertions(+)
> 
> diff --git a/man2/flock.2 b/man2/flock.2
> index 61d4b5396..4b6e5cc24 100644
> --- a/man2/flock.2
> +++ b/man2/flock.2
> @@ -239,6 +239,35 @@ see the discussion of the
>   .I "local_lock"
>   option in
>   .BR nfs (5).
> +.SS CIFS details
> +In Linux kernels up to 5.4,
> +.BR 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 ()
> +locks 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. Another important side-effect is that
> +the locks are not advisory anymore: a write on a locked file will
> +always fail with
> +.BR EACCESS .

EACCES

> +This difference originates from the design of locks in the SMB
> +protocol, which provides mandatory locking semantics. The
> +.I nobrl
> +mount option (see
> +.BR mount.cifs (8))
> +turns off
> +.BR fnctl (2)
> +and
> +.BR flock ()
> +lock propagation to remote clients and makes
> +.BR flock ()
> +locks advisory again.
>   .SH SEE ALSO
>   .BR flock (1),
>   .BR close (2),
> 

Re: [PATCH v3] flock.2: add CIFS details

[Aurélien Aptel]

Tom Talpey <tom@talpey.com> writes:
> It looks great, and sorry to be a pest, but I just noticed - it's
> EACCES (not EACCESS).

No worries, thanks for the review.

Cheers,
-- 
Aurélien Aptel / SUSE Labs Samba Team
GPG: 1839 CB5F 9F5B FB9B AA97  8C99 03C8 A49B 521B D5D3
SUSE Software Solutions Germany GmbH, Maxfeldstr. 5, 90409 Nürnberg, DE
GF: Felix Imendörffer, Mary Higgins, Sri Rasiah HRB 247165 (AG München)

[PATCH v4] flock.2: add CIFS details

[Aurélien Aptel]

From: Aurelien Aptel <aaptel@suse.com>

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

Here is the rendered text:

CIFS details
  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.

  Since Linux 5.5, flock() locks are emulated with SMB  byte-range  locks
  on  the  entire  file.  Similarly  to NFS, this means that fcntl(2) and
  flock() locks interact with one another. Another important  side-effect
  is  that  the  locks are not advisory anymore: a write on a locked file
  will always fail with EACCES.   This difference originates from the de-
  sign of locks in the SMB protocol, which provides mandatory locking se-
  mantics. The nobrl mount option (see mount.cifs(8)) turns off  fnctl(2)
  and  flock() lock propagation to remote clients and makes flock() locks
  advisory again.

Signed-off-by: Aurelien Aptel <aaptel@suse.com>
Reviewed-By: Tom Talpey <tom@talpey.com>
---
 man2/flock.2 | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/man2/flock.2 b/man2/flock.2
index 61d4b5396..d447eac9c 100644
--- a/man2/flock.2
+++ b/man2/flock.2
@@ -239,6 +239,35 @@ see the discussion of the
 .I "local_lock"
 option in
 .BR nfs (5).
+.SS CIFS details
+In Linux kernels up to 5.4,
+.BR 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 ()
+locks 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. Another important side-effect is that
+the locks are not advisory anymore: a write on a locked file will
+always fail with
+.BR EACCES .
+This difference originates from the design of locks in the SMB
+protocol, which provides mandatory locking semantics. The
+.I nobrl
+mount option (see
+.BR mount.cifs (8))
+turns off
+.BR fnctl (2)
+and
+.BR flock ()
+lock propagation to remote clients and makes
+.BR flock ()
+locks advisory again.
 .SH SEE ALSO
 .BR flock (1),
 .BR close (2),
-- 
2.30.0

Re: [PATCH v4] flock.2: add CIFS details

[Alejandro Colomar (man-pages)]

On 3/4/21 10:50 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.
> 
> Here is the rendered text:
> 
> CIFS details
>    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.
> 
>    Since Linux 5.5, flock() locks are emulated with SMB  byte-range  locks
>    on  the  entire  file.  Similarly  to NFS, this means that fcntl(2) and
>    flock() locks interact with one another. Another important  side-effect
>    is  that  the  locks are not advisory anymore: a write on a locked file
>    will always fail with EACCES.   This difference originates from the de-
>    sign of locks in the SMB protocol, which provides mandatory locking se-
>    mantics. The nobrl mount option (see mount.cifs(8)) turns off  fnctl(2)
>    and  flock() lock propagation to remote clients and makes flock() locks
>    advisory again.
> 
> Signed-off-by: Aurelien Aptel <aaptel@suse.com>
> Reviewed-By: Tom Talpey <tom@talpey.com>
> ---
[...]
> +This difference originates from the design of locks in the SMB
> +protocol, which provides mandatory locking semantics. The
> +.I nobrl

I agree with Tom.  It's much easier to read if you just say that 'nobrl' 
torns off the non-locale behaviour, and acts as 5.4 and earlier kernels. 
  Unless there's any subtlety that makes it different.  Is there any?

BTW, you should use "semantic newlines":

$ man 7 man-pages |sed -n '/semantic newlines/,/^$/p'
    Use semantic newlines
        In the source of a manual page,  new  sentences  should  be
        started  on new lines, and long sentences should split into
        lines at clause breaks (commas, semicolons, colons, and  so
        on).   This  convention,  sometimes known as "semantic new-
        lines", makes it easier to see the effect of patches, which
        often  operate at the level of individual sentences or sen-
        tence clauses.


Thanks,

Alex

> +mount option (see
> +.BR mount.cifs (8))
> +turns off
> +.BR fnctl (2)
> +and
> +.BR flock ()
> +lock propagation to remote clients and makes
> +.BR flock ()
> +locks advisory again.
>   .SH SEE ALSO
>   .BR flock (1),
>   .BR close (2),
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH v4] flock.2: add CIFS details

[Aurélien Aptel]

"Alejandro Colomar (man-pages)" <alx.manpages@gmail.com> writes:
> I agree with Tom.  It's much easier to read if you just say that 'nobrl' 
> torns off the non-locale behaviour, and acts as 5.4 and earlier kernels. 
>   Unless there's any subtlety that makes it different.  Is there any?

nobrl also makes fnctl() locks local.
In 5.4 and earlier kernel, flock() is local but fnctl() isn't.

> BTW, you should use "semantic newlines":

Ok, I'll redo once we agree on the text.

Cheers,
-- 
Aurélien Aptel / SUSE Labs Samba Team
GPG: 1839 CB5F 9F5B FB9B AA97  8C99 03C8 A49B 521B D5D3
SUSE Software Solutions Germany GmbH, Maxfeldstr. 5, 90409 Nürnberg, DE
GF: Felix Imendörffer, Mary Higgins, Sri Rasiah HRB 247165 (AG München)

Re: [PATCH v4] flock.2: add CIFS details

[Tom Talpey]

On 3/11/2021 5:11 AM, Aurélien Aptel wrote:
> "Alejandro Colomar (man-pages)" <alx.manpages@gmail.com> writes:
>> I agree with Tom.  It's much easier to read if you just say that 'nobrl'
>> torns off the non-locale behaviour, and acts as 5.4 and earlier kernels.
>>    Unless there's any subtlety that makes it different.  Is there any?
> 
> nobrl also makes fnctl() locks local.
> In 5.4 and earlier kernel, flock() is local but fnctl() isn't.
> 
>> BTW, you should use "semantic newlines":
> 
> Ok, I'll redo once we agree on the text.

I wonder if it's best to leave the nobrl details to the mount.cifs
manpage, and just make a reference from here.

Another advantage of putting this in a cifs.ko-specific manpage
is that it would be significantly easier to maintain. The details
of a 5.4-to-5.5 transition are going to fade over time, and the
APIs in fcntl(2)/flock(2) really aren't driving that.

If not, it's going to be messy... Aurélien is this correct?

cifs.ko flock()
- local in <= 5.4
- remote by default in >= 5.5
- local if nobrl in >= 5.5

cifs.ko fcntl()
- remote by default in X.Y
- local if nobrl in X.Y

Not sure what the value(s) of X.Y actually might be.

It seems odd that "nobrl" means "handle locking locally, and never
send to server". I mean, there is always byte-range locking, right?

Are there any other options or configurations that alter this?

Tom.

Re: [PATCH v4] flock.2: add CIFS details

[Aurélien Aptel]

Tom Talpey <tom@talpey.com> writes:

> On 3/11/2021 5:11 AM, Aurélien Aptel wrote:
>> "Alejandro Colomar (man-pages)" <alx.manpages@gmail.com> writes:
>>> I agree with Tom.  It's much easier to read if you just say that 'nobrl'
>>> torns off the non-locale behaviour, and acts as 5.4 and earlier kernels.
>>>    Unless there's any subtlety that makes it different.  Is there any?
>> 
>> nobrl also makes fnctl() locks local.
>> In 5.4 and earlier kernel, flock() is local but fnctl() isn't.
>> 
>>> BTW, you should use "semantic newlines":
>> 
>> Ok, I'll redo once we agree on the text.
>
> I wonder if it's best to leave the nobrl details to the mount.cifs
> manpage, and just make a reference from here.
>
> Another advantage of putting this in a cifs.ko-specific manpage
> is that it would be significantly easier to maintain. The details
> of a 5.4-to-5.5 transition are going to fade over time, and the
> APIs in fcntl(2)/flock(2) really aren't driving that.

I was trying to write in the same style as the NFS details just above (see
existing man page). Give basic overview of the issues.

> If not, it's going to be messy... Aurélien is this correct?
>
> cifs.ko flock()
> - local in <= 5.4
> - remote by default in >= 5.5
> - local if nobrl in >= 5.5
>
> cifs.ko fcntl()
> - remote by default in X.Y
> - local if nobrl in X.Y

Correct.

> Not sure what the value(s) of X.Y actually might be.

AFAIK fcntl() was always remote by default.
And nobrl was added in 2.6.15 (15 years ago). I wouldn't bother
mentionning X.Y, it's already complex enough as it is.

> It seems odd that "nobrl" means "handle locking locally, and never
> send to server". I mean, there is always byte-range locking, right?

Yes the option name can be confusing. Byte-range locking is always
possible, but with "nobrl" it's local-only.

> Are there any other options or configurations that alter this?

I've taken another long look at the cifs.ko and samba code. There are
many knobs that would make an accurate matrix table pretty big.

* If the mount point is done on an SMB1+UNIX Extensions
  connection, locking becomes advisory. Unless
  forcemandatorylock option is passed. This will eventually be
  implemented for SMB3 posix extensions as well (I've started a
  thread on the samba-technical mailing list).
* If cifs.ko can get guarantees (via oplocks or leases) that it is the
  only user of a file, it caches read/writes but also locking
  locally. If the lease is broke then it will send the locks.
  The levels of caching cifs.ko can do can be changed with the cache
  mount option.

Cheers,
-- 
Aurélien Aptel / SUSE Labs Samba Team
GPG: 1839 CB5F 9F5B FB9B AA97  8C99 03C8 A49B 521B D5D3
SUSE Software Solutions Germany GmbH, Maxfeldstr. 5, 90409 Nürnberg, DE
GF: Felix Imendörffer, Mary Higgins, Sri Rasiah HRB 247165 (AG München)

Re: [PATCH v4] flock.2: add CIFS details

[Tom Talpey]

On 3/11/2021 12:13 PM, Aurélien Aptel wrote:
> Tom Talpey <tom@talpey.com> writes:
> 
>> On 3/11/2021 5:11 AM, Aurélien Aptel wrote:
>>> "Alejandro Colomar (man-pages)" <alx.manpages@gmail.com> writes:
>>>> I agree with Tom.  It's much easier to read if you just say that 'nobrl'
>>>> torns off the non-locale behaviour, and acts as 5.4 and earlier kernels.
>>>>     Unless there's any subtlety that makes it different.  Is there any?
>>>
>>> nobrl also makes fnctl() locks local.
>>> In 5.4 and earlier kernel, flock() is local but fnctl() isn't.
>>>
>>>> BTW, you should use "semantic newlines":
>>>
>>> Ok, I'll redo once we agree on the text.
>>
>> I wonder if it's best to leave the nobrl details to the mount.cifs
>> manpage, and just make a reference from here.
>>
>> Another advantage of putting this in a cifs.ko-specific manpage
>> is that it would be significantly easier to maintain. The details
>> of a 5.4-to-5.5 transition are going to fade over time, and the
>> APIs in fcntl(2)/flock(2) really aren't driving that.
> 
> I was trying to write in the same style as the NFS details just above (see
> existing man page). Give basic overview of the issues.
> 
>> If not, it's going to be messy... Aurélien is this correct?
>>
>> cifs.ko flock()
>> - local in <= 5.4
>> - remote by default in >= 5.5
>> - local if nobrl in >= 5.5
>>
>> cifs.ko fcntl()
>> - remote by default in X.Y
>> - local if nobrl in X.Y
> 
> Correct.
> 
>> Not sure what the value(s) of X.Y actually might be.
> 
> AFAIK fcntl() was always remote by default.
> And nobrl was added in 2.6.15 (15 years ago). I wouldn't bother
> mentionning X.Y, it's already complex enough as it is.
> 
>> It seems odd that "nobrl" means "handle locking locally, and never
>> send to server". I mean, there is always byte-range locking, right?
> 
> Yes the option name can be confusing. Byte-range locking is always
> possible, but with "nobrl" it's local-only.
> 
>> Are there any other options or configurations that alter this?
> 
> I've taken another long look at the cifs.ko and samba code. There are
> many knobs that would make an accurate matrix table pretty big.

I vote for simplicity! Especially on the fcntl(2) page in question.
Totally agree on not mentioning 2.6.x in a current manpage.

> * If the mount point is done on an SMB1+UNIX Extensions
>    connection, locking becomes advisory. Unless
>    forcemandatorylock option is passed. This will eventually be
>    implemented for SMB3 posix extensions as well (I've started a
>    thread on the samba-technical mailing list).

NO SMB1 discussion! Any manpage update should not add discussion of
an obsolete nonsecure deprecated protocol, and should definitely not
passively encourage its consideration.

> * If cifs.ko can get guarantees (via oplocks or leases) that it is the
>    only user of a file, it caches read/writes but also locking
>    locally. If the lease is broke then it will send the locks.
>    The levels of caching cifs.ko can do can be changed with the cache
>    mount option.

I think this is relevant to some sort of smb(7) manpage, but is much
too detailed and subtle for a paragraph summary in fcntl(2).

To be more clear, my updated thinking is to mostly drop the details
in the closing sentence:

> The nobrl mount option (see mount.cifs(8)) turns off  fnctl(2)
>   and  flock() lock propagation to remote clients and makes flock() locks
>   advisory again.

and simply state (perhaps)

  "Remote and mandatory locking semantics may vary with SMB protocol,
   mount options and server type. See mount.cifs(8) for additional
   information."

Tom.

Re: [PATCH v4] flock.2: add CIFS details

[Aurélien Aptel]

Tom Talpey <tom@talpey.com> writes:
> and simply state (perhaps)
>
>   "Remote and mandatory locking semantics may vary with SMB protocol,
>    mount options and server type. See mount.cifs(8) for additional
>    information."

This would be the complete addition to the man page? I feel like we
should at least say it is *likely* that:
- locks will be mandatory
- flock() is emulated via fnctl() and so they interact with each other

Which are the 2 aspects that really diverges from the expected behaviour
of flock() and likely to hit people in the wild. Mentionning this will
send people trying to debug their app in the right direction.

Cheers,
-- 
Aurélien Aptel / SUSE Labs Samba Team
GPG: 1839 CB5F 9F5B FB9B AA97  8C99 03C8 A49B 521B D5D3
SUSE Software Solutions Germany GmbH, Maxfeldstr. 5, 90409 Nürnberg, DE
GF: Felix Imendörffer, Mary Higgins, Sri Rasiah HRB 247165 (AG München)

Re: [PATCH v4] flock.2: add CIFS details

[Tom Talpey]

On 3/11/2021 12:45 PM, Aurélien Aptel wrote:
> Tom Talpey <tom@talpey.com> writes:
>> and simply state (perhaps)
>>
>>    "Remote and mandatory locking semantics may vary with SMB protocol,
>>     mount options and server type. See mount.cifs(8) for additional
>>     information."
> 
> This would be the complete addition to the man page? I feel like we

Only replacing the last sentence, which I quoted earlier.

> should at least say it is *likely* that:
> - locks will be mandatory
> - flock() is emulated via fnctl() and so they interact with each other
> 
> Which are the 2 aspects that really diverges from the expected behaviour
> of flock() and likely to hit people in the wild. Mentionning this will
> send people trying to debug their app in the right direction.

Ok, and agreed. SMB lock semantics are certainly important to describe.

Tom.

Re: [PATCH v4] flock.2: add CIFS details

[Aurélien Aptel]

Ok, then I agree with your last paragraph. Here's the current version, with semantic newlines:

 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.
 
 Since Linux 5.5, flock() locks are emulated with SMB byte-range locks on the entire file.
 Similarly to NFS, this means that fcntl(2) and flock() locks interact with one another.
 Another important side-effect is that the locks are not advisory anymore:
 a write on a locked file will always fail with EACCES.
 This difference originates from the design of locks in the SMB protocol, which provides mandatory locking semantics.
 
 Remote and mandatory locking semantics may vary with SMB protocol, mount options and server type.
 See mount.cifs(8) for additional information.

Cheers,
-- 
Aurélien Aptel / SUSE Labs Samba Team
GPG: 1839 CB5F 9F5B FB9B AA97  8C99 03C8 A49B 521B D5D3
SUSE Software Solutions Germany GmbH, Maxfeldstr. 5, 90409 Nürnberg, DE
GF: Felix Imendörffer, Mary Higgins, Sri Rasiah HRB 247165 (AG München)

Re: [PATCH v4] flock.2: add CIFS details

[Pavel Shilovsky]

чт, 11 мар. 2021 г. в 14:41, Aurélien Aptel <aaptel@suse.com>:


Hi Aurelien,

>
> Ok, then I agree with your last paragraph. Here's the current version, with semantic newlines:
>
>  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.
>
>  Since Linux 5.5, flock() locks are emulated with SMB byte-range locks on the entire file.
>  Similarly to NFS, this means that fcntl(2) and flock() locks interact with one another.
>  Another important side-effect is that the locks are not advisory anymore:
>  a write on a locked file will always fail with EACCES.

It is not only about writing to a locked file. It is also about any IO
against a locked file if such a file is locked through another file
handle. Right?

--
Best regards,
Pavel Shilovsky

Re: [PATCH v4] flock.2: add CIFS details

[Aurélien Aptel]

Pavel Shilovsky <piastryyy@gmail.com> writes:
> It is not only about writing to a locked file. It is also about any IO
> against a locked file if such a file is locked through another file
> handle. Right?

Yes that was implied, the write was a simple example to illustrate. I'll
update to make it more generic:

  Another important side-effect is that the locks are not advisory anymore:
  any IO on a locked file will always fail with EACCES,
  even when done from a separate file descriptor.

If you have comments please provide direct text suggestion to save time.

Cheers,
-- 
Aurélien Aptel / SUSE Labs Samba Team
GPG: 1839 CB5F 9F5B FB9B AA97  8C99 03C8 A49B 521B D5D3
SUSE Software Solutions Germany GmbH, Maxfeldstr. 5, 90409 Nürnberg, DE
GF: Felix Imendörffer, Mary Higgins, Sri Rasiah HRB 247165 (AG München)

Re: [PATCH v4] flock.2: add CIFS details

[Pavel Shilovsky]

Sure. Thanks!

I would put more details from
https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-lockfileex
:

"""
  Another important side-effect is that the locks are not advisory anymore:
  any IO on an exclusively locked file will always fail with EACCES
  when done from a separate file descriptor; write calls on
  a file locked for shared access will fail with EACCES when done
  from any file descriptor including the one used to lock the file.
"""

Thoughts?

--
Best regards,
Pavel Shilovsky

вт, 16 мар. 2021 г. в 03:42, Aurélien Aptel <aaptel@suse.com>:
>
> Pavel Shilovsky <piastryyy@gmail.com> writes:
> > It is not only about writing to a locked file. It is also about any IO
> > against a locked file if such a file is locked through another file
> > handle. Right?
>
> Yes that was implied, the write was a simple example to illustrate. I'll
> update to make it more generic:
>
>   Another important side-effect is that the locks are not advisory anymore:
>   any IO on a locked file will always fail with EACCES,
>   even when done from a separate file descriptor.
>
> If you have comments please provide direct text suggestion to save time.
>
> Cheers,
> --
> Aurélien Aptel / SUSE Labs Samba Team
> GPG: 1839 CB5F 9F5B FB9B AA97  8C99 03C8 A49B 521B D5D3
> SUSE Software Solutions Germany GmbH, Maxfeldstr. 5, 90409 Nürnberg, DE
> GF: Felix Imendörffer, Mary Higgins, Sri Rasiah HRB 247165 (AG München)
>

Re: [PATCH v4] flock.2: add CIFS details

[Tom Talpey]

On 3/16/2021 1:39 PM, Pavel Shilovsky wrote:
> Sure. Thanks!
> 
> I would put more details from
> https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-lockfileex
> :
> 
> """
>    Another important side-effect is that the locks are not advisory anymore:
>    any IO on an exclusively locked file will always fail with EACCES
>    when done from a separate file descriptor; write calls on
>    a file locked for shared access will fail with EACCES when done
>    from any file descriptor including the one used to lock the file.
> """
> 
> Thoughts?

I think it'll be important to define what "exclusive" and "shared"
mean from a Linux/POSIX API perspective, and that will get into dragon
territory. I don't think it's a good idea to attempt that in this
manpage. It is best to leave Windows semantics, and interop with
Windows clients, out of it.

IOW, I personally prefer Aurélien's simple version for now.

Tom.

> 
> --
> Best regards,
> Pavel Shilovsky
> 
> вт, 16 мар. 2021 г. в 03:42, Aurélien Aptel <aaptel@suse.com>:
>>
>> Pavel Shilovsky <piastryyy@gmail.com> writes:
>>> It is not only about writing to a locked file. It is also about any IO
>>> against a locked file if such a file is locked through another file
>>> handle. Right?
>>
>> Yes that was implied, the write was a simple example to illustrate. I'll
>> update to make it more generic:
>>
>>    Another important side-effect is that the locks are not advisory anymore:
>>    any IO on a locked file will always fail with EACCES,
>>    even when done from a separate file descriptor.
>>
>> If you have comments please provide direct text suggestion to save time.
>>
>> Cheers,
>> --
>> Aurélien Aptel / SUSE Labs Samba Team
>> GPG: 1839 CB5F 9F5B FB9B AA97  8C99 03C8 A49B 521B D5D3
>> SUSE Software Solutions Germany GmbH, Maxfeldstr. 5, 90409 Nürnberg, DE
>> GF: Felix Imendörffer, Mary Higgins, Sri Rasiah HRB 247165 (AG München)
>>
> 

Re: [PATCH v4] flock.2: add CIFS details

[Pavel Shilovsky]

Make sense to make it simpler. Then I would just propose a minor fix -
to remove "even" on the last line because IO from the same file
descriptor is allowed.

"""
  Another important side-effect is that the locks are not advisory anymore:
  any IO on a locked file will always fail with EACCES,
  when done from a separate file descriptor.
"""
--
Best regards,
Pavel Shilovsky

вт, 16 мар. 2021 г. в 12:42, Tom Talpey <tom@talpey.com>:
>
> On 3/16/2021 1:39 PM, Pavel Shilovsky wrote:
> > Sure. Thanks!
> >
> > I would put more details from
> > https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-lockfileex
> > :
> >
> > """
> >    Another important side-effect is that the locks are not advisory anymore:
> >    any IO on an exclusively locked file will always fail with EACCES
> >    when done from a separate file descriptor; write calls on
> >    a file locked for shared access will fail with EACCES when done
> >    from any file descriptor including the one used to lock the file.
> > """
> >
> > Thoughts?
>
> I think it'll be important to define what "exclusive" and "shared"
> mean from a Linux/POSIX API perspective, and that will get into dragon
> territory. I don't think it's a good idea to attempt that in this
> manpage. It is best to leave Windows semantics, and interop with
> Windows clients, out of it.
>
> IOW, I personally prefer Aurélien's simple version for now.
>
> Tom.
>
> >
> > --
> > Best regards,
> > Pavel Shilovsky
> >
> > вт, 16 мар. 2021 г. в 03:42, Aurélien Aptel <aaptel@suse.com>:
> >>
> >> Pavel Shilovsky <piastryyy@gmail.com> writes:
> >>> It is not only about writing to a locked file. It is also about any IO
> >>> against a locked file if such a file is locked through another file
> >>> handle. Right?
> >>
> >> Yes that was implied, the write was a simple example to illustrate. I'll
> >> update to make it more generic:
> >>
> >>    Another important side-effect is that the locks are not advisory anymore:
> >>    any IO on a locked file will always fail with EACCES,
> >>    even when done from a separate file descriptor.
> >>
> >> If you have comments please provide direct text suggestion to save time.
> >>
> >> Cheers,
> >> --
> >> Aurélien Aptel / SUSE Labs Samba Team
> >> GPG: 1839 CB5F 9F5B FB9B AA97  8C99 03C8 A49B 521B D5D3
> >> SUSE Software Solutions Germany GmbH, Maxfeldstr. 5, 90409 Nürnberg, DE
> >> GF: Felix Imendörffer, Mary Higgins, Sri Rasiah HRB 247165 (AG München)
> >>
> >

[PATCH v5] flock.2: add CIFS details

[Aurélien Aptel]

From: Aurelien Aptel <aaptel@suse.com>

CIFS flock() locks behave differently than the standard. Give overview
of those differences.

Here is the rendered text:

CIFS details
  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.

  Since Linux 5.5, flock() locks are emulated with SMB  byte-range  locks
  on  the  entire  file.   Similarly to NFS, this means that fcntl(2) and
  flock() locks interact with one another.  Another important side-effect
  is  that  the  locks  are not advisory anymore: any IO on a locked file
  will always fail with EACCES when done from a separate file descriptor.
  This  difference  originates from the design of locks in the SMB proto-
  col, which provides mandatory locking semantics.

  Remote and mandatory locking semantics  may  vary  with  SMB  protocol,
  mount options and server type.  See mount.cifs(8) for additional infor-
  mation.

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

diff --git a/man2/flock.2 b/man2/flock.2
index 328377365..61822c9bc 100644
--- a/man2/flock.2
+++ b/man2/flock.2
@@ -239,6 +239,31 @@ see the discussion of the
 .I "local_lock"
 option in
 .BR nfs (5).
+.SS CIFS details
+In Linux kernels up to 5.4,
+.BR 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 ()
+locks 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.
+Another important side-effect is that the locks are not advisory anymore:
+any IO on a locked file will always fail with
+.BR EACCES
+when done from a separate file descriptor.
+This difference originates from the design of locks in the SMB protocol,
+which provides mandatory locking semantics.
+.PP
+Remote and mandatory locking semantics may vary with SMB protocol, mount options and server type.
+See
+.BR mount.cifs (8)
+for additional information.
 .SH SEE ALSO
 .BR flock (1),
 .BR close (2),
-- 
2.30.0

Re: [PATCH v5] flock.2: add CIFS details

[Aurélien Aptel]

Friendly ping to the man page maintainers

Cheers,
-- 
Aurélien Aptel / SUSE Labs Samba Team
GPG: 1839 CB5F 9F5B FB9B AA97  8C99 03C8 A49B 521B D5D3
SUSE Software Solutions Germany GmbH, Maxfeldstr. 5, 90409 Nürnberg, DE
GF: Felix Imendörffer, Mary Higgins, Sri Rasiah HRB 247165 (AG München)

Re: [PATCH v5] flock.2: add CIFS details

[Alejandro Colomar (man-pages)]

Hello Aurélien,

On 4/9/21 2:13 PM, Aurélien Aptel wrote:
> 
> Friendly ping to the man page maintainers
> 
> Cheers,
> 

Sorry for the delay and thanks for the ping!
Patch applied.

Cheers,

Alex


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH v4] flock.2: add CIFS details

[Matthew Wilcox]

On Thu, Mar 04, 2021 at 10:50:26AM +0100, Aurélien Aptel wrote:
>   mantics. The nobrl mount option (see mount.cifs(8)) turns off  fnctl(2)

s/fnctl/fcntl/

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

[Tom Talpey]

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,
> 

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

[Aurélien Aptel]

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,
-- 
Aurélien Aptel / SUSE Labs Samba Team
GPG: 1839 CB5F 9F5B FB9B AA97  8C99 03C8 A49B 521B D5D3
SUSE Software Solutions Germany GmbH, Maxfeldstr. 5, 90409 Nürnberg, DE
GF: Felix Imendörffer, Mary Higgins, Sri Rasiah HRB 247165 (AG München)

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

[Tom Talpey]

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.