man7/namespaces.7

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