[PATCH] landlock: Clarify LANDLOCK_RULE_PATH_BENEATH properties in documentation

[Günther Noack]

On Thu, Mar 05, 2026 at 10:15:07AM -0500, Justin Suess wrote:
> Add paragraph to Landlock userspace documentation clarifying the strictly
> cumulative property of access rights with respect to the file hierarchy.
> 
> Signed-off-by: Justin Suess <utilityemal77 at gmail.com>
> ---
>  Documentation/userspace-api/landlock.rst | 11 +++++++++++
>  1 file changed, 11 insertions(+)
> 
> diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
> index 13134bccdd39..d02036bb2893 100644
> --- a/Documentation/userspace-api/landlock.rst
> +++ b/Documentation/userspace-api/landlock.rst
> @@ -173,6 +173,17 @@ this file descriptor.
>          return 1;
>      }
>  
> +The effective access rights for a path are the union of the access rights on
> +the path and all its parents.  For instance, in this example, ``/usr/bin/grep``
> +inherits rights granted on ``/usr``, in addition to any rights we choose to
> +grant on ``/usr/bin`` and ``/usr/bin/grep``.  Because
> +``LANDLOCK_RULE_PATH_BENEATH`` rights are cumulative, they can only increase
> +down the file hierarchy. Therefore, child paths cannot have fewer effective
> +access rights than their parents. This cumulative behavior is a key property of
> +``LANDLOCK_RULE_PATH_BENEATH`` and requires careful ruleset design to minimize
> +granted accesses.  Please see the :ref:`Good practices` section for more
> +details.
> +
>  It may also be required to create rules following the same logic as explained
>  for the ruleset creation, by filtering access rights according to the Landlock
>  ABI version.  In this example, this is not required because all of the requested
> 
> base-commit: f300a1c3a8ae4abca60913b4d26c405a905e4702
> prerequisite-patch-id: 2b17c4f0b741a703f61294989a53677de0b1a54d
> -- 
> 2.51.0
> 

Thanks! I think this is a good addition to the docs in this place. 👍

Reviewed-by: Günther Noack <gnoack3000 at gmail.com>

–Günther