man7/namespaces.7

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