systemd: Add support for managing cgroups through systemd

`SystemdCgroup` takes a `parent`, which is the name of a slice, and a
`unit`, which is the name of a slice or a scope unit, and provides methods
to start, kill the unit, as well as set properties for the unit.

The mods, `cpu`, `memory`, `cpuset`, and `pids`, are designed to generate
properties quickly. It hides the difference between cgroups v1 and v2, and
does simple checks for the systemd version and arguments.

Signed-off-by: Xuewei Niu <[email protected]>

Author: justxuewei

Cargo.toml

@@ -18,6 +18,8 @@ libc = "0.2"
 serde = { version = "1.0", features = ["derive"], optional = true }
 thiserror = "1"
 oci-spec = "0.6"
+zbus = "3.12"
+bit-vec = "0.6"
 
 [dev-dependencies]
 libc = "0.2.76"

src/lib.rs

@@ -9,6 +9,7 @@ pub mod manager;
 pub use manager::{FsManager, Manager};
 pub mod stat;
 pub use stat::Stats;
+pub mod systemd;
 
 /// The maximum value for CPU shares in cgroups v1
 pub const CPU_SHARES_V1_MAX: u64 = 262144;

src/systemd/cgroup.rs

@@ -0,0 +1,176 @@
+// Copyright (c) 2025 Ant Group
+//
+// SPDX-License-Identifier: Apache-2.0 or MIT
+//
+
+use libc::SIGKILL;
+use zbus::blocking::Connection;
+use zbus::zvariant::Value;
+use zbus::Error as ZbusError;
+
+use crate::fs::hierarchies;
+use crate::systemd::dbus::{
+    SystemManager, BLOCK_IO_ACCOUNTING, CPU_ACCOUNTING, DEFAULT_DEPENDENCIES, DELEGATE,
+    DESCRIPTION, IO_ACCOUNTING, MEMORY_ACCOUNTING, NO_SUCH_UNIT, PIDS, SLICE, TASKS_ACCOUNTING,
+    UNIT_MODE_REPLACE, WANTS, WHO_ENUM_ALL,
+};
+use crate::systemd::error::{Error, Result};
+use crate::systemd::{utils, Property};
+use crate::CgroupPid;
+
+pub struct SystemdCgroup {
+    /// The name of slice
+    slice: String,
+    /// The name of the systemd unit (slice or scope)
+    unit: String,
+    /// Whether the systemd unit is using cgroup v2
+    v2: bool,
+}
+
+impl SystemdCgroup {
+    pub fn new(slice: &str, unit: &str) -> Result<Self> {
+        Ok(Self {
+            slice: slice.to_string(),
+            unit: unit.to_string(),
+            v2: hierarchies::is_cgroup2_unified_mode(),
+        })
+    }
+}
+
+impl SystemdCgroup {
+    fn system_manager(&self) -> Result<SystemManager> {
+        let system_bus = Connection::system()?;
+        let proxy = SystemManager::new(&system_bus)?;
+
+        Ok(proxy)
+    }
+
+    /// Start a slice or a scope unit controlled and supervised by systemd.
+    ///
+    /// For more information, see:
+    /// https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html
+    /// https://www.freedesktop.org/software/systemd/man/latest/systemd.slice.html
+    /// https://www.freedesktop.org/software/systemd/man/latest/systemd.scope.html
+    pub fn start(&self, pid: CgroupPid) -> Result<()> {
+        let mut properties: Vec<Property> = vec![
+            (CPU_ACCOUNTING, Value::Bool(true)),
+            (DEFAULT_DEPENDENCIES, Value::Bool(false)),
+            // MemoryAccount is for cgroupsv2 as documented in dbus.
+            // However, "github.com/opencontainer/runc" uses it for all.
+            // Shall we follow the same way?
+            (MEMORY_ACCOUNTING, Value::Bool(true)),
+            (TASKS_ACCOUNTING, Value::Bool(true)),
+            (DESCRIPTION, Value::Str("kata-containers unit".into())),
+            (PIDS, Value::Array(vec![pid.pid as u32].into())),
+        ];
+
+        if self.v2() {
+            properties.push((IO_ACCOUNTING, Value::Bool(true)));
+        } else {
+            properties.push((BLOCK_IO_ACCOUNTING, Value::Bool(true)));
+        }
+
+        if utils::is_slice_unit(&self.unit) {
+            // If we create a slice, the parent is defined via a Wants=.
+            properties.push((WANTS, Value::Str(self.slice.as_str().into())));
+        } else {
+            // Otherwise it's a scope, which we put into a Slice=.
+            properties.push((SLICE, Value::Str(self.slice.as_str().into())));
+            // Assume scopes always support delegation (supported since systemd v218).
+            properties.push((DELEGATE, Value::Bool(true)));
+        }
+
+        let sysmgr = self.system_manager()?;
+
+        sysmgr.start_transient_unit(&self.unit, UNIT_MODE_REPLACE, &properties, &[])?;
+
+        Ok(())
+    }
+
+    /// Set properties for the unit through dbus `SetUnitProperties`.
+    pub fn set_properties(&self, properties: &Vec<Property>) -> Result<()> {
+        let sysmgr = self.system_manager()?;
+
+        sysmgr.set_unit_properties(&self.unit, true, properties)?;
+
+        Ok(())
+    }
+
+    /// Kill the unit through dbus `KillUnit` with `SIGKILL` signal.
+    pub fn kill(&self) -> Result<()> {
+        let sysmgr = self.system_manager()?;
+
+        let ret = sysmgr.kill_unit(&self.unit, WHO_ENUM_ALL, SIGKILL);
+
+        // Ignore no such unit error
+        if let Err(ZbusError::MethodError(err_name, _, _)) = &ret {
+            if err_name.as_str() == NO_SUCH_UNIT {
+                return Ok(());
+            }
+        }
+        ret?;
+
+        Ok(())
+    }
+
+    /// Freeze the unit through dbus `FreezeUnit`.
+    pub fn freeze(&self) -> Result<()> {
+        let sysmgr = self.system_manager()?;
+
+        sysmgr.freeze_unit(&self.unit)?;
+
+        Ok(())
+    }
+
+    /// Thaw the frozen unit through dbus `ThawUnit`.
+    pub fn thaw(&self) -> Result<()> {
+        let sysmgr = self.system_manager()?;
+
+        sysmgr.thaw_unit(&self.unit)?;
+
+        Ok(())
+    }
+
+    /// Get the systemd version.
+    pub fn systemd_version(&self) -> Result<usize> {
+        let sysmgr = self.system_manager()?;
+
+        let version = sysmgr.version()?;
+        let version = version
+            .parse::<usize>()
+            .map_err(|_| Error::CorruptedSystemdVersion(version.clone()))?;
+
+        Ok(version)
+    }
+
+    /// Check if the unit exists.
+    pub fn exists(&self) -> Result<bool> {
+        let sysmgr = self.system_manager()?;
+
+        let ret = sysmgr.get_unit(&self.unit);
+
+        if let Err(ZbusError::MethodError(err_name, _, _)) = &ret {
+            if err_name.as_str() == NO_SUCH_UNIT {
+                return Ok(false);
+            }
+        }
+
+        ret?;
+
+        Ok(true)
+    }
+
+    /// Add a process (tgid) to the unit through dbus
+    /// `AttachProcessesToUnit`.
+    pub fn add_process(&self, pid: CgroupPid, subcgroup: &str) -> Result<()> {
+        let sysmgr = self.system_manager()?;
+
+        sysmgr.attach_processes_to_unit(&self.unit, subcgroup, &[pid.pid as u32])?;
+
+        Ok(())
+    }
+
+    pub fn v2(&self) -> bool {
+        self.v2
+    }
+}

