Debian Codegraph @

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