man2/ioctl_ns.2

   1 .\" Copyright (c) 2017 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\"
   6 .TH IOCTL_NS 2 2022-09-17 "Linux man-pages (unreleased)"
   7 .SH NAME
   8 ioctl_ns \- ioctl() operations for Linux namespaces
   9 .SH DESCRIPTION
  10 .\" ============================================================
  11 .\"
  12 .SS Discovering namespace relationships
  13 The following
  14 .BR ioctl (2)
  15 operations are provided to allow discovery of namespace relationships (see
  16 .BR user_namespaces (7)
  17 and
  18 .BR pid_namespaces (7)).
  19 The form of the calls is:
  20 .PP
  21 .in +4n
  22 .EX
  23 new_fd = ioctl(fd, request);
  24 .EE
  25 .in
  26 .PP
  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 .BR NS_GET_USERNS " (since Linux 4.9)"
  35 .\" commit bcac25a58bfc6bd79191ac5d7afb49bea96da8c9
  36 .\" commit 6786741dbf99e44fb0c0ed85a37582b8a26f1c3b
  37 Returns a file descriptor that refers to the owning user namespace
  38 for the namespace referred to by
  39 .IR fd .
  40 .TP
  41 .BR NS_GET_PARENT " (since Linux 4.9)"
  42 .\" commit a7306ed8d94af729ecef8b6e37506a1c6fc14788
  43 Returns a file descriptor that refers to the parent namespace of
  44 the namespace referred to by
  45 .IR fd .
  46 This operation is valid only for hierarchical namespaces
  47 (i.e., PID and user namespaces).
  48 For user namespaces,
  49 .B NS_GET_PARENT
  50 is synonymous with
  51 .BR NS_GET_USERNS .
  52 .PP
  53 The new file descriptor returned by these operations is opened with the
  54 .B O_RDONLY
  55 and
  56 .B O_CLOEXEC
  57 (close-on-exec; see
  58 .BR fcntl (2))
  59 flags.
  60 .PP
  61 By applying
  62 .BR fstat (2)
  63 to the returned file descriptor, one obtains a
  64 .I stat
  65 structure whose
  66 .I st_dev
  67 (resident device) and
  68 .I st_ino
  69 (inode number) fields together identify the owning/parent namespace.
  70 This inode number can be matched with the inode number of another
  71 .IR /proc/ pid /ns/ { pid , user }
  72 file to determine whether that is the owning/parent namespace.
  73 .PP
  74 Either of these
  75 .BR ioctl (2)
  76 operations can fail with the following 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 .PP
  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 .PP
  96 See the EXAMPLES section for an example of the use of these operations.
  97 .\" ============================================================
  98 .\"
  99 .SS Discovering the namespace type
 100 The
 101 .B NS_GET_NSTYPE
 102 .\" commit e5ff5ce6e20ee22511398bb31fb912466cf82a36
 103 operation (available since Linux 4.11) can be used to discover
 104 the type of namespace referred to by the file descriptor
 105 .IR fd :
 106 .PP
 107 .in +4n
 108 .EX
 109 nstype = ioctl(fd, NS_GET_NSTYPE);
 110 .EE
 111 .in
 112 .PP
 113 .I fd
 114 refers to a
 115 .IR /proc/ pid /ns/*
 116 file.
 117 .PP
 118 The return value is one of the
 119 .B CLONE_NEW*
 120 values that can be specified to
 121 .BR clone (2)
 122 or
 123 .BR unshare (2)
 124 in order to create a namespace.
 125 .\" ============================================================
 126 .\"
 127 .SS Discovering the owner of a user namespace
 128 The
 129 .B NS_GET_OWNER_UID
 130 .\" commit 015bb305b8ebe8d601a238ab70ebdc394c7a19ba
 131 operation (available since Linux 4.11) can be used to discover
 132 the owner user ID of a user namespace (i.e., the effective user ID
 133 of the process that created the user namespace).
 134 The form of the call is:
 135 .PP
 136 .in +4n
 137 .EX
 138 uid_t uid;
 139 ioctl(fd, NS_GET_OWNER_UID, &uid);
 140 .EE
 141 .in
 142 .PP
 143 .I fd
 144 refers to a
 145 .IR /proc/ pid /ns/user
 146 file.
 147 .PP
 148 The owner user ID is returned in the
 149 .I uid_t
 150 pointed to by the third argument.
 151 .PP
 152 This operation can fail with the following error:
 153 .TP
 154 .B EINVAL
 155 .I fd
 156 does not refer to a user namespace.
 157 .SH ERRORS
 158 Any of the above
 159 .BR ioctl ()
 160 operations can return the following errors:
 161 .TP
 162 .B ENOTTY
 163 .I fd
 164 does not refer to a
 165 .I /proc/[pid]/ns/*
 166 file.
 167 .SH STANDARDS
 168 Namespaces and the operations described on this page are a Linux-specific.
 169 .SH EXAMPLES
 170 The example shown below uses the
 171 .BR ioctl (2)
 172 operations described above to perform simple
 173 discovery of namespace relationships.
 174 The following shell sessions show various examples of the use
 175 of this program.
 176 .PP
 177 Trying to get the parent of the initial user namespace fails,
 178 since it has no parent:
 179 .PP
 180 .in +4n
 181 .EX
 182 $ \fB./ns_show /proc/self/ns/user p\fP
 183 The parent namespace is outside your namespace scope
 184 .EE
 185 .in
 186 .PP
 187 Create a process running
 188 .BR sleep (1)
 189 that resides in new user and UTS namespaces,
 190 and show that the new UTS namespace is associated with the new user namespace:
 191 .PP
 192 .in +4n
 193 .EX
 194 $ \fBunshare \-Uu sleep 1000 &\fP
 195 [1] 23235
 196 $ \fB./ns_show /proc/23235/ns/uts u\fP
 197 Device/Inode of owning user namespace is: [0,3] / 4026532448
 198 $ \fBreadlink /proc/23235/ns/user\fP
 199 user:[4026532448]
 200 .EE
 201 .in
 202 .PP
 203 Then show that the parent of the new user namespace in the preceding
 204 example is the initial user namespace:
 205 .PP
 206 .in +4n
 207 .EX
 208 $ \fBreadlink /proc/self/ns/user\fP
 209 user:[4026531837]
 210 $ \fB./ns_show /proc/23235/ns/user p\fP
 211 Device/Inode of parent namespace is: [0,3] / 4026531837
 212 .EE
 213 .in
 214 .PP
 215 Start a shell in a new user namespace, and show that from within
 216 this shell, the parent user namespace can't be discovered.
 217 Similarly, the UTS namespace
 218 (which is associated with the initial user namespace)
 219 can't be discovered.
 220 .PP
 221 .in +4n
 222 .EX
 223 $ \fBPS1="sh2$ " unshare \-U bash\fP
 224 sh2$ \fB./ns_show /proc/self/ns/user p\fP
 225 The parent namespace is outside your namespace scope
 226 sh2$ \fB./ns_show /proc/self/ns/uts u\fP
 227 The owning user namespace is outside your namespace scope
 228 .EE
 229 .in
 230 .SS Program source
 231 \&
 232 .\" SRC BEGIN (ns_show.c)
 233 .EX
 234 /* ns_show.c
 235
 236    Licensed under the GNU General Public License v2 or later.
 237 */
 238 #include <errno.h>
 239 #include <fcntl.h>
 240 #include <linux/nsfs.h>
 241 #include <stdint.h>
 242 #include <stdio.h>
 243 #include <stdlib.h>
 244 #include <string.h>
 245 #include <sys/ioctl.h>
 246 #include <sys/stat.h>
 247 #include <sys/sysmacros.h>
 248 #include <unistd.h>
 249
 250 int
 251 main(int argc, char *argv[])
 252 {
 253     int          fd, userns_fd, parent_fd;
 254     struct stat  sb;
 255
 256     if (argc < 2) {
 257         fprintf(stderr, "Usage: %s /proc/[pid]/ns/[file] [p|u]\en",
 258                 argv[0]);
 259         fprintf(stderr, "\enDisplay the result of one or both "
 260                 "of NS_GET_USERNS (u) or NS_GET_PARENT (p)\en"
 261                 "for the specified /proc/[pid]/ns/[file]. If neither "
 262                 "\(aqp\(aq nor \(aqu\(aq is specified,\en"
 263                 "NS_GET_USERNS is the default.\en");
 264         exit(EXIT_FAILURE);
 265     }
 266
 267     /* Obtain a file descriptor for the \(aqns\(aq file specified
 268        in argv[1]. */
 269
 270     fd = open(argv[1], O_RDONLY);
 271     if (fd == \-1) {
 272         perror("open");
 273         exit(EXIT_FAILURE);
 274     }
 275
 276     /* Obtain a file descriptor for the owning user namespace and
 277        then obtain and display the inode number of that namespace. */
 278
 279     if (argc < 3 || strchr(argv[2], \(aqu\(aq)) {
 280         userns_fd = ioctl(fd, NS_GET_USERNS);
 281
 282         if (userns_fd == \-1) {
 283             if (errno == EPERM)
 284                 printf("The owning user namespace is outside "
 285                        "your namespace scope\en");
 286             else
 287                perror("ioctl\-NS_GET_USERNS");
 288             exit(EXIT_FAILURE);
 289          }
 290
 291         if (fstat(userns_fd, &sb) == \-1) {
 292             perror("fstat\-userns");
 293             exit(EXIT_FAILURE);
 294         }
 295         printf("Device/Inode of owning user namespace is: "
 296                "[%x,%x] / %ju\en",
 297                major(sb.st_dev),
 298                minor(sb.st_dev),
 299                (uintmax_t) sb.st_ino);
 300
 301         close(userns_fd);
 302     }
 303
 304     /* Obtain a file descriptor for the parent namespace and
 305        then obtain and display the inode number of that namespace. */
 306
 307     if (argc > 2 && strchr(argv[2], \(aqp\(aq)) {
 308         parent_fd = ioctl(fd, NS_GET_PARENT);
 309
 310         if (parent_fd == \-1) {
 311             if (errno == EINVAL)
 312                 printf("Can\(aq get parent namespace of a "
 313                        "nonhierarchical namespace\en");
 314             else if (errno == EPERM)
 315                 printf("The parent namespace is outside "
 316                        "your namespace scope\en");
 317             else
 318                 perror("ioctl\-NS_GET_PARENT");
 319             exit(EXIT_FAILURE);
 320         }
 321
 322         if (fstat(parent_fd, &sb) == \-1) {
 323             perror("fstat\-parentns");
 324             exit(EXIT_FAILURE);
 325         }
 326         printf("Device/Inode of parent namespace is: [%x,%x] / %ju\en",
 327                major(sb.st_dev),
 328                minor(sb.st_dev),
 329                (uintmax_t) sb.st_ino);
 330
 331         close(parent_fd);
 332     }
 333
 334     exit(EXIT_SUCCESS);
 335 }
 336 .EE
 337 .\" SRC END
 338 .SH SEE ALSO
 339 .BR fstat (2),
 340 .BR ioctl (2),
 341 .BR proc (5),
 342 .BR namespaces (7)