man/man2/landlock_create_ruleset.2: Clarify default Landlock ABI

PATCH Applied Günther Noack 2 participants 7 messages Apr 13 – Apr 20 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore

Share & tools

lore

Günther Noack

author

2026-04-13 19:35 UTC #0 lore raw

PATCH 1/4 man/man2/landlock_create_ruleset.2: Clarify default Landlock ABI

The documented Landlock features are not all available since ABI v1. We are mentioning it explicitly when features require specific Landlock ABI versions.

Signed-off-by Günther Noack <[email protected]>

---
 man/man2/landlock_create_ruleset.2 | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

man/man2/landlock_create_ruleset.2 +4 -2

index 5425ed59878b..7bca831cbd65 100644
@@ -125,8 +125,10 @@ is 0, then the returned value is the highest supported Landlock ABI version
 This version can be used for a best-effort security approach,
 which is encouraged when user space is not pinned to a specific kernel
 version.
-All features documented in these man pages are available with the version
-1.
+.IP
+Unless noted otherwise,
+all features documented in these man pages are available with the
+version 1.
 .SH RETURN VALUE
 On success,
 .BR landlock_create_ruleset ()

Signature · 1 line

2.53.0

Günther Noack

author

2026-04-13 19:37 UTC #1 lore raw

PATCH 2/4 man/man[27]/{landlock_create_ruleset.2,landlock.7}: Document LANDLOCK_CREATE_RULESET_ERRATA

Document 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.

Signed-off-by Günther Noack <[email protected]>

---
 man/man2/landlock_create_ruleset.2 | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

man/man2/landlock_create_ruleset.2 +24 -1

index 7bca831cbd65..90d0341d2682 100644
@@ -129,11 +129,34 @@ version.
 Unless noted otherwise,
 all features documented in these man pages are available with the
 version 1.
+.TP
+.B LANDLOCK_CREATE_RULESET_ERRATA
+If
+.I attr
+is NULL and
+.I size
+is 0, then the returned value is 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.
+The fixes generally make Landlock less restrictive or more correct,
+not more restrictive.
+.IP
+This flag is available on Linux versions where errata were fixed.
 .SH RETURN VALUE
 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 .
 On error,

Signature · 1 line

2.53.0

Alejandro Colomar

maintainer

2026-04-19 20:11 UTC #2 lore raw

Re: [PATCH 2/4] man/man[27]/{landlock_create_ruleset.2,landlock.7}: Document LANDLOCK_CREATE_RULESET_ERRATA

Hi Günther,

Quoted 19 lines · Günther Noack

Document 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.
Signed-off-by Günther Noack <[email protected]>
---
 man/man2/landlock_create_ruleset.2 | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)
man/man2/landlock_create_ruleset.2 +0 -0
index 7bca831cbd65..90d0341d2682 100644

man/man2/landlock_create_ruleset.2 version. · line 138

Quoted 10 lines

man/man2/landlock_create_ruleset.2 +7 -0

@@ -129,11 +129,34 @@ version.
 Unless noted otherwise,
 all features documented in these man pages are available with the
 version 1.
+.TP
+.B LANDLOCK_CREATE_RULESET_ERRATA
+If
+.I attr
+is NULL and
+.I size
+is 0,

You don't say what happens otherwise. Is it an error? If so, you should say so; or rather, specify that they must be NULL and 0, instead of having a condition.

man/man2/landlock_create_ruleset.2 version. · line 142

Quoted 5 lines

then the returned value is a bitmask of fixed issues
man/man2/landlock_create_ruleset.2 +4 -0
+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.

Are those bits documented anywhere?

Quoted 2 lines

+.IP
+In addition to ABI versions, Landlock's errata mechanism tracks fixes

Please use semantic newlines.

man/man2/landlock_create_ruleset.2 version. · line 146

Quoted 2 lines

man/man2/landlock_create_ruleset.2 +2 -0

+for issues that may affect backwards compatibility
+or require userspace awareness.

I'd reflow the above as:

In addition to ABI versions,
Landlock's errata mechanism
tracks fixes for issues that
may affect backwards compatibility
or require user-space awareness.

