1=========================
2Process Number Controller
3=========================
4
5Abstract
6--------
7
8The process number controller is used to allow a cgroup hierarchy to stop any
9new tasks from being fork()'d or clone()'d after a certain limit is reached.
10
11Since it is trivial to hit the task limit without hitting any kmemcg limits in
12place, PIDs are a fundamental resource. As such, PID exhaustion must be
13preventable in the scope of a cgroup hierarchy by allowing resource limiting of
14the number of tasks in a cgroup.
15
16Usage
17-----
18
19In order to use the `pids` controller, set the maximum number of tasks in
20pids.max (this is not available in the root cgroup for obvious reasons). The
21number of processes currently in the cgroup is given by pids.current.
22
23Organisational operations are not blocked by cgroup policies, so it is possible
24to have pids.current > pids.max. This can be done by either setting the limit to
25be smaller than pids.current, or attaching enough processes to the cgroup such
26that pids.current > pids.max. However, it is not possible to violate a cgroup
27policy through fork() or clone(). fork() and clone() will return -EAGAIN if the
28creation of a new process would cause a cgroup policy to be violated.
29
30To set a cgroup to have no limit, set pids.max to "max". This is the default for
31all new cgroups (N.B. that PID limits are hierarchical, so the most stringent
32limit in the hierarchy is followed).
33
34pids.current tracks all child cgroup hierarchies, so parent/pids.current is a
35superset of parent/child/pids.current.
36
37The pids.events file contains event counters:
38
39  - max: Number of times fork failed because limit was hit.
40
41Example
42-------
43
44First, we mount the pids controller::
45
46	# mkdir -p /sys/fs/cgroup/pids
47	# mount -t cgroup -o pids none /sys/fs/cgroup/pids
48
49Then we create a hierarchy, set limits and attach processes to it::
50
51	# mkdir -p /sys/fs/cgroup/pids/parent/child
52	# echo 2 > /sys/fs/cgroup/pids/parent/pids.max
53	# echo $$ > /sys/fs/cgroup/pids/parent/cgroup.procs
54	# cat /sys/fs/cgroup/pids/parent/pids.current
55	2
56	#
57
58It should be noted that attempts to overcome the set limit (2 in this case) will
59fail::
60
61	# cat /sys/fs/cgroup/pids/parent/pids.current
62	2
63	# ( /bin/echo "Here's some processes for you." | cat )
64	sh: fork: Resource temporary unavailable
65	#
66
67Even if we migrate to a child cgroup (which doesn't have a set limit), we will
68not be able to overcome the most stringent limit in the hierarchy (in this case,
69parent's)::
70
71	# echo $$ > /sys/fs/cgroup/pids/parent/child/cgroup.procs
72	# cat /sys/fs/cgroup/pids/parent/pids.current
73	2
74	# cat /sys/fs/cgroup/pids/parent/child/pids.current
75	2
76	# cat /sys/fs/cgroup/pids/parent/child/pids.max
77	max
78	# ( /bin/echo "Here's some processes for you." | cat )
79	sh: fork: Resource temporary unavailable
80	#
81
82We can set a limit that is smaller than pids.current, which will stop any new
83processes from being forked at all (note that the shell itself counts towards
84pids.current)::
85
86	# echo 1 > /sys/fs/cgroup/pids/parent/pids.max
87	# /bin/echo "We can't even spawn a single process now."
88	sh: fork: Resource temporary unavailable
89	# echo 0 > /sys/fs/cgroup/pids/parent/pids.max
90	# /bin/echo "We can't even spawn a single process now."
91	sh: fork: Resource temporary unavailable
92	#
93