Debian Codegraph @

upstream/debian-trixie/man2/NS_GET_USERNS.2const

raw
1 .\" Copyright 2017, Michael Kerrisk <[email protected]>
2 .\" Copyright 2024, Alejandro Colomar <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH NS_GET_USERNS 2const 2024-06-15 "Linux man-pages 6.9.1"
7 .SH NAME
8 NS_GET_USERNS,
9 NS_GET_PARENT
10 \-
11 discovering namespace relationships
12 .SH SYNOPSIS
13 .nf
14 .BR "#include <linux/nsfs.h>" " /* Definition of " NS_GET_* " constants */"
15 .B #include <sys/ioctl.h>
16 .P
17 .BI "int ioctl(int " fd ", unsigned long " op );
18 .fi
19 .SH DESCRIPTION
20 The following
21 .BR ioctl (2)
22 operations are provided to allow discovery of namespace relationships (see
23 .BR user_namespaces (7)
24 and
25 .BR pid_namespaces (7)).
26 .P
27 In each case,
28 .I fd
29 refers to a
30 .IR /proc/ pid /ns/*
31 file.
32 Both operations return a new file descriptor on success.
33 .TP
34 .B NS_GET_USERNS
35 Returns a file descriptor that refers to the owning user namespace
36 for the namespace referred to by
37 .IR fd .
38 .TP
39 .B NS_GET_PARENT
40 Returns a file descriptor that refers to the parent namespace of
41 the namespace referred to by
42 .IR fd .
43 This operation is valid only for hierarchical namespaces
44 (i.e., PID and user namespaces).
45 For user namespaces,
46 .B NS_GET_PARENT
47 is synonymous with
48 .BR NS_GET_USERNS .
49 .P
50 The new file descriptor returned by these operations is opened with the
51 .B O_RDONLY
52 and
53 .B O_CLOEXEC
54 (close-on-exec; see
55 .BR fcntl (2))
56 flags.
57 .P
58 By applying
59 .BR fstat (2)
60 to the returned file descriptor, one obtains a
61 .I stat
62 structure whose
63 .I st_dev
64 (resident device) and
65 .I st_ino
66 (inode number) fields together identify the owning/parent namespace.
67 This inode number can be matched with the inode number of another
68 .IR /proc/ pid /ns/ { pid , user }
69 file to determine whether that is the owning/parent namespace.
70 .SH RETURN VALUE
71 On success,
72 a file descriptor is returned.
73 Or error, \-1 is returned, and
74 .I errno
75 is set to indicate the error.
76 .SH ERRORS
77 .TP
78 .B EPERM
79 The requested namespace is outside of the caller's namespace scope.
80 This error can occur if, for example, the owning user namespace is an
81 ancestor of the caller's current user namespace.
82 It can also occur on attempts to obtain the parent of the initial
83 user or PID namespace.
84 .TP
85 .B ENOTTY
86 The operation is not supported by this kernel version.
87 .P
88 Additionally, the
89 .B NS_GET_PARENT
90 operation can fail with the following error:
91 .TP
92 .B EINVAL
93 .I fd
94 refers to a nonhierarchical namespace.
95 .SH STANDARDS
96 Linux.
97 .SH HISTORY
98 .TP
99 .B NS_GET_USERNS
100 .\" linux.git bcac25a58bfc6bd79191ac5d7afb49bea96da8c9
101 .\" linux.git 6786741dbf99e44fb0c0ed85a37582b8a26f1c3b
102 Linux 4.9.
103 .TP
104 .B NS_GET_PARENT
105 .\" linux.git a7306ed8d94af729ecef8b6e37506a1c6fc14788
106 Linux 4.9.
107 .SH EXAMPLES
108 The example shown below uses the
109 .BR ioctl (2)
110 operations described above to perform simple
111 discovery of namespace relationships.
112 The following shell sessions show various examples of the use
113 of this program.
114 .P
115 Trying to get the parent of the initial user namespace fails,
116 since it has no parent:
117 .P
118 .in +4n
119 .EX
120 $ \fB./ns_show /proc/self/ns/user p\fP
121 The parent namespace is outside your namespace scope
122 .EE
123 .in
124 .P
125 Create a process running
126 .BR sleep (1)
127 that resides in new user and UTS namespaces,
128 and show that the new UTS namespace is associated with the new user namespace:
129 .P
130 .in +4n
131 .EX
132 $ \fBunshare \-Uu sleep 1000 &\fP
133 [1] 23235
134 $ \fB./ns_show /proc/23235/ns/uts u\fP
135 Device/Inode of owning user namespace is: [0,3] / 4026532448
136 $ \fBreadlink /proc/23235/ns/user\fP
137 user:[4026532448]
138 .EE
139 .in
140 .P
141 Then show that the parent of the new user namespace in the preceding
142 example is the initial user namespace:
143 .P
144 .in +4n
145 .EX
146 $ \fBreadlink /proc/self/ns/user\fP
147 user:[4026531837]
148 $ \fB./ns_show /proc/23235/ns/user p\fP
149 Device/Inode of parent namespace is: [0,3] / 4026531837
150 .EE
151 .in
152 .P
153 Start a shell in a new user namespace, and show that from within
154 this shell, the parent user namespace can't be discovered.
155 Similarly, the UTS namespace
156 (which is associated with the initial user namespace)
157 can't be discovered.
158 .P
159 .in +4n
160 .EX
161 $ \fBPS1="sh2$ " unshare \-U bash\fP
162 sh2$ \fB./ns_show /proc/self/ns/user p\fP
163 The parent namespace is outside your namespace scope
164 sh2$ \fB./ns_show /proc/self/ns/uts u\fP
165 The owning user namespace is outside your namespace scope
166 .EE
167 .in
168 .SS Program source
169 \&
170 .\" SRC BEGIN (ns_show.c)
171 .EX
172 /* ns_show.c
173 \&
174 Licensed under the GNU General Public License v2 or later.
175 */
176 #include <errno.h>
177 #include <fcntl.h>
178 #include <linux/nsfs.h>
179 #include <stdint.h>
180 #include <stdio.h>
181 #include <stdlib.h>
182 #include <string.h>
183 #include <sys/ioctl.h>
184 #include <sys/stat.h>
185 #include <sys/sysmacros.h>
186 #include <unistd.h>
187 \&
188 int
189 main(int argc, char *argv[])
190 {
191 int fd, userns_fd, parent_fd;
192 struct stat sb;
193 \&
194 if (argc < 2) {
195 fprintf(stderr, "Usage: %s /proc/[pid]/ns/[file] [p|u]\[rs]n",
196 argv[0]);
197 fprintf(stderr, "\[rs]nDisplay the result of one or both "
198 "of NS_GET_USERNS (u) or NS_GET_PARENT (p)\[rs]n"
199 "for the specified /proc/[pid]/ns/[file]. If neither "
200 "\[aq]p\[aq] nor \[aq]u\[aq] is specified,\[rs]n"
201 "NS_GET_USERNS is the default.\[rs]n");
202 exit(EXIT_FAILURE);
203 }
204 \&
205 /* Obtain a file descriptor for the \[aq]ns\[aq] file specified
206 in argv[1]. */
207 \&
208 fd = open(argv[1], O_RDONLY);
209 if (fd == \-1) {
210 perror("open");
211 exit(EXIT_FAILURE);
212 }
213 \&
214 /* Obtain a file descriptor for the owning user namespace and
215 then obtain and display the inode number of that namespace. */
216 \&
217 if (argc < 3 || strchr(argv[2], \[aq]u\[aq])) {
218 userns_fd = ioctl(fd, NS_GET_USERNS);
219 \&
220 if (userns_fd == \-1) {
221 if (errno == EPERM)
222 printf("The owning user namespace is outside "
223 "your namespace scope\[rs]n");
224 else
225 perror("ioctl\-NS_GET_USERNS");
226 exit(EXIT_FAILURE);
227 }
228 \&
229 if (fstat(userns_fd, &sb) == \-1) {
230 perror("fstat\-userns");
231 exit(EXIT_FAILURE);
232 }
233 printf("Device/Inode of owning user namespace is: "
234 "[%x,%x] / %ju\[rs]n",
235 major(sb.st_dev),
236 minor(sb.st_dev),
237 (uintmax_t) sb.st_ino);
238 \&
239 close(userns_fd);
240 }
241 \&
242 /* Obtain a file descriptor for the parent namespace and
243 then obtain and display the inode number of that namespace. */
244 \&
245 if (argc > 2 && strchr(argv[2], \[aq]p\[aq])) {
246 parent_fd = ioctl(fd, NS_GET_PARENT);
247 \&
248 if (parent_fd == \-1) {
249 if (errno == EINVAL)
250 printf("Can\[aq] get parent namespace of a "
251 "nonhierarchical namespace\[rs]n");
252 else if (errno == EPERM)
253 printf("The parent namespace is outside "
254 "your namespace scope\[rs]n");
255 else
256 perror("ioctl\-NS_GET_PARENT");
257 exit(EXIT_FAILURE);
258 }
259 \&
260 if (fstat(parent_fd, &sb) == \-1) {
261 perror("fstat\-parentns");
262 exit(EXIT_FAILURE);
263 }
264 printf("Device/Inode of parent namespace is: [%x,%x] / %ju\[rs]n",
265 major(sb.st_dev),
266 minor(sb.st_dev),
267 (uintmax_t) sb.st_ino);
268 \&
269 close(parent_fd);
270 }
271 \&
272 exit(EXIT_SUCCESS);
273 }
274 .EE
275 .\" SRC END
276 .SH SEE ALSO
277 .BR ioctl (2),
278 .BR ioctl_nsfs (2)