[PATCH] Documentation/cgroup-v2: warn about cgroup.kill / cgroup.freeze delegation

[Maoyi Xie <maoyixie.tju@gmail.com>]

From: Maoyi Xie <maoyi.xie@ntu.edu.sg>

cgroup.kill and cgroup.freeze act on every process in the cgroup
or its descendants without checking the writer's signal authority
over those processes. Delegating either file (by chown, or by
passing an open file descriptor) therefore grants the recipient
unconditional kill or freeze authority over whatever ends up in the
subtree.

This works as intended: the files are deliberate "delegated control"
knobs, and the standard signal-permission rules of kill(2) and
SIGSTOP do not apply. The current text in
Documentation/admin-guide/cgroup-v2.rst describes the behaviour of
cgroup.kill and cgroup.freeze in functional terms but does not flag
the delegation footgun, which makes it easy for runtime authors to
hand the files to a less-privileged user without realising the
implications.

Add a paragraph to each section explicitly calling out the
delegation contract and the open-FD equivalence, so runtime authors
have a single place to read the rule before deciding whether to
chown or pass FDs to these files.

No code change.

Suggested-by: Michal Koutný <mkoutny@suse.com>
Signed-off-by: Maoyi Xie <maoyi.xie@ntu.edu.sg>
---
 Documentation/admin-guide/cgroup-v2.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 91beaa679..6013e2d1d 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -1048,6 +1048,15 @@ All cgroup core files are prefixed with "cgroup."
 	it's possible to delete a frozen (and empty) cgroup, as well as
 	create new sub-cgroups.
 
+	A write to cgroup.freeze affects every process currently in the
+	cgroup or its descendants regardless of the writer's signal
+	authority over those processes. The file therefore acts as a
+	delegated stop knob: chowning it, or passing an open file
+	descriptor to it, grants the recipient unconditional freeze
+	authority over whatever lands in the subtree. Runtime authors
+	should not delegate cgroup.freeze outside of the trust boundary
+	of the cgroup itself.
+
   cgroup.kill
 	A write-only single value file which exists in non-root cgroups.
 	The only allowed value is "1".
@@ -1063,6 +1072,15 @@ All cgroup core files are prefixed with "cgroup."
 	killing cgroups is a process directed operation, i.e. it affects
 	the whole thread-group.
 
+	A write to cgroup.kill sends SIGKILL to every process currently
+	in the cgroup or its descendants regardless of the writer's
+	signal authority over those processes. The file therefore acts
+	as a delegated kill knob: chowning it, or passing an open file
+	descriptor to it, grants the recipient unconditional kill
+	authority over whatever lands in the subtree. Runtime authors
+	should not delegate cgroup.kill outside of the trust boundary
+	of the cgroup itself.
+
   cgroup.pressure
 	A read-write single value file that allowed values are "0" and "1".
 	The default is "1".
-- 
2.34.1