Debian Codegraph @

upstream/debian-unstable/man7/pid_namespaces.7

raw
1 .\" Copyright 2013, Michael Kerrisk <[email protected]>
2 .\" Copyright 2012, Eric W. Biederman <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH pid_namespaces 7 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 pid_namespaces \- overview of Linux PID namespaces
10 .SH DESCRIPTION
11 For an overview of namespaces, see
12 .BR namespaces (7).
13 .P
14 PID namespaces isolate the process ID number space,
15 meaning that processes in different PID namespaces can have the same PID.
16 PID namespaces allow containers to provide functionality
17 such as suspending/resuming the set of processes in the container and
18 migrating the container to a new host
19 while the processes inside the container maintain the same PIDs.
20 .P
21 PIDs in a new PID namespace start at 1,
22 somewhat like a standalone system, and calls to
23 .BR fork (2),
24 .BR vfork (2),
25 or
26 .BR clone (2)
27 will produce processes with PIDs that are unique within the namespace.
28 .P
29 Use of PID namespaces requires a kernel that is configured with the
30 .B CONFIG_PID_NS
31 option.
32 .\"
33 .\" ============================================================
34 .\"
35 .SS The namespace "init" process
36 The first process created in a new namespace
37 (i.e., the process created using
38 .BR clone (2)
39 with the
40 .B CLONE_NEWPID
41 flag, or the first child created by a process after a call to
42 .BR unshare (2)
43 using the
44 .B CLONE_NEWPID
45 flag) has the PID 1, and is the "init" process for the namespace (see
46 .BR init (1)).
47 This process becomes the parent of any child processes that are orphaned
48 because a process that resides in this PID namespace terminated
49 (see below for further details).
50 .P
51 If the "init" process of a PID namespace terminates,
52 the kernel terminates all of the processes in the namespace via a
53 .B SIGKILL
54 signal.
55 This behavior reflects the fact that the "init" process
56 is essential for the correct operation of a PID namespace.
57 In this case, a subsequent
58 .BR fork (2)
59 into this PID namespace fail with the error
60 .BR ENOMEM ;
61 it is not possible to create a new process in a PID namespace whose "init"
62 process has terminated.
63 Such scenarios can occur when, for example,
64 a process uses an open file descriptor for a
65 .IR /proc/ pid /ns/pid
66 file corresponding to a process that was in a namespace to
67 .BR setns (2)
68 into that namespace after the "init" process has terminated.
69 Another possible scenario can occur after a call to
70 .BR unshare (2):
71 if the first child subsequently created by a
72 .BR fork (2)
73 terminates, then subsequent calls to
74 .BR fork (2)
75 fail with
76 .BR ENOMEM .
77 .P
78 Only signals for which the "init" process has established a signal handler
79 can be sent to the "init" process by other members of the PID namespace.
80 This restriction applies even to privileged processes,
81 and prevents other members of the PID namespace from
82 accidentally killing the "init" process.
83 .P
84 Likewise, a process in an ancestor namespace
85 can\[em]subject to the usual permission checks described in
86 .BR kill (2)\[em]send
87 signals to the "init" process of a child PID namespace only
88 if the "init" process has established a handler for that signal.
89 (Within the handler, the
90 .I siginfo_t
91 .I si_pid
92 field described in
93 .BR sigaction (2)
94 will be zero.)
95 .B SIGKILL
96 or
97 .B SIGSTOP
98 are treated exceptionally:
99 these signals are forcibly delivered when sent from an ancestor PID namespace.
100 Neither of these signals can be caught by the "init" process,
101 and so will result in the usual actions associated with those signals
102 (respectively, terminating and stopping the process).
103 .P
104 Starting with Linux 3.4, the
105 .BR reboot (2)
106 system call causes a signal to be sent to the namespace "init" process.
107 See
108 .BR reboot (2)
109 for more details.
110 .\"
111 .\" ============================================================
112 .\"
113 .SS Nesting PID namespaces
114 PID namespaces can be nested:
115 each PID namespace has a parent,
116 except for the initial ("root") PID namespace.
117 The parent of a PID namespace is the PID namespace of the process that
118 created the namespace using
119 .BR clone (2)
120 or
121 .BR unshare (2).
122 PID namespaces thus form a tree,
123 with all namespaces ultimately tracing their ancestry to the root namespace.
124 Since Linux 3.7,
125 .\" commit f2302505775fd13ba93f034206f1e2a587017929
126 .\" The kernel constant MAX_PID_NS_LEVEL
127 the kernel limits the maximum nesting depth for PID namespaces to 32.
128 .P
129 A process is visible to other processes in its PID namespace,
130 and to the processes in each direct ancestor PID namespace
131 going back to the root PID namespace.
132 In this context, "visible" means that one process
133 can be the target of operations by another process using
134 system calls that specify a process ID.
135 Conversely, the processes in a child PID namespace can't see
136 processes in the parent and further removed ancestor namespaces.
137 More succinctly: a process can see (e.g., send signals with
138 .BR kill (2),
139 set nice values with
140 .BR setpriority (2),
141 etc.) only processes contained in its own PID namespace
142 and in descendants of that namespace.
143 .P
144 A process has one process ID in each of the layers of the PID
145 namespace hierarchy in which is visible,
146 and walking back though each direct ancestor namespace
147 through to the root PID namespace.
148 System calls that operate on process IDs always
149 operate using the process ID that is visible in the
150 PID namespace of the caller.
151 A call to
152 .BR getpid (2)
153 always returns the PID associated with the namespace in which
154 the process was created.
155 .P
156 Some processes in a PID namespace may have parents
157 that are outside of the namespace.
158 For example, the parent of the initial process in the namespace
159 (i.e., the
160 .BR init (1)
161 process with PID 1) is necessarily in another namespace.
162 Likewise, the direct children of a process that uses
163 .BR setns (2)
164 to cause its children to join a PID namespace are in a different
165 PID namespace from the caller of
166 .BR setns (2).
167 Calls to
168 .BR getppid (2)
169 for such processes return 0.
170 .P
171 While processes may freely descend into child PID namespaces
172 (e.g., using
173 .BR setns (2)
174 with a PID namespace file descriptor),
175 they may not move in the other direction.
176 That is to say, processes may not enter any ancestor namespaces
177 (parent, grandparent, etc.).
178 Changing PID namespaces is a one-way operation.
179 .P
180 The
181 .B NS_GET_PARENT
182 .BR ioctl (2)
183 operation can be used to discover the parental relationship
184 between PID namespaces;
185 see
186 .BR ioctl_nsfs (2).
187 .\"
188 .\" ============================================================
189 .\"
190 .SS setns(2) and unshare(2) semantics
191 Calls to
192 .BR setns (2)
193 that specify a PID namespace file descriptor
194 and calls to
195 .BR unshare (2)
196 with the
197 .B CLONE_NEWPID
198 flag cause children subsequently created
199 by the caller to be placed in a different PID namespace from the caller.
200 (Since Linux 4.12, that PID namespace is shown via the
201 .IR /proc/ pid /ns/pid_for_children
202 file, as described in
203 .BR namespaces (7).)
204 These calls do not, however,
205 change the PID namespace of the calling process,
206 because doing so would change the caller's idea of its own PID
207 (as reported by
208 .BR getpid ()),
209 which would break many applications and libraries.
210 .P
211 To put things another way:
212 a process's PID namespace membership is determined when the process is created
213 and cannot be changed thereafter.
214 Among other things, this means that the parental relationship
215 between processes mirrors the parental relationship between PID namespaces:
216 the parent of a process is either in the same namespace
217 or resides in the immediate parent PID namespace.
218 .P
219 A process may call
220 .BR unshare (2)
221 with the
222 .B CLONE_NEWPID
223 flag only once.
224 After it has performed this operation, its
225 .IR /proc/ pid /ns/pid_for_children
226 symbolic link will be empty until the first child is created in the namespace.
227 .\"
228 .\" ============================================================
229 .\"
230 .SS Adoption of orphaned children
231 When a child process becomes orphaned, it is reparented to the "init"
232 process in the PID namespace of its parent
233 (unless one of the nearer ancestors of the parent employed the
234 .BR prctl (2)
235 .B PR_SET_CHILD_SUBREAPER
236 command to mark itself as the reaper of orphaned descendant processes).
237 Note that because of the
238 .BR setns (2)
239 and
240 .BR unshare (2)
241 semantics described above, this may be the "init" process in the PID
242 namespace that is the
243 .I parent
244 of the child's PID namespace,
245 rather than the "init" process in the child's own PID namespace.
246 .\" Furthermore, by definition, the parent of the "init" process
247 .\" of a PID namespace resides in the parent PID namespace.
248 .\"
249 .\" ============================================================
250 .\"
251 .SS Compatibility of CLONE_NEWPID with other CLONE_* flags
252 In current versions of Linux,
253 .B CLONE_NEWPID
254 can't be combined with
255 .BR CLONE_THREAD .
256 Threads are required to be in the same PID namespace such that
257 the threads in a process can send signals to each other.
258 Similarly, it must be possible to see all of the threads
259 of a process in the
260 .BR proc (5)
261 filesystem.
262 Additionally, if two threads were in different PID
263 namespaces, the process ID of the process sending a signal
264 could not be meaningfully encoded when a signal is sent
265 (see the description of the
266 .I siginfo_t
267 type in
268 .BR sigaction (2)).
269 Since this is computed when a signal is enqueued,
270 a signal queue shared by processes in multiple PID namespaces
271 would defeat that.
272 .P
273 .\" Note these restrictions were all introduced in
274 .\" 8382fcac1b813ad0a4e68a838fc7ae93fa39eda0
275 .\" when CLONE_NEWPID|CLONE_VM was disallowed
276 In earlier versions of Linux,
277 .B CLONE_NEWPID
278 was additionally disallowed (failing with the error
279 .BR EINVAL )
280 in combination with
281 .B CLONE_SIGHAND
282 .\" (restriction lifted in faf00da544045fdc1454f3b9e6d7f65c841de302)
283 (before Linux 4.3) as well as
284 .\" (restriction lifted in e79f525e99b04390ca4d2366309545a836c03bf1)
285 .B CLONE_VM
286 (before Linux 3.12).
287 The changes that lifted these restrictions have also been ported to
288 earlier stable kernels.
289 .\"
290 .\" ============================================================
291 .\"
292 .SS /proc and PID namespaces
293 A
294 .I /proc
295 filesystem shows (in the
296 .IR /proc/ pid
297 directories) only processes visible in the PID namespace
298 of the process that performed the mount, even if the
299 .I /proc
300 filesystem is viewed from processes in other namespaces.
301 .P
302 After creating a new PID namespace,
303 it is useful for the child to change its root directory
304 and mount a new procfs instance at
305 .I /proc
306 so that tools such as
307 .BR ps (1)
308 work correctly.
309 If a new mount namespace is simultaneously created by including
310 .B CLONE_NEWNS
311 in the
312 .I flags
313 argument of
314 .BR clone (2)
315 or
316 .BR unshare (2),
317 then it isn't necessary to change the root directory:
318 a new procfs instance can be mounted directly over
319 .IR /proc .
320 .P
321 From a shell, the command to mount
322 .I /proc
323 is:
324 .P
325 .in +4n
326 .EX
327 $ mount \-t proc proc /proc
328 .EE
329 .in
330 .P
331 Calling
332 .BR readlink (2)
333 on the path
334 .I /proc/self
335 yields the process ID of the caller in the PID namespace of the procfs mount
336 (i.e., the PID namespace of the process that mounted the procfs).
337 This can be useful for introspection purposes,
338 when a process wants to discover its PID in other namespaces.
339 .\"
340 .\" ============================================================
341 .\"
342 .SS /proc files
343 .TP
344 .BR /proc/sys/kernel/ns_last_pid " (since Linux 3.3)"
345 .\" commit b8f566b04d3cddd192cfd2418ae6d54ac6353792
346 This file
347 (which is virtualized per PID namespace)
348 displays the last PID that was allocated in this PID namespace.
349 When the next PID is allocated,
350 the kernel will search for the lowest unallocated PID
351 that is greater than this value,
352 and when this file is subsequently read it will show that PID.
353 .IP
354 This file is writable by a process that has the
355 .B CAP_SYS_ADMIN
356 or (since Linux 5.9)
357 .B CAP_CHECKPOINT_RESTORE
358 capability inside the user namespace that owns the PID namespace.
359 .\" This ability is necessary to support checkpoint restore in user-space
360 This makes it possible to determine the PID that is allocated
361 to the next process that is created inside this PID namespace.
362 .\"
363 .\" ============================================================
364 .\"
365 .SS Miscellaneous
366 When a process ID is passed over a UNIX domain socket to a
367 process in a different PID namespace (see the description of
368 .B SCM_CREDENTIALS
369 in
370 .BR unix (7)),
371 it is translated into the corresponding PID value in
372 the receiving process's PID namespace.
373 .SH STANDARDS
374 Linux.
375 .SH EXAMPLES
376 See
377 .BR user_namespaces (7).
378 .SH SEE ALSO
379 .BR clone (2),
380 .BR reboot (2),
381 .BR setns (2),
382 .BR unshare (2),
383 .BR proc (5),
384 .BR capabilities (7),
385 .BR credentials (7),
386 .BR mount_namespaces (7),
387 .BR namespaces (7),
388 .BR user_namespaces (7),
389 .BR switch_root (8)