Debian Codegraph @

upstream/debian-unstable/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-04-06 "Linux man-pages 6.18"
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 EBADF
143 .I ruleset_fd
144 is not a file descriptor for the current thread,
145 or a member of
146 .I rule_attr
147 is not a file descriptor as expected.
148 .TP
149 .B EBADFD
150 .I ruleset_fd
151 is not a ruleset file descriptor,
152 or a member of
153 .I rule_attr
154 is not the expected file descriptor type.
155 .TP
156 .B EFAULT
157 .I rule_attr
158 was not a valid address.
159 .TP
160 .B EINVAL
161 .I flags
162 is not 0.
163 .TP
164 .B EINVAL
165 The rule accesses are inconsistent (i.e.,
166 .I rule_attr\->allowed_access
167 is not a subset of the ruleset handled accesses).
168 .TP
169 .B EINVAL
170 In
171 .IR \%struct\~landlock_path_beneath_attr ,
172 the rule accesses are not applicable to the file
173 (i.e., some access rights in
174 .I \%rule_attr\->allowed_access
175 are only applicable to directories, but
176 .I \%rule_attr\->parent_fd
177 does not refer to a directory).
178 .TP
179 .B EINVAL
180 In
181 .IR \%struct\~landlock_net_port_attr ,
182 the port number is greater than 65535.
183 .TP
184 .B ENOMSG
185 Empty accesses (i.e.,
186 .I rule_attr\->allowed_access
187 is 0).
188 .TP
189 .B EOPNOTSUPP
190 Landlock is supported by the kernel but disabled at boot time.
191 .TP
192 .B EPERM
193 .I ruleset_fd
194 has no write access to the underlying ruleset.
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)