man/man2/landlock_create_ruleset.2 version. · line 151

Quoted 6 lines

+.IP

man/man2/landlock_create_ruleset.2 +4 -0

+Only check errata if your application specifically relies on behavior
+that changed due to the fix.
 
+The fixes generally make Landlock less restrictive or more correct,
+not more restrictive.

This sentence seems inconsistent. Is more correct the same as less restrictive? Otherwise, more correct could imply more restrictive in some cases. If more correct *always* means less restrictive, it should be parenthesized. If it doesn't, then I'm not convinced by the sentence.

Quoted 2 lines

+.IP
+This flag is available on Linux versions where errata were fixed.

Is it possible that future Linux versions don't have any errata that were fixed? If so, does this mean that it won't be available then?

Have a lovely night!
Alex

Quoted 14 lines

.SH RETURN VALUE
On success,
.BR landlock_create_ruleset ()
returns a new Landlock ruleset file descriptor,
man/man2/landlock_create_ruleset.2 +2 -1
-or a Landlock ABI version,
+a Landlock ABI version,
+or a Landlock errata bitmask,
 according to
 .IR flags .
 On error,
Signature · 1 line
2.53.0

Signature · 1 line

<https://www.alejandro-colomar.es>

Günther Noack

author

2026-04-20 22:25 UTC #3 lore raw

Re: [PATCH 2/4] man/man[27]/{landlock_create_ruleset.2,landlock.7}: Document LANDLOCK_CREATE_RULESET_ERRATA

Hello Alejandro,

Quoted 26 lines · Alejandro Colomar

Quoted 25 lines · Günther Noack
Document 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.
Signed-off-by Günther Noack <[email protected]>
---
 man/man2/landlock_create_ruleset.2 | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)
man/man2/landlock_create_ruleset.2 +3 -0
index 7bca831cbd65..90d0341d2682 100644
@@ -129,11 +129,34 @@ version.
 Unless noted otherwise,
 all features documented in these man pages are available with the
 version 1.
+.TP
+.B LANDLOCK_CREATE_RULESET_ERRATA
+If

Quoted 8 lines

man/man2/landlock_create_ruleset.2 version.
Quoted 4 lines
man/man2/landlock_create_ruleset.2 +4 -0
+.I attr
+is NULL and
+.I size
+is 0,
You don't say what happens otherwise. Is it an error? If so, you should say so; or rather, specify that they must be NULL and 0, instead of having a condition.

Yes, good point that the explanation is a bit incomplete.

The "If attr is NULL and size is 0, ..." formulation is found in the man pages only and I copied it from LANDLOCK_CREATE_RULESET_VERSION which started the same way. Let me switch to a slightly clearer format where the docs for LANDLOCK_CREATE_RULESET_VERSION and LANDLOCK_CREATE_RULESET_ERRATA just explain what is returned and I explain below these two tagged paragraphs that they both require attr=NULL and size=0. I'll use the same formulation as in the kernel docs [1]:

If LANDLOCK_CREATE_RULESET_VERSION or LANDLOCK_CREATE_RULESET_ERRATA is set, then attr must be NULL and size must be 0.

(Done.)

Quoted 7 lines

man/man2/landlock_create_ruleset.2 version. · line 142
Quoted 5 lines
then the returned value is a bitmask of fixed issues
man/man2/landlock_create_ruleset.2 +4 -0
+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.
Are those bits documented anywhere?

Yes, in https://docs.kernel.org/userspace-api/landlock.html#landlock-errata.

It feels a bit awkward to copy these explanations into the manpage, as they are lengthy, and because they are errata, any user interested in them should ideally consult the most up to date version in the kernel docs. I'll add a link to it.

Quoted 10 lines

Quoted 2 lines
+.IP
+In addition to ABI versions, Landlock's errata mechanism tracks fixes
Please use semantic newlines.
man/man2/landlock_create_ruleset.2 version. · line 146
Quoted 2 lines
man/man2/landlock_create_ruleset.2 +2 -0
+for issues that may affect backwards compatibility
+or require userspace awareness.
I'd reflow the above as:

Quoted 5 lines

