Debian Codegraph @

upstream/mageia-cauldron/man2/landlock_create_ruleset.2

raw
1 .\" Copyright 2017-2020, Mickaël Salaün <[email protected]>
2 .\" Copyright 2019-2020, ANSSI
3 .\" Copyright 2021, Microsoft Corp.
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .TH landlock_create_ruleset 2 2026-02-08 "Linux man-pages 6.17"
9 .SH NAME
10 landlock_create_ruleset \- create a new Landlock ruleset
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .BR "#include <linux/landlock.h>" " /* Definition of " LANDLOCK_* " constants */"
17 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
18 .B #include <unistd.h>
19 .P
20 .B int syscall(SYS_landlock_create_ruleset,
21 .BI " const struct landlock_ruleset_attr *" attr ,
22 .BI " size_t " size " , uint32_t " flags );
23 .fi
24 .SH DESCRIPTION
25 A Landlock ruleset identifies a set of rules (i.e., actions on objects).
26 This
27 .BR landlock_create_ruleset ()
28 system call creates a new file descriptor
29 which identifies a ruleset.
30 This file descriptor can then be used by
31 .BR landlock_add_rule (2)
32 and
33 .BR landlock_restrict_self (2).
34 See
35 .BR landlock (7)
36 for a global overview.
37 .P
38 .I attr
39 specifies the properties of the new ruleset.
40 It points to the following structure:
41 .IP
42 .in +4n
43 .EX
44 struct landlock_ruleset_attr {
45 __u64 handled_access_fs;
46 __u64 handled_access_net;
47 };
48 .EE
49 .in
50 .IP
51 .I handled_access_fs
52 is a bitmask of handled filesystem actions
53 (see
54 .B Filesystem actions
55 in
56 .BR landlock (7)).
57 .IP
58 .I handled_access_net
59 is a bitmask of handled network actions
60 (see
61 .B Network actions
62 in
63 .BR landlock (7)).
64 .IP
65 This structure defines a set of
66 .IR "handled access rights" ,
67 a set of actions on different object types,
68 which should be denied by default
69 when the ruleset is enacted.
70 Vice versa,
71 access rights that are not specifically listed here
72 are not going to be denied by this ruleset when it is enacted.
73 .IP
74 For historical reasons, the
75 .B LANDLOCK_ACCESS_FS_REFER
76 right is always denied by default,
77 even when its bit is not set in
78 .IR handled_access_fs .
79 In order to add new rules with this access right,
80 the bit must still be set explicitly
81 (see
82 .B Filesystem actions
83 in
84 .BR landlock (7)).
85 .IP
86 The explicit listing of
87 .I handled access rights
88 is required for backwards compatibility reasons.
89 In most use cases,
90 processes that use Landlock will
91 .I handle
92 a wide range or all access rights that they know about at build time
93 (and that they have tested with a kernel that supported them all).
94 .IP
95 This structure can grow in future Landlock versions.
96 .P
97 .I size
98 must be specified as
99 .I sizeof(struct landlock_ruleset_attr)
100 for compatibility reasons.
101 .P
102 .I flags
103 must be 0 if
104 .I attr
105 is used.
106 Otherwise,
107 .I flags
108 can be set to:
109 .TP
110 .B LANDLOCK_CREATE_RULESET_VERSION
111 If
112 .I attr
113 is NULL and
114 .I size
115 is 0, then the returned value is the highest supported Landlock ABI version
116 (starting at 1).
117 This version can be used for a best-effort security approach,
118 which is encouraged when user space is not pinned to a specific kernel
119 version.
120 All features documented in these man pages are available with the version
121 1.
122 .SH RETURN VALUE
123 On success,
124 .BR landlock_create_ruleset ()
125 returns a new Landlock ruleset file descriptor,
126 or a Landlock ABI version,
127 according to
128 .IR flags .
129 On error,
130 \-1 is returned and
131 .I errno
132 is set to indicate the error.
133 .SH ERRORS
134 .BR landlock_create_ruleset ()
135 can fail for the following reasons:
136 .TP
137 .B EOPNOTSUPP
138 Landlock is supported by the kernel but disabled at boot time.
139 .TP
140 .B EINVAL
141 Unknown
142 .IR flags ,
143 or unknown access, or too small
144 .IR size .
145 .TP
146 .B E2BIG
147 .I size
148 is too big.
149 .TP
150 .B EFAULT
151 .I attr
152 was not a valid address.
153 .TP
154 .B ENOMSG
155 Empty accesses (i.e.,
156 .I attr
157 did not specify any access rights to restrict).
158 .SH STANDARDS
159 Linux.
160 .SH HISTORY
161 Linux 5.13.
162 .SH EXAMPLES
163 See
164 .BR landlock (7).
165 .SH SEE ALSO
166 .BR landlock_add_rule (2),
167 .BR landlock_restrict_self (2),
168 .BR landlock (7)