Re: [PATCH v3 1/2] landlock.7: Document Landlock ABI v2 (file reparenting; Linux 5.19)

Thanks Günther. I agree with this approach. Let's start with a 
common-enough example, and then point to exceptions. Targeting common 
(and simple) utilities at first sounds reasonable.


On 05/03/2023 11:24, Günther Noack wrote:
> +landlock mailing list (feeback welcome)
> 
> Hello!
> 
> On Sat, Mar 04, 2023 at 06:16:06PM +0100, Günther Noack wrote:
>> * Add LANDLOCK_ACCESS_FS_REFER to the code example.
> 
> To follow up on the discussion on the man page update v1 [1] -- let me
> make a constructive proposal for a simpler code example for "best
> effort" fallback in the man page.
> 
> I feel that implementing the full generic "best effort" fallback logic
> would complicate the example too much:
> 
>   (a) examples that try to demonstrate too many things at once
>       tend to become confusing to the reader
>   (b) there are readers to whom the full example might not matter:
>       - readers who know what kernel their software runs on
>       - readers in the future or on cutting-edge distributions
>         who can assume that their kernel is likely to be fresh enough
> 
> The main complication with the "best effort" logic is really just that
> the "refer" right requires a different fallback logic, and this is
> easy to overlook (has happened in multiple instances already).
> 
> I believe that many potential Landlock users, especially smaller
> tools, probably do not need to reparent files ("refer").
> 
> We can group the existing Landlock use cases like this:
> 
> Case 1: Callers who know they *do not* need to reparent files
>          can skip the "refer" complications.
> 
> Case 2: Callers who know they *do* need to reparent files
>          need to fall back to no-op if the kernel only suppports ABI v1,
>          as reparenting files is always forbidden with ABI v1.
> 
> Case 3: Callers who *sometimes do and sometimes don't* reparent files
>          are the only ones where it's harder to implement.
> 
> I've put the required for code cases 1, 2, and 3 on my weblog at [2]
> (skip to the "Implementation" section).
> 
> The complicated case 3 is what we need in the Go and Rust helper
> libraries for Landlock, but it should hopefully not be needed for
> most Landlock users who use it directly from C.
> 
> 
> **This is how I think we should describe it in the man page**:
> 
>    * Define the backwards compatibility table.
>    * Implement fallback logic for programs
>      which do *not* need to reparent files.
>    * Call it out prominently that the fallback code is different
>      if the program needs file reparenting, and explain that separately,
>      in the man page or elsewhere.
> 
> I believe this should cover the use cases for a large chunk of simple
> Unix tools, and I would like to encourage the use of Landlock in
> these.  Readers should not have to adapt the example code to work in
> their program.
> 
> Let me know what you think!
> –Günther
> 
> [1] https://lore.kernel.org/linux-man/Y%2FcvfmEM1XEL%2FTPz@galopp/
> [2] https://blog.gnoack.org/post/landlock-best-effort/