Unverified Commit 25b1fc1c authored by Mickaël Salaün's avatar Mickaël Salaün
Browse files

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: default avatarMickaël Salaün <mic@digikod.net>
parent 50492f94

include/uapi/linux/landlock.h

+36 −25
Original line number Diff line number Diff line
@@ -69,31 +69,42 @@ struct landlock_ruleset_attr { 
#define LANDLOCK_CREATE_RULESET_ERRATA			(1U << 1)

/* clang-format on */



/*

 * sys_landlock_restrict_self() flags:

 *

 * - %LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF: Do not create any log related to the

 *   enforced restrictions.  This should only be set by tools launching unknown

 *   or untrusted programs (e.g. a sandbox tool, container runtime, system

 *   service manager).  Because programs sandboxing themselves should fix any

 *   denied access, they should not set this flag to be aware of potential

 *   issues reported by system's logs (i.e. audit).

 * - %LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON: Explicitly ask to continue

 *   logging denied access requests even after an :manpage:`execve(2)` call.

 *   This flag should only be set if all the programs than can legitimately be

 *   executed will not try to request a denied access (which could spam audit

 *   logs).

 * - %LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF: Do not create any log related

 *   to the enforced restrictions coming from future nested domains created by

 *   the caller or its descendants.  This should only be set according to a

 *   runtime configuration (i.e. not hardcoded) by programs launching other

 *   unknown or untrusted programs that may create their own Landlock domains

 *   and spam logs.  The main use case is for container runtimes to enable users

 *   to mute buggy sandboxed programs for a specific container image.  Other use

 *   cases include sandboxer tools and init systems.  Unlike

 *   %LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF,

 *   %LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF does not impact the requested

 *   restriction (if any) but only the future nested domains.

/**

 * DOC: landlock_restrict_self_flags

 *

 * **Flags**

 *

 * %LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF

 *     Do not create any log related to the enforced restrictions.  This should

 *     only be set by tools launching unknown or untrusted programs (e.g. a

 *     sandbox tool, container runtime, system service manager).  Because

 *     programs sandboxing themselves should fix any denied access, they should

 *     not set this flag to be aware of potential issues reported by system's

 *     logs (i.e. audit).

 *

 * %LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON

 *     Explicitly ask to continue logging denied access requests even after an

 *     :manpage:`execve(2)` call.  This flag should only be set if all the

 *     programs than can legitimately be executed will not try to request a

 *     denied access (which could spam audit logs).

 *

 * %LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF

 *     Do not create any log related to the enforced restrictions coming from

 *     future nested domains created by the caller or its descendants.  This

 *     should only be set according to a runtime configuration (i.e. not

 *     hardcoded) by programs launching other unknown or untrusted programs that

 *     may create their own Landlock domains and spam logs.  The main use case

 *     is for container runtimes to enable users to mute buggy sandboxed

 *     programs for a specific container image.  Other use cases include

 *     sandboxer tools and init systems.  Unlike

 *     ``LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF``,

 *     ``LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF`` does not impact the

 *     requested restriction (if any) but only the future nested domains.

 *

 *     It is allowed to only pass the

 *     ``LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF`` flag with a @ruleset_fd

 *     value of -1.

 *

 */

/* clang-format off */

#define LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF		(1U << 0)

security/landlock/syscalls.c

+6 −6
Original line number Diff line number Diff line
@@ -460,9 +460,6 @@ SYSCALL_DEFINE4(landlock_add_rule, const int, ruleset_fd, 
 * namespace or is running with no_new_privs.  This avoids scenarios where

 * unprivileged tasks can affect the behavior of privileged children.

 *

 * It is allowed to only pass the %LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF

 * flag with a @ruleset_fd value of -1.

 *

 * Possible returned errors are:

 *

 * - %EOPNOTSUPP: Landlock is supported by the kernel but disabled at boot time;
@@ -474,6 +471,9 @@ SYSCALL_DEFINE4(landlock_add_rule, const int, ruleset_fd, 
 *   %CAP_SYS_ADMIN in its namespace.

 * - %E2BIG: The maximum number of stacked rulesets is reached for the current

 *   thread.

 *

 * .. kernel-doc:: include/uapi/linux/landlock.h

 *     :identifiers: landlock_restrict_self_flags

 */

SYSCALL_DEFINE2(landlock_restrict_self, const int, ruleset_fd, const __u32,

		flags)