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.
Showing the changes to include/uapi/linux (1 of 2 files). Show all
Unified · Split
| @@ -69,31 +69,42 @@ struct landlock_ruleset_attr { · 68 unmodified lines | |||
| 69 | #define LANDLOCK_CREATE_RULESET_ERRATA (1U << 1) | 69 | #define LANDLOCK_CREATE_RULESET_ERRATA (1U << 1) |
| 70 | /* clang-format on */ | 70 | /* clang-format on */ |
| 71 | 71 | ||
| 72 | /* | 72 | /** |
| 73 | * sys_landlock_restrict_self() flags: | 73 | * DOC: landlock_restrict_self_flags |
| 74 | * | 74 | * |
| 75 | * - %LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF: Do not create any log related to the | 75 | * **Flags** |
| 76 | * enforced restrictions. This should only be set by tools launching unknown | 76 | * |
| 77 | * or untrusted programs (e.g. a sandbox tool, container runtime, system | 77 | * %LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF |
| 78 | * service manager). Because programs sandboxing themselves should fix any | 78 | * Do not create any log related to the enforced restrictions. This should |
| 79 | * denied access, they should not set this flag to be aware of potential | 79 | * only be set by tools launching unknown or untrusted programs (e.g. a |
| 80 | * issues reported by system's logs (i.e. audit). | 80 | * sandbox tool, container runtime, system service manager). Because |
| 81 | * - %LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON: Explicitly ask to continue | 81 | * programs sandboxing themselves should fix any denied access, they should |
| 82 | * logging denied access requests even after an :manpage:`execve(2)` call. | 82 | * not set this flag to be aware of potential issues reported by system's |
| 83 | * This flag should only be set if all the programs than can legitimately be | 83 | * logs (i.e. audit). |
| 84 | * executed will not try to request a denied access (which could spam audit | 84 | * |
| 85 | * logs). | 85 | * %LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON |
| 86 | * - %LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF: Do not create any log related | 86 | * Explicitly ask to continue logging denied access requests even after an |
| 87 | * to the enforced restrictions coming from future nested domains created by | 87 | * :manpage:`execve(2)` call. This flag should only be set if all the |
| 88 | * the caller or its descendants. This should only be set according to a | 88 | * programs than can legitimately be executed will not try to request a |
| 89 | * runtime configuration (i.e. not hardcoded) by programs launching other | 89 | * denied access (which could spam audit logs). |
| 90 | * unknown or untrusted programs that may create their own Landlock domains | 90 | * |
| 91 | * and spam logs. The main use case is for container runtimes to enable users | 91 | * %LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF |
| 92 | * to mute buggy sandboxed programs for a specific container image. Other use | 92 | * Do not create any log related to the enforced restrictions coming from |
| 93 | * cases include sandboxer tools and init systems. Unlike | 93 | * future nested domains created by the caller or its descendants. This |
| 94 | * %LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF, | 94 | * should only be set according to a runtime configuration (i.e. not |
| 95 | * %LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF does not impact the requested | 95 | * hardcoded) by programs launching other unknown or untrusted programs that |
| 96 | * restriction (if any) but only the future nested domains. | 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 | /* clang-format off */ | 109 | /* clang-format off */ |
| 99 | #define LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF (1U << 0) | 110 | #define LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF (1U << 0) |