feat(box): CRI applies pod sysctls in the guest

PodSandboxConfig.linux.sysctls now flow CRI → BoxConfig.sysctls →
BOX_SYSCTL_<i> boot env → guest-init, which writes each to
/proc/sys/<name with '.' as '/'> at VM startup (best-effort: a sysctl the
guest kernel does not expose is logged and skipped, not fatal).

Verified on the KVM server: the CRI "should support safe sysctls"
conformance spec passes. "unsafe sysctls" still fails only because it
reads fs.mqueue.msg_max, which the libkrun guest kernel does not compile
in (CONFIG_POSIX_MQUEUE absent) — a guest-kernel limitation, not a CRI
defect.

Author: Roy Lin

src/core/src/config.rs

@@ -349,6 +349,13 @@ pub struct BoxConfig {
     #[serde(default)]
     pub security_opt: Vec<String>,
 
+    /// Kernel sysctls (name → value) applied in the guest at boot.
+    ///
+    /// Pod-level sysctls from the CRI `PodSandboxConfig`; the guest writes each
+    /// to `/proc/sys/<name with '.' as '/'>` once the VM is up.
+    #[serde(default)]
+    pub sysctls: Vec<(String, String)>,
+
     /// Run in privileged mode (disables all security restrictions)
     #[serde(default)]
     pub privileged: bool,
@@ -409,6 +416,7 @@ impl Default for BoxConfig {
             cap_add: vec![],
             cap_drop: vec![],
             security_opt: vec![],
+            sysctls: vec![],
             privileged: false,
             read_only: false,
             sidecar: None,

src/cri/src/config_mapper.rs

@@ -46,10 +46,27 @@ pub fn pod_sandbox_config_to_box_config(
         port_map,
         network,
         hostname,
+        sysctls: parse_sysctls(config),
         ..Default::default()
     })
 }
 
+/// Extract pod-level sysctls from the CRI sandbox config.
+///
+/// Sorted by name for deterministic ordering (the guest applies them in order).
+fn parse_sysctls(config: &PodSandboxConfig) -> Vec<(String, String)> {
+    let Some(linux) = config.linux.as_ref() else {
+        return Vec::new();
+    };
+    let mut sysctls: Vec<(String, String)> = linux
+        .sysctls
+        .iter()
+        .map(|(name, value)| (name.clone(), value.clone()))
+        .collect();
+    sysctls.sort();
+    sysctls
+}
+
 fn parse_hostname(config: &PodSandboxConfig) -> Result<Option<String>> {
     let hostname = config.hostname.trim();
     if hostname.is_empty() {
@@ -232,6 +249,40 @@ mod tests {
         assert_eq!(box_config.image, DEFAULT_AGENT_IMAGE);
     }
 
+    #[test]
+    fn test_sysctls_extracted_and_sorted() {
+        use crate::cri_api::LinuxPodSandboxConfig;
+        let mut config = make_config(HashMap::new());
+        config.linux = Some(LinuxPodSandboxConfig {
+            sysctls: HashMap::from([
+                (
+                    "net.ipv4.ip_local_port_range".to_string(),
+                    "1024 65000".to_string(),
+                ),
+                ("kernel.shm_rmid_forced".to_string(), "1".to_string()),
+            ]),
+            ..Default::default()
+        });
+        let box_config = pod_sandbox_config_to_box_config(&config, DEFAULT_AGENT_IMAGE).unwrap();
+        assert_eq!(
+            box_config.sysctls,
+            vec![
+                ("kernel.shm_rmid_forced".to_string(), "1".to_string()),
+                (
+                    "net.ipv4.ip_local_port_range".to_string(),
+                    "1024 65000".to_string()
+                ),
+            ]
+        );
+    }
+
+    #[test]
+    fn test_sysctls_empty_without_linux_config() {
+        let config = make_config(HashMap::new());
+        let box_config = pod_sandbox_config_to_box_config(&config, DEFAULT_AGENT_IMAGE).unwrap();
+        assert!(box_config.sysctls.is_empty());
+    }
+
     #[test]
     fn test_empty_default_agent_image_without_annotation_is_rejected() {
         let config = make_config(HashMap::new());

src/guest/init/src/host_config.rs

@@ -1,15 +1,41 @@
-//! Guest hostname configuration.
+//! Guest hostname and sysctl configuration.
 
 use std::path::Path;
 
-/// Apply hostname configuration from `BOX_HOSTNAME`, if present.
+/// Apply host configuration from the boot environment: pod sysctls and, if
+/// present, the hostname.
 pub fn apply_from_env() -> Result<(), Box<dyn std::error::Error>> {
+    apply_sysctls_from_env();
+
     let Ok(hostname) = std::env::var("BOX_HOSTNAME") else {
         return Ok(());
     };
     apply_hostname(&hostname, Path::new("/etc/hostname"))
 }
 
+/// Apply pod sysctls passed as `BOX_SYSCTL_<index>=<name>=<value>`.
+///
+/// Each is written to `/proc/sys/<name with '.' as '/'>`. Best-effort: a sysctl
+/// the guest kernel does not expose is logged and skipped rather than aborting
+/// VM startup.
+fn apply_sysctls_from_env() {
+    let mut index = 0;
+    loop {
+        let Ok(spec) = std::env::var(format!("BOX_SYSCTL_{index}")) else {
+            break;
+        };
+        index += 1;
+        let Some((name, value)) = spec.split_once('=') else {
+            continue;
+        };
+        let path = format!("/proc/sys/{}", name.trim().replace('.', "/"));
+        match std::fs::write(&path, value) {
+            Ok(()) => tracing::info!("Applied sysctl {name}={value}"),
+            Err(e) => tracing::warn!("Failed to apply sysctl {name}={value} ({path}): {e}"),
+        }
+    }
+}
+
 fn apply_hostname(hostname: &str, hostname_path: &Path) -> Result<(), Box<dyn std::error::Error>> {
     a3s_box_core::dns::validate_hostname(hostname)
         .map_err(|e| format!("invalid BOX_HOSTNAME: {e}"))?;

src/runtime/src/vm/spec.rs

@@ -175,6 +175,12 @@ impl VmManager {
                 env.push((format!("BOX_TMPFS_{}", i), tmpfs_spec.clone()));
             }
 
+            // Pass pod sysctls to guest init.
+            // Format: BOX_SYSCTL_<index>=<name>=<value>
+            for (i, (name, value)) in self.config.sysctls.iter().enumerate() {
+                env.push((format!("BOX_SYSCTL_{}", i), format!("{}={}", name, value)));
+            }
+
             // Pass security configuration to guest init
             let security_config = a3s_box_core::SecurityConfig::from_options(
                 &self.config.security_opt,