Docs: recqemu

Documentation

recqemu

Library for running scenario VMs as libvirt domains and driving them over the serial console.

Overview

recqemu is a Rust library, not a standalone CLI. Every VM the scenarios and cargo xtask run boot is a transient libvirt domain on the user's session (qemu:///session, or LEVITATE_LIBVIRT_URI), named <distro>-<scenario>, so it can be watched and managed in Cockpit or with virsh -c qemu:///session list.

Note
Library-only: use this from Rust code paths; there is no user-facing recqemu command binary.

Each domain has 4 GiB of memory, 4 CPUs (KVM when /dev/kvm exists), a q35 machine with UEFI (OVMF), user networking through passt, and a VNC display on 127.0.0.1 for Cockpit. A guest reboot or power-off ends the domain, so the caller starts the next boot.

Primary API Surface

APIPurpose
libvirt::DomainSpecA VM: firmware, disk, boot ISO, extra CDs, fw_cfg entries, SSH forward, serial target and log
libvirt::DomainCreate (paused), resume, keep running, or destroy a domain
serial::ConsoleSerial console: wait for boot, log in, run commands and read their exit status
serial::protocolThe serial test protocol and its guest-side profile script
find_ovmf / find_ovmf_varsFirmware discovery (OVMF_PATH, else the Fedora, Debian/Ubuntu, Arch and NixOS locations)
create_diskCreate a qcow2 disk with qemu-img

Rust Example

Rust
use recqemu::libvirt::{Domain, DomainSpec, SerialTarget, UefiVars};
use recqemu::serial::Console;

let spec = DomainSpec {
    name: "levitate-test-live-ssh".into(),
    title: "Scenario VM levitate-test-live-ssh".into(),
    uefi_code: recqemu::find_ovmf()?,
    uefi_vars: UefiVars::Fresh { template: recqemu::find_ovmf_vars()?, path: vars_path },
    disk: Some(disk),
    boot_iso: Some(iso),
    extra_cdroms: vec![],
    fw_cfg: vec![],
    ssh_forward: Some(port),
    serial: SerialTarget::Socket(socket.clone()),
    serial_log: log,
};
let domain = Domain::create_paused(&spec)?;   // paused: no output is missed
let mut console = Console::connect(&socket, Duration::from_secs(20))?;
domain.resume()?;

Requirements

  • libvirt with the QEMU driver (the session daemon starts on demand)
  • passt, for user networking
  • OVMF (edk2) firmware
  • qemu-img, for create_disk
  • Cockpit with cockpit-machines to manage the VMs in a browser (optional)

cargo xtask doctor checks these.

Consumers

  • testing/install-tests (the scenarios)
  • xtask (cargo xtask run, with a pty serial console for virsh console)

See Also