Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

fix(cua-vmm): explain KVM fallback and refuse unusable /dev/kvm for native guests (#4971)

injaneitye9dc65780bdb
diff --git a/libs/cua/crates/cua-vmm/src/auto.rs b/libs/cua/crates/cua-vmm/src/auto.rs
index 678f7fe304..860996786b 100644
--- a/libs/cua/crates/cua-vmm/src/auto.rs
+++ b/libs/cua/crates/cua-vmm/src/auto.rs
@@ -88,6 +88,12 @@ pub struct QemuReport {
pub ssh_keygen: Option<PathBuf>,
}
+impl QemuReport {
+ fn installed(&self, arch: Arch) -> bool {
+ self.binaries.get(arch.qemu()).is_some_and(Option::is_some) && self.qemu_img.is_some()
+ }
+}
+
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct LumeReport {
pub supported_host: bool,
@@ -191,14 +197,17 @@ impl QemuPackageManager {
pub async fn doctor() -> DoctorReport {
let host_os = HostOs::current();
let host_arch = Arch::host();
+ let kvm = host::kvm_usable();
let mut accel = BTreeMap::new();
for a in [Arch::Aarch64, Arch::X86_64] {
- accel.insert(a.qemu().to_string(), host::qemu_accel(a).to_string());
+ if let Ok(acc) = host::qemu_accel(host_os, a, &kvm) {
+ accel.insert(a.qemu().to_string(), acc.to_string());
+ }
}
let host = HostReport {
os: host_os,
arch: host_arch,
- kvm: host::kvm_usable(),
+ kvm: kvm.is_ok(),
accel,
};
@@ -225,8 +234,7 @@ pub async fn doctor() -> DoctorReport {
.and_then(|s| s.lines().next().map(str::to_string));
}
let native = host_arch.qemu().to_string();
- let qemu_ready =
- qemu.binaries.get(&native).is_some_and(Option::is_some) && qemu.qemu_img.is_some();
+ let qemu_ready = qemu.installed(host_arch);
let mut qemu_status = BackendStatus {
backend: BackendKind::Qemu,
ready: qemu_ready,
@@ -252,6 +260,7 @@ pub async fn doctor() -> DoctorReport {
qemu_status.provisioning.push(s);
}
}
+ note_kvm(&mut qemu_status, host_os, &kvm);
// Lume.
let mut lume = LumeReport {
@@ -399,6 +408,19 @@ pub async fn doctor() -> DoctorReport {
}
}
+fn note_kvm(status: &mut BackendStatus, host_os: HostOs, kvm: &std::io::Result<()>) {
+ if let Err(e) = kvm
+ && host_os == HostOs::Linux
+ {
+ if host::qemu_accel(host_os, Arch::host(), kvm).is_err() {
+ status.ready = false;
+ status.missing.push(host::kvm_hint(e));
+ } else {
+ status.detail = format!("{}; {}", status.detail, host::kvm_hint(e));
+ }
+ }
+}
+
/// The built-in Linux runtime ([`crate::managed`]) for `doctor`: ready
/// while its VM runs; else used (set up or booted on demand) when the
/// `runtime.linux` setting picks it here.
@@ -501,7 +523,10 @@ pub fn select(req: &SelectRequest, report: &DoctorReport) -> Result<Selection> {
.get(arch.qemu())
.cloned()
.unwrap_or_else(|| "tcg".into());
- if q.ready || q.provisionable {
+ if q.ready
+ || q.provisionable
+ || arch != host.arch && report.qemu.installed(host.arch)
+ {
let mut reason = format!("{:?} {arch} guest: QEMU with {accel}", req.os);
if accel == "tcg" {
reason.push_str(" (software emulation, slow; prefer an image for the host architecture)");
@@ -649,11 +674,57 @@ mod tests {
assert!(select(&req(ImageKind::Container, GuestOs::Linux, None), &r).is_err());
}
+ #[test]
+ fn doctor_reports_why_native_qemu_has_no_kvm() {
+ let noted = |kvm: std::io::Result<()>| {
+ let mut q = report(true, false, false, false, HostOs::Linux).backends[1].clone();
+ q.detail = "QEMU 10".into();
+ q.missing.clear();
+ note_kvm(&mut q, HostOs::Linux, &kvm);
+ q
+ };
+ let missing = noted(Err(std::io::ErrorKind::NotFound.into()));
+ assert!(missing.ready && missing.missing.is_empty(), "{missing:?}");
+ assert!(missing.detail.starts_with("QEMU 10; "), "{missing:?}");
+ assert!(
+ missing.detail.contains("nested virtualization"),
+ "{missing:?}"
+ );
+ let denied = noted(Err(std::io::ErrorKind::PermissionDenied.into()));
+ assert!(!denied.ready && !denied.provisionable, "{denied:?}");
+ assert!(
+ denied.missing[0].contains("sudo usermod -aG kvm"),
+ "{denied:?}"
+ );
+ let ok = noted(Ok(()));
+ assert!(
+ ok.ready && ok.missing.is_empty() && ok.detail == "QEMU 10",
+ "{ok:?}"
+ );
+ }
+
+ #[test]
+ fn unopenable_kvm_still_selects_qemu_for_foreign_guests() {
+ let mut r = report(false, false, false, false, HostOs::Linux);
+ r.qemu = QemuReport {
+ qemu_img: Some("qemu-img".into()),
+ ..Default::default()
+ };
+ r.qemu
+ .binaries
+ .insert("aarch64".into(), Some("qemu-system".into()));
+ let s = select(&req(ImageKind::Vm, GuestOs::Linux, Some(Arch::X86_64)), &r).unwrap();
+ assert_eq!(s.backend, BackendKind::Qemu);
+ assert!(select(&req(ImageKind::Vm, GuestOs::Linux, None), &r).is_err());
+ }
+
/// The report `cua runtime doctor --json` prints round-trips.
#[test]
fn doctor_report_serialises() {
let r = report(true, false, true, false, HostOs::Macos);
let json = serde_json::to_value(&r).unwrap();
+ assert_eq!(json["host"]["kvm"], serde_json::json!(false));
+ assert_eq!(json["host"]["accel"]["x86_64"], serde_json::json!("tcg"));
assert_eq!(json["backends"].as_array().unwrap().len(), 4);
assert_eq!(json["backends"][0]["backend"], serde_json::json!("lume"));
let back: DoctorReport = serde_json::from_value(json).unwrap();
diff --git a/libs/cua/crates/cua-vmm/src/host.rs b/libs/cua/crates/cua-vmm/src/host.rs
index a87481f688..f7747efe8d 100644
--- a/libs/cua/crates/cua-vmm/src/host.rs
+++ b/libs/cua/crates/cua-vmm/src/host.rs
@@ -165,24 +165,42 @@ pub async fn run(program: impl AsRef<std::ffi::OsStr>, args: &[&str]) -> Result<
/// Whether hardware virtualisation is usable for a guest of `guest` arch, and
/// which QEMU accelerator to use.
-pub fn qemu_accel(guest: Arch) -> &'static str {
+pub fn qemu_accel(os: HostOs, guest: Arch, kvm: &std::io::Result<()>) -> Result<&'static str> {
let host = Arch::host();
- match HostOs::current() {
+ match (os, kvm) {
// HVF only virtualises the host's own architecture.
- HostOs::Macos if host == guest => "hvf",
- HostOs::Linux if host == guest && kvm_usable() => "kvm",
- HostOs::Windows if host == guest => "whpx",
- _ => "tcg",
+ (HostOs::Macos, _) if host == guest => Ok("hvf"),
+ (HostOs::Linux, Ok(())) if host == guest => Ok("kvm"),
+ (HostOs::Linux, Err(e)) if host == guest && e.kind() != std::io::ErrorKind::NotFound => {
+ Err(VmmError::missing("KVM", kvm_hint(e)))
+ }
+ (HostOs::Windows, _) if host == guest => Ok("whpx"),
+ _ => Ok("tcg"),
}
}
-/// `/dev/kvm` exists and is openable read/write.
-pub fn kvm_usable() -> bool {
+/// Opens `/dev/kvm` read/write.
+pub fn kvm_usable() -> std::io::Result<()> {
std::fs::OpenOptions::new()
.read(true)
.write(true)
.open("/dev/kvm")
- .is_ok()
+ .map(drop)
+}
+
+/// Why `/dev/kvm` could not be opened, and how to fix it.
+pub fn kvm_hint(e: &std::io::Error) -> String {
+ match e.kind() {
+ std::io::ErrorKind::NotFound => "/dev/kvm is missing, so same-architecture guests run \
+ under slow TCG emulation; enable virtualization on the host (nested virtualization \
+ if the host is a VM)"
+ .into(),
+ std::io::ErrorKind::PermissionDenied => "permission denied opening /dev/kvm; add your \
+ user to its group (for the kvm group: `sudo usermod -aG kvm \"$USER\"`), then log \
+ out and back in"
+ .into(),
+ _ => format!("cannot open /dev/kvm: {e}"),
+ }
}
/// Unix seconds.
@@ -278,9 +296,43 @@ mod tests {
Arch::X86_64 => Arch::Aarch64,
Arch::Aarch64 => Arch::X86_64,
};
- assert_eq!(qemu_accel(foreign), "tcg");
- #[cfg(target_os = "macos")]
- assert_eq!(qemu_accel(Arch::host()), "hvf");
+ let denied = Err(std::io::ErrorKind::PermissionDenied.into());
+ for os in [HostOs::Linux, HostOs::Macos, HostOs::Windows] {
+ assert_eq!(qemu_accel(os, foreign, &denied).unwrap(), "tcg");
+ }
+ assert_eq!(
+ qemu_accel(HostOs::Macos, Arch::host(), &denied).unwrap(),
+ "hvf"
+ );
+ assert_eq!(
+ qemu_accel(HostOs::Windows, Arch::host(), &denied).unwrap(),
+ "whpx"
+ );
+ }
+
+ #[test]
+ fn native_linux_accel_tells_missing_from_unopenable_kvm() {
+ let native = |kvm| qemu_accel(HostOs::Linux, Arch::host(), &kvm);
+ assert_eq!(native(Ok(())).unwrap(), "kvm");
+ assert_eq!(
+ native(Err(std::io::ErrorKind::NotFound.into())).unwrap(),
+ "tcg"
+ );
+ let missing = kvm_hint(&std::io::ErrorKind::NotFound.into());
+ assert!(missing.contains("nested virtualization"), "{missing}");
+ let denied = native(Err(std::io::ErrorKind::PermissionDenied.into()))
+ .unwrap_err()
+ .to_string();
+ assert!(denied.contains("permission denied"), "{denied}");
+ assert!(
+ denied.contains("sudo usermod -aG kvm \"$USER\""),
+ "{denied}"
+ );
+ let other = native(Err(std::io::Error::other("device busy")))
+ .unwrap_err()
+ .to_string();
+ assert!(other.contains("device busy"), "{other}");
+ assert!(!other.contains("usermod"), "{other}");
}
/// Regression for #4756: Windows reported every pid as dead.
diff --git a/libs/cua/crates/cua-vmm/src/qemu/mod.rs b/libs/cua/crates/cua-vmm/src/qemu/mod.rs
index 69ffd69ba1..9e8e96ed6c 100644
--- a/libs/cua/crates/cua-vmm/src/qemu/mod.rs
+++ b/libs/cua/crates/cua-vmm/src/qemu/mod.rs
@@ -279,11 +279,18 @@ impl QemuRuntime {
))
}
- fn accel_for(&self, arch: Arch) -> String {
- self.cfg
- .accel
- .clone()
- .unwrap_or_else(|| host::qemu_accel(arch).to_string())
+ fn accel_for(&self, arch: Arch, kvm: &std::io::Result<()>) -> Result<String> {
+ if let Some(accel) = &self.cfg.accel {
+ return Ok(accel.clone());
+ }
+ let accel = host::qemu_accel(host::HostOs::current(), arch, kvm)?;
+ if let Err(e) = kvm
+ && accel == "tcg"
+ && arch == Arch::host()
+ {
+ tracing::warn!("{}", host::kvm_hint(e));
+ }
+ Ok(accel.to_string())
}
async fn resolve_source(
@@ -465,7 +472,7 @@ impl QemuRuntime {
} else {
None
};
- st.accel = self.accel_for(st.arch);
+ st.accel = self.accel_for(st.arch, &host::kvm_usable())?;
st.cpus = spec.cpus;
st.memory_mb = spec.memory_mb;
st.restrict_network = spec.restrict_network;
@@ -1438,6 +1445,31 @@ mod tests {
assert!(err.to_string().contains("DiskResolver"));
}
+ #[cfg(target_os = "linux")]
+ #[test]
+ fn native_launch_refuses_unopenable_kvm_and_falls_back_when_missing() {
+ let tmp = tempfile::tempdir().unwrap();
+ let r = rt(tmp.path());
+ let denied = Err(std::io::ErrorKind::PermissionDenied.into());
+ let err = r.accel_for(Arch::host(), &denied).unwrap_err().to_string();
+ assert!(err.contains("permission denied"), "{err}");
+ assert!(err.contains("sudo usermod -aG kvm"), "{err}");
+ let missing = Err(std::io::ErrorKind::NotFound.into());
+ assert_eq!(r.accel_for(Arch::host(), &missing).unwrap(), "tcg");
+ }
+
+ #[test]
+ fn explicit_tcg_override_is_allowed() {
+ let tmp = tempfile::tempdir().unwrap();
+ let r = QemuRuntime::new(QemuConfig {
+ root: tmp.path().to_path_buf(),
+ accel: Some("tcg".into()),
+ ..Default::default()
+ });
+ let denied = Err(std::io::ErrorKind::PermissionDenied.into());
+ assert_eq!(r.accel_for(Arch::host(), &denied).unwrap(), "tcg");
+ }
+
/// Records the credentials each resolve got.
struct SeenCreds(std::sync::Mutex<Vec<Option<String>>>);