From 77b9a528deb965be03043bbb27a66e9dd66ae4af Mon Sep 17 00:00:00 2001
From: Kamalesh Babulal <kamalesh.babulal@oracle.com>
Date: Mon, 1 Jan 2024 15:25:21 +0530
Subject: [PATCH] man: update cgconfig.conf with systemd settings

Update the cgconfig.conf for available systemd settings, along with an
example.

Fixes: https://github.com/libcgroup/libcgroup/issues/418
Signed-off-by: Kamalesh Babulal <kamalesh.babulal@oracle.com>
Signed-off-by: Tom Hromatka <tom.hromatka@oracle.com>
TJH: Minor grammatical changes
---
 doc/man/cgconfig.conf.5 | 67 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/doc/man/cgconfig.conf.5 b/doc/man/cgconfig.conf.5
index 8673bb0c..f58c70ce 100644
--- a/doc/man/cgconfig.conf.5
+++ b/doc/man/cgconfig.conf.5
@@ -253,6 +253,53 @@ Templates does not use
 .B default
 section settings.
 
+.I systemd
+section has this form (supported on cgroup v2):
+.RS
+.nf
+.ft B
+.sp
+systemd {
+.RS
+.ft B
+slice = <slice-name.slice>;
+scope = <scope-name.scope>;
+setdefault = <yes>;
+pid = <pid>;
+.ft B
+.RE
+}
+.fi
+.RE
+.ft
+
+.TP
+.B slice
+The name of the systemd slice unit, should end with '.slice'  and obey the rules set forth by systemd slice unit. The slice unit is created, if it doesn't exist.  This configuration requires
+.B 'scope=<scope-name.scope>'.
+The term  'unit'  and 'cgroup' is used interchangeably.
+
+.TP
+.B scope
+The name of the systemd scope unit should end with '.scope'  and obey the rules set forth by systemd transient scope unit. This configuration requires
+.B 'slice=<slice-name.scope>'
+
+.TP
+.B setdefault
+Set the scope as the default libcgroup scope. This default scope is used by libcgroup tools to build up the cgroup path.
+
+.TP
+.B pid
+Moves the provided pid into the <slice-name.slice>/<scope-name.scope>. Without this configuration, libcgroup will create and attach a default idle program
+.B 'libcgroup_systemd_idle_thread'
+required by a systemd transient scope unit. The
+.B 'scope-name.scope'
+is automatically removed by systemd when the last task in the cgroup exits, but the
+.B 'slice-name.slice'
+will exist until manually removed.
+
+.LP
+
 .I /etc/cgconfig.d/
 directory can be used for additional configuration files. cgrulesengd searches this directory for additional templates.
 
@@ -789,6 +836,26 @@ It mounts the cpu controller with MS_NODEV, MS_NOSUID and MS_NOEXEC
 options passed.
 
 
+.SS Example 9
+.LP
+The configuration file:
+
+.LP
+.RS
+.nf
+systemd {
+.RS
+slice = database.slice;
+scope = db.scope;
+setdefault = yes;
+.RE
+}
+
+.fi
+.RE
+
+This creates a systemd transient scope unit db.scope under the systemd slice unit database.slice and spawns a libcgroup_systemd_idle_thread in the scope cgroup unit. The 'setdefault' configuration appends database.slice/db.scope to the path constructed by libcgroup and its tools.
+
 .SH RECOMMENDATIONS
 .SS Keep hierarchies separated
 Having multiple hierarchies is perfectly valid and can be useful
-- 
2.47.2