Skip to main content

runnerd_core/
isolation.rs

1//! How a runner container is kept from the host while it runs its own Docker Engine. A backend decides only how
2//! the container is created; its name, limits, labels and slice are the same for every backend (`docker`). It also
3//! words what the host must have for a backend to start one, so a refused start and `runnerd doctor` say it alike; it
4//! reads nothing from the host.
5
6use std::fmt;
7
8use bollard::models::HostConfig;
9
10use crate::api::{Check, CheckStatus};
11use crate::config;
12
13/// An isolation backend: how runner containers are created so their Docker Engine cannot reach the host.
14pub trait Isolation: Send + Sync + fmt::Debug {
15    /// The name `runnerd.toml` uses, also put on the container's `runnerd.isolation` label.
16    fn name(&self) -> &'static str;
17    /// Whether a job in the container can take over the host.
18    fn is_unsafe(&self) -> bool;
19    /// Sets the container's runtime and privileges.
20    fn configure(&self, host_config: &mut HostConfig);
21}
22
23/// Sysbox runs Docker inside an unprivileged container, in its own user namespace.
24#[derive(Debug)]
25pub struct Sysbox;
26
27impl Isolation for Sysbox {
28    fn name(&self) -> &'static str {
29        "sysbox"
30    }
31
32    fn is_unsafe(&self) -> bool {
33        false
34    }
35
36    fn configure(&self, host_config: &mut HostConfig) {
37        host_config.runtime = Some("sysbox-runc".to_owned());
38        host_config.privileged = Some(false);
39    }
40}
41
42/// Privileged Docker-in-Docker: root in the container is root on the host.
43#[derive(Debug)]
44pub struct UnsafeDind;
45
46impl Isolation for UnsafeDind {
47    fn name(&self) -> &'static str {
48        "unsafe-dind"
49    }
50
51    fn is_unsafe(&self) -> bool {
52        true
53    }
54
55    fn configure(&self, host_config: &mut HostConfig) {
56        // Named, not left to the Engine's default runtime, which may be sysbox-runc.
57        host_config.runtime = Some("runc".to_owned());
58        host_config.privileged = Some(true);
59    }
60}
61
62/// The backend `runnerd.toml` names.
63pub fn backend(isolation: config::Isolation) -> &'static dyn Isolation {
64    match isolation {
65        config::Isolation::Sysbox => &Sysbox,
66        config::Isolation::UnsafeDind => &UnsafeDind,
67    }
68}
69
70/// What Sysbox's runtime says when it cannot mount the running kernel's modules into a runner, up to the release.
71const MODULES_STAT_REFUSED: &str = "failed to stat mount source at /lib/modules/";
72
73/// The kernel release whose modules directory Docker's `error` says is not there, such as `7.2.11-arch1-1`. A stat
74/// that failed for another reason, as `permission denied`, is not a reboot's to fix.
75fn missing_modules_release(error: &str) -> Option<&str> {
76    let (_, after) = error.split_once(MODULES_STAT_REFUSED)?;
77    if !after.contains("no such file or directory") {
78        return None;
79    }
80    let release = after.split(['/', ':']).next()?;
81    (!release.is_empty()).then_some(release)
82}
83
84/// Why `runner` did not start, as the daemon logs it and announces it (`runner.failed`): what Docker said, and when
85/// that is the running kernel's modules gone from `/lib/modules`, which a package upgrade does while the old kernel
86/// runs, what happened and that the host must reboot.
87pub fn start_failure(runner: &str, docker_error: &str) -> String {
88    match missing_modules_release(docker_error) {
89        Some(release) => format!(
90            "cannot start {runner}: the running kernel's modules are gone (/lib/modules/{release} does not exist), \
91             most likely removed by a package upgrade; reboot to run the installed kernel. Docker said: {docker_error}"
92        ),
93        None => format!("cannot start {runner}: {docker_error}"),
94    }
95}
96
97/// The doctor's check that Sysbox can mount the running kernel's modules, which it does into every runner:
98/// `present` says whether `/lib/modules/{release}` exists.
99pub fn modules_check(release: &str, present: bool) -> Check {
100    if present {
101        return Check {
102            name: "kernel modules".to_owned(),
103            status: CheckStatus::Pass,
104            detail: format!("/lib/modules/{release} exists"),
105            fix: None,
106        };
107    }
108    Check {
109        name: "kernel modules".to_owned(),
110        status: CheckStatus::Fail,
111        detail: format!(
112            "/lib/modules/{release} does not exist, which sysbox mounts into every runner, so no runner starts; a \
113             package upgrade removes it while that kernel runs"
114        ),
115        fix: Some("reboot to run the installed kernel".to_owned()),
116    }
117}
118
119#[cfg(test)]
120mod tests;