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