[PATCH 0/3] landlock: Document audit logging

[PATCH 0/3] landlock: Document audit logging

[Günther Noack]

Hello!

This brings the Landlock man pages up to speed with Landlock's audit
logging support (introduced in March last year, about a year ago).

–Günther

Günther Noack (3):
  man/man2/landlock*.2: Reorder errors alphabetically
  man/man2/landlock_create_ruleset.2: Document scoped field in struct
    landlock_ruleset_attr (ABI v6)
  man/man2/landlock_restrict_self.2, man/man7/landlock.7: Document audit
    logging (ABI v7)

 man/man2/landlock_add_rule.2       | 38 ++++++-------
 man/man2/landlock_create_ruleset.2 | 26 +++++----
 man/man2/landlock_restrict_self.2  | 87 +++++++++++++++++++++++++-----
 man/man7/landlock.7                |  6 ++-
 4 files changed, 116 insertions(+), 41 deletions(-)

-- 
2.53.0

[PATCH 1/3] man/man2/landlock*.2: Reorder errors alphabetically

[Günther Noack]

Reorder lists of error codes alphabetically, in line with man-pages(7).

Cc: Mickaël Salaün <mic@digikod.net>
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---
 man/man2/landlock_add_rule.2       | 38 +++++++++++++++---------------
 man/man2/landlock_create_ruleset.2 | 18 +++++++-------
 man/man2/landlock_restrict_self.2  | 20 ++++++++--------
 3 files changed, 38 insertions(+), 38 deletions(-)

diff --git a/man/man2/landlock_add_rule.2 b/man/man2/landlock_add_rule.2
index 108364528830..48d7d3b25c9e 100644
--- a/man/man2/landlock_add_rule.2
+++ b/man/man2/landlock_add_rule.2
@@ -139,8 +139,23 @@ is
 .BR LANDLOCK_RULE_NET_PORT ,
 but TCP is not supported by the running kernel.
 .TP
-.B EOPNOTSUPP
-Landlock is supported by the kernel but disabled at boot time.
+.B EBADF
+.I ruleset_fd
+is not a file descriptor for the current thread,
+or a member of
+.I rule_attr
+is not a file descriptor as expected.
+.TP
+.B EBADFD
+.I ruleset_fd
+is not a ruleset file descriptor,
+or a member of
+.I rule_attr
+is not the expected file descriptor type.
+.TP
+.B EFAULT
+.I rule_attr
+was not a valid address.
 .TP
 .B EINVAL
 .I flags
@@ -171,27 +186,12 @@ Empty accesses (i.e.,
 .I rule_attr\->allowed_access
 is 0).
 .TP
-.B EBADF
-.I ruleset_fd
-is not a file descriptor for the current thread,
-or a member of
-.I rule_attr
-is not a file descriptor as expected.
-.TP
-.B EBADFD
-.I ruleset_fd
-is not a ruleset file descriptor,
-or a member of
-.I rule_attr
-is not the expected file descriptor type.
+.B EOPNOTSUPP
+Landlock is supported by the kernel but disabled at boot time.
 .TP
 .B EPERM
 .I ruleset_fd
 has no write access to the underlying ruleset.
-.TP
-.B EFAULT
-.I rule_attr
-was not a valid address.
 .SH STANDARDS
 Linux.
 .SH HISTORY
diff --git a/man/man2/landlock_create_ruleset.2 b/man/man2/landlock_create_ruleset.2
index ae5c89f5354f..8cffd8c770fa 100644
--- a/man/man2/landlock_create_ruleset.2
+++ b/man/man2/landlock_create_ruleset.2
@@ -134,15 +134,6 @@ is set to indicate the error.
 .BR landlock_create_ruleset ()
 can fail for the following reasons:
 .TP
-.B EOPNOTSUPP
-Landlock is supported by the kernel but disabled at boot time.
-.TP
-.B EINVAL
-Unknown
-.IR flags ,
-or unknown access, or too small
-.IR size .
-.TP
 .B E2BIG
 .I size
 is too big.
