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>
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
8 .TH namespaces 7 (date) "Linux man-pages (unreleased)"
10 namespaces \- overview of Linux namespaces
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.
19 This page provides pointers to information on the various namespace types,
20 describes the associated
22 files, and summarizes the APIs for working with namespaces.
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
36 Namespace Flag Page Isolates
38 Cgroup CLONE_NEWCGROUP \fBcgroup_namespaces\fP(7) T{
43 IPC CLONE_NEWIPC \fBipc_namespaces\fP(7) T{
49 Network CLONE_NEWNET \fBnetwork_namespaces\fP(7) T{
55 Mount CLONE_NEWNS \fBmount_namespaces\fP(7) Mount points
56 PID CLONE_NEWPID \fBpid_namespaces\fP(7) Process IDs
57 Time CLONE_NEWTIME \fBtime_namespaces\fP(7) T{
60 Boot and monotonic clocks
62 User CLONE_NEWUSER \fBuser_namespaces\fP(7) T{
65 UTS CLONE_NEWUTS \fButs_namespaces\fP(7) T{
68 Hostname and NIS domain name
72 .\" ==================== The namespaces API ====================
74 .SS The namespaces API
77 files described below,
78 the namespaces API includes the following system calls:
83 system call creates a new process.
86 argument of the call specifies one or more of the
88 flags listed above, then new namespaces are created for each flag,
89 and the child process is made a member of those namespaces.
90 (This system call also implements a number of features
91 unrelated to namespaces.)
96 system call allows the calling process to join an existing namespace.
97 The namespace to join is specified via a file descriptor that refers to
100 files described below.
105 system call moves the calling process to a new namespace.
108 argument of the call specifies one or more of the
110 flags listed above, then new namespaces are created for each flag,
111 and the calling process is made a member of those namespaces.
112 (This system call also implements a number of features
113 unrelated to namespaces.)
118 operations can be used to discover information about namespaces.
119 These operations are described in
122 Creation of new namespaces using
126 in most cases requires the
128 capability, since, in the new namespace,
129 the creator will have the power to change global resources
130 that are visible to other processes that are subsequently created in,
131 or join the namespace.
132 User namespaces are the exception: since Linux 3.8,
133 no privilege is required to create a user namespace.
135 .\" ==================== The /proc/[pid]/ns/ directory ====================
137 .SS The \fI/proc/\fPpid\fI/ns/\fP directory
140 .\" See commit 6b4e306aa3dc94a0545eb9279475b1ab6209a31f
141 subdirectory containing one entry for each namespace that
142 supports being manipulated by
147 $ \fBls \-l /proc/$$/ns | awk \[aq]{print $1, $9, $10, $11}\[aq]\fP
149 lrwxrwxrwx. cgroup \-> cgroup:[4026531835]
150 lrwxrwxrwx. ipc \-> ipc:[4026531839]
151 lrwxrwxrwx. mnt \-> mnt:[4026531840]
152 lrwxrwxrwx. net \-> net:[4026531969]
153 lrwxrwxrwx. pid \-> pid:[4026531836]
154 lrwxrwxrwx. pid_for_children \-> pid:[4026531834]
155 lrwxrwxrwx. time \-> time:[4026531834]
156 lrwxrwxrwx. time_for_children \-> time:[4026531834]
157 lrwxrwxrwx. user \-> user:[4026531837]
158 lrwxrwxrwx. uts \-> uts:[4026531838]
164 one of the files in this directory
165 to somewhere else in the filesystem keeps
166 the corresponding namespace of the process specified by
168 alive even if all processes currently in the namespace terminate.
170 Opening one of the files in this directory
171 (or a file that is bind mounted to one of these files)
172 returns a file handle for
173 the corresponding namespace of the process specified by
175 As long as this file descriptor remains open,
176 the namespace will remain alive,
177 even if all processes in the namespace terminate.
178 The file descriptor can be passed to
181 In Linux 3.7 and earlier, these files were visible as hard links.
183 .\" commit bf056bfa80596a5d14b26b17276a56a0dcb080e5
184 they appear as symbolic links.
185 If two processes are in the same namespace,
186 then the device IDs and inode numbers of their
187 .IR /proc/ pid /ns/ xxx
188 symbolic links will be the same; an application can check this using the
190 .\" Eric Biederman: "I reserve the right for st_dev to be significant
191 .\" when comparing namespaces."
192 .\" https://lore.kernel.org/lkml/87poky5ca9.fsf@xmission.com/
193 .\" Re: Documenting the ioctl interfaces to discover relationships...
194 .\" Date: Mon, 12 Dec 2016 11:30:38 +1300
199 The content of this symbolic link is a string containing
200 the namespace type and inode number as in the following example:
204 $ \fBreadlink /proc/$$/ns/uts\fP
209 The symbolic links in this subdirectory are as follows:
211 .IR /proc/ pid /ns/cgroup " (since Linux 4.6)"
212 This file is a handle for the cgroup namespace of the process.
214 .IR /proc/ pid /ns/ipc " (since Linux 3.0)"
215 This file is a handle for the IPC namespace of the process.
217 .IR /proc/ pid /ns/mnt " (since Linux 3.8)"
218 .\" commit 8823c079ba7136dc1948d6f6dcb5f8022bde438e
219 This file is a handle for the mount namespace of the process.
221 .IR /proc/ pid /ns/net " (since Linux 3.0)"
222 This file is a handle for the network namespace of the process.
224 .IR /proc/ pid /ns/pid " (since Linux 3.8)"
225 .\" commit 57e8391d327609cbf12d843259c968b9e5c1838f
226 This file is a handle for the PID namespace of the process.
227 This handle is permanent for the lifetime of the process
228 (i.e., a process's PID namespace membership never changes).
230 .IR /proc/ pid /ns/pid_for_children " (since Linux 4.12)"
231 .\" commit eaa0d190bfe1ed891b814a52712dcd852554cb08
232 This file is a handle for the PID namespace of
233 child processes created by this process.
234 This can change as a consequence of calls to
239 .BR pid_namespaces (7)),
240 so the file may differ from
241 .IR /proc/ pid /ns/pid .
242 The symbolic link gains a value only after the first child process
243 is created in the namespace.
246 of the symbolic link will return an empty buffer.)
248 .IR /proc/ pid /ns/time " (since Linux 5.6)"
249 This file is a handle for the time namespace of the process.
251 .IR /proc/ pid /ns/time_for_children " (since Linux 5.6)"
252 This file is a handle for the time namespace of
253 child processes created by this process.
254 This can change as a consequence of calls to
259 .BR time_namespaces (7)),
260 so the file may differ from
261 .IR /proc/ pid /ns/time .
263 .IR /proc/ pid /ns/user " (since Linux 3.8)"
264 .\" commit cde1975bc242f3e1072bde623ef378e547b73f91
265 This file is a handle for the user namespace of the process.
267 .IR /proc/ pid /ns/uts " (since Linux 3.0)"
268 This file is a handle for the UTS namespace of the process.
270 Permission to dereference or read
272 these symbolic links is governed by a ptrace access mode
273 .B PTRACE_MODE_READ_FSCREDS
277 .\" ==================== The /proc/sys/user directory ====================
279 .SS The \fI/proc/sys/user\fP directory
282 directory (which is present since Linux 4.9) expose limits
283 on the number of namespaces of various types that can be created.
284 The files are as follows:
286 .I max_cgroup_namespaces
287 The value in this file defines a per-user limit on the number of
288 cgroup namespaces that may be created in the user namespace.
290 .I max_ipc_namespaces
291 The value in this file defines a per-user limit on the number of
292 ipc namespaces that may be created in the user namespace.
294 .I max_mnt_namespaces
295 The value in this file defines a per-user limit on the number of
296 mount namespaces that may be created in the user namespace.
298 .I max_net_namespaces
299 The value in this file defines a per-user limit on the number of
300 network namespaces that may be created in the user namespace.
302 .I max_pid_namespaces
303 The value in this file defines a per-user limit on the number of
304 PID namespaces that may be created in the user namespace.
306 .IR max_time_namespaces " (since Linux 5.7)"
307 .\" commit eeec26d5da8248ea4e240b8795bb4364213d3247
308 The value in this file defines a per-user limit on the number of
309 time namespaces that may be created in the user namespace.
311 .I max_user_namespaces
312 The value in this file defines a per-user limit on the number of
313 user namespaces that may be created in the user namespace.
315 .I max_uts_namespaces
316 The value in this file defines a per-user limit on the number of
317 uts namespaces that may be created in the user namespace.
319 Note the following details about these files:
321 The values in these files are modifiable by privileged processes.
323 The values exposed by these files are the limits for the user namespace
324 in which the opening process resides.
326 The limits are per-user.
327 Each user in the same user namespace
328 can create namespaces up to the defined limit.
330 The limits apply to all users, including UID 0.
332 These limits apply in addition to any other per-namespace
333 limits (such as those for PID and user namespaces) that may be enforced.
335 Upon encountering these limits,
342 For the initial user namespace,
343 the default value in each of these files is half the limit on the number
344 of threads that may be created
345 .RI ( /proc/sys/kernel/threads\-max ).
346 In all descendant user namespaces, the default value in each file is
349 When a namespace is created, the object is also accounted
350 against ancestor namespaces.
354 Each user namespace has a creator UID.
356 When a namespace is created,
357 it is accounted against the creator UIDs in each of the
358 ancestor user namespaces,
359 and the kernel ensures that the corresponding namespace limit
360 for the creator UID in the ancestor namespace is not exceeded.
362 The aforementioned point ensures that creating a new user namespace
363 cannot be used as a means to escape the limits in force
364 in the current user namespace.
367 .SS Namespace lifetime
368 Absent any other factors,
369 a namespace is automatically torn down when the last process in
370 the namespace terminates or leaves the namespace.
371 However, there are a number of other factors that may pin
372 a namespace into existence even though it has no member processes.
373 These factors include the following:
375 An open file descriptor or a bind mount exists for the corresponding
379 The namespace is hierarchical (i.e., a PID or user namespace),
380 and has a child namespace.
382 It is a user namespace that owns one or more nonuser namespaces.
384 It is a PID namespace,
385 and there is a process that refers to the namespace via a
386 .IR /proc/ pid /ns/pid_for_children
389 It is a time namespace,
390 and there is a process that refers to the namespace via a
391 .IR /proc/ pid /ns/time_for_children
394 It is an IPC namespace, and a corresponding mount of an
398 refers to this namespace.
400 It is a PID namespace, and a corresponding mount of a
402 filesystem refers to this namespace.
407 .BR user_namespaces (7).
417 .BR capabilities (7),
418 .BR cgroup_namespaces (7),
421 .BR ipc_namespaces (7),
422 .BR network_namespaces (7),
423 .BR pid_namespaces (7),
424 .BR user_namespaces (7),
425 .BR uts_namespaces (7),