src/systemd/cpu.rs

@@ -0,0 +1,50 @@
+// Copyright (c) 2025 Ant Group
+//
+// SPDX-License-Identifier: Apache-2.0 or MIT
+//
+
+use crate::systemd::error::{Error, Result};
+use crate::systemd::{dbus, CPU_SYSTEMD_VERSION};
+use crate::{CPU_SHARES_V1_MAX, CPU_WEIGHT_V2_MAX};
+
+/// Returns the property for CPU shares.
+///
+/// Please note that if the shares is obtained from OCI runtime spec, it
+/// MUST be converted, see [1] and `convert_shares_to_v2()`.
+///
+/// 1: https://github.com/containers/crun/blob/main/crun.1.md#cgroup-v2
+pub fn shares(shares: u64, v2: bool) -> Result<(&'static str, u64)> {
+    let (id, shares) = if v2 {
+        let shares = match shares {
+            0 => 100,
+            1..=CPU_WEIGHT_V2_MAX => shares,
+            _ => return Err(Error::InvalidArgument),
+        };
+
+        (dbus::CPU_WEIGHT, shares)
+    } else {
+        let shares = match shares {
+            0 => 1024,
+            2..=CPU_SHARES_V1_MAX => shares,
+            _ => return Err(Error::InvalidArgument),
+        };
+
+        (dbus::CPU_SHARES, shares)
+    };
+
+    Ok((id, shares))
+}
+
+/// Returns the property for CPU period.
+pub fn period(period: u64, systemd_version: usize) -> Result<(&'static str, u64)> {
+    if systemd_version < CPU_SYSTEMD_VERSION {
+        return Err(Error::ObsoleteSystemd);
+    }
+
+    Ok((dbus::CPU_QUOTA_PERIOD_US, period))
+}
+
+/// Return the property for CPU quota.
+pub fn quota(quota: u64) -> Result<(&'static str, u64)> {
+    Ok((dbus::CPU_QUOTA_PER_SEC_US, quota))
+}

