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

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

[Günther Noack]

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

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

[Mickaël Salaün]

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/

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

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1233 bytes --]

Hello Günther!

On 3/5/23 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

I prefer if examples assume latest and greatest kernel.

Examples of how to support old kernels would be good in complete
tutorials, but over-complicate a short example.

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Günther Noack]

Hello Alex!

On Fri, Mar 10, 2023 at 01:31:22AM +0100, Alejandro Colomar wrote:
> On 3/5/23 11:24, Günther Noack wrote:
> > I feel that implementing the full generic "best effort" fallback logic
> > would complicate the example too much:
> >
> >  [...]
> 
> I prefer if examples assume latest and greatest kernel.
> 
> Examples of how to support old kernels would be good in complete
> tutorials, but over-complicate a short example.

Thank you for the review!

Fair enough, let's use the variant then where we just assume the
newest kernel -- that is the code which we already have right now, in
fact. I'll add a small remark to point out the place where people
might want to handle the backwards compatibility with older kernels.

–-Günther