cgroups(7): documenting cgroups v2 delegation

[Michael Kerrisk (man-pages)]

Hello Tejun and Serge

The delegation feature of cgroups v2 has of course been around
for a while now, but was not documented so far in cgroups(7).
I have written some text to describe the delegation feature.
I would be happy to receive suggestions for fixes, improvements,
or corrections to errors, from you (or others). The plain-text
version for (easy review) is shown below. (Please note the FIXME!)

The branch containing the pending cgroups(7) changes can be found at: 
https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=draft_cgroup_updates

[[
   Cgroups v2 delegation
       In the context of cgroups, delegation means passing  management
       of  some  subtree  of  the  cgroup hierarchy to a nonprivileged
       process.  Cgroups v1 provides support for delegation  that  was
       accidental  and  not fully secure.  Cgroups v2 supports delegaâ
       tion by explicit design.

       Some terminology is required in order to  describe  delegation.
       A delegater is a privileged user (i.e., root) who owns a parent
       cgroup.  A delegatee  is  a  nonprivileged  user  who  will  be
       granted  the  permissions  needed  to  manage some subhierarchy
       under that parent cgroup, known as the delegated subtree.

       To perform delegation, the delegater makes certain  directories
       and  files writable by the delegatee, typically by changing the
       ownership of the objects to be the user ID  of  the  delegatee.
       Assuming that we want to delegate the hierarchy rooted at (say)
       /dlgt_grp and that there are not yet any  child  cgroups  under
       that  cgroup,  the ownership of the following is changed to the
       user ID of the delegatee:

       /dlgt_grp
              Changing the ownership of the root of the subtree  means
              that  any new cgroups created under the subtree (and the
              files they contain) will also be owned by the delegatee.

       /dlgt_grp/cgroup.procs
              Changing the ownership of this file means that the deleâ
              gatee  can move processes into the root of the delegated
              subtree.

       /dlgt_grp/cgroup.subtree_control
              Making this file owned by  the  delegatee  is  optional.
              Doing  so  means that that the delegatee can enable conâ
              trollers  (that  are  present  in  /dlgt_grp/cgroup.conâ
              trollers)  in order to further redistribute resources at
              lower levels in  the  subtree.   As  an  alternative  to
              changing the ownership of this file, the delegater might
              instead add selected controllers to this file.

       The delegater should not change the ownership  of  any  of  the
       controller  interfaces  files  (e.g., pids.max, memory.high) in
       dlgt_grp.  Those files are used from the next level  above  the
       delegated  subtree  in  order  to distribute resources into the
       subtree, and the delegatee should not have permission to change
       the resources that are distributed into the delegated subtree.

       After the aforementioned steps have been performed, the delegaâ
       tee can create child cgroups within the delegated  subtree  and
       move  processes  between  cgroups in the subtree.  If some conâ
       trollers are present in dlgt_grp/cgroup.subtree_control, or the
       ownership of that file was passed to the delegatee, the delegaâ
       tee can also control the further redistribution of  the  correâ
       sponding resources into the delegated subtree.

       Some delegation containment rules ensure that the delegatee can
       move processes between cgroups within  the  delegated  subtree,
       but  can't  move  processes  from outside the delegated subtree
       into the subtree or vice versa.  A nonprivileged process (i.e.,
       the  delegatee)  can write the PID of a "target" process into a
       cgroup.procs file only if all of the following are true:

       *  The effective  UID  of  the  writer  (i.e.,  the  delegatee)
          matches  the  real  user  ID or the saved set-user-ID of the
          target process.

       *  The writer has write permission on the cgroup.procs file  in
          the destination cgroup.

       *  The  writer has write permission on the cgroup.procs file in
          the common ancestor of the source and  destination  cgroups.
          (In  some  cases,  the  common ancestor may be the source or
          destination cgroup itself.)

          âââââââââââââââââââââââââââââââââââââââââââââââââââââââ
          âFIXME                                                â
          âââââââââââââââââââââââââââââââââââââââââââââââââââââââ
          âPlease confirm that the following is correct:        â
          âââââââââââââââââââââââââââââââââââââââââââââââââââââââ

       Note: one consequence of these delegation containment rules  is
       that  the  unprivileged delegatee can't place the first process
       into the delegated subtree; instead, the delegater  must  place
       the  first  process (a process owned by the delegatee) into the
       delegated subtree.
]]

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/