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/
