Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
landlock: Fix documentation for landlock_restrict_self(2)
Fix, deduplicate, and improve rendering of landlock_restrict_self(2)'s
flags documentation.
The flags are now rendered like the syscall's parameters and
description.
Cc: Günther Noack <gnoack@google.com>
Cc: Paul Moore <paul@paul-moore.com>
Link: https://lore.kernel.org/r/20250416154716.1799902-2-mic@digikod.net
Signed-off-by: Mickaël Salaün <mic@digikod.net>
+41
-30
+35
-24
include/uapi/linux/landlock.h
+35
-24
include/uapi/linux/landlock.h
···
69
69
#define LANDLOCK_CREATE_RULESET_ERRATA (1U << 1)
70
70
/* clang-format on */
71
71
72
-
/*
73
-
* sys_landlock_restrict_self() flags:
72
+
/**
73
+
* DOC: landlock_restrict_self_flags
74
74
*
75
-
* - %LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF: Do not create any log related to the
76
-
* enforced restrictions. This should only be set by tools launching unknown
77
-
* or untrusted programs (e.g. a sandbox tool, container runtime, system
78
-
* service manager). Because programs sandboxing themselves should fix any
79
-
* denied access, they should not set this flag to be aware of potential
80
-
* issues reported by system's logs (i.e. audit).
81
-
* - %LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON: Explicitly ask to continue
82
-
* logging denied access requests even after an :manpage:`execve(2)` call.
83
-
* This flag should only be set if all the programs than can legitimately be
84
-
* executed will not try to request a denied access (which could spam audit
85
-
* logs).
86
-
* - %LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF: Do not create any log related
87
-
* to the enforced restrictions coming from future nested domains created by
88
-
* the caller or its descendants. This should only be set according to a
89
-
* runtime configuration (i.e. not hardcoded) by programs launching other
90
-
* unknown or untrusted programs that may create their own Landlock domains
91
-
* and spam logs. The main use case is for container runtimes to enable users
92
-
* to mute buggy sandboxed programs for a specific container image. Other use
93
-
* cases include sandboxer tools and init systems. Unlike
94
-
* %LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF,
95
-
* %LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF does not impact the requested
96
-
* restriction (if any) but only the future nested domains.
75
+
* **Flags**
76
+
*
77
+
* %LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
78
+
* Do not create any log related to the enforced restrictions. This should
79
+
* only be set by tools launching unknown or untrusted programs (e.g. a
80
+
* sandbox tool, container runtime, system service manager). Because
81
+
* programs sandboxing themselves should fix any denied access, they should
82
+
* not set this flag to be aware of potential issues reported by system's
83
+
* logs (i.e. audit).
84
+
*
85
+
* %LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
86
+
* Explicitly ask to continue logging denied access requests even after an
87
+
* :manpage:`execve(2)` call. This flag should only be set if all the
88
+
* programs than can legitimately be executed will not try to request a
89
+
* denied access (which could spam audit logs).
90
+
*
91
+
* %LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF
92
+
* Do not create any log related to the enforced restrictions coming from
93
+
* future nested domains created by the caller or its descendants. This
94
+
* should only be set according to a runtime configuration (i.e. not
95
+
* hardcoded) by programs launching other unknown or untrusted programs that
96
+
* may create their own Landlock domains and spam logs. The main use case
97
+
* is for container runtimes to enable users to mute buggy sandboxed
98
+
* programs for a specific container image. Other use cases include
99
+
* sandboxer tools and init systems. Unlike
100
+
* ``LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF``,
101
+
* ``LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF`` does not impact the
102
+
* requested restriction (if any) but only the future nested domains.
103
+
*
104
+
* It is allowed to only pass the
105
+
* ``LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF`` flag with a @ruleset_fd
106
+
* value of -1.
107
+
*
97
108
*/
98
109
/* clang-format off */
99
110
#define LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF (1U << 0)
+6
-6
security/landlock/syscalls.c
+6
-6
security/landlock/syscalls.c
···
451
451
* @ruleset_fd: File descriptor tied to the ruleset to merge with the target.
452
452
* @flags: Supported values:
453
453
*
454
-
* - %LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
455
-
* - %LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
456
-
* - %LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF
454
+
* - %LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
455
+
* - %LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
456
+
* - %LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF
457
457
*
458
458
* This system call enables to enforce a Landlock ruleset on the current
459
459
* thread. Enforcing a ruleset requires that the task has %CAP_SYS_ADMIN in its
460
460
* namespace or is running with no_new_privs. This avoids scenarios where
461
461
* unprivileged tasks can affect the behavior of privileged children.
462
-
*
463
-
* It is allowed to only pass the %LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF
464
-
* flag with a @ruleset_fd value of -1.
465
462
*
466
463
* Possible returned errors are:
467
464
*
···
471
474
* %CAP_SYS_ADMIN in its namespace.
472
475
* - %E2BIG: The maximum number of stacked rulesets is reached for the current
473
476
* thread.
477
+
*
478
+
* .. kernel-doc:: include/uapi/linux/landlock.h
479
+
* :identifiers: landlock_restrict_self_flags
474
480
*/
475
481
SYSCALL_DEFINE2(landlock_restrict_self, const int, ruleset_fd, const __u32,
476
482
flags)