@@ -151,10 +142,19 @@ is too big.
 .I attr
 was not a valid address.
 .TP
+.B EINVAL
+Unknown
+.IR flags ,
+or unknown access, or too small
+.IR size .
+.TP
 .B ENOMSG
 Empty accesses (i.e.,
 .I attr
 did not specify any access rights to restrict).
+.TP
+.B EOPNOTSUPP
+Landlock is supported by the kernel but disabled at boot time.
 .SH STANDARDS
 Linux.
 .SH HISTORY
diff --git a/man/man2/landlock_restrict_self.2 b/man/man2/landlock_restrict_self.2
index 43fc8c6efcc7..530ef9a4cd25 100644
--- a/man/man2/landlock_restrict_self.2
+++ b/man/man2/landlock_restrict_self.2
@@ -82,12 +82,9 @@ is set to indicate the error.
 .BR landlock_restrict_self ()
 can fail for the following reasons:
 .TP
-.B EOPNOTSUPP
-Landlock is supported by the kernel but disabled at boot time.
-.TP
-.B EINVAL
-.I flags
-is not 0.
+.B E2BIG
+The maximum number of composed rulesets is reached for the calling thread.
+This limit is currently 64.
 .TP
 .B EBADF
 .I ruleset_fd
@@ -97,6 +94,13 @@ is not a file descriptor for the current thread.
 .I ruleset_fd
 is not a ruleset file descriptor.
 .TP
+.B EINVAL
+Invalid value in
+.IR flags .
+.TP
+.B EOPNOTSUPP
+Landlock is supported by the kernel but disabled at boot time.
+.TP
 .B EPERM
 .I ruleset_fd
 has no read access to the underlying ruleset,
@@ -105,10 +109,6 @@ or the calling thread is not running with
 or it doesn't have the
 .B CAP_SYS_ADMIN
 in its user namespace.
-.TP
-.B E2BIG
-The maximum number of composed rulesets is reached for the calling thread.
-This limit is currently 64.
 .SH STANDARDS
 Linux.
 .SH HISTORY
-- 
2.53.0

[PATCH 2/3] man/man2/landlock_create_ruleset.2: Document scoped field in struct landlock_ruleset_attr (ABI v6)

[Günther Noack]

Add the missing scoped field to the struct landlock_ruleset_attr
definition, and document it as a bitmask of scope flags.

Available since Linux 6.12 (Landlock ABI version 6).

Cc: Tahera Fahimi <fahimitahera@gmail.com>
Cc: Mickaël Salaün <mic@digikod.net>
Fixes: 5a89b5bd (2025-03-06; "man/man7/landlock.7: Document IPC scoping (Landlock ABI v6)")
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---
 man/man2/landlock_create_ruleset.2 | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/man/man2/landlock_create_ruleset.2 b/man/man2/landlock_create_ruleset.2
index 8cffd8c770fa..5425ed59878b 100644
--- a/man/man2/landlock_create_ruleset.2
+++ b/man/man2/landlock_create_ruleset.2
@@ -44,6 +44,7 @@ It points to the following structure:
 struct landlock_ruleset_attr {
     __u64 handled_access_fs;
     __u64 handled_access_net;
+    __u64 scoped;
 };
 .EE
 .in
@@ -62,6 +63,13 @@ is a bitmask of handled network actions
 in
 .BR landlock (7)).
 .IP
+.I scoped
+is a bitmask of scope flags
+(see
+.B Scope flags
+in
+.BR landlock (7)).
+.IP
 This structure defines a set of
 .IR "handled access rights" ,
 a set of actions on different object types,
-- 
2.53.0

[PATCH 3/3] man/man2/landlock_restrict_self.2, man/man7/landlock.7: Document audit logging (ABI v7)

[Günther Noack]

* Document the flags LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF,
  LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF and
  LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON.
* List these flags in the compatibility table in landlock.7

The documentation text is copied from the kernel documentation,
originally authored by Mickaël Salaün in [1] and [2].