src/systemd/cpuset.rs

@@ -0,0 +1,106 @@
+// Copyright (c) 2025 Ant Group
+//
+// SPDX-License-Identifier: Apache-2.0 or MIT
+//
+
+use bit_vec::BitVec;
+
+use crate::systemd::error::{Error, Result};
+use crate::systemd::{dbus, CPUSET_SYSTEMD_VERSION};
+
+const BYTE_IN_BITS: usize = 8;
+
+/// Returns the property for cpuset CPUs.
+pub fn cpuset_cpus(cpus: &str, systemd_version: usize) -> Result<(&'static str, Vec<u8>)> {
+    if systemd_version < CPUSET_SYSTEMD_VERSION {
+        return Err(Error::ObsoleteSystemd);
+    }
+
+    let mask = convert_list_to_mask(cpus)?;
+
+    Ok((dbus::ALLOWED_CPUS, mask))
+}
+
+/// Returns the property for cpuset memory nodes.
+pub fn cpuset_mems(mems: &str, systemd_version: usize) -> Result<(&'static str, Vec<u8>)> {
+    if systemd_version < CPUSET_SYSTEMD_VERSION {
+        return Err(Error::ObsoleteSystemd);
+    }
+
+    let mask = convert_list_to_mask(mems)?;
+
+    Ok((dbus::ALLOWED_MEMORY_NODES, mask))
+}
+
+/// Convert cpuset cpus/mems from the string in comma-separated list format
+/// to bitmask restored in `Vec<u8>`, see [1].
+///
+/// 1: https://man7.org/linux/man-pages/man7/cpuset.7.html
+///
+/// # Arguments
+///
+/// * `list` - A string slice that holds the list of CPUs in the format
+///   "0-3,5,7".
+fn convert_list_to_mask(list: &str) -> Result<Vec<u8>> {
+    let mut bit_vec = BitVec::from_elem(8, false);
+
+    let local_idx =
+        |index: usize| -> usize { index / BYTE_IN_BITS * BYTE_IN_BITS + 7 - index % BYTE_IN_BITS };
+
+    for part1 in list.split(',') {
+        let range: Vec<&str> = part1.split('-').collect();
+        match range.len() {
+            // x-
+            1 => {
+                let left: usize = range[0].parse().map_err(|_| Error::InvalidArgument)?;
+
+                while left >= bit_vec.len() {
+                    bit_vec.grow(BYTE_IN_BITS, false);
+                }
+                bit_vec.set(local_idx(left), true);
+            }
+            // x-y
+            2 => {
+                let left: usize = range[0].parse().map_err(|_| Error::InvalidArgument)?;
+                let right: usize = range[1].parse().map_err(|_| Error::InvalidArgument)?;
+
+                while right >= bit_vec.len() {
+                    bit_vec.grow(BYTE_IN_BITS, false);
+                }
+
+                for index in left..=right {
+                    bit_vec.set(local_idx(index), true);
+                }
+            }
+            _ => {
+                return Err(Error::InvalidArgument);
+            }
+        }
+    }
+
+    let mut mask = bit_vec.to_bytes();
+    mask.reverse();
+
+    Ok(mask)
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::systemd::cpuset::convert_list_to_mask;
+
+    #[test]
+    fn test_convert_list_to_mask() {
+        let mask = convert_list_to_mask("2-4").unwrap();
+        assert_eq!(vec![0b00011100 as u8], mask);
+
+        let mask = convert_list_to_mask("1,7").unwrap();
+        assert_eq!(vec![0b10000010 as u8], mask);
+
+        let mask = convert_list_to_mask("0-4,9").unwrap();
+        assert_eq!(vec![0b00000010 as u8, 0b00011111 as u8], mask);
+
+        assert!(convert_list_to_mask("1-3-4").is_err());
+
+        assert!(convert_list_to_mask("1-3,,").is_err());
+    }
+}