1PID_NAMESPACES(7) Linux Programmer's Manual PID_NAMESPACES(7)
2
6 pid_namespaces - overview of Linux PID namespaces
7
9 For an overview of namespaces, see namespaces(7).
10 PID namespaces isolate the process ID number space, meaning that pro‐
12 cesses in different PID namespaces can have the same PID. PID name‐
13 spaces allow containers to provide functionality such as suspending/re‐
14 suming the set of processes in the container and migrating the con‐
15 tainer to a new host while the processes inside the container maintain
16 the same PIDs.
17 PIDs in a new PID namespace start at 1, somewhat like a standalone sys‐
19 tem, and calls to fork(2), vfork(2), or clone(2) will produce processes
20 with PIDs that are unique within the namespace.
21 Use of PID namespaces requires a kernel that is configured with the
23 CONFIG_PID_NS option.
24 The namespace init process
26 The first process created in a new namespace (i.e., the process created
27 using clone(2) with the CLONE_NEWPID flag, or the first child created
28 by a process after a call to unshare(2) using the CLONE_NEWPID flag)
29 has the PID 1, and is the "init" process for the namespace (see
30 init(1)). This process becomes the parent of any child processes that
31 are orphaned because a process that resides in this PID namespace ter‐
32 minated (see below for further details).
33 If the "init" process of a PID namespace terminates, the kernel termi‐
35 nates all of the processes in the namespace via a SIGKILL signal. This
36 behavior reflects the fact that the "init" process is essential for the
37 correct operation of a PID namespace. In this case, a subsequent
38 fork(2) into this PID namespace fail with the error ENOMEM; it is not
39 possible to create a new process in a PID namespace whose "init"
40 process has terminated. Such scenarios can occur when, for example, a
41 process uses an open file descriptor for a /proc/[pid]/ns/pid file cor‐
42 responding to a process that was in a namespace to setns(2) into that
43 namespace after the "init" process has terminated. Another possible
44 scenario can occur after a call to unshare(2): if the first child sub‐
45 sequently created by a fork(2) terminates, then subsequent calls to
46 fork(2) fail with ENOMEM.
47 Only signals for which the "init" process has established a signal han‐
49 dler can be sent to the "init" process by other members of the PID
50 namespace. This restriction applies even to privileged processes, and
51 prevents other members of the PID namespace from accidentally killing
52 the "init" process.
53 Likewise, a process in an ancestor namespace can—subject to the usual
55 permission checks described in kill(2)—send signals to the "init"
56 process of a child PID namespace only if the "init" process has estab‐
57 lished a handler for that signal. (Within the handler, the siginfo_t
58 si_pid field described in sigaction(2) will be zero.) SIGKILL or
59 SIGSTOP are treated exceptionally: these signals are forcibly delivered
60 when sent from an ancestor PID namespace. Neither of these signals can
61 be caught by the "init" process, and so will result in the usual ac‐
62 tions associated with those signals (respectively, terminating and
63 stopping the process).
64 Starting with Linux 3.4, the reboot(2) system call causes a signal to
66 be sent to the namespace "init" process. See reboot(2) for more de‐
67 tails.
68 Nesting PID namespaces
70 PID namespaces can be nested: each PID namespace has a parent, except
71 for the initial ("root") PID namespace. The parent of a PID namespace
72 is the PID namespace of the process that created the namespace using
73 clone(2) or unshare(2). PID namespaces thus form a tree, with all
74 namespaces ultimately tracing their ancestry to the root namespace.
75 Since Linux 3.7, the kernel limits the maximum nesting depth for PID
76 namespaces to 32.
77 A process is visible to other processes in its PID namespace, and to
79 the processes in each direct ancestor PID namespace going back to the
80 root PID namespace. In this context, "visible" means that one process
81 can be the target of operations by another process using system calls
82 that specify a process ID. Conversely, the processes in a child PID
83 namespace can't see processes in the parent and further removed ances‐
84 tor namespaces. More succinctly: a process can see (e.g., send signals
85 with kill(2), set nice values with setpriority(2), etc.) only processes
86 contained in its own PID namespace and in descendants of that name‐
87 space.
88 A process has one process ID in each of the layers of the PID namespace
90 hierarchy in which is visible, and walking back though each direct an‐
91 cestor namespace through to the root PID namespace. System calls that
92 operate on process IDs always operate using the process ID that is vis‐
93 ible in the PID namespace of the caller. A call to getpid(2) always
94 returns the PID associated with the namespace in which the process was
95 created.
96 Some processes in a PID namespace may have parents that are outside of
98 the namespace. For example, the parent of the initial process in the
99 namespace (i.e., the init(1) process with PID 1) is necessarily in an‐
100 other namespace. Likewise, the direct children of a process that uses
101 setns(2) to cause its children to join a PID namespace are in a differ‐
102 ent PID namespace from the caller of setns(2). Calls to getppid(2) for
103 such processes return 0.
104 While processes may freely descend into child PID namespaces (e.g., us‐
106 ing setns(2) with a PID namespace file descriptor), they may not move
107 in the other direction. That is to say, processes may not enter any
108 ancestor namespaces (parent, grandparent, etc.). Changing PID name‐
109 spaces is a one-way operation.
110 The NS_GET_PARENT ioctl(2) operation can be used to discover the
112 parental relationship between PID namespaces; see ioctl_ns(2).
113 setns(2) and unshare(2) semantics
115 Calls to setns(2) tha