[PATCH] landlock: Clarify LANDLOCK_RULE_PATH_BENEATH properties in documentation

[Justin Suess]

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