Re: [PATCH 2/5] landlock_create_ruleset.2: Update docs for landlock_ruleset_attr

["Mickaël Salaün" <mic@digikod.net>]

On Mon, Jul 15, 2024 at 03:55:51PM +0000, Günther Noack wrote:
> This updates the documentation for struct landlock_ruleset_attr
> in line with the changed kernel documentation (see link below).
> 
> Cc: Alejandro Colomar <alx@kernel.org>
> Cc: Mickaël Salaün <mic@digikod.net>
> Link: https://lore.kernel.org/all/20240711165456.2148590-2-gnoack@google.com/
> Signed-off-by: Günther Noack <gnoack@google.com>

Reviewed-by: Mickaël Salaün <mic@digikod.net>

> ---
>  man/man2/landlock_create_ruleset.2 | 34 ++++++++++++++++++++++++++++--
>  1 file changed, 32 insertions(+), 2 deletions(-)
> 
> diff --git a/man/man2/landlock_create_ruleset.2 b/man/man2/landlock_create_ruleset.2
> index 871b91dcb..105e9b062 100644
> --- a/man/man2/landlock_create_ruleset.2
> +++ b/man/man2/landlock_create_ruleset.2
> @@ -51,8 +51,38 @@ is a bitmask of handled filesystem actions
>  .B Filesystem actions
>  in
>  .BR landlock (7)).
> -This enables simply restricting ambient rights
> -(e.g., global filesystem access) and is needed for compatibility reasons.
> +.IP
> +This structure defines a set of
> +.IR "handled access rights" ,
> +a set of actions on different object types,
> +which should be denied by default
> +when the ruleset is enacted.
> +Vice versa,
> +access rights that are not specifically listed here
> +are not going to be denied by this ruleset when it is enacted.
> +.IP
> +For historical reasons, the
> +.B LANDLOCK_ACCESS_FS_REFER
> +right is always denied by default,
> +even when its bit is not set in
> +.IR handled_access_fs .
> +In order to add new rules with this access right,
> +the bit must still be set explicitly
> +(see
> +.B Filesystem actions
> +in
> +.BR landlock (7)).
> +.IP
> +The explicit listing of
> +.I handled access rights
> +is required for backwards compatibility reasons.
> +In most use cases,
> +processes that use Landlock will
> +.I handle
> +a wide range or all access rights that they know about at build time
> +(and that they have tested with a kernel that supported them all).
> +.IP
> +This structure can grow in future Landlock versions.
>  .P
>  .I size
>  must be specified as
> -- 
> 2.45.2.993.g49e7a77208-goog
>