Update Landlock docs to Landlock ABI v8
v3 cover Update Landlock docs to Landlock ABI v8
Hello!
Thanks for the review, Alejandro! Here's the third round of the patch set to bring the Landlock manpages up to speed with Landlock ABI v8.
Change Log
==========
v3:
- split the size/attr clarifications from the "errata" patch into a separate commit
- earlier patch from v2 about the "scoped" EINVAL error was already merged
v2:
- landlock_create_ruleset.2: added a tiny patch to add a missing mention of "scoped" in the errors list.
- landlock_create_ruleset.2: various reformulations for errata
- earlier patch from v1 about the default ABI version assumption was already merged (thanks!)
Günther Noack (4):
man/man2/landlock_create_ruleset.2: Clarify attr and size constraints man/man[27]/{landlock_create_ruleset.2,landlock.7}: Document
LANDLOCK_CREATE_RULESET_ERRATA
man/man[27]/{landlock_restrict_self.2,landlock.7}: Document
LANDLOCK_RESTRICT_SELF_TSYNC (ABI v8)
man/man2/landlock_restrict_self.2: Document ABI requirement for
logging flags
man/man2/landlock_create_ruleset.2 | 57 ++++++++++++++++++++++++++---- man/man2/landlock_restrict_self.2 | 20 +++++++++++ man/man7/landlock.7 | 2 ++ 3 files changed, 73 insertions(+), 6 deletions(-)
Signature · 1 line
2.53.0
PATCH v3 1/4 man/man2/landlock_create_ruleset.2: Clarify attr and size constraints
When used with special flags like LANDLOCK_CREATE_RULESET_VERSION, attr must be NULL and size must be 0.
--- man/man2/landlock_create_ruleset.2 | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-)
man/man2/landlock_create_ruleset.2 +18 -5
@@ -116,11 +116,7 @@ Otherwise, can be set to: .TP .B LANDLOCK_CREATE_RULESET_VERSION -If -.I attr -is NULL and -.I size -is 0, then the returned value is the highest supported Landlock ABI version +Return the highest supported Landlock ABI version (starting at 1). This version can be used for a best-effort security approach, which is encouraged when user space is not pinned to a specific kernel
@@ -129,6 +125,15 @@ version. Unless noted otherwise, all features documented in these manual pages are available with the version 1. +.P +If +.B LANDLOCK_CREATE_RULESET_VERSION +is set, +then +.I attr +must be NULL and +.I size +must be 0. .SH RETURN VALUE On success, .BR landlock_create_ruleset ()
@@ -159,6 +164,14 @@ Unknown or unknown access, or unknown scope, or too small .IR size . .TP +.B EINVAL +Non-NULL +.I attr +or non-zero +.I size +in combination with +.BR LANDLOCK_CREATE_RULESET_VERSION . +.TP .B ENOMSG Empty accesses (i.e., .I attr
Signature · 1 line
2.53.0
PATCH v3 2/4 man/man[27]/{landlock_create_ruleset.2,landlock.7}: Document LANDLOCK_CREATE_RULESET_ERRATA
In reply to Günther NoackDocument the LANDLOCK_CREATE_RULESET_ERRATA flag, which returns a bitmask of fixed issues for the current Landlock ABI version.
This mechanism was introduced in Linux 6.15, but backported to all older kernel releases where these errata fixes were backported to. On official Linux kernel releases, if landlock_create_ruleset() with LANDLOCK_CREATE_RULESET_ERRATA returns an error, this is equivalent to the case where none of the known errata have been fixed.
--- man/man2/landlock_create_ruleset.2 | 36 ++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-)
man/man2/landlock_create_ruleset.2 +34 -2
@@ -125,9 +125,38 @@ version. Unless noted otherwise, all features documented in these manual pages are available with the version 1. +.TP +.B LANDLOCK_CREATE_RULESET_ERRATA +Return a bitmask of fixed issues +for the current Landlock ABI version. +If bit N is set (i.e., +.IR "errata & (1 << (N - 1))" ), +then erratum N has been fixed in the running kernel. +.IP +In addition to ABI versions, +Landlock's errata mechanism +tracks fixes for issues that +may affect backwards compatibility +or require userspace awareness. +.IP +Only check errata if your application specifically relies on behavior +that changed due to the fix. +.IP +The full list of Landlock errata is available at +.UR https:\://docs.kernel.org/userspace\-api/landlock.html#landlock\-errata +.UE . +.IP +This flag is available on all Linux versions +where Landlock errata were fixed. +This specifically includes +all newest bugfix releases +of stable kernels +where Landlock is supported. .P If .B LANDLOCK_CREATE_RULESET_VERSION +or +.B LANDLOCK_CREATE_RULESET_ERRATA is set, then .I attr
@@ -138,7 +167,8 @@ must be 0. On success, .BR landlock_create_ruleset () returns a new Landlock ruleset file descriptor, -or a Landlock ABI version, +a Landlock ABI version, +or a Landlock errata bitmask, according to .IR flags . .P
@@ -170,7 +200,9 @@ Non-NULL or non-zero .I size in combination with -.BR LANDLOCK_CREATE_RULESET_VERSION . +.B LANDLOCK_CREATE_RULESET_VERSION +or +.BR LANDLOCK_CREATE_RULESET_ERRATA . .TP .B ENOMSG Empty accesses (i.e.,
Signature · 1 line
2.53.0
PATCH v3 3/4 man/man[27]/{landlock_restrict_self.2,landlock.7}: Document LANDLOCK_RESTRICT_SELF_TSYNC (ABI v8)
In reply to Günther NoackDocument the new LANDLOCK_RESTRICT_SELF_TSYNC flag, which applies the Landlock configuration atomically to all threads of the calling process.
Available since Linux 7.0 (Landlock ABI version 8).
--- man/man2/landlock_restrict_self.2 | 18 ++++++++++++++++++ man/man7/landlock.7 | 2 ++ 2 files changed, 20 insertions(+)
man/man2/landlock_restrict_self.2 +18 -0
@@ -133,6 +133,24 @@ It can also be used with a .I ruleset_fd value of \-1 to mute subdomain logs without creating a domain. +.P +The following flag supports policy enforcement in multithreaded processes: +.TP +.B LANDLOCK_RESTRICT_SELF_TSYNC +Applies the new Landlock configuration atomically +to all threads of the current process, +including the Landlock domain and logging configuration. +This overrides the Landlock configuration of sibling threads, +irrespective of previously established Landlock domains +and logging configurations on those threads. +.IP +If the calling thread is running with +.IR no_new_privs , +this operation enables +.I no_new_privs +on the sibling threads as well. +.IP +This flag is available since Landlock ABI version 8. .SH RETURN VALUE On success, .BR landlock_restrict_self ()
man/man7/landlock.7 +2 -0
@@ -476,6 +476,8 @@ _ _ _ 7 6.15 LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF \^ \^ LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON \^ \^ LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF +_ _ _ +8 7.0 LANDLOCK_RESTRICT_SELF_TSYNC .TE .P Users should use the Landlock ABI version rather than the kernel version
Signature · 1 line
2.53.0
PATCH v3 4/4 man/man2/landlock_restrict_self.2: Document ABI requirement for logging flags
In reply to Günther NoackMissed this on the earlier commit; we should mention since which Landlock version these flags are available. Users can correlate this with the Landlock ABI version as it can be queried through landlock_create_ruleset(2).
--- man/man2/landlock_restrict_self.2 | 2 ++ 1 file changed, 2 insertions(+)
man/man2/landlock_restrict_self.2 +2 -0
@@ -134,6 +134,8 @@ It can also be used with a value of \-1 to mute subdomain logs without creating a domain. .P +These flags are available since Landlock ABI version 7. +.P The following flag supports policy enforcement in multithreaded processes: .TP .B LANDLOCK_RESTRICT_SELF_TSYNC
Signature · 1 line
2.53.0
Alejandro Colomar
maintainerRe: [PATCH v3 4/4] man/man2/landlock_restrict_self.2: Document ABI requirement for logging flags
Hi Günther,
Quoted 6 lines · Günther Noack
Missed this on the earlier commit; we should mention since which Landlock version these flags are available. Users can correlate this with the Landlock ABI version as it can be queried through
landlock_create_ruleset(2).Signed-off-by Günther Noack <[email protected]>
I've applied patches 1,2,3. I've amended them significantly, and this one doesn't apply anymore. Would you mind rebasing and using a format similar to the one I used when amending patch 3?
Have a lovely night!
Alex
Quoted 20 lines
--- man/man2/landlock_restrict_self.2 | 2 ++ 1 file changed, 2 insertions(+)man/man2/landlock_restrict_self.2 +2
-0@@ -134,6 +134,8 @@ It can also be used with a value of \-1 to mute subdomain logs without creating a domain. .P +These flags are available since Landlock ABI version 7. +.P The following flag supports policy enforcement in multithreaded processes: .TP .B LANDLOCK_RESTRICT_SELF_TSYNCSignature · 1 line
2.53.0
Signature · 1 line
<https://www.alejandro-colomar.es>