1NAMESPACES(7)              Linux Programmer's Manual             NAMESPACES(7)
2
3
4

NAME

6       namespaces - overview of Linux namespaces
7

DESCRIPTION

9       A namespace wraps a global system resource in an abstraction that makes
10       it appear to the processes within the namespace that  they  have  their
11       own  isolated  instance  of the global resource.  Changes to the global
12       resource are visible to other processes that are members of  the  name‐
13       space,  but are invisible to other processes.  One use of namespaces is
14       to implement containers.
15
16       This page provides pointers to information  on  the  various  namespace
17       types,  describes  the  associated /proc files, and summarizes the APIs
18       for working with namespaces.
19
20   Namespace types
21       The following table shows the namespace types available on Linux.   The
22       second column of the table shows the flag value that is used to specify
23       the namespace type in various APIs.  The third  column  identifies  the
24       manual page that provides details on the namespace type.  The last col‐
25       umn is a summary of the resources that are isolated  by  the  namespace
26       type.
27
28       Namespace Flag            Page                  Isolates
29       Cgroup    CLONE_NEWCGROUP cgroup_namespaces(7)  Cgroup root
30                                                       directory
31       IPC       CLONE_NEWIPC    ipc_namespaces(7)     System V IPC, POSIX
32                                                       message queues
33       Network   CLONE_NEWNET    network_namespaces(7) Network devices,
34                                                       stacks, ports, etc.
35       Mount     CLONE_NEWNS     mount_namespaces(7)   Mount points
36       PID       CLONE_NEWPID    pid_namespaces(7)     Process IDs
37       Time      CLONE_NEWTIME   time_namespaces(7)    Boot and monotonic
38                                                       clocks
39       User      CLONE_NEWUSER   user_namespaces(7)    T{User and group IDs
40       T}
41       UTS       CLONE_NEWUTS    uts_namespaces(7)     Hostname and NIS
42                                                       domain name
43
44   The namespaces API
45       As well as various /proc files described below, the namespaces API  in‐
46       cludes the following system calls:
47
48       clone(2)
49              The  clone(2)  system  call creates a new process.  If the flags
50              argument of the call specifies one or  more  of  the  CLONE_NEW*
51              flags  listed  below,  then  new namespaces are created for each
52              flag, and the child process is made  a  member  of  those  name‐
53              spaces.   (This system call also implements a number of features
54              unrelated to namespaces.)
55
56       setns(2)
57              The setns(2) system call allows the calling process to  join  an
58              existing  namespace.   The  namespace to join is specified via a
59              file descriptor that refers to one of the  /proc/[pid]/ns  files
60              described below.
61
62       unshare(2)
63              The  unshare(2)  system  call moves the calling process to a new
64              namespace.  If the flags argument of the call specifies  one  or
65              more  of  the CLONE_NEW* flags listed below, then new namespaces
66              are created for each flag, and the calling  process  is  made  a
67              member of those namespaces.  (This system call also implements a
68              number of features unrelated to namespaces.)
69
70       ioctl(2)
71              Various ioctl(2) operations can be used to discover  information
72              about   namespaces.    These   operations   are   described   in
73              ioctl_ns(2).
74
75       Creation of new namespaces using clone(2) and unshare(2) in most  cases
76       requires the CAP_SYS_ADMIN capability, since, in the new namespace, the
77       creator will have the power to change global resources that are visible
78       to  other processes that are subsequently created in, or join the name‐
79       space.  User namespaces are the exception: since Linux 3.8,  no  privi‐
80       lege is required to create a user namespace.
81
82   The /proc/[pid]/ns/ directory
83       Each  process  has  a /proc/[pid]/ns/ subdirectory containing one entry
84       for each namespace that supports being manipulated by setns(2):
85
86           $ ls -l /proc/$$/ns | awk '{print $1, $9, $10, $11}'
87           total 0
88           lrwxrwxrwx. cgroup -> cgroup:[4026531835]
89           lrwxrwxrwx. ipc -> ipc:[4026531839]
90           lrwxrwxrwx. mnt -> mnt:[4026531840]
91           lrwxrwxrwx. net -> net:[4026531969]
92           lrwxrwxrwx. pid -> pid:[4026531836]
93           lrwxrwxrwx. pid_for_children -> pid:[4026531834]
94           lrwxrwxrwx. time -> time:[4026531834]
95           lrwxrwxrwx. time_for_children -> time:[4026531834]
96           lrwxrwxrwx. user -> user:[4026531837]
97           lrwxrwxrwx. uts -> uts:[4026531838]
98
99       Bind mounting (see mount(2)) one of the  files  in  this  directory  to
100       somewhere  else  in the filesystem keeps the corresponding namespace of
101       the process specified by pid alive even if all processes  currently  in
102       the namespace terminate.
103
104       Opening  one  of  the  files  in this directory (or a file that is bind
105       mounted to one of these files) returns a file  handle  for  the  corre‐
106       sponding  namespace  of  the process specified by pid.  As long as this
107       file descriptor remains open, the namespace will remain alive, even  if
108       all  processes  in the namespace terminate.  The file descriptor can be
109       passed to setns(2).
110
111       In Linux 3.7 and earlier, these  files  were  visible  as  hard  links.
112       Since  Linux  3.8, they appear as symbolic links.  If two processes are
113       in the same namespace, then the device IDs and inode numbers  of  their
114       /proc/[pid]/ns/xxx  symbolic links will be the same; an application can
115       check this using the stat.st_dev and  stat.st_ino  fields  returned  by
116       stat(2).   The content of this symbolic link is a string containing the
117       namespace type and inode number as in the following example:
118
119           $ readlink /proc/$$/ns/uts
120           uts:[4026531838]
121
122       The symbolic links in this subdirectory are as follows:
123
124       /proc/[pid]/ns/cgroup (since Linux 4.6)
125              This file is a handle for the cgroup namespace of the process.
126
127       /proc/[pid]/ns/ipc (since Linux 3.0)
128              This file is a handle for the IPC namespace of the process.
129
130       /proc/[pid]/ns/mnt (since Linux 3.8)
131              This file is a handle for the mount namespace of the process.
132
133       /proc/[pid]/ns/net (since Linux 3.0)
134              This file is a handle for the network namespace of the process.
135
136       /proc/[pid]/ns/pid (since Linux 3.8)
137              This file is a handle for the  PID  namespace  of  the  process.
138              This  handle is permanent for the lifetime of the process (i.e.,
139              a process's PID namespace membership never changes).
140
141       /proc/[pid]/ns/pid_for_children (since Linux 4.12)
142              This file is a handle for the PID namespace of  child  processes
143              created  by  this  process.  This can change as a consequence of
144              calls to unshare(2) and setns(2) (see pid_namespaces(7)), so the
145              file  may  differ  from  /proc/[pid]/ns/pid.   The symbolic link
146              gains a value only after the first child process is  created  in
147              the  namespace.   (Beforehand,  readlink(2) of the symbolic link
148              will return an empty buffer.)
149
150       /proc/[pid]/ns/time (since Linux 5.6)
151              This file is a handle for the time namespace of the process.
152
153       /proc/[pid]/ns/time_for_children (since Linux 5.6)
154              This file is a handle for the time namespace of child  processes
155              created  by  this  process.  This can change as a consequence of
156              calls to unshare(2) and setns(2)  (see  time_namespaces(7)),  so
157              the file may differ from /proc/[pid]/ns/time.
158
159       /proc/[pid]/ns/user (since Linux 3.8)
160              This file is a handle for the user namespace of the process.
161
162       /proc/[pid]/ns/uts (since Linux 3.0)
163              This file is a handle for the UTS namespace of the process.
164
165       Permission to dereference or read (readlink(2)) these symbolic links is
166       governed by a ptrace access mode  PTRACE_MODE_READ_FSCREDS  check;  see
167       ptrace(2).
168
169   The /proc/sys/user directory
170       The files in the /proc/sys/user directory (which is present since Linux
171       4.9) expose limits on the number of namespaces of  various  types  that
172       can be created.  The files are as follows:
173
174       max_cgroup_namespaces
175              The value in this file defines a per-user limit on the number of
176              cgroup namespaces that may be created in the user namespace.
177
178       max_ipc_namespaces
179              The value in this file defines a per-user limit on the number of
180              ipc namespaces that may be created in the user namespace.
181
182       max_mnt_namespaces
183              The value in this file defines a per-user limit on the number of
184              mount namespaces that may be created in the user namespace.
185
186       max_net_namespaces
187              The value in this file defines a per-user limit on the number of
188              network namespaces that may be created in the user namespace.
189
190       max_pid_namespaces
191              The value in this file defines a per-user limit on the number of
192              PID namespaces that may be created in the user namespace.
193
194       max_time_namespaces (since Linux 5.7)
195              The value in this file defines a per-user limit on the number of
196              time namespaces that may be created in the user namespace.
197
198       max_user_namespaces
199              The value in this file defines a per-user limit on the number of
200              user namespaces that may be created in the user namespace.
201
202       max_uts_namespaces
203              The value in this file defines a per-user limit on the number of
204              uts namespaces that may be created in the user namespace.
205
206       Note the following details about these files:
207
208       *  The values in these files are modifiable by privileged processes.
209
210       *  The  values exposed by these files are the limits for the user name‐
211          space in which the opening process resides.
212
213       *  The limits are per-user.  Each user in the same user  namespace  can
214          create namespaces up to the defined limit.
215
216       *  The limits apply to all users, including UID 0.
217
218       *  These  limits  apply  in  addition to any other per-namespace limits
219          (such as those for PID and user namespaces) that may be enforced.
220
221       *  Upon encountering these limits, clone(2) and  unshare(2)  fail  with
222          the error ENOSPC.
223
224       *  For  the  initial user namespace, the default value in each of these
225          files is half the limit on the number of threads that may be created
226          (/proc/sys/kernel/threads-max).   In all descendant user namespaces,
227          the default value in each file is MAXINT.
228
229       *  When a namespace is created, the object is  also  accounted  against
230          ancestor namespaces.  More precisely:
231
232          +  Each user namespace has a creator UID.
233
234          +  When  a namespace is created, it is accounted against the creator
235             UIDs in each of the ancestor user namespaces, and the kernel  en‐
236             sures  that the corresponding namespace limit for the creator UID
237             in the ancestor namespace is not exceeded.
238
239          +  The aforementioned point ensures that creating a new  user  name‐
240             space  cannot be used as a means to escape the limits in force in
241             the current user namespace.
242
243   Namespace lifetime
244       Absent any other factors, a namespace is automatically torn  down  when
245       the  last  process in the namespace terminates or leaves the namespace.
246       However, there are a number of other factors that may pin  a  namespace
247       into  existence  even though it has no member processes.  These factors
248       include the following:
249
250       *  An open file descriptor or a bind mount exists for the corresponding
251          /proc/[pid]/ns/* file.
252
253       *  The  namespace  is hierarchical (i.e., a PID or user namespace), and
254          has a child namespace.
255
256       *  It is a user namespace that owns one or more nonuser namespaces.
257
258       *  It is a PID namespace, and there is a process  that  refers  to  the
259          namespace via a /proc/[pid]/ns/pid_for_children symbolic link.
260
261       *  It  is  a  time namespace, and there is a process that refers to the
262          namespace via a /proc/[pid]/ns/time_for_children symbolic link.
263
264       *  It is an IPC namespace, and  a  corresponding  mount  of  an  mqueue
265          filesystem (see mq_overview(7)) refers to this namespace.
266
267       *  It  is  a  PID  namespace,  and  a  corresponding mount of a proc(5)
268          filesystem refers to this namespace.
269

EXAMPLES

271       See clone(2) and user_namespaces(7).
272

SEE ALSO

274       nsenter(1), readlink(1), unshare(1), clone(2),  ioctl_ns(2),  setns(2),
275       unshare(2), proc(5), capabilities(7), cgroup_namespaces(7), cgroups(7),
276       credentials(7),  ipc_namespaces(7),  network_namespaces(7),   pid_name‐
277       spaces(7),      user_namespaces(7),     uts_namespaces(7),     lsns(8),
278       switch_root(8)
279

COLOPHON

281       This page is part of release 5.12 of the Linux  man-pages  project.   A
282       description  of  the project, information about reporting bugs, and the
283       latest    version    of    this    page,    can     be     found     at
284       https://www.kernel.org/doc/man-pages/.
285
286
287
288Linux                             2021-03-22                     NAMESPACES(7)
Impressum