From 4242dfbe4f4726f7b4c95617b1130f8fea33b913 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Mon, 25 Dec 2017 09:13:29 +0100 Subject: [PATCH] cgroups.7: Add subsection describing cgroups v2 subtree delegation Signed-off-by: Michael Kerrisk --- man7/cgroups.7 | 98 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 97 insertions(+), 1 deletion(-) diff --git a/man7/cgroups.7 b/man7/cgroups.7 index ef56f8f1b..91fd650bb 100644 --- a/man7/cgroups.7 +++ b/man7/cgroups.7 @@ -1,5 +1,5 @@ .\" Copyright (C) 2015 Serge Hallyn -.\" and Copyright (C) 2016 Michael Kerrisk +.\" and Copyright (C) 2016, 2017 Michael Kerrisk .\" .\" %%%LICENSE_START(VERBATIM) .\" Permission is granted to make and distribute verbatim copies of this @@ -750,6 +750,102 @@ of a process for each notification. Second, notification can be delegated to a process that lives inside a container associated with the newly empty cgroup. .\" +.SS 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 delegation by explicit design. +.PP +Some terminology is required in order to describe delegation. +A +.I delegater +is a privileged user (i.e., root) who owns a parent cgroup. +A +.I delegatee +is a nonprivileged user who will be granted the permissions needed +to manage some subhierarchy under that parent cgroup, +known as the +.IR "delegated subtree" . +.PP +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 +.I /grp1 +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: +.TP +.IR /grp1 +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. +.TP +.IR /grp1/cgroup.procs +Changing ownership of this file means that the delegatee +can move processes into the root of the delegated subtree. +.TP +.IR /grp1/cgroup.subtree_control +Making this file owned by the delegatee is optional. +Doing so means that that the delegatee can enable controllers +(that are present in +.IR /grp1/cgroup.controllers ) +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. +.PP +The delegater should +.I not +change the ownership of any of the controller interfaces files (e.g., +.IR pids.max , +.IR memory.high ) +in +.IR grp1 . +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. +.PP +After the aforementioned steps have been performed, +the delegatee can create child cgroups within the delegated subtree +and move processes between cgroups in the subtree. +If some controllers are present in +.IR grp1/cgroup.subtree_control , +or the ownership of that file was passed to the delegatee, +the the delegatee can also control the further redistribution +of the corresponding resources into the delegated subtree. +.PP +Some delegation +.IR "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 +.IR cgroup.procs +file only if all of the following are true: +.IP * 3 +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. +.IP * +The writer has write permission on the +.I cgroup.procs +file in the destination cgroup. +.IP * +The writer has write permission on the +.I 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.) +.PP +.IR Note : +one consequence of these delegation containment rules is that the +delegater must place the first process (a process owned by the delegatee) +into the delegated subtree. +.\" .SS /proc files .TP .IR /proc/cgroups " (since Linux 2.6.24)"