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.

Mickaël Salaün committed 1 year ago

Commit 25b1fc11 parent 50492f92 files · +42 −31Browse files

Showing the changes to include/uapi/linux (1 of 2 files). Show all

Unified · Split

include/uapi/linux/landlock.h+36−25

@@ -69,31 +69,42 @@ struct landlock_ruleset_attr { · 68 unmodified lines
69	69	#define LANDLOCK_CREATE_RULESET_ERRATA (1U << 1)
70	70	/* clang-format on */
71	71
72		−/*
73		− * sys_landlock_restrict_self() flags:
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.
	72	+/**
	73	+ * DOC: landlock_restrict_self_flags
	74	+ *
	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)