Link[1]: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/include/uapi/linux/landlock.h?id=ead9079f75696a028aea8860787770c80eddb8f9>
Link[2]: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/include/uapi/linux/landlock.h?id=12bfcda73ac2cf3083c9d6d05724af92da3a4b4b>
Cc: Mickaël Salaün <mic@digikod.net>
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---
 man/man2/landlock_restrict_self.2 | 67 ++++++++++++++++++++++++++++++-
 man/man7/landlock.7               |  6 ++-
 2 files changed, 70 insertions(+), 3 deletions(-)

diff --git a/man/man2/landlock_restrict_self.2 b/man/man2/landlock_restrict_self.2
index 530ef9a4cd25..9e80a40ee4a4 100644
--- a/man/man2/landlock_restrict_self.2
+++ b/man/man2/landlock_restrict_self.2
@@ -68,8 +68,71 @@ is a Landlock ruleset file descriptor obtained with
 and fully populated with a set of calls to
 .BR landlock_add_rule (2).
 .P
-.I flags
-must be 0.
+By default,
+denied accesses originating from programs that sandbox themselves
+are logged via the audit subsystem.
+Such events typically indicate unexpected behavior,
+such as bugs or exploitation attempts.
+However, to avoid excessive logging,
+access requests denied by a domain not created by the originating program
+are not logged by default.
+The rationale is that programs should know their own behavior,
+but not necessarily the behavior of other programs.
+This default configuration is suitable for most programs
+that sandbox themselves.
+For specific use cases,
+the following flags allow programs to modify this default logging behavior.
+.P
+The
+.B LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
+and
+.B LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
+flags apply to the newly created Landlock domain.
+.TP
+.B LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
+Disables logging of denied accesses
+originating from the thread creating the Landlock domain,
+as well as its children,
+as long as they continue running the same executable code
+(i.e., without an intervening
+.BR execve (2)
+call).
+This is intended for programs that execute unknown code
+without invoking
+.BR execve (2),
+such as script interpreters.
+Programs that only sandbox themselves should not set this flag,
+so users can be notified of unauthorized access attempts
+via system logs.
+.TP
+.B LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
+Enables logging of denied accesses after an
+.BR execve (2)
+call,
+providing visibility into unauthorized access attempts
+by newly executed programs within the created Landlock domain.
+This flag is recommended only when all potential executables
+in the domain are expected to comply with the access restrictions,
+as excessive audit log entries could make it more difficult
+to identify critical events.
+.TP
+.B LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF
+Disables logging of denied accesses
+originating from nested Landlock domains created by the caller
+or its descendants.
+This flag should be set according to runtime configuration,
+not hardcoded, to avoid suppressing important security events.
+It is useful for container runtimes or sandboxing tools
+that may launch programs which themselves create Landlock domains
+and could otherwise generate excessive logs.
+Unlike
+.BR LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF ,
+this flag only affects future nested domains,
+not the one being created.
+It can also be used with a
+.I ruleset_fd
+value of \-1 to mute subdomain logs
+without creating a domain.
 .SH RETURN VALUE
 On success,
 .BR landlock_restrict_self ()
diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
index 05664b3d7cba..bcf06ea30ad4 100644
--- a/man/man7/landlock.7
+++ b/man/man7/landlock.7
@@ -445,7 +445,7 @@ users should query the Landlock ABI version:
 box;
 ntb| ntb| lbx
 nt| nt| lbx.
-ABI	Kernel	Newly introduced access rights
+ABI	Kernel	Newly introduced constants
 _	_	_
 1	5.13	LANDLOCK_ACCESS_FS_EXECUTE
 \^	\^	LANDLOCK_ACCESS_FS_WRITE_FILE
@@ -472,6 +472,10 @@ _	_	_
 _	_	_
 6	6.12	LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
 \^	\^	LANDLOCK_SCOPE_SIGNAL
+_	_	_
+7	6.15	LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
+\^	\^	LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
+\^	\^	LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF
 .TE
 .P
 Users should use the Landlock ABI version rather than the kernel version
-- 
2.53.0