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