2 Cgroup unified hierarchy
4 April, 2014 Tejun Heo <tj@kernel.org>
6 This document describes the changes made by unified hierarchy and
7 their rationales. It will eventually be merged into the main cgroup
15 2-2. cgroup.subtree_control
16 2-3. cgroup.controllers
17 3. Structural Constraints
19 3-2. No internal tasks
21 4-1. Model of delegation
22 4-2. Common ancestor rule
24 5-1. [Un]populated Notification
25 5-2. Other Core Changes
26 5-3. Controller File Conventions
29 5-4. Per-Controller Changes
34 6-1. CAP for resource control
39 cgroup allows an arbitrary number of hierarchies and each hierarchy
40 can host any number of controllers. While this seems to provide a
41 high level of flexibility, it isn't quite useful in practice.
43 For example, as there is only one instance of each controller, utility
44 type controllers such as freezer which can be useful in all
45 hierarchies can only be used in one. The issue is exacerbated by the
46 fact that controllers can't be moved around once hierarchies are
47 populated. Another issue is that all controllers bound to a hierarchy
48 are forced to have exactly the same view of the hierarchy. It isn't
49 possible to vary the granularity depending on the specific controller.
51 In practice, these issues heavily limit which controllers can be put
52 on the same hierarchy and most configurations resort to putting each
53 controller on its own hierarchy. Only closely related ones, such as
54 the cpu and cpuacct controllers, make sense to put on the same
55 hierarchy. This often means that userland ends up managing multiple
56 similar hierarchies repeating the same steps on each hierarchy
57 whenever a hierarchy management operation is necessary.
59 Unfortunately, support for multiple hierarchies comes at a steep cost.
60 Internal implementation in cgroup core proper is dazzlingly
61 complicated but more importantly the support for multiple hierarchies
62 restricts how cgroup is used in general and what controllers can do.
64 There's no limit on how many hierarchies there may be, which means
65 that a task's cgroup membership can't be described in finite length.
66 The key may contain any varying number of entries and is unlimited in
67 length, which makes it highly awkward to handle and leads to addition
68 of controllers which exist only to identify membership, which in turn
69 exacerbates the original problem.
71 Also, as a controller can't have any expectation regarding what shape
72 of hierarchies other controllers would be on, each controller has to
73 assume that all other controllers are operating on completely
74 orthogonal hierarchies. This makes it impossible, or at least very
75 cumbersome, for controllers to cooperate with each other.
77 In most use cases, putting controllers on hierarchies which are
78 completely orthogonal to each other isn't necessary. What usually is
79 called for is the ability to have differing levels of granularity
80 depending on the specific controller. In other words, hierarchy may
81 be collapsed from leaf towards root when viewed from specific
82 controllers. For example, a given configuration might not care about
83 how memory is distributed beyond a certain level while still wanting
84 to control how CPU cycles are distributed.
86 Unified hierarchy is the next version of cgroup interface. It aims to
87 address the aforementioned issues by having more structure while
88 retaining enough flexibility for most use cases. Various other
89 general and controller-specific interface issues are also addressed in
97 Unified hierarchy can be mounted with the following mount command.
99 mount -t cgroup2 none $MOUNT_POINT
101 All controllers which support the unified hierarchy and are not bound
102 to other hierarchies are automatically bound to unified hierarchy and
103 show up at the root of it. Controllers which are enabled only in the
104 root of unified hierarchy can be bound to other hierarchies. This
105 allows mixing unified hierarchy with the traditional multiple
106 hierarchies in a fully backward compatible way.
108 A controller can be moved across hierarchies only after the controller
109 is no longer referenced in its current hierarchy. Because per-cgroup
110 controller states are destroyed asynchronously and controllers may
111 have lingering references, a controller may not show up immediately on
112 the unified hierarchy after the final umount of the previous
113 hierarchy. Similarly, a controller should be fully disabled to be
114 moved out of the unified hierarchy and it may take some time for the
115 disabled controller to become available for other hierarchies;
116 furthermore, due to dependencies among controllers, other controllers
117 may need to be disabled too.
119 While useful for development and manual configurations, dynamically
120 moving controllers between the unified and other hierarchies is
121 strongly discouraged for production use. It is recommended to decide
122 the hierarchies and controller associations before starting using the
126 2-2. cgroup.subtree_control
128 All cgroups on unified hierarchy have a "cgroup.subtree_control" file
129 which governs which controllers are enabled on the children of the
130 cgroup. Let's assume a hierarchy like the following.
135 root's "cgroup.subtree_control" file determines which controllers are
136 enabled on A. A's on B. B's on C and D. This coincides with the
137 fact that controllers on the immediate sub-level are used to
138 distribute the resources of the parent. In fact, it's natural to
139 assume that resource control knobs of a child belong to its parent.
140 Enabling a controller in a "cgroup.subtree_control" file declares that
141 distribution of the respective resources of the cgroup will be
142 controlled. Note that this means that controller enable states are
143 shared among siblings.
145 When read, the file contains a space-separated list of currently
146 enabled controllers. A write to the file should contain a
147 space-separated list of controllers with '+' or '-' prefixed (without
148 the quotes). Controllers prefixed with '+' are enabled and '-'
149 disabled. If a controller is listed multiple times, the last entry
150 wins. The specific operations are executed atomically - either all
154 2-3. cgroup.controllers
156 Read-only "cgroup.controllers" file contains a space-separated list of
157 controllers which can be enabled in the cgroup's
158 "cgroup.subtree_control" file.
160 In the root cgroup, this lists controllers which are not bound to
161 other hierarchies and the content changes as controllers are bound to
162 and unbound from other hierarchies.
164 In non-root cgroups, the content of this file equals that of the
165 parent's "cgroup.subtree_control" file as only controllers enabled
166 from the parent can be used in its children.
169 3. Structural Constraints
173 As it doesn't make sense to nest control of an uncontrolled resource,
174 all non-root "cgroup.subtree_control" files can only contain
175 controllers which are enabled in the parent's "cgroup.subtree_control"
176 file. A controller can be enabled only if the parent has the
177 controller enabled and a controller can't be disabled if one or more
178 children have it enabled.
181 3-2. No internal tasks
183 One long-standing issue that cgroup faces is the competition between
184 tasks belonging to the parent cgroup and its children cgroups. This
185 is inherently nasty as two different types of entities compete and
186 there is no agreed-upon obvious way to handle it. Different
187 controllers are doing different things.
189 The cpu controller considers tasks and cgroups as equivalents and maps
190 nice levels to cgroup weights. This works for some cases but falls
191 flat when children should be allocated specific ratios of CPU cycles
192 and the number of internal tasks fluctuates - the ratios constantly
193 change as the number of competing entities fluctuates. There also are
194 other issues. The mapping from nice level to weight isn't obvious or
195 universal, and there are various other knobs which simply aren't
198 The io controller implicitly creates a hidden leaf node for each
199 cgroup to host the tasks. The hidden leaf has its own copies of all
200 the knobs with "leaf_" prefixed. While this allows equivalent control
201 over internal tasks, it's with serious drawbacks. It always adds an
202 extra layer of nesting which may not be necessary, makes the interface
203 messy and significantly complicates the implementation.
205 The memory controller currently doesn't have a way to control what
206 happens between internal tasks and child cgroups and the behavior is
207 not clearly defined. There have been attempts to add ad-hoc behaviors
208 and knobs to tailor the behavior to specific workloads. Continuing
209 this direction will lead to problems which will be extremely difficult
210 to resolve in the long term.
212 Multiple controllers struggle with internal tasks and came up with
213 different ways to deal with it; unfortunately, all the approaches in
214 use now are severely flawed and, furthermore, the widely different
215 behaviors make cgroup as whole highly inconsistent.
217 It is clear that this is something which needs to be addressed from
218 cgroup core proper in a uniform way so that controllers don't need to
219 worry about it and cgroup as a whole shows a consistent and logical
220 behavior. To achieve that, unified hierarchy enforces the following
221 structural constraint:
223 Except for the root, only cgroups which don't contain any task may
224 have controllers enabled in their "cgroup.subtree_control" files.
226 Combined with other properties, this guarantees that, when a
227 controller is looking at the part of the hierarchy which has it
228 enabled, tasks are always only on the leaves. This rules out
229 situations where child cgroups compete against internal tasks of the
232 There are two things to note. Firstly, the root cgroup is exempt from
233 the restriction. Root contains tasks and anonymous resource
234 consumption which can't be associated with any other cgroup and
235 requires special treatment from most controllers. How resource
236 consumption in the root cgroup is governed is up to each controller.
238 Secondly, the restriction doesn't take effect if there is no enabled
239 controller in the cgroup's "cgroup.subtree_control" file. This is
240 important as otherwise it wouldn't be possible to create children of a
241 populated cgroup. To control resource distribution of a cgroup, the
242 cgroup must create children and transfer all its tasks to the children
243 before enabling controllers in its "cgroup.subtree_control" file.
248 4-1. Model of delegation
250 A cgroup can be delegated to a less privileged user by granting write
251 access of the directory and its "cgroup.procs" file to the user. Note
252 that the resource control knobs in a given directory concern the
253 resources of the parent and thus must not be delegated along with the
256 Once delegated, the user can build sub-hierarchy under the directory,
257 organize processes as it sees fit and further distribute the resources
258 it got from the parent. The limits and other settings of all resource
259 controllers are hierarchical and regardless of what happens in the
260 delegated sub-hierarchy, nothing can escape the resource restrictions
261 imposed by the parent.
263 Currently, cgroup doesn't impose any restrictions on the number of
264 cgroups in or nesting depth of a delegated sub-hierarchy; however,
265 this may in the future be limited explicitly.
268 4-2. Common ancestor rule
270 On the unified hierarchy, to write to a "cgroup.procs" file, in
271 addition to the usual write permission to the file and uid match, the
272 writer must also have write access to the "cgroup.procs" file of the
273 common ancestor of the source and destination cgroups. This prevents
274 delegatees from smuggling processes across disjoint sub-hierarchies.
276 Let's say cgroups C0 and C1 have been delegated to user U0 who created
277 C00, C01 under C0 and C10 under C1 as follows.
279 ~~~~~~~~~~~~~ - C0 - C00
282 ~~~~~~~~~~~~~ - C1 - C10
284 C0 and C1 are separate entities in terms of resource distribution
285 regardless of their relative positions in the hierarchy. The
286 resources the processes under C0 are entitled to are controlled by
287 C0's ancestors and may be completely different from C1. It's clear
288 that the intention of delegating C0 to U0 is allowing U0 to organize
289 the processes under C0 and further control the distribution of C0's
292 On traditional hierarchies, if a task has write access to "tasks" or
293 "cgroup.procs" file of a cgroup and its uid agrees with the target, it
294 can move the target to the cgroup. In the above example, U0 will not
295 only be able to move processes in each sub-hierarchy but also across
296 the two sub-hierarchies, effectively allowing it to violate the
297 organizational and resource restrictions implied by the hierarchical
298 structure above C0 and C1.
300 On the unified hierarchy, let's say U0 wants to write the pid of a
301 process which has a matching uid and is currently in C10 into
302 "C00/cgroup.procs". U0 obviously has write access to the file and
303 migration permission on the process; however, the common ancestor of
304 the source cgroup C10 and the destination cgroup C00 is above the
305 points of delegation and U0 would not have write access to its
306 "cgroup.procs" and thus be denied with -EACCES.
311 5-1. [Un]populated Notification
313 cgroup users often need a way to determine when a cgroup's
314 subhierarchy becomes empty so that it can be cleaned up. cgroup
315 currently provides release_agent for it; unfortunately, this mechanism
316 is riddled with issues.
318 - It delivers events by forking and execing a userland binary
319 specified as the release_agent. This is a long deprecated method of
320 notification delivery. It's extremely heavy, slow and cumbersome to
321 integrate with larger infrastructure.
323 - There is single monitoring point at the root. There's no way to
324 delegate management of a subtree.
326 - The event isn't recursive. It triggers when a cgroup doesn't have
327 any tasks or child cgroups. Events for internal nodes trigger only
328 after all children are removed. This again makes it impossible to
329 delegate management of a subtree.
331 - Events are filtered from the kernel side. A "notify_on_release"
332 file is used to subscribe to or suppress release events. This is
333 unnecessarily complicated and probably done this way because event
334 delivery itself was expensive.
336 Unified hierarchy implements "populated" field in "cgroup.events"
337 interface file which can be used to monitor whether the cgroup's
338 subhierarchy has tasks in it or not. Its value is 0 if there is no
339 task in the cgroup and its descendants; otherwise, 1. poll and
340 [id]notify events are triggered when the value changes.
342 This is significantly lighter and simpler and trivially allows
343 delegating management of subhierarchy - subhierarchy monitoring can
344 block further propagation simply by putting itself or another process
345 in the subhierarchy and monitor events that it's interested in from
346 there without interfering with monitoring higher in the tree.
348 In unified hierarchy, the release_agent mechanism is no longer
349 supported and the interface files "release_agent" and
350 "notify_on_release" do not exist.
353 5-2. Other Core Changes
355 - None of the mount options is allowed.
357 - remount is disallowed.
359 - rename(2) is disallowed.
361 - The "tasks" file is removed. Everything should at process
362 granularity. Use the "cgroup.procs" file instead.
364 - The "cgroup.procs" file is not sorted. pids will be unique unless
365 they got recycled in-between reads.
367 - The "cgroup.clone_children" file is removed.
369 - /proc/PID/cgroup keeps reporting the cgroup that a zombie belonged
370 to before exiting. If the cgroup is removed before the zombie is
371 reaped, " (deleted)" is appeneded to the path.
374 5-3. Controller File Conventions
378 In general, all controller files should be in one of the following
379 formats whenever possible.
393 KEY0 SUB_KEY0=VAL00 SUB_KEY1=VAL01...
394 KEY1 SUB_KEY0=VAL10 SUB_KEY1=VAL11...
397 For a writeable file, the format for writing should generally match
398 reading; however, controllers may allow omitting later fields or
399 implement restricted shortcuts for most common use cases.
401 For both flat and nested keyed files, only the values for a single key
402 can be written at a time. For nested keyed files, the sub key pairs
403 may be specified in any order and not all pairs have to be specified.
408 - Settings for a single feature should generally be implemented in a
411 - In general, the root cgroup should be exempt from resource control
412 and thus shouldn't have resource control knobs.
414 - If a controller implements ratio based resource distribution, the
415 control knob should be named "weight" and have the range [1, 10000]
416 and 100 should be the default value. The values are chosen to allow
417 enough and symmetric bias in both directions while keeping it
418 intuitive (the default is 100%).
420 - If a controller implements an absolute resource guarantee and/or
421 limit, the control knobs should be named "min" and "max"
422 respectively. If a controller implements best effort resource
423 gurantee and/or limit, the control knobs should be named "low" and
426 In the above four control files, the special token "max" should be
427 used to represent upward infinity for both reading and writing.
429 - If a setting has configurable default value and specific overrides,
430 the default settings should be keyed with "default" and appear as
431 the first entry in the file. Specific entries can use "default" as
432 its value to indicate inheritance of the default value.
434 - For events which are not very high frequency, an interface file
435 "events" should be created which lists event key value pairs.
436 Whenever a notifiable event happens, file modified event should be
437 generated on the file.
440 5-4. Per-Controller Changes
444 - blkio is renamed to io. The interface is overhauled anyway. The
445 new name is more in line with the other two major controllers, cpu
446 and memory, and better suited given that it may be used for cgroup
447 writeback without involving block layer.
449 - Everything including stat is always hierarchical making separate
450 recursive stat files pointless and, as no internal node can have
451 tasks, leaf weights are meaningless. The operation model is
452 simplified and the interface is overhauled accordingly.
456 The stat file. The reported stats are from the point where
457 bio's are issued to request_queue. The stats are counted
458 independent of which policies are enabled. Each line in the
459 file follows the following format. More fields may later be
462 $MAJ:$MIN rbytes=$RBYTES wbytes=$WBYTES rios=$RIOS wrios=$WIOS
466 The weight setting, currently only available and effective if
467 cfq-iosched is in use for the target device. The weight is
468 between 1 and 10000 and defaults to 100. The first line
469 always contains the default weight in the following format to
470 use when per-device setting is missing.
474 Subsequent lines list per-device weights of the following
479 Writing "$WEIGHT" or "default $WEIGHT" changes the default
480 setting. Writing "$MAJ:$MIN $WEIGHT" sets per-device weight
481 while "$MAJ:$MIN default" clears it.
483 This file is available only on non-root cgroups.
487 The maximum bandwidth and/or iops setting, only available if
488 blk-throttle is enabled. The file is of the following format.
490 $MAJ:$MIN rbps=$RBPS wbps=$WBPS riops=$RIOPS wiops=$WIOPS
492 ${R|W}BPS are read/write bytes per second and ${R|W}IOPS are
493 read/write IOs per second. "max" indicates no limit. Writing
494 to the file follows the same format but the individual
495 settings may be omitted or specified in any order.
497 This file is available only on non-root cgroups.
502 - Tasks are kept in empty cpusets after hotplug and take on the masks
503 of the nearest non-empty ancestor, instead of being moved to it.
505 - A task can be moved into an empty cpuset, and again it takes on the
506 masks of the nearest non-empty ancestor.
511 - use_hierarchy is on by default and the cgroup file for the flag is
514 - The original lower boundary, the soft limit, is defined as a limit
515 that is per default unset. As a result, the set of cgroups that
516 global reclaim prefers is opt-in, rather than opt-out. The costs
517 for optimizing these mostly negative lookups are so high that the
518 implementation, despite its enormous size, does not even provide the
519 basic desirable behavior. First off, the soft limit has no
520 hierarchical meaning. All configured groups are organized in a
521 global rbtree and treated like equal peers, regardless where they
522 are located in the hierarchy. This makes subtree delegation
523 impossible. Second, the soft limit reclaim pass is so aggressive
524 that it not just introduces high allocation latencies into the
525 system, but also impacts system performance due to overreclaim, to
526 the point where the feature becomes self-defeating.
528 The memory.low boundary on the other hand is a top-down allocated
529 reserve. A cgroup enjoys reclaim protection when it and all its
530 ancestors are below their low boundaries, which makes delegation of
531 subtrees possible. Secondly, new cgroups have no reserve per
532 default and in the common case most cgroups are eligible for the
533 preferred reclaim pass. This allows the new low boundary to be
534 efficiently implemented with just a minor addition to the generic
535 reclaim code, without the need for out-of-band data structures and
536 reclaim passes. Because the generic reclaim code considers all
537 cgroups except for the ones running low in the preferred first
538 reclaim pass, overreclaim of individual groups is eliminated as
539 well, resulting in much better overall workload performance.
541 - The original high boundary, the hard limit, is defined as a strict
542 limit that can not budge, even if the OOM killer has to be called.
543 But this generally goes against the goal of making the most out of
544 the available memory. The memory consumption of workloads varies
545 during runtime, and that requires users to overcommit. But doing
546 that with a strict upper limit requires either a fairly accurate
547 prediction of the working set size or adding slack to the limit.
548 Since working set size estimation is hard and error prone, and
549 getting it wrong results in OOM kills, most users tend to err on the
550 side of a looser limit and end up wasting precious resources.
552 The memory.high boundary on the other hand can be set much more
553 conservatively. When hit, it throttles allocations by forcing them
554 into direct reclaim to work off the excess, but it never invokes the
555 OOM killer. As a result, a high boundary that is chosen too
556 aggressively will not terminate the processes, but instead it will
557 lead to gradual performance degradation. The user can monitor this
558 and make corrections until the minimal memory footprint that still
559 gives acceptable performance is found.
561 In extreme cases, with many concurrent allocations and a complete
562 breakdown of reclaim progress within the group, the high boundary
563 can be exceeded. But even then it's mostly better to satisfy the
564 allocation from the slack available in other groups or the rest of
565 the system than killing the group. Otherwise, memory.max is there
566 to limit this type of spillover and ultimately contain buggy or even
567 malicious applications.
569 - The original control file names are unwieldy and inconsistent in
570 many different ways. For example, the upper boundary hit count is
571 exported in the memory.failcnt file, but an OOM event count has to
572 be manually counted by listening to memory.oom_control events, and
573 lower boundary / soft limit events have to be counted by first
574 setting a threshold for that value and then counting those events.
575 Also, usage and limit files encode their units in the filename.
576 That makes the filenames very long, even though this is not
577 information that a user needs to be reminded of every time they type
580 To address these naming issues, as well as to signal clearly that
581 the new interface carries a new configuration model, the naming
582 conventions in it necessarily differ from the old interface.
584 - The original limit files indicate the state of an unset limit with a
585 Very High Number, and a configured limit can be unset by echoing -1
586 into those files. But that very high number is implementation and
587 architecture dependent and not very descriptive. And while -1 can
588 be understood as an underflow into the highest possible value, -2 or
589 -10M etc. do not work, so it's not consistent.
591 memory.low, memory.high, and memory.max will use the string "max" to
592 indicate and set the highest possible value.
596 6-1. CAP for resource control
598 Unified hierarchy will require one of the capabilities(7), which is
599 yet to be decided, for all resource control related knobs. Process
600 organization operations - creation of sub-cgroups and migration of
601 processes in sub-hierarchies may be delegated by changing the
602 ownership and/or permissions on the cgroup directory and
603 "cgroup.procs" interface file; however, all operations which affect
604 resource control - writes to a "cgroup.subtree_control" file or any
605 controller-specific knobs - will require an explicit CAP privilege.
607 This, in part, is to prevent the cgroup interface from being
608 inadvertently promoted to programmable API used by non-privileged
609 binaries. cgroup exposes various aspects of the system in ways which
610 aren't properly abstracted for direct consumption by regular programs.
611 This is an administration interface much closer to sysctl knobs than
612 system calls. Even the basic access model, being filesystem path
613 based, isn't suitable for direct consumption. There's no way to
614 access "my cgroup" in a race-free way or make multiple operations
615 atomic against migration to another cgroup.
617 Another aspect is that, for better or for worse, the cgroup interface
618 goes through far less scrutiny than regular interfaces for
619 unprivileged userland. The upside is that cgroup is able to expose
620 useful features which may not be suitable for general consumption in a
621 reasonable time frame. It provides a relatively short path between
622 internal details and userland-visible interface. Of course, this
623 shortcut comes with high risk. We go through what we go through for
624 general kernel APIs for good reasons. It may end up leaking internal
625 details in a way which can exert significant pain by locking the
626 kernel into a contract that can't be maintained in a reasonable
629 Also, due to the specific nature, cgroup and its controllers don't
630 tend to attract attention from a wide scope of developers. cgroup's
631 short history is already fraught with severely mis-designed
632 interfaces, unnecessary commitments to and exposing of internal
633 details, broken and dangerous implementations of various features.
635 Keeping cgroup as an administration interface is both advantageous for
636 its role and imperative given its nature. Some of the cgroup features
637 may make sense for unprivileged access. If deemed justified, those
638 must be further abstracted and implemented as a different interface,
639 be it a system call or process-private filesystem, and survive through
640 the scrutiny that any interface for general consumption is required to
643 Requiring CAP is not a complete solution but should serve as a
644 significant deterrent against spraying cgroup usages in non-privileged