In addition to ABI versions,
Landlock's errata mechanism
tracks fixes for issues that
may affect backwards compatibility
or require user-space awareness.

Done.

Quoted 4 lines

Quoted 3 lines
+.IP
man/man2/landlock_create_ruleset.2 +2 -0
+Only check errata if your application specifically relies on behavior
+that changed due to the fix.

Quoted 8 lines

man/man2/landlock_create_ruleset.2 version. · line 151
Quoted 2 lines
man/man2/landlock_create_ruleset.2 +2 -0
+The fixes generally make Landlock less restrictive or more correct,
+not more restrictive.
This sentence seems inconsistent. Is more correct the same as less restrictive? Otherwise, more correct could imply more restrictive in some cases. If more correct *always* means less restrictive, it should be parenthesized. If it doesn't, then I'm not convinced by the sentence.

I copied the sentence from
https://docs.kernel.org/userspace-api/landlock.html#landlock-errata

For Landlock, ABI backwards compatibility means two things:

* Existing programs keep working (that means that the interpretation of the enforced Landlock policies can not get stricter)
* When a process enforces a policy, the policy still needs to enforce what the policy meant to enforce.

I can see that the phrasing of this sentence is a bit confusing. Let me drop it.

Quoted 6 lines

Quoted 3 lines
+.IP
+This flag is available on Linux versions where errata were fixed.
Is it possible that future Linux versions don't have any errata that were fixed? If so, does this mean that it won't be available then?

No, the errata numbers are stable over time and have to accumulate, as they too are part of the ABI. When we have an erratum, it has generally been backported to all stable releases where it applied. As we have had erratums that went all the way back to the oldest Landlock-enabled stable release, all Landlock-enabled kernels in their latest bugfix versions have this flag and will return some subset of the existing errata.

I added a short sentence to explain that this can be expected in all newer stable kernel bugfix releases where Landlock is supported.

I'll send a V2.

Thanks for the review!
–Günther

[1] https://docs.kernel.org/userspace-api/landlock.html#c.sys_landlock_create_ruleset

Günther Noack

author

2026-04-13 19:37 UTC #4 lore raw

PATCH 3/4 man/man[27]/{landlock_restrict_self.2,landlock.7}: Document LANDLOCK_RESTRICT_SELF_TSYNC (ABI v8)

In reply to Günther Noack

Document 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).

Signed-off-by Günther Noack <[email protected]>

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

index 9e80a40ee4a4..1265ea2feb91 100644
@@ -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

index bcf06ea30ad4..06910ccab5b1 100644
@@ -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

Günther Noack

author

2026-04-13 19:37 UTC #5 lore raw

PATCH 4/4 man/man2/landlock_restrict_self.2: Document ABI requirement for logging flags

In reply to 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]>

---
 man/man2/landlock_restrict_self.2 | 2 ++
 1 file changed, 2 insertions(+)

man/man2/landlock_restrict_self.2 +2 -0

index 1265ea2feb91..99288b582fea 100644
@@ -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

maintainer Applied

2026-04-19 20:02 UTC #6 lore raw

In reply to Günther Noack

Hi Günther,

Quoted 5 lines · Günther Noack

The documented Landlock features are not all available since ABI v1. We are mentioning it explicitly when features require specific Landlock ABI versions.
Signed-off-by Günther Noack <[email protected]>

I've applied this patch. Thanks!

Have a lovely night!
Alex

Quoted 25 lines

---
 man/man2/landlock_create_ruleset.2 | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

man/man2/landlock_create_ruleset.2 +4 -2

index 5425ed59878b..7bca831cbd65 100644
@@ -125,8 +125,10 @@ is 0, then the returned value is the highest supported Landlock ABI version
 This version can be used for a best-effort security approach,
 which is encouraged when user space is not pinned to a specific kernel
 version.
-All features documented in these man pages are available with the version
-1.
+.IP
+Unless noted otherwise,
+all features documented in these man pages are available with the
+version 1.
 .SH RETURN VALUE
 On success,
 .BR landlock_create_ruleset ()

Signature · 1 line

2.53.0

Signature · 1 line

<https://www.alejandro-colomar.es>