Debian Codegraph @

upstream/debian-unstable/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-04-21 "Linux man-pages 6.18"
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 __u64 scoped;
48 };
49 .EE
50 .in
51 .IP
52 .I handled_access_fs
53 is a bitmask of handled filesystem actions
54 (see
55 .B Filesystem actions
56 in
57 .BR landlock (7)).
58 .IP
59 .I handled_access_net
60 is a bitmask of handled network actions
61 (see
62 .B Network actions
63 in
64 .BR landlock (7)).
65 .IP
66 .I scoped
67 is a bitmask of scope flags
68 (see
69 .B Scope flags
70 in
71 .BR landlock (7)).
72 .IP
73 This structure defines a set of
74 .IR "handled access rights" ,
75 a set of actions on different object types,
76 which should be denied by default
77 when the ruleset is enacted.
78 Vice versa,
79 access rights that are not specifically listed here
80 are not going to be denied by this ruleset when it is enacted.
81 .IP
82 For historical reasons, the
83 .B LANDLOCK_ACCESS_FS_REFER
84 right is always denied by default,
85 even when its bit is not set in
86 .IR handled_access_fs .
87 In order to add new rules with this access right,
88 the bit must still be set explicitly
89 (see
90 .B Filesystem actions
91 in
92 .BR landlock (7)).
93 .IP
94 The explicit listing of
95 .I handled access rights
96 is required for backwards compatibility reasons.
97 In most use cases,
98 processes that use Landlock will
99 .I handle
100 a wide range or all access rights that they know about at build time
101 (and that they have tested with a kernel that supported them all).
102 .IP
103 This structure can grow in future Landlock versions.
104 .P
105 .I size
106 must be specified as
107 .I sizeof(struct landlock_ruleset_attr)
108 for compatibility reasons.
109 .P
110 .I flags
111 must be 0 if
112 .I attr
113 is used.
114 Otherwise,
115 .I flags
116 can be set to:
117 .TP
118 .B LANDLOCK_CREATE_RULESET_VERSION
119 Return the highest supported Landlock ABI version
120 (starting at 1).
121 This version can be used for a best-effort security approach,
122 which is encouraged when user space is not pinned to a specific kernel
123 version.
124 .IP
125 Unless noted otherwise,
126 all features documented in these manual pages are available with the
127 version 1.
128 .TP
129 .B LANDLOCK_CREATE_RULESET_ERRATA
130 Return a bitmask of fixed issues
131 for the current Landlock ABI version.
132 If bit N is set (i.e.,
133 .IR errata\~&\~(1\~<<\~(N\~\-\~1)) ),
134 then erratum N has been fixed in the running kernel.
135 .IP
136 In addition to ABI versions,
137 Landlock's errata mechanism
138 tracks fixes for issues that
139 may affect backwards compatibility
140 or require userspace awareness.
141 .IP
142 Only check errata if your application specifically relies on behavior
143 that changed due to the fix.
144 .IP
145 The full list of Landlock errata is available at
146 .UR https:\://docs.kernel.org/\:userspace\-api/\:landlock.html#landlock\-errata
147 .UE .
148 .IP
149 This flag is available on all Linux versions
150 where Landlock errata were fixed.
151 This specifically includes
152 all newest bugfix releases
153 of stable kernels
154 where Landlock is supported.
155 .P
156 If
157 .B LANDLOCK_CREATE_RULESET_VERSION
158 or
159 .B LANDLOCK_CREATE_RULESET_ERRATA
160 is set,
161 then
162 .I attr
163 must be NULL and
164 .I size
165 must be 0.
166 .SH RETURN VALUE
167 On success,
168 .BR landlock_create_ruleset ()
169 returns a new Landlock ruleset file descriptor,
170 a Landlock ABI version,
171 or a Landlock errata bitmask,
172 according to
173 .IR flags .
174 .P
175 On error,
176 \-1 is returned and
177 .I errno
178 is set to indicate the error.
179 .SH ERRORS
180 .BR landlock_create_ruleset ()
181 can fail for the following reasons:
182 .TP
183 .B E2BIG
184 .I size
185 is too big.
186 .TP
187 .B EFAULT
188 .I attr
189 was not a valid address.
190 .TP
191 .B EINVAL
192 Unknown
193 .IR flags ,
194 or unknown access, or unknown scope, or too small
195 .IR size .
196 .TP
197 .B EINVAL
198 Non-NULL
199 .I attr
200 or non-zero
201 .I size
202 in combination with
203 .B LANDLOCK_CREATE_RULESET_VERSION
204 or
205 .BR LANDLOCK_CREATE_RULESET_ERRATA .
206 .TP
207 .B ENOMSG
208 Empty accesses (i.e.,
209 .I attr
210 did not specify any access rights to restrict).
211 .TP
212 .B EOPNOTSUPP
213 Landlock is supported by the kernel but disabled at boot time.
214 .SH STANDARDS
215 Linux.
216 .SH HISTORY
217 Linux 5.13.
218 .SH EXAMPLES
219 See
220 .BR landlock (7).
221 .SH SEE ALSO
222 .BR landlock_add_rule (2),
223 .BR landlock_restrict_self (2),
224 .BR landlock (7)