2Cgroup unified hierarchy
   4April, 2014             Tejun Heo <>
   6This document describes the changes made by unified hierarchy and
   7their rationales.  It will eventually be merged into the main cgroup
  121. Background
  132. Basic Operation
  14  2-1. Mounting
  15  2-2. cgroup.subtree_control
  16  2-3. cgroup.controllers
  173. Structural Constraints
  18  3-1. Top-down
  19  3-2. No internal tasks
  204. Other Changes
  21  4-1. [Un]populated Notification
  22  4-2. Other Core Changes
  23  4-3. Per-Controller Changes
  24    4-3-1. blkio
  25    4-3-2. cpuset
  26    4-3-3. memory
  275. Planned Changes
  28  5-1. CAP for resource control
  311. Background
  33cgroup allows an arbitrary number of hierarchies and each hierarchy
  34can host any number of controllers.  While this seems to provide a
  35high level of flexibility, it isn't quite useful in practice.
  37For example, as there is only one instance of each controller, utility
  38type controllers such as freezer which can be useful in all
  39hierarchies can only be used in one.  The issue is exacerbated by the
  40fact that controllers can't be moved around once hierarchies are
  41populated.  Another issue is that all controllers bound to a hierarchy
  42are forced to have exactly the same view of the hierarchy.  It isn't
  43possible to vary the granularity depending on the specific controller.
  45In practice, these issues heavily limit which controllers can be put
  46on the same hierarchy and most configurations resort to putting each
  47controller on its own hierarchy.  Only closely related ones, such as
  48the cpu and cpuacct controllers, make sense to put on the same
  49hierarchy.  This often means that userland ends up managing multiple
  50similar hierarchies repeating the same steps on each hierarchy
  51whenever a hierarchy management operation is necessary.
  53Unfortunately, support for multiple hierarchies comes at a steep cost.
  54Internal implementation in cgroup core proper is dazzlingly
  55complicated but more importantly the support for multiple hierarchies
  56restricts how cgroup is used in general and what controllers can do.
  58There's no limit on how many hierarchies there may be, which means
  59that a task's cgroup membership can't be described in finite length.
  60The key may contain any varying number of entries and is unlimited in
  61length, which makes it highly awkward to handle and leads to addition
  62of controllers which exist only to identify membership, which in turn
  63exacerbates the original problem.
  65Also, as a controller can't have any expectation regarding what shape
  66of hierarchies other controllers would be on, each controller has to
  67assume that all other controllers are operating on completely
  68orthogonal hierarchies.  This makes it impossible, or at least very
  69cumbersome, for controllers to cooperate with each other.
  71In most use cases, putting controllers on hierarchies which are
  72completely orthogonal to each other isn't necessary.  What usually is
  73called for is the ability to have differing levels of granularity
  74depending on the specific controller.  In other words, hierarchy may
  75be collapsed from leaf towards root when viewed from specific
  76controllers.  For example, a given configuration might not care about
  77how memory is distributed beyond a certain level while still wanting
  78to control how CPU cycles are distributed.
  80Unified hierarchy is the next version of cgroup interface.  It aims to
  81address the aforementioned issues by having more structure while
  82retaining enough flexibility for most use cases.  Various other
  83general and controller-specific interface issues are also addressed in
  84the process.
  872. Basic Operation
  892-1. Mounting
  91Currently, unified hierarchy can be mounted with the following mount
  92command.  Note that this is still under development and scheduled to
  93change soon.
  95 mount -t cgroup -o __DEVEL__sane_behavior cgroup $MOUNT_POINT
  97All controllers which support the unified hierarchy and are not bound
  98to other hierarchies are automatically bound to unified hierarchy and
  99show up at the root of it.  Controllers which are enabled only in the
 100root of unified hierarchy can be bound to other hierarchies.  This
 101allows mixing unified hierarchy with the traditional multiple
 102hierarchies in a fully backward compatible way.
 104For development purposes, the following boot parameter makes all
 105controllers to appear on the unified hierarchy whether supported or
 108 cgroup__DEVEL__legacy_files_on_dfl
 110A controller can be moved across hierarchies only after the controller
 111is no longer referenced in its current hierarchy.  Because per-cgroup
 112controller states are destroyed asynchronously and controllers may
 113have lingering references, a controller may not show up immediately on
 114the unified hierarchy after the final umount of the previous
 115hierarchy.  Similarly, a controller should be fully disabled to be
 116moved out of the unified hierarchy and it may take some time for the
 117disabled controller to become available for other hierarchies;
 118furthermore, due to dependencies among controllers, other controllers
 119may need to be disabled too.
 121While useful for development and manual configurations, dynamically
 122moving controllers between the unified and other hierarchies is
 123strongly discouraged for production use.  It is recommended to decide
 124the hierarchies and controller associations before starting using the
 1282-2. cgroup.subtree_control
 130All cgroups on unified hierarchy have a "cgroup.subtree_control" file
 131which governs which controllers are enabled on the children of the
 132cgroup.  Let's assume a hierarchy like the following.
 134  root - A - B - C
 135               \ D
 137root's "cgroup.subtree_control" file determines which controllers are
 138enabled on A.  A's on B.  B's on C and D.  This coincides with the
 139fact that controllers on the immediate sub-level are used to
 140distribute the resources of the parent.  In fact, it's natural to
 141assume that resource control knobs of a child belong to its parent.
 142Enabling a controller in a "cgroup.subtree_control" file declares that
 143distribution of the respective resources of the cgroup will be
 144controlled.  Note that this means that controller enable states are
 145shared among siblings.
 147When read, the file contains a space-separated list of currently
 148enabled controllers.  A write to the file should contain a
 149space-separated list of controllers with '+' or '-' prefixed (without
 150the quotes).  Controllers prefixed with '+' are enabled and '-'
 151disabled.  If a controller is listed multiple times, the last entry
 152wins.  The specific operations are executed atomically - either all
 153succeed or fail.
 1562-3. cgroup.controllers
 158Read-only "cgroup.controllers" file contains a space-separated list of
 159controllers which can be enabled in the cgroup's
 160"cgroup.subtree_control" file.
 162In the root cgroup, this lists controllers which are not bound to
 163other hierarchies and the content changes as controllers are bound to
 164and unbound from other hierarchies.
 166In non-root cgroups, the content of this file equals that of the
 167parent's "cgroup.subtree_control" file as only controllers enabled
 168from the parent can be used in its children.
 1713. Structural Constraints
 1733-1. Top-down
 175As it doesn't make sense to nest control of an uncontrolled resource,
 176all non-root "cgroup.subtree_control" files can only contain
 177controllers which are enabled in the parent's "cgroup.subtree_control"
 178file.  A controller can be enabled only if the parent has the
 179controller enabled and a controller can't be disabled if one or more
 180children have it enabled.
 1833-2. No internal tasks
 185One long-standing issue that cgroup faces is the competition between
 186tasks belonging to the parent cgroup and its children cgroups.  This
 187is inherently nasty as two different types of entities compete and
 188there is no agreed-upon obvious way to handle it.  Different
 189controllers are doing different things.
 191The cpu controller considers tasks and cgroups as equivalents and maps
 192nice levels to cgroup weights.  This works for some cases but falls
 193flat when children should be allocated specific ratios of CPU cycles
 194and the number of internal tasks fluctuates - the ratios constantly
 195change as the number of competing entities fluctuates.  There also are
 196other issues.  The mapping from nice level to weight isn't obvious or
 197universal, and there are various other knobs which simply aren't
 198available for tasks.
 200The blkio controller implicitly creates a hidden leaf node for each
 201cgroup to host the tasks.  The hidden leaf has its own copies of all
 202the knobs with "leaf_" prefixed.  While this allows equivalent control
 203over internal tasks, it's with serious drawbacks.  It always adds an
 204extra layer of nesting which may not be necessary, makes the interface
 205messy and significantly complicates the implementation.
 207The memory controller currently doesn't have a way to control what
 208happens between internal tasks and child cgroups and the behavior is
 209not clearly defined.  There have been attempts to add ad-hoc behaviors
 210and knobs to tailor the behavior to specific workloads.  Continuing
 211this direction will lead to problems which will be extremely difficult
 212to resolve in the long term.
 214Multiple controllers struggle with internal tasks and came up with
 215different ways to deal with it; unfortunately, all the approaches in
 216use now are severely flawed and, furthermore, the widely different
 217behaviors make cgroup as whole highly inconsistent.
 219It is clear that this is something which needs to be addressed from
 220cgroup core proper in a uniform way so that controllers don't need to
 221worry about it and cgroup as a whole shows a consistent and logical
 222behavior.  To achieve that, unified hierarchy enforces the following
 223structural constraint:
 225 Except for the root, only cgroups which don't contain any task may
 226 have controllers enabled in their "cgroup.subtree_control" files.
 228Combined with other properties, this guarantees that, when a
 229controller is looking at the part of the hierarchy which has it
 230enabled, tasks are always only on the leaves.  This rules out
 231situations where child cgroups compete against internal tasks of the
 234There are two things to note.  Firstly, the root cgroup is exempt from
 235the restriction.  Root contains tasks and anonymous resource
 236consumption which can't be associated with any other cgroup and
 237requires special treatment from most controllers.  How resource
 238consumption in the root cgroup is governed is up to each controller.
 240Secondly, the restriction doesn't take effect if there is no enabled
 241controller in the cgroup's "cgroup.subtree_control" file.  This is
 242important as otherwise it wouldn't be possible to create children of a
 243populated cgroup.  To control resource distribution of a cgroup, the
 244cgroup must create children and transfer all its tasks to the children
 245before enabling controllers in its "cgroup.subtree_control" file.
 2484. Other Changes
 2504-1. [Un]populated Notification
 252cgroup users often need a way to determine when a cgroup's
 253subhierarchy becomes empty so that it can be cleaned up.  cgroup
 254currently provides release_agent for it; unfortunately, this mechanism
 255is riddled with issues.
 257- It delivers events by forking and execing a userland binary
 258  specified as the release_agent.  This is a long deprecated method of
 259  notification delivery.  It's extremely heavy, slow and cumbersome to
 260  integrate with larger infrastructure.
 262- There is single monitoring point at the root.  There's no way to
 263  delegate management of a subtree.
 265- The event isn't recursive.  It triggers when a cgroup doesn't have
 266  any tasks or child cgroups.  Events for internal nodes trigger only
 267  after all children are removed.  This again makes it impossible to
 268  delegate management of a subtree.
 270- Events are filtered from the kernel side.  A "notify_on_release"
 271  file is used to subscribe to or suppress release events.  This is
 272  unnecessarily complicated and probably done this way because event
 273  delivery itself was expensive.
 275Unified hierarchy implements an interface file "cgroup.populated"
 276which can be used to monitor whether the cgroup's subhierarchy has
 277tasks in it or not.  Its value is 0 if there is no task in the cgroup
 278and its descendants; otherwise, 1.  poll and [id]notify events are
 279triggered when the value changes.
 281This is significantly lighter and simpler and trivially allows
 282delegating management of subhierarchy - subhierarchy monitoring can
 283block further propagation simply by putting itself or another process
 284in the subhierarchy and monitor events that it's interested in from
 285there without interfering with monitoring higher in the tree.
 287In unified hierarchy, the release_agent mechanism is no longer
 288supported and the interface files "release_agent" and
 289"notify_on_release" do not exist.
 2924-2. Other Core Changes
 294- None of the mount options is allowed.
 296- remount is disallowed.
 298- rename(2) is disallowed.
 300- The "tasks" file is removed.  Everything should at process
 301  granularity.  Use the "cgroup.procs" file instead.
 303- The "cgroup.procs" file is not sorted.  pids will be unique unless
 304  they got recycled in-between reads.
 306- The "cgroup.clone_children" file is removed.
 3094-3. Per-Controller Changes
 3114-3-1. blkio
 313- blk-throttle becomes properly hierarchical.
 3164-3-2. cpuset
 318- Tasks are kept in empty cpusets after hotplug and take on the masks
 319  of the nearest non-empty ancestor, instead of being moved to it.
 321- A task can be moved into an empty cpuset, and again it takes on the
 322  masks of the nearest non-empty ancestor.
 3254-3-3. memory
 327- use_hierarchy is on by default and the cgroup file for the flag is
 328  not created.
 3315. Planned Changes
 3335-1. CAP for resource control
 335Unified hierarchy will require one of the capabilities(7), which is
 336yet to be decided, for all resource control related knobs.  Process
 337organization operations - creation of sub-cgroups and migration of
 338processes in sub-hierarchies may be delegated by changing the
 339ownership and/or permissions on the cgroup directory and
 340"cgroup.procs" interface file; however, all operations which affect
 341resource control - writes to a "cgroup.subtree_control" file or any
 342controller-specific knobs - will require an explicit CAP privilege.
 344This, in part, is to prevent the cgroup interface from being
 345inadvertently promoted to programmable API used by non-privileged
 346binaries.  cgroup exposes various aspects of the system in ways which
 347aren't properly abstracted for direct consumption by regular programs.
 348This is an administration interface much closer to sysctl knobs than
 349system calls.  Even the basic access model, being filesystem path
 350based, isn't suitable for direct consumption.  There's no way to
 351access "my cgroup" in a race-free way or make multiple operations
 352atomic against migration to another cgroup.
 354Another aspect is that, for better or for worse, the cgroup interface
 355goes through far less scrutiny than regular interfaces for
 356unprivileged userland.  The upside is that cgroup is able to expose
 357useful features which may not be suitable for general consumption in a
 358reasonable time frame.  It provides a relatively short path between
 359internal details and userland-visible interface.  Of course, this
 360shortcut comes with high risk.  We go through what we go through for
 361general kernel APIs for good reasons.  It may end up leaking internal
 362details in a way which can exert significant pain by locking the
 363kernel into a contract that can't be maintained in a reasonable
 366Also, due to the specific nature, cgroup and its controllers don't
 367tend to attract attention from a wide scope of developers.  cgroup's
 368short history is already fraught with severely mis-designed
 369interfaces, unnecessary commitments to and exposing of internal
 370details, broken and dangerous implementations of various features.
 372Keeping cgroup as an administration interface is both advantageous for
 373its role and imperative given its nature.  Some of the cgroup features
 374may make sense for unprivileged access.  If deemed justified, those
 375must be further abstracted and implemented as a different interface,
 376be it a system call or process-private filesystem, and survive through
 377the scrutiny that any interface for general consumption is required to
 378go through.
 380Requiring CAP is not a complete solution but should serve as a
 381significant deterrent against spraying cgroup usages in non-privileged