[PATCH v3] landlock: Clarify documentation for the LANDLOCK_ACCESS_FS_REFER right

[Günther Noack]

On Fri, Feb 17, 2023 at 08:28:41PM +0100, Mickaël Salaün wrote:
> On 16/02/2023 21:07, Günther Noack wrote:
> > Clarify the "refer" documentation by splitting up a big paragraph of text.
> > 
> > - Call out specifically that the denial by default applies to ABI v1 as well.
> > - Turn the three additional constraints for link/rename operations
> >    into bullet points, to give it more structure.
> > 
> > Includes wording and semantics corrections by Mickaël Salaün.
> 
> No need to add this line, It's part of the maintainer job. ;)

OK, removed for V4.

> Some of my suggestions are about style, so feel free to ignore them if you
> think the original is better. Anyway, I'm not a native english speaker
> either, so there are good chances I'm not correct on some suggestions. What
> about that?:
> 
> This is the only access right implicitly handled by any ruleset, even if
> this right is not specified at ruleset creation time. Reparenting files will
> then always be denied by default. Given that %LANDLOCK_ACCESS_FS_REFER is
> available since the second Landlock ABI version, using the first Landlock
> ABI version will always forbid file reparenting.
> 
> For these kind of link or rename actions to be possible, one or two rules
> must explicitly allow %LANDLOCK_ACCESS_FS_REFER on the source and the
> destination hierarchies. In addition, the following constraints must be met:

I reworded it again, it's meeting somewhere in the middle I hope. It
should be a bit better now. (Sending another version.)

Documentation is hard... it's difficult to find an objective best wording.

–-Günther