| blob | 0e7f46661e89dbdea29319f9d68a345ed0313914 |
1 '\" t
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>
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .\"
8 .TH namespaces 7 (date) "Linux man-pages (unreleased)"
9 .SH NAME
10 namespaces \- overview of Linux namespaces
11 .SH DESCRIPTION
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.
18 .P
19 This page provides pointers to information on the various namespace types,
20 describes the associated
21 .I /proc
22 files, and summarizes the APIs for working with namespaces.
23 .\"
24 .SS Namespace types
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
31 the namespace type.
32 .P
33 .TS
34 lB lB lB lB
35 l lB lw(21n) lx.
36 Namespace Flag Page Isolates
37 _
38 Cgroup CLONE_NEWCGROUP \fBcgroup_namespaces\fP(7) T{
39 .na
40 .nh
41 Cgroup root directory
42 T}
43 IPC CLONE_NEWIPC \fBipc_namespaces\fP(7) T{
44 .na
45 .nh
46 System V IPC,
47 POSIX message queues
48 T}
49 Network CLONE_NEWNET \fBnetwork_namespaces\fP(7) T{
50 .na
51 .nh
52 Network devices,
53 stacks, ports, etc.
54 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{
58 .na
59 .nh
60 Boot and monotonic clocks
61 T}
62 User CLONE_NEWUSER \fBuser_namespaces\fP(7) T{
63 User and group IDs
64 T}
65 UTS CLONE_NEWUTS \fButs_namespaces\fP(7) T{
66 .na
67 .nh
68 Hostname and NIS domain name
69 T}
70 .TE
71 .\"
72 .\" ==================== The namespaces API ====================
73 .\"
74 .SS The namespaces API
75 As well as various
76 .I /proc
77 files described below,
78 the namespaces API includes the following system calls:
79 .TP
80 .BR clone (2)
81 The
82 .BR clone (2)
83 system call creates a new process.
84 If the
85 .I flags
86 argument of the call specifies one or more of the
87 .B CLONE_NEW*
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.)
92 .TP
93 .BR setns (2)
94 The
95 .BR setns (2)
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
98 one of the
99 .IR /proc/ pid /ns
100 files described below.
101 .TP
102 .BR unshare (2)
103 The
104 .BR unshare (2)
105 system call moves the calling process to a new namespace.
106 If the
107 .I flags
108 argument of the call specifies one or more of the
109 .B CLONE_NEW*
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.)
114 .TP
115 .BR ioctl (2)
116 Various
117 .BR ioctl (2)
118 operations can be used to discover information about namespaces.
119 These operations are described in
120 .BR ioctl_nsfs (2).
121 .P
122 Creation of new namespaces using
123 .BR clone (2)
124 and
125 .BR unshare (2)
126 in most cases requires the
127 .B CAP_SYS_ADMIN
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.
134 .\"
135 .\" ==================== The /proc/[pid]/ns/ directory ====================
136 .\"
137 .SS The \fI/proc/\fPpid\fI/ns/\fP directory
138 Each process has a
139 .IR /proc/ pid /ns/
140 .\" See commit 6b4e306aa3dc94a0545eb9279475b1ab6209a31f
141 subdirectory containing one entry for each namespace that
142 supports being manipulated by
143 .BR setns (2):
144 .P
145 .in +4n
146 .EX
147 $ \fBls \-l /proc/$$/ns | awk \[aq]{print $1, $9, $10, $11}\[aq]\fP
148 total 0
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]
159 .EE
160 .in
161 .P
162 Bind mounting (see
163 .BR mount (2))
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
167 .I pid
168 alive even if all processes currently in the namespace terminate.
169 .P
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
174 .IR pid .
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
179 .BR setns (2).
180 .P
181 In Linux 3.7 and earlier, these files were visible as hard links.
182 Since Linux 3.8,
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
189 .I stat.st_dev
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
195 and
196 .I stat.st_ino
197 fields returned by
198 .BR stat (2).
199 The content of this symbolic link is a string containing
200 the namespace type and inode number as in the following example:
201 .P
202 .in +4n
203 .EX
204 $ \fBreadlink /proc/$$/ns/uts\fP
205 uts:[4026531838]
206 .EE
207 .in
208 .P
209 The symbolic links in this subdirectory are as follows:
210 .TP
211 .IR /proc/ pid /ns/cgroup " (since Linux 4.6)"
212 This file is a handle for the cgroup namespace of the process.
213 .TP
214 .IR /proc/ pid /ns/ipc " (since Linux 3.0)"
215 This file is a handle for the IPC namespace of the process.
216 .TP
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.
220 .TP
221 .IR /proc/ pid /ns/net " (since Linux 3.0)"
222 This file is a handle for the network namespace of the process.
223 .TP
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).
229 .TP
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
235 .BR unshare (2)
236 and
237 .BR setns (2)
238 (see
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.
244 (Beforehand,
245 .BR readlink (2)
246 of the symbolic link will return an empty buffer.)
247 .TP
248 .IR /proc/ pid /ns/time " (since Linux 5.6)"
249 This file is a handle for the time namespace of the process.
250 .TP
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
255 .BR unshare (2)
256 and
257 .BR setns (2)
258 (see
259 .BR time_namespaces (7)),
260 so the file may differ from
261 .IR /proc/ pid /ns/time .
262 .TP
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.
266 .TP
267 .IR /proc/ pid /ns/uts " (since Linux 3.0)"
268 This file is a handle for the UTS namespace of the process.
269 .P
270 Permission to dereference or read
271 .RB ( readlink (2))
272 these symbolic links is governed by a ptrace access mode
273 .B PTRACE_MODE_READ_FSCREDS
274 check; see
275 .BR ptrace (2).
276 .\"
277 .\" ==================== The /proc/sys/user directory ====================
278 .\"
279 .SS The \fI/proc/sys/user\fP directory
280 The files in the
281 .I /proc/sys/user
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:
285 .TP
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.
289 .TP
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.
293 .TP
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.
297 .TP
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.
301 .TP
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.
305 .TP
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.
310 .TP
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.
314 .TP
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.
318 .P
319 Note the following details about these files:
320 .IP \[bu] 3
321 The values in these files are modifiable by privileged processes.
322 .IP \[bu]
323 The values exposed by these files are the limits for the user namespace
324 in which the opening process resides.
325 .IP \[bu]
326 The limits are per-user.
327 Each user in the same user namespace
328 can create namespaces up to the defined limit.
329 .IP \[bu]
330 The limits apply to all users, including UID 0.
331 .IP \[bu]
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.
334 .IP \[bu]
335 Upon encountering these limits,
336 .BR clone (2)
337 and
338 .BR unshare (2)
339 fail with the error
340 .BR ENOSPC .
341 .IP \[bu]
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
347 .BR MAXINT .
348 .IP \[bu]
349 When a namespace is created, the object is also accounted
350 against ancestor namespaces.
351 More precisely:
352 .RS
353 .IP \[bu] 3
354 Each user namespace has a creator UID.
355 .IP \[bu]
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.
361 .IP \[bu]
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.
365 .RE
366 .\"
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:
374 .IP \[bu] 3
375 An open file descriptor or a bind mount exists for the corresponding
376 .IR /proc/ pid /ns/*
377 file.
378 .IP \[bu]
379 The namespace is hierarchical (i.e., a PID or user namespace),
380 and has a child namespace.
381 .IP \[bu]
382 It is a user namespace that owns one or more nonuser namespaces.
383 .IP \[bu]
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
387 symbolic link.
388 .IP \[bu]
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
392 symbolic link.
393 .IP \[bu]
394 It is an IPC namespace, and a corresponding mount of an
395 .I mqueue
396 filesystem (see
397 .BR mq_overview (7))
398 refers to this namespace.
399 .IP \[bu]
400 It is a PID namespace, and a corresponding mount of a
401 .BR proc (5)
402 filesystem refers to this namespace.
403 .SH EXAMPLES
404 See
405 .BR clone (2)
406 and
407 .BR user_namespaces (7).
408 .SH SEE ALSO
409 .BR nsenter (1),
410 .BR readlink (1),
411 .BR unshare (1),
412 .BR clone (2),
413 .BR ioctl_nsfs (2),
414 .BR setns (2),
415 .BR unshare (2),
416 .BR proc (5),
417 .BR capabilities (7),
418 .BR cgroup_namespaces (7),
419 .BR cgroups (7),
420 .BR credentials (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),
426 .BR lsns (8),
427 .BR switch_root (8)