| 1 |
'\" t |
| 2 |
.\" Copyright 2013-2017, Michael Kerrisk <[email protected]> |
| 3 |
.\" Copyright 2012, Eric W. Biederman <[email protected]> |
| 4 |
.\" Copyright, the authors of the Linux man-pages project |
| 5 |
.\" |
| 6 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 7 |
.\" |
| 8 |
.TH namespaces 7 2026-02-08 "Linux man-pages 6.18" |
| 9 |
.SH NAME |
| 10 |
namespaces \- overview of Linux namespaces |
| 11 |
.SH DESCRIPTION |
| 12 |
A namespace wraps a global system resource in an abstraction that |
| 13 |
makes it appear to the processes within the namespace that they |
| 14 |
have their own isolated instance of the global resource. |
| 15 |
Changes to the global resource are visible to other processes |
| 16 |
that are members of the namespace, but are invisible to other processes. |
| 17 |
One use of namespaces is to implement containers. |
| 18 |
.P |
| 19 |
This page provides pointers to information on the various namespace types, |
| 20 |
describes the associated |
| 21 |
.I /proc |
| 22 |
files, and summarizes the APIs for working with namespaces. |
| 23 |
.\" |
| 24 |
.SS Namespace types |
| 25 |
The following table shows the namespace types available on Linux. |
| 26 |
The second column of the table shows the flag value that is used to specify |
| 27 |
the namespace type in various APIs. |
| 28 |
The third column identifies the manual page that provides details |
| 29 |
on the namespace type. |
| 30 |
The last column is a summary of the resources that are isolated by |
| 31 |
the namespace type. |
| 32 |
.P |
| 33 |
.TS |
| 34 |
lB lB lB lB |
| 35 |
l lB lw(21n) lx. |
| 36 |
Namespace Flag Page Isolates |
| 37 |
_ |
| 38 |
Cgroup CLONE_NEWCGROUP \f[B]cgroup_namespaces\f[](7) T{ |
| 39 |
.na |
| 40 |
.nh |
| 41 |
Cgroup root directory |
| 42 |
T} |
| 43 |
IPC CLONE_NEWIPC \f[B]ipc_namespaces\f[](7) T{ |
| 44 |
.na |
| 45 |
.nh |
| 46 |
System V IPC, |
| 47 |
POSIX message queues |
| 48 |
T} |
| 49 |
Network CLONE_NEWNET \f[B]network_namespaces\f[](7) T{ |
| 50 |
.na |
| 51 |
.nh |
| 52 |
Network devices, |
| 53 |
stacks, ports, etc. |
| 54 |
T} |
| 55 |
Mount CLONE_NEWNS \f[B]mount_namespaces\f[](7) Mount points |
| 56 |
PID CLONE_NEWPID \f[B]pid_namespaces\f[](7) Process IDs |
| 57 |
Time CLONE_NEWTIME \f[B]time_namespaces\f[](7) T{ |
| 58 |
.na |
| 59 |
.nh |
| 60 |
Boot and monotonic clocks |
| 61 |
T} |
| 62 |
User CLONE_NEWUSER \f[B]user_namespaces\f[](7) T{ |
| 63 |
User and group IDs |
| 64 |
T} |
| 65 |
UTS CLONE_NEWUTS \f[B]uts_namespaces\f[](7) T{ |
| 66 |
.na |
| 67 |
.nh |
| 68 |
Hostname and NIS domain name |
| 69 |
T} |
| 70 |
.TE |
| 71 |
.\" |
| 72 |
.\" ==================== The namespaces API ==================== |
| 73 |
.\" |
| 74 |
.SS The namespaces API |
| 75 |
As well as various |
| 76 |
.I /proc |
| 77 |
files described below, |
| 78 |
the namespaces API includes the following system calls: |
| 79 |
.TP |
| 80 |
.BR clone (2) |
| 81 |
The |
| 82 |
.BR clone (2) |
| 83 |
system call creates a new process. |
| 84 |
If the |
| 85 |
.I flags |
| 86 |
argument of the call specifies one or more of the |
| 87 |
.B CLONE_NEW* |
| 88 |
flags listed above, then new namespaces are created for each flag, |
| 89 |
and the child process is made a member of those namespaces. |
| 90 |
(This system call also implements a number of features |
| 91 |
unrelated to namespaces.) |
| 92 |
.TP |
| 93 |
.BR setns (2) |
| 94 |
The |
| 95 |
.BR setns (2) |
| 96 |
system call allows the calling process to join an existing namespace. |
| 97 |
The namespace to join is specified via a file descriptor that refers to |
| 98 |
one of the |
| 99 |
.IR /proc/ pid /ns |
| 100 |
files described below. |
| 101 |
.TP |
| 102 |
.BR unshare (2) |
| 103 |
The |
| 104 |
.BR unshare (2) |
| 105 |
system call moves the calling process to a new namespace. |
| 106 |
If the |
| 107 |
.I flags |
| 108 |
argument of the call specifies one or more of the |
| 109 |
.B CLONE_NEW* |
| 110 |
flags listed above, then new namespaces are created for each flag, |
| 111 |
and the calling process is made a member of those namespaces. |
| 112 |
(This system call also implements a number of features |
| 113 |
unrelated to namespaces.) |
| 114 |
.TP |
| 115 |
.BR ioctl (2) |
| 116 |
Various |
| 117 |
.BR ioctl (2) |
| 118 |
operations can be used to discover information about namespaces. |
| 119 |
These operations are described in |
| 120 |
.BR ioctl_nsfs (2). |
| 121 |
.P |
| 122 |
Creation of new namespaces using |
| 123 |
.BR clone (2) |
| 124 |
and |
| 125 |
.BR unshare (2) |
| 126 |
in most cases requires the |
| 127 |
.B CAP_SYS_ADMIN |
| 128 |
capability, since, in the new namespace, |
| 129 |
the creator will have the power to change global resources |
| 130 |
that are visible to other processes that are subsequently created in, |
| 131 |
or join the namespace. |
| 132 |
User namespaces are the exception: since Linux 3.8, |
| 133 |
no privilege is required to create a user namespace. |
| 134 |
.\" |
| 135 |
.\" ==================== The /proc/[pid]/ns/ directory ==================== |
| 136 |
.\" |
| 137 |
.SS The \f[I]/proc/\f[]pid\f[I]/ns/\f[] directory |
| 138 |
Each process has a |
| 139 |
.IR /proc/ pid /ns/ |
| 140 |
.\" See commit 6b4e306aa3dc94a0545eb9279475b1ab6209a31f |
| 141 |
subdirectory containing one entry for each namespace that |
| 142 |
supports being manipulated by |
| 143 |
.BR setns (2): |
| 144 |
.P |
| 145 |
.in +4n |
| 146 |
.EX |
| 147 |
.RB $ " ls \-l /proc/$$/ns | awk \[aq]{print $1, $9, $10, $11}\[aq]" |
| 148 |
total 0 |
| 149 |
lrwxrwxrwx.\& cgroup \-> cgroup:[4026531835] |
| 150 |
lrwxrwxrwx.\& ipc \-> ipc:[4026531839] |
| 151 |
lrwxrwxrwx.\& mnt \-> mnt:[4026531840] |
| 152 |
lrwxrwxrwx.\& net \-> net:[4026531969] |
| 153 |
lrwxrwxrwx.\& pid \-> pid:[4026531836] |
| 154 |
lrwxrwxrwx.\& pid_for_children \-> pid:[4026531834] |
| 155 |
lrwxrwxrwx.\& time \-> time:[4026531834] |
| 156 |
lrwxrwxrwx.\& time_for_children \-> time:[4026531834] |
| 157 |
lrwxrwxrwx.\& user \-> user:[4026531837] |
| 158 |
lrwxrwxrwx.\& uts \-> uts:[4026531838] |
| 159 |
.EE |
| 160 |
.in |
| 161 |
.P |
| 162 |
Bind mounting (see |
| 163 |
.BR mount (2)) |
| 164 |
one of the files in this directory |
| 165 |
to somewhere else in the filesystem keeps |
| 166 |
the corresponding namespace of the process specified by |
| 167 |
.I pid |
| 168 |
alive even if all processes currently in the namespace terminate. |
| 169 |
.P |
| 170 |
Opening one of the files in this directory |
| 171 |
(or a file that is bind mounted to one of these files) |
| 172 |
returns a file handle for |
| 173 |
the corresponding namespace of the process specified by |
| 174 |
.IR pid . |
| 175 |
As long as this file descriptor remains open, |
| 176 |
the namespace will remain alive, |
| 177 |
even if all processes in the namespace terminate. |
| 178 |
The file descriptor can be passed to |
| 179 |
.BR setns (2). |
| 180 |
.P |
| 181 |
In Linux 3.7 and earlier, these files were visible as hard links. |
| 182 |
Since Linux 3.8, |
| 183 |
.\" commit bf056bfa80596a5d14b26b17276a56a0dcb080e5 |
| 184 |
they appear as symbolic links. |
| 185 |
If two processes are in the same namespace, |
| 186 |
then the device IDs and inode numbers of their |
| 187 |
.IR /proc/ pid /ns/ xxx |
| 188 |
symbolic links will be the same; |
| 189 |
an application can check this using the |
| 190 |
.I stat.st_dev |
| 191 |
.\" Eric Biederman: "I reserve the right for st_dev to be significant |
| 192 |
.\" when comparing namespaces." |
| 193 |
.\" https://lore.kernel.org/lkml/[email protected]/ |
| 194 |
.\" Re: Documenting the ioctl interfaces to discover relationships... |
| 195 |
.\" Date: Mon, 12 Dec 2016 11:30:38 +1300 |
| 196 |
and |
| 197 |
.I stat.st_ino |
| 198 |
fields returned by |
| 199 |
.BR stat (2). |
| 200 |
The content of this symbolic link is a string containing |
| 201 |
the namespace type and inode number as in the following example: |
| 202 |
.P |
| 203 |
.in +4n |
| 204 |
.EX |
| 205 |
.RB $ " readlink /proc/$$/ns/uts" |
| 206 |
uts:[4026531838] |
| 207 |
.EE |
| 208 |
.in |
| 209 |
.P |
| 210 |
The symbolic links in this subdirectory are as follows: |
| 211 |
.TP |
| 212 |
.IR /proc/ pid /ns/cgroup " (since Linux 4.6)" |
| 213 |
This file is a handle for the cgroup namespace of the process. |
| 214 |
.TP |
| 215 |
.IR /proc/ pid /ns/ipc " (since Linux 3.0)" |
| 216 |
This file is a handle for the IPC namespace of the process. |
| 217 |
.TP |
| 218 |
.IR /proc/ pid /ns/mnt " (since Linux 3.8)" |
| 219 |
.\" commit 8823c079ba7136dc1948d6f6dcb5f8022bde438e |
| 220 |
This file is a handle for the mount namespace of the process. |
| 221 |
.TP |
| 222 |
.IR /proc/ pid /ns/net " (since Linux 3.0)" |
| 223 |
This file is a handle for the network namespace of the process. |
| 224 |
.TP |
| 225 |
.IR /proc/ pid /ns/pid " (since Linux 3.8)" |
| 226 |
.\" commit 57e8391d327609cbf12d843259c968b9e5c1838f |
| 227 |
This file is a handle for the PID namespace of the process. |
| 228 |
This handle is permanent for the lifetime of the process |
| 229 |
(i.e., a process's PID namespace membership never changes). |
| 230 |
.TP |
| 231 |
.IR /proc/ pid /ns/pid_for_children " (since Linux 4.12)" |
| 232 |
.\" commit eaa0d190bfe1ed891b814a52712dcd852554cb08 |
| 233 |
This file is a handle for the PID namespace of |
| 234 |
child processes created by this process. |
| 235 |
This can change as a consequence of calls to |
| 236 |
.BR unshare (2) |
| 237 |
and |
| 238 |
.BR setns (2) |
| 239 |
(see |
| 240 |
.BR pid_namespaces (7)), |
| 241 |
so the file may differ from |
| 242 |
.IR /proc/ pid /ns/pid . |
| 243 |
The symbolic link gains a value only after the first child process |
| 244 |
is created in the namespace. |
| 245 |
(Beforehand, |
| 246 |
.BR readlink (2) |
| 247 |
of the symbolic link will return an empty buffer.) |
| 248 |
.TP |
| 249 |
.IR /proc/ pid /ns/time " (since Linux 5.6)" |
| 250 |
This file is a handle for the time namespace of the process. |
| 251 |
.TP |
| 252 |
.IR /proc/ pid /ns/time_for_children " (since Linux 5.6)" |
| 253 |
This file is a handle for the time namespace of |
| 254 |
child processes created by this process. |
| 255 |
This can change as a consequence of calls to |
| 256 |
.BR unshare (2) |
| 257 |
and |
| 258 |
.BR setns (2) |
| 259 |
(see |
| 260 |
.BR time_namespaces (7)), |
| 261 |
so the file may differ from |
| 262 |
.IR /proc/ pid /ns/time . |
| 263 |
.TP |
| 264 |
.IR /proc/ pid /ns/user " (since Linux 3.8)" |
| 265 |
.\" commit cde1975bc242f3e1072bde623ef378e547b73f91 |
| 266 |
This file is a handle for the user namespace of the process. |
| 267 |
.TP |
| 268 |
.IR /proc/ pid /ns/uts " (since Linux 3.0)" |
| 269 |
This file is a handle for the UTS namespace of the process. |
| 270 |
.P |
| 271 |
Permission to dereference or read |
| 272 |
.RB ( readlink (2)) |
| 273 |
these symbolic links is governed by a ptrace access mode |
| 274 |
.B PTRACE_MODE_READ_FSCREDS |
| 275 |
check; |
| 276 |
see |
| 277 |
.BR ptrace (2). |
| 278 |
.\" |
| 279 |
.\" ==================== The /proc/sys/user directory ==================== |
| 280 |
.\" |
| 281 |
.SS The \f[I]/proc/sys/user\f[] directory |
| 282 |
The files in the |
| 283 |
.I /proc/sys/user |
| 284 |
directory (which is present since Linux 4.9) expose limits |
| 285 |
on the number of namespaces of various types that can be created. |
| 286 |
The files are as follows: |
| 287 |
.TP |
| 288 |
.I max_cgroup_namespaces |
| 289 |
The value in this file defines a per-user limit on the number of |
| 290 |
cgroup namespaces that may be created in the user namespace. |
| 291 |
.TP |
| 292 |
.I max_ipc_namespaces |
| 293 |
The value in this file defines a per-user limit on the number of |
| 294 |
ipc namespaces that may be created in the user namespace. |
| 295 |
.TP |
| 296 |
.I max_mnt_namespaces |
| 297 |
The value in this file defines a per-user limit on the number of |
| 298 |
mount namespaces that may be created in the user namespace. |
| 299 |
.TP |
| 300 |
.I max_net_namespaces |
| 301 |
The value in this file defines a per-user limit on the number of |
| 302 |
network namespaces that may be created in the user namespace. |
| 303 |
.TP |
| 304 |
.I max_pid_namespaces |
| 305 |
The value in this file defines a per-user limit on the number of |
| 306 |
PID namespaces that may be created in the user namespace. |
| 307 |
.TP |
| 308 |
.IR max_time_namespaces " (since Linux 5.7)" |
| 309 |
.\" commit eeec26d5da8248ea4e240b8795bb4364213d3247 |
| 310 |
The value in this file defines a per-user limit on the number of |
| 311 |
time namespaces that may be created in the user namespace. |
| 312 |
.TP |
| 313 |
.I max_user_namespaces |
| 314 |
The value in this file defines a per-user limit on the number of |
| 315 |
user namespaces that may be created in the user namespace. |
| 316 |
.TP |
| 317 |
.I max_uts_namespaces |
| 318 |
The value in this file defines a per-user limit on the number of |
| 319 |
uts namespaces that may be created in the user namespace. |
| 320 |
.P |
| 321 |
Note the following details about these files: |
| 322 |
.IP \[bu] 3 |
| 323 |
The values in these files are modifiable by privileged processes. |
| 324 |
.IP \[bu] |
| 325 |
The values exposed by these files are the limits for the user namespace |
| 326 |
in which the opening process resides. |
| 327 |
.IP \[bu] |
| 328 |
The limits are per-user. |
| 329 |
Each user in the same user namespace |
| 330 |
can create namespaces up to the defined limit. |
| 331 |
.IP \[bu] |
| 332 |
The limits apply to all users, including UID 0. |
| 333 |
.IP \[bu] |
| 334 |
These limits apply in addition to any other per-namespace |
| 335 |
limits (such as those for PID and user namespaces) that may be enforced. |
| 336 |
.IP \[bu] |
| 337 |
Upon encountering these limits, |
| 338 |
.BR clone (2) |
| 339 |
and |
| 340 |
.BR unshare (2) |
| 341 |
fail with the error |
| 342 |
.BR ENOSPC . |
| 343 |
.IP \[bu] |
| 344 |
For the initial user namespace, |
| 345 |
the default value in each of these files is half the limit on the number |
| 346 |
of threads that may be created |
| 347 |
.RI ( /proc/sys/kernel/threads\-max ). |
| 348 |
In all descendant user namespaces, the default value in each file is |
| 349 |
.BR MAXINT . |
| 350 |
.IP \[bu] |
| 351 |
When a namespace is created, the object is also accounted |
| 352 |
against ancestor namespaces. |
| 353 |
More precisely: |
| 354 |
.RS |
| 355 |
.IP \[bu] 3 |
| 356 |
Each user namespace has a creator UID. |
| 357 |
.IP \[bu] |
| 358 |
When a namespace is created, |
| 359 |
it is accounted against the creator UIDs in each of the |
| 360 |
ancestor user namespaces, |
| 361 |
and the kernel ensures that the corresponding namespace limit |
| 362 |
for the creator UID in the ancestor namespace is not exceeded. |
| 363 |
.IP \[bu] |
| 364 |
The aforementioned point ensures that creating a new user namespace |
| 365 |
cannot be used as a means to escape the limits in force |
| 366 |
in the current user namespace. |
| 367 |
.RE |
| 368 |
.\" |
| 369 |
.SS Namespace lifetime |
| 370 |
Absent any other factors, |
| 371 |
a namespace is automatically torn down when the last process in |
| 372 |
the namespace terminates or leaves the namespace. |
| 373 |
However, there are a number of other factors that may pin |
| 374 |
a namespace into existence even though it has no member processes. |
| 375 |
These factors include the following: |
| 376 |
.IP \[bu] 3 |
| 377 |
An open file descriptor or a bind mount exists for the corresponding |
| 378 |
.IR /proc/ pid /ns/* |
| 379 |
file. |
| 380 |
.IP \[bu] |
| 381 |
The namespace is hierarchical (i.e., a PID or user namespace), |
| 382 |
and has a child namespace. |
| 383 |
.IP \[bu] |
| 384 |
It is a user namespace that owns one or more nonuser namespaces. |
| 385 |
.IP \[bu] |
| 386 |
It is a PID namespace, |
| 387 |
and there is a process that refers to the namespace via a |
| 388 |
.IR /proc/ pid /ns/pid_for_children |
| 389 |
symbolic link. |
| 390 |
.IP \[bu] |
| 391 |
It is a time namespace, |
| 392 |
and there is a process that refers to the namespace via a |
| 393 |
.IR /proc/ pid /ns/time_for_children |
| 394 |
symbolic link. |
| 395 |
.IP \[bu] |
| 396 |
It is an IPC namespace, and a corresponding mount of an |
| 397 |
.I mqueue |
| 398 |
filesystem (see |
| 399 |
.BR mq_overview (7)) |
| 400 |
refers to this namespace. |
| 401 |
.IP \[bu] |
| 402 |
It is a PID namespace, and a corresponding mount of a |
| 403 |
.BR proc (5) |
| 404 |
filesystem refers to this namespace. |
| 405 |
.SH EXAMPLES |
| 406 |
See |
| 407 |
.BR clone (2) |
| 408 |
and |
| 409 |
.BR user_namespaces (7). |
| 410 |
.SH SEE ALSO |
| 411 |
.BR nsenter (1), |
| 412 |
.BR readlink (1), |
| 413 |
.BR unshare (1), |
| 414 |
.BR clone (2), |
| 415 |
.BR ioctl_nsfs (2), |
| 416 |
.BR setns (2), |
| 417 |
.BR unshare (2), |
| 418 |
.BR proc (5), |
| 419 |
.BR capabilities (7), |
| 420 |
.BR cgroup_namespaces (7), |
| 421 |
.BR cgroups (7), |
| 422 |
.BR credentials (7), |
| 423 |
.BR ipc_namespaces (7), |
| 424 |
.BR network_namespaces (7), |
| 425 |
.BR pid_namespaces (7), |
| 426 |
.BR user_namespaces (7), |
| 427 |
.BR uts_namespaces (7), |
| 428 |
.BR lsns (8), |
| 429 |
.BR switch_root (8) |