On 10/03/2023 23:08, Günther Noack wrote:
Signed-off-by: Günther Noack <gnoack3000@xxxxxxxxx>
---
man7/landlock.7 | 16 ++++++++++++++--
1 file changed, 14 insertions(+), 2 deletions(-)
diff --git a/man7/landlock.7 b/man7/landlock.7
index 9c305edef..c173cbb98 100644
--- a/man7/landlock.7
+++ b/man7/landlock.7
@@ -393,12 +393,14 @@ accessible through these system call families:
Future Landlock evolutions will enable to restrict them.
.SH EXAMPLES
We first need to create the ruleset that will contain our rules.
+.PP
For this example,
the ruleset will contain rules that only allow read actions,
but write actions will be denied.
The ruleset then needs to handle both of these kinds of actions.
-See below for the description of filesystem actions.
-.PP
+See the
+.B DESCRIPTION
+section for the description of filesystem actions.
.in +4n
.EX
struct landlock_ruleset_attr attr = {0};
@@ -429,6 +431,16 @@ if (ruleset_fd == \-1) {
.EE
.in
.PP
+The ruleset we have constructed requires Landlock ABI version 3 or higher.
+On kernels which do not provide that,
+the call to
+.BR landlock_create_ruleset (2)
+will fail.
One of the goal of Landlock is to avoid developers and their code to
(lazily) error out if one feature is not supported by the running
kernel. If this happens, a lot of sandboxing will be disabled (and then
useless) because users don't necessarily have the same kernel as
developers'.
Such security feature is not the same as a "necessary" feature. Indeed,
sandboxing is and should be optional for applications to run correctly,
hence the recommended best-effort approach:
https://docs.kernel.org/userspace-api/landlock.html#backward-and-forward-compatibility
I agree that the man page should not be too complex, but I think
teaching the best (default) approach should be the goal.
For the example, we can ignore LANDLOCK_ACCESS_FS_REFER but use all
other access rights, especially LANDLOCK_ACCESS_FS_TRUNCATE. However,
this last one should be masked if not supported by the running kernel.
See
https://docs.kernel.org/userspace-api/landlock.html#defining-and-enforcing-a-security-policy
An alternative would be to ignore access rights for ABI > 1 to make it
simple, but this would not help developers dealing with real use cases.
This comment applies to all these 3 patches.
+You can build a more graceful fallback mechanism
+by using the version compatibility table from the
+.B VERSIONS
+section.
+.PP
We can now add a new rule to this ruleset thanks to the returned file
descriptor referring to this ruleset.
The rule will only allow reading the file hierarchy
