Debian Codegraph @

upstream/mageia-cauldron/man2/landlock_add_rule.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_add_rule 2 2026-02-08 "Linux man-pages 6.17"
9 .SH NAME
10 landlock_add_rule \- add a new Landlock rule to a 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 .P
19 .BI "int syscall(SYS_landlock_add_rule, int " ruleset_fd ,
20 .BI " enum landlock_rule_type " rule_type ,
21 .BI " const void *" rule_attr ", uint32_t " flags );
22 .fi
23 .SH DESCRIPTION
24 A Landlock rule describes an action on an object
25 which the process intends to perform.
26 A set of rules is aggregated in a ruleset,
27 which can then restrict the thread enforcing it, and its future children.
28 .P
29 The
30 .BR landlock_add_rule ()
31 system call adds a new Landlock rule to an existing ruleset.
32 See
33 .BR landlock (7)
34 for a global overview.
35 .P
36 .I ruleset_fd
37 is a Landlock ruleset file descriptor obtained with
38 .BR landlock_create_ruleset (2).
39 .P
40 .I rule_type
41 identifies the structure type pointed to by
42 .IR rule_attr .
43 Currently, Linux supports the following
44 .I rule_type
45 values:
46 .TP
47 .B LANDLOCK_RULE_PATH_BENEATH
48 For these rules,
49 the object is a file hierarchy,
50 and the related filesystem actions
51 are defined with
52 .IR "filesystem access rights" .
53 .IP
54 In this case,
55 .I rule_attr
56 points to the following structure:
57 .IP
58 .in +4n
59 .EX
60 struct landlock_path_beneath_attr {
61 __u64 allowed_access;
62 __s32 parent_fd;
63 } __attribute__((packed));
64 .EE
65 .in
66 .IP
67 .I allowed_access
68 contains a bitmask of allowed filesystem actions,
69 which can be applied on the given
70 .I parent_fd
71 (see
72 .B Filesystem actions
73 in
74 .BR landlock (7)).
75 .IP
76 .I parent_fd
77 is an opened file descriptor, preferably with the
78 .I O_PATH
79 flag,
80 which identifies the parent directory of the file hierarchy or
81 just a file.
82 .TP
83 .B LANDLOCK_RULE_NET_PORT
84 For these rules,
85 the object is a TCP port,
86 and the related actions are defined with
87 .IR "network access rights" .
88 .IP
89 In this case,
90 .I rule_attr
91 points to the following structure:
92 .IP
93 .in +4n
94 .EX
95 struct landlock_net_port_attr {
96 __u64 allowed_access;
97 __u64 port;
98 };
99 .EE
100 .in
101 .IP
102 .I allowed_access
103 contains a bitmask of allowed network actions,
104 which can be applied on the given port.
105 .IP
106 .I port
107 is the network port in host endianness.
108 .IP
109 It should be noted that port 0 passed to
110 .BR bind (2)
111 will bind to an available port from the ephemeral port range.
112 This can be configured in the
113 .I /proc/sys/net/ipv4/ip_local_port_range
114 sysctl (also used for IPv6).
115 .IP
116 A Landlock rule with port 0
117 and the
118 .B LANDLOCK_ACCESS_NET_BIND_TCP
119 right means that requesting to bind on port 0 is allowed
120 and it will automatically translate to binding on the related port range.
121 .P
122 .I flags
123 must be 0.
124 .SH RETURN VALUE
125 On success,
126 .BR landlock_add_rule ()
127 returns 0.
128 On error,
129 \-1 is returned and
130 .I errno
131 is set to indicate the error.
132 .SH ERRORS
133 .BR landlock_add_rule ()
134 can fail for the following reasons:
135 .TP
136 .B EAFNOSUPPORT
137 .I rule_type
138 is
139 .BR LANDLOCK_RULE_NET_PORT ,
140 but TCP is not supported by the running kernel.
141 .TP
142 .B EOPNOTSUPP
143 Landlock is supported by the kernel but disabled at boot time.
144 .TP
145 .B EINVAL
146 .I flags
147 is not 0.
148 .TP
149 .B EINVAL
150 The rule accesses are inconsistent (i.e.,
151 .I rule_attr\->allowed_access
152 is not a subset of the ruleset handled accesses).
153 .TP
154 .B EINVAL
155 In
156 .IR \%struct\~landlock_path_beneath_attr ,
157 the rule accesses are not applicable to the file
158 (i.e., some access rights in
159 .I \%rule_attr\->allowed_access
160 are only applicable to directories, but
161 .I \%rule_attr\->parent_fd
162 does not refer to a directory).
163 .TP
164 .B EINVAL
165 In
166 .IR \%struct\~landlock_net_port_attr ,
167 the port number is greater than 65535.
168 .TP
169 .B ENOMSG
170 Empty accesses (i.e.,
171 .I rule_attr\->allowed_access
172 is 0).
173 .TP
174 .B EBADF
175 .I ruleset_fd
176 is not a file descriptor for the current thread,
177 or a member of
178 .I rule_attr
179 is not a file descriptor as expected.
180 .TP
181 .B EBADFD
182 .I ruleset_fd
183 is not a ruleset file descriptor,
184 or a member of
185 .I rule_attr
186 is not the expected file descriptor type.
187 .TP
188 .B EPERM
189 .I ruleset_fd
190 has no write access to the underlying ruleset.
191 .TP
192 .B EFAULT
193 .I rule_attr
194 was not a valid address.
195 .SH STANDARDS
196 Linux.
197 .SH HISTORY
198 Linux 5.13.
199 .SH EXAMPLES
200 See
201 .BR landlock (7).
202 .SH SEE ALSO
203 .BR landlock_create_ruleset (2),
204 .BR landlock_restrict_self (2),
205 .BR landlock (7)