Debian Codegraph @

upstream/debian-unstable/man7/namespaces.7

raw
1 '\" t
2 .\" Copyright 2013-2017, Michael Kerrisk <[email protected]>
3 .\" Copyright 2012, Eric W. Biederman <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .TH namespaces 7 2026-02-08 "Linux man-pages 6.18"
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 \f[B]cgroup_namespaces\f[](7) T{
39 .na
40 .nh
41 Cgroup root directory
42 T}
43 IPC CLONE_NEWIPC \f[B]ipc_namespaces\f[](7) T{
44 .na
45 .nh
46 System V IPC,
47 POSIX message queues
48 T}
49 Network CLONE_NEWNET \f[B]network_namespaces\f[](7) T{
50 .na
51 .nh
52 Network devices,
53 stacks, ports, etc.
54 T}
55 Mount CLONE_NEWNS \f[B]mount_namespaces\f[](7) Mount points
56 PID CLONE_NEWPID \f[B]pid_namespaces\f[](7) Process IDs
57 Time CLONE_NEWTIME \f[B]time_namespaces\f[](7) T{
58 .na
59 .nh
60 Boot and monotonic clocks
61 T}
62 User CLONE_NEWUSER \f[B]user_namespaces\f[](7) T{
63 User and group IDs
64 T}
65 UTS CLONE_NEWUTS \f[B]uts_namespaces\f[](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 \f[I]/proc/\f[]pid\f[I]/ns/\f[] 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 .RB $ " ls \-l /proc/$$/ns | awk \[aq]{print $1, $9, $10, $11}\[aq]"
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;
189 an application can check this using the
190 .I stat.st_dev
191 .\" Eric Biederman: "I reserve the right for st_dev to be significant
192 .\" when comparing namespaces."
193 .\" https://lore.kernel.org/lkml/[email protected]/
194 .\" Re: Documenting the ioctl interfaces to discover relationships...
195 .\" Date: Mon, 12 Dec 2016 11:30:38 +1300
196 and
197 .I stat.st_ino
198 fields returned by
199 .BR stat (2).
200 The content of this symbolic link is a string containing
201 the namespace type and inode number as in the following example:
202 .P
203 .in +4n
204 .EX
205 .RB $ " readlink /proc/$$/ns/uts"
206 uts:[4026531838]
207 .EE
208 .in
209 .P
210 The symbolic links in this subdirectory are as follows:
211 .TP
212 .IR /proc/ pid /ns/cgroup " (since Linux 4.6)"
213 This file is a handle for the cgroup namespace of the process.
214 .TP
215 .IR /proc/ pid /ns/ipc " (since Linux 3.0)"
216 This file is a handle for the IPC namespace of the process.
217 .TP
218 .IR /proc/ pid /ns/mnt " (since Linux 3.8)"
219 .\" commit 8823c079ba7136dc1948d6f6dcb5f8022bde438e
220 This file is a handle for the mount namespace of the process.
221 .TP
222 .IR /proc/ pid /ns/net " (since Linux 3.0)"
223 This file is a handle for the network namespace of the process.
224 .TP
225 .IR /proc/ pid /ns/pid " (since Linux 3.8)"
226 .\" commit 57e8391d327609cbf12d843259c968b9e5c1838f
227 This file is a handle for the PID namespace of the process.
228 This handle is permanent for the lifetime of the process
229 (i.e., a process's PID namespace membership never changes).
230 .TP
231 .IR /proc/ pid /ns/pid_for_children " (since Linux 4.12)"
232 .\" commit eaa0d190bfe1ed891b814a52712dcd852554cb08
233 This file is a handle for the PID namespace of
234 child processes created by this process.
235 This can change as a consequence of calls to
236 .BR unshare (2)
237 and
238 .BR setns (2)
239 (see
240 .BR pid_namespaces (7)),
241 so the file may differ from
242 .IR /proc/ pid /ns/pid .
243 The symbolic link gains a value only after the first child process
244 is created in the namespace.
245 (Beforehand,
246 .BR readlink (2)
247 of the symbolic link will return an empty buffer.)
248 .TP
249 .IR /proc/ pid /ns/time " (since Linux 5.6)"
250 This file is a handle for the time namespace of the process.
251 .TP
252 .IR /proc/ pid /ns/time_for_children " (since Linux 5.6)"
253 This file is a handle for the time namespace of
254 child processes created by this process.
255 This can change as a consequence of calls to
256 .BR unshare (2)
257 and
258 .BR setns (2)
259 (see
260 .BR time_namespaces (7)),
261 so the file may differ from
262 .IR /proc/ pid /ns/time .
263 .TP
264 .IR /proc/ pid /ns/user " (since Linux 3.8)"
265 .\" commit cde1975bc242f3e1072bde623ef378e547b73f91
266 This file is a handle for the user namespace of the process.
267 .TP
268 .IR /proc/ pid /ns/uts " (since Linux 3.0)"
269 This file is a handle for the UTS namespace of the process.
270 .P
271 Permission to dereference or read
272 .RB ( readlink (2))
273 these symbolic links is governed by a ptrace access mode
274 .B PTRACE_MODE_READ_FSCREDS
275 check;
276 see
277 .BR ptrace (2).
278 .\"
279 .\" ==================== The /proc/sys/user directory ====================
280 .\"
281 .SS The \f[I]/proc/sys/user\f[] directory
282 The files in the
283 .I /proc/sys/user
284 directory (which is present since Linux 4.9) expose limits
285 on the number of namespaces of various types that can be created.
286 The files are as follows:
287 .TP
288 .I max_cgroup_namespaces
289 The value in this file defines a per-user limit on the number of
290 cgroup namespaces that may be created in the user namespace.
291 .TP
292 .I max_ipc_namespaces
293 The value in this file defines a per-user limit on the number of
294 ipc namespaces that may be created in the user namespace.
295 .TP
296 .I max_mnt_namespaces
297 The value in this file defines a per-user limit on the number of
298 mount namespaces that may be created in the user namespace.
299 .TP
300 .I max_net_namespaces
301 The value in this file defines a per-user limit on the number of
302 network namespaces that may be created in the user namespace.
303 .TP
304 .I max_pid_namespaces
305 The value in this file defines a per-user limit on the number of
306 PID namespaces that may be created in the user namespace.
307 .TP
308 .IR max_time_namespaces " (since Linux 5.7)"
309 .\" commit eeec26d5da8248ea4e240b8795bb4364213d3247
310 The value in this file defines a per-user limit on the number of
311 time namespaces that may be created in the user namespace.
312 .TP
313 .I max_user_namespaces
314 The value in this file defines a per-user limit on the number of
315 user namespaces that may be created in the user namespace.
316 .TP
317 .I max_uts_namespaces
318 The value in this file defines a per-user limit on the number of
319 uts namespaces that may be created in the user namespace.
320 .P
321 Note the following details about these files:
322 .IP \[bu] 3
323 The values in these files are modifiable by privileged processes.
324 .IP \[bu]
325 The values exposed by these files are the limits for the user namespace
326 in which the opening process resides.
327 .IP \[bu]
328 The limits are per-user.
329 Each user in the same user namespace
330 can create namespaces up to the defined limit.
331 .IP \[bu]
332 The limits apply to all users, including UID 0.
333 .IP \[bu]
334 These limits apply in addition to any other per-namespace
335 limits (such as those for PID and user namespaces) that may be enforced.
336 .IP \[bu]
337 Upon encountering these limits,
338 .BR clone (2)
339 and
340 .BR unshare (2)
341 fail with the error
342 .BR ENOSPC .
343 .IP \[bu]
344 For the initial user namespace,
345 the default value in each of these files is half the limit on the number
346 of threads that may be created
347 .RI ( /proc/sys/kernel/threads\-max ).
348 In all descendant user namespaces, the default value in each file is
349 .BR MAXINT .
350 .IP \[bu]
351 When a namespace is created, the object is also accounted
352 against ancestor namespaces.
353 More precisely:
354 .RS
355 .IP \[bu] 3
356 Each user namespace has a creator UID.
357 .IP \[bu]
358 When a namespace is created,
359 it is accounted against the creator UIDs in each of the
360 ancestor user namespaces,
361 and the kernel ensures that the corresponding namespace limit
362 for the creator UID in the ancestor namespace is not exceeded.
363 .IP \[bu]
364 The aforementioned point ensures that creating a new user namespace
365 cannot be used as a means to escape the limits in force
366 in the current user namespace.
367 .RE
368 .\"
369 .SS Namespace lifetime
370 Absent any other factors,
371 a namespace is automatically torn down when the last process in
372 the namespace terminates or leaves the namespace.
373 However, there are a number of other factors that may pin
374 a namespace into existence even though it has no member processes.
375 These factors include the following:
376 .IP \[bu] 3
377 An open file descriptor or a bind mount exists for the corresponding
378 .IR /proc/ pid /ns/*
379 file.
380 .IP \[bu]
381 The namespace is hierarchical (i.e., a PID or user namespace),
382 and has a child namespace.
383 .IP \[bu]
384 It is a user namespace that owns one or more nonuser namespaces.
385 .IP \[bu]
386 It is a PID namespace,
387 and there is a process that refers to the namespace via a
388 .IR /proc/ pid /ns/pid_for_children
389 symbolic link.
390 .IP \[bu]
391 It is a time namespace,
392 and there is a process that refers to the namespace via a
393 .IR /proc/ pid /ns/time_for_children
394 symbolic link.
395 .IP \[bu]
396 It is an IPC namespace, and a corresponding mount of an
397 .I mqueue
398 filesystem (see
399 .BR mq_overview (7))
400 refers to this namespace.
401 .IP \[bu]
402 It is a PID namespace, and a corresponding mount of a
403 .BR proc (5)
404 filesystem refers to this namespace.
405 .SH EXAMPLES
406 See
407 .BR clone (2)
408 and
409 .BR user_namespaces (7).
410 .SH SEE ALSO
411 .BR nsenter (1),
412 .BR readlink (1),
413 .BR unshare (1),
414 .BR clone (2),
415 .BR ioctl_nsfs (2),
416 .BR setns (2),
417 .BR unshare (2),
418 .BR proc (5),
419 .BR capabilities (7),
420 .BR cgroup_namespaces (7),
421 .BR cgroups (7),
422 .BR credentials (7),
423 .BR ipc_namespaces (7),
424 .BR network_namespaces (7),
425 .BR pid_namespaces (7),
426 .BR user_namespaces (7),
427 .BR uts_namespaces (7),
428 .BR lsns (8),
429 .BR switch_root (8)