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