[PATCH v4 3/4] landlock_add_rule.2: Document new syscall

Mickaël Salaün mic at digikod.net
Wed Aug 18 15:59:30 UTC 2021

From: Mickaël Salaün <mic at linux.microsoft.com>

This is an adaptation of

Signed-off-by: Mickaël Salaün <mic at linux.microsoft.com>
Link: https://lore.kernel.org/r/20210818155931.484070-4-mic@digikod.net

Changes since v2:
* Fix syscall's rule_attr pointer.
* Add an EXAMPLES section referring to landlock(7).
* Change list order in the SEE ALSO section.
* Fix .IR and .BR use as explained by Alejandro Colomar.

Changes since v1:
* Replace all ".I" with ".IR", except when used for titles.
* Append punctuation to ".IR" and ".BR" when it makes sense (requested
  by Alejandro Colomar).
* Cut lines according to the semantic newline rules (requested by
  Alejandro Colomar).
* Remove roman style from ".TP" section titles (requested by Alejandro
* Add comma after "i.e." and "e.g.".
* Add a "CONFORMING TO" section.
* Replace "(2)" with "()" for the described syscall name.
 man2/landlock_add_rule.2 | 144 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 144 insertions(+)
 create mode 100644 man2/landlock_add_rule.2

diff --git a/man2/landlock_add_rule.2 b/man2/landlock_add_rule.2
new file mode 100644
index 000000000000..eafb8f8201b7
--- /dev/null
+++ b/man2/landlock_add_rule.2
@@ -0,0 +1,144 @@
+.\" Copyright © 2017-2020 Mickaël Salaün <mic at digikod.net>
+.\" Copyright © 2019-2020 ANSSI
+.\" Copyright © 2021 Microsoft Corporation
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.TH LANDLOCK_ADD_RULE 2 2021-06-27 Linux "Linux Programmer's Manual"
+landlock_add_rule \- add a new Landlock rule to a ruleset
+.BR "#include <linux/landlock.h>" "  /* Definition of " LANDLOCK_* " constants */"
+.BR "#include <sys/syscall.h>" "     /* Definition of " SYS_* " constants */"
+.BI "int syscall(SYS_landlock_add_rule, int " ruleset_fd ,
+.BI "            enum landlock_rule_type " rule_type ,
+.BI "            const void *" rule_attr ", __u32 " flags );
+A Landlock rule describes an action on an object.
+An object is currently a file hierarchy, and the related filesystem actions
+are defined with a set of access rights.
+.BR landlock_add_rule ()
+system call enables adding a new Landlock rule to an existing ruleset
+created with
+.BR landlock_create_ruleset (2).
+.BR landlock (7)
+for a global overview.
+.I ruleset_fd
+is a Landlock ruleset file descriptor obtained with
+.BR landlock_create_ruleset (2).
+.I rule_type
+identifies the structure type pointed to by
+.IR rule_attr .
+Currently, Linux supports the following
+.I rule_type
+This defines the object type as a file hierarchy.
+In this case,
+.I rule_attr
+points to the following structure:
+.in +4n
+struct landlock_path_beneath_attr {
+    __u64 allowed_access;
+    __s32 parent_fd;
+} __attribute__((packed));
+.I allowed_access
+contains a bitmask of allowed filesystem actions for this file hierarchy
+.B Filesystem actions
+.BR landlock (7)).
+.I parent_fd
+is an opened file descriptor, preferably with the
+which identifies the parent directory of the file hierarchy or
+just a file.
+.I flags
+must be 0.
+On success,
+.BR landlock_add_rule ()
+returns 0.
+.BR landlock_add_rule ()
+can failed for the following reasons:
+Landlock is supported by the kernel but disabled at boot time.
+.I flags
+is not 0, or the rule accesses are inconsistent (i.e.,
+.I rule_attr->allowed_access
+is not a subset of the ruleset handled accesses).
+Empty accesses (i.e.,
+.I rule_attr->allowed_access
+is 0).
+.I ruleset_fd
+is not a file descriptor for the current thread, or a member of
+.I rule_attr
+is not a file descriptor as expected.
+.I ruleset_fd
+is not a ruleset file descriptor, or a member of
+.I rule_attr
+is not the expected file descriptor type.
+.I ruleset_fd
+has no write access to the underlying ruleset.
+.I rule_attr
+was not a valid address.
+Landlock was added in Linux 5.13.
+This system call is Linux-specific.
+.BR landlock (7).
+.BR landlock_create_ruleset (2),
+.BR landlock_restrict_self (2),
+.BR landlock (7)

More information about the Linux-security-module-archive mailing list