original/man7/namespaces.7

   1 .\" Copyright (c) 2013 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 2014-09-21 "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
  38 Linux provides the following namespaces:
  39 .TS
  40 lB lB lB
  41 l lB l.
  42 Namespace       Constant        Isolates
  43 IPC     CLONE_NEWIPC    System V IPC, POSIX message queues
  44 Network CLONE_NEWNET    Network devices, stacks, ports, etc.
  45 Mount   CLONE_NEWNS     Mount points
  46 PID     CLONE_NEWPID    Process IDs
  47 User    CLONE_NEWUSER   User and group IDs
  48 UTS     CLONE_NEWUTS    Hostname and NIS domain name
  49 .TE
  50
  51 This page describes the various namespaces and the associated
  52 .I /proc
  53 files, and summarizes the APIs for working with namespaces.
  54 .\"
  55 .\" ==================== The namespaces API ====================
  56 .\"
  57 .SS The namespaces API
  58 As well as various
  59 .I /proc
  60 files described below,
  61 the namespaces API includes the following system calls:
  62 .TP
  63 .BR clone (2)
  64 The
  65 .BR clone (2)
  66 system call creates a new process.
  67 If the
  68 .I flags
  69 argument of the call specifies one or more of the
  70 .B CLONE_NEW*
  71 flags listed below, then new namespaces are created for each flag,
  72 and the child process is made a member of those namespaces.
  73 (This system call also implements a number of features
  74 unrelated to namespaces.)
  75 .TP
  76 .BR setns (2)
  77 The
  78 .BR setns (2)
  79 system call allows the calling process to join an existing namespace.
  80 The namespace to join is specified via a file descriptor that refers to
  81 one of the
  82 .IR /proc/[pid]/ns
  83 files described below.
  84 .TP
  85 .BR unshare (2)
  86 The
  87 .BR unshare (2)
  88 system call moves the calling process to a new namespace.
  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 calling process is made a member of those namespaces.
  95 (This system call also implements a number of features
  96 unrelated to namespaces.)
  97 .PP
  98 Creation of new namespaces using
  99 .BR clone (2)
 100 and
 101 .BR unshare (2)
 102 in most cases requires the
 103 .BR CAP_SYS_ADMIN
 104 capability.
 105 User namespaces are the exception: since Linux 3.8,
 106 no privilege is required to create a user namespace.
 107 .\"
 108 .\" ==================== The /proc/[pid]/ns/ directory ====================
 109 .\"
 110 .SS The /proc/[pid]/ns/ directory
 111 Each process has a
 112 .IR /proc/[pid]/ns/
 113 .\" See commit 6b4e306aa3dc94a0545eb9279475b1ab6209a31f
 114 subdirectory containing one entry for each namespace that
 115 supports being manipulated by
 116 .BR setns (2):
 117
 118 .in +4n
 119 .nf
 120 $ \fBls -l /proc/$$/ns\fP
 121 total 0
 122 lrwxrwxrwx. 1 mtk mtk 0 Jan 14 01:20 ipc -> ipc:[4026531839]
 123 lrwxrwxrwx. 1 mtk mtk 0 Jan 14 01:20 mnt -> mnt:[4026531840]
 124 lrwxrwxrwx. 1 mtk mtk 0 Jan 14 01:20 net -> net:[4026531956]
 125 lrwxrwxrwx. 1 mtk mtk 0 Jan 14 01:20 pid -> pid:[4026531836]
 126 lrwxrwxrwx. 1 mtk mtk 0 Jan 14 01:20 user -> user:[4026531837]
 127 lrwxrwxrwx. 1 mtk mtk 0 Jan 14 01:20 uts -> uts:[4026531838]
 128 .fi
 129 .in
 130
 131 Bind mounting (see
 132 .BR mount (2))
 133 one of the files in this directory
 134 to somewhere else in the filesystem keeps
 135 the corresponding namespace of the process specified by
 136 .I pid
 137 alive even if all processes currently in the namespace terminate.
 138
 139 Opening one of the files in this directory
 140 (or a file that is bind mounted to one of these files)
 141 returns a file handle for
 142 the corresponding namespace of the process specified by
 143 .IR pid .
 144 As long as this file descriptor remains open,
 145 the namespace will remain alive,
 146 even if all processes in the namespace terminate.
 147 The file descriptor can be passed to
 148 .BR setns (2).
 149
 150 In Linux 3.7 and earlier, these files were visible as hard links.
 151 Since Linux 3.8, they appear as symbolic links.
 152 If two processes are in the same namespace, then the inode numbers of their
 153 .IR /proc/[pid]/ns/xxx
 154 symbolic links will be the same; an application can check this using the
 155 .I stat.st_ino
 156 field returned by
 157 .BR stat (2).
 158 The content of this symbolic link is a string containing
 159 the namespace type and inode number as in the following example:
 160
 161 .in +4n
 162 .nf
 163 $ \fBreadlink /proc/$$/ns/uts\fP
 164 uts:[4026531838]
 165 .fi
 166 .in
 167
 168 The files in this subdirectory are as follows:
 169 .TP
 170 .IR /proc/[pid]/ns/ipc " (since Linux 3.0)"
 171 This file is a handle for the IPC namespace of the process.
 172 .TP
 173 .IR /proc/[pid]/ns/mnt " (since Linux 3.8)"
 174 This file is a handle for the mount namespace of the process.
 175 .TP
 176 .IR /proc/[pid]/ns/net " (since Linux 3.0)"
 177 This file is a handle for the network namespace of the process.
 178 .TP
 179 .IR /proc/[pid]/ns/pid " (since Linux 3.8)"
 180 This file is a handle for the PID namespace of the process.
 181 .TP
 182 .IR /proc/[pid]/ns/user " (since Linux 3.8)"
 183 This file is a handle for the user namespace of the process.
 184 .TP
 185 .IR /proc/[pid]/ns/uts " (since Linux 3.0)"
 186 This file is a handle for the UTS namespace of the process.
 187 .\"
 188 .\" ==================== IPC namespaces ====================
 189 .\"
 190 .SS IPC namespaces (CLONE_NEWIPC)
 191 IPC namespaces isolate certain IPC resources,
 192 namely, System V IPC objects (see
 193 .BR svipc (7))
 194 and (since Linux 2.6.30)
 195 .\" commit 7eafd7c74c3f2e67c27621b987b28397110d643f
 196 .\" https://lwn.net/Articles/312232/
 197 POSIX message queues (see
 198 .BR mq_overview (7)).
 199 The common characteristic of these IPC mechanisms is that IPC
 200 objects are identified by mechanisms other than filesystem
 201 pathnames.
 202
 203 Each IPC namespace has its own set of System V IPC identifiers and
 204 its own POSIX message queue filesystem.
 205 Objects created in an IPC namespace are visible to all other processes
 206 that are members of that namespace,
 207 but are not visible to processes in other IPC namespaces.
 208
 209 The following
 210 .I /proc
 211 interfaces are distinct in each IPC namespace:
 212 .IP * 3
 213 The POSIX message queue interfaces in
 214 .IR /proc/sys/fs/mqueue .
 215 .IP *
 216 The System V IPC interfaces in
 217 .IR /proc/sys/kernel ,
 218 namely:
 219 .IR msgmax ,
 220 .IR msgmnb  ,
 221 .IR msgmni ,
 222 .IR sem ,
 223 .IR shmall ,
 224 .IR shmmax ,
 225 .IR shmmni ,
 226 and
 227 .IR shm_rmid_forced .
 228 .IP *
 229 The System V IPC interfaces in
 230 .IR /proc/sysvipc .
 231 .PP
 232 When an IPC namespace is destroyed
 233 (i.e., when the last process that is a member of the namespace terminates),
 234 all IPC objects in the namespace are automatically destroyed.
 235
 236 Use of IPC namespaces requires a kernel that is configured with the
 237 .B CONFIG_IPC_NS
 238 option.
 239 .\"
 240 .\" ==================== Network namespaces ====================
 241 .\"
 242 .SS Network namespaces (CLONE_NEWNET)
 243 Network namespaces provide isolation of the system resources associated
 244 with networking: network devices, IPv4 and IPv6 protocol stacks,
 245 IP routing tables, firewalls, the
 246 .I /proc/net
 247 directory, the
 248 .I /sys/class/net
 249 directory, port numbers (sockets), and so on.
 250 A physical network device can live in exactly one
 251 network namespace.
 252 A virtual network device ("veth") pair provides a pipe-like abstraction
 253 .\" FIXME Add pointer to veth(4) page when it is eventually completed
 254 that can be used to create tunnels between network namespaces,
 255 and can be used to create a bridge to a physical network device
 256 in another namespace.
 257
 258 When a network namespace is freed
 259 (i.e., when the last process in the namespace terminates),
 260 its physical network devices are moved back to the
 261 initial network namespace (not to the parent of the process).
 262
 263 Use of network namespaces requires a kernel that is configured with the
 264 .B CONFIG_NET_NS
 265 option.
 266 .\"
 267 .\" ==================== Mount namespaces ====================
 268 .\"
 269 .SS Mount namespaces (CLONE_NEWNS)
 270 Mount namespaces isolate the set of filesystem mount points,
 271 meaning that processes in different mount namespaces can
 272 have different views of the filesystem hierarchy.
 273 The set of mounts in a mount namespace is modified using
 274 .BR mount (2)
 275 and
 276 .BR umount (2).
 277
 278 The
 279 .IR /proc/[pid]/mounts
 280 file (present since Linux 2.4.19)
 281 lists all the filesystems currently mounted in the
 282 process's mount namespace.
 283 The format of this file is documented in
 284 .BR fstab (5).
 285 Since kernel version 2.6.15, this file is pollable:
 286 after opening the file for reading, a change in this file
 287 (i.e., a filesystem mount or unmount) causes
 288 .BR select (2)
 289 to mark the file descriptor as readable, and
 290 .BR poll (2)
 291 and
 292 .BR epoll_wait (2)
 293 mark the file as having an error condition.
 294
 295 The
 296 .IR /proc/[pid]/mountstats
 297 file (present since Linux 2.6.17)
 298 exports information (statistics, configuration information)
 299 about the mount points in the process's mount namespace.
 300 This file is readable only by the owner of the process.
 301 Lines in this file have the form:
 302 .RS
 303 .in 12
 304 .nf
 305
 306 device /dev/sda7 mounted on /home with fstype ext3 [statistics]
 307 (       1      )            ( 2 )             (3 ) (4)
 308 .fi
 309 .in
 310
 311 The fields in each line are:
 312 .TP 5
 313 (1)
 314 The name of the mounted device
 315 (or "nodevice" if there is no corresponding device).
 316 .TP
 317 (2)
 318 The mount point within the filesystem tree.
 319 .TP
 320 (3)
 321 The filesystem type.
 322 .TP
 323 (4)
 324 Optional statistics and configuration information.
 325 Currently (as at Linux 2.6.26), only NFS filesystems export
 326 information via this field.
 327 .RE
 328 .\"
 329 .\" ==================== PID namespaces ====================
 330 .\"
 331 .SS PID namespaces (CLONE_NEWPID)
 332 See
 333 .BR pid_namespaces (7).
 334 .\"
 335 .\" ==================== User namespaces ====================
 336 .\"
 337 .SS User namespaces (CLONE_NEWUSER)
 338 See
 339 .BR user_namespaces (7).
 340 .\"
 341 .\" ==================== UTS namespaces ====================
 342 .\"
 343 .SS UTS namespaces (CLONE_NEWUTS)
 344 UTS namespaces provide isolation of two system identifiers:
 345 the hostname and the NIS domain name.
 346 These identifiers are set using
 347 .BR sethostname (2)
 348 and
 349 .BR setdomainname (2),
 350 and can be retrieved using
 351 .BR uname (2),
 352 .BR gethostname (2),
 353 and
 354 .BR getdomainname (2).
 355
 356 Use of UTS namespaces requires a kernel that is configured with the
 357 .B CONFIG_UTS_NS
 358 option.
 359 .SH CONFORMING TO
 360 Namespaces are a Linux-specific feature.
 361 .SH EXAMPLE
 362 See
 363 .BR user_namespaces (7).
 364 .SH SEE ALSO
 365 .BR nsenter (1),
 366 .BR readlink (1),
 367 .BR unshare (1),
 368 .BR clone (2),
 369 .BR setns (2),
 370 .BR unshare (2),
 371 .BR proc (5),
 372 .BR credentials (7),
 373 .BR capabilities (7),
 374 .BR pid_namespaces (7),
 375 .BR user_namespaces (7),
 376 .BR switch_root (8)
 377 .SH COLOPHON
 378 This page is part of release 3.79 of the Linux
 379 .I man-pages
 380 project.
 381 A description of the project,
 382 information about reporting bugs,
 383 and the latest version of this page,
 384 can be found at
 385 \%http://www.kernel.org/doc/man\-pages/.