From: Günther Noack <gnoack@google.com>
Date: Fri, 19 Jul 2024 13:37:59 +0000 (+0000)
Subject: landlock_create_ruleset.2: Update docs for landlock_ruleset_attr
X-Git-Tag: man-pages-6.10~204
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=be64e5913e793ee0ecb999f26bc79d32ea465c2c;p=thirdparty%2Fman-pages.git

landlock_create_ruleset.2: Update docs for landlock_ruleset_attr

This updates the documentation for struct landlock_ruleset_attr
in line with the changed kernel documentation (see link below).

Link: <https://lore.kernel.org/all/20240711165456.2148590-2-gnoack@google.com/>
Reviewed-by: Mickaël Salaün <mic@digikod.net>
Signed-off-by: Günther Noack <gnoack@google.com>
Message-ID: <20240719133801.3541732-4-gnoack@google.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

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