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