Linux (KVM)

Capsa's Linux backend uses KVM (Kernel-based Virtual Machine) for hardware-accelerated virtualization.

Requirements

Hardware

• x86_64 processor with virtualization extensions (Intel VT-x or AMD-V)
• Check if enabled: grep -E 'vmx|svm' /proc/cpuinfo

Software

• Linux kernel 4.20+ with KVM support
• /dev/kvm device accessible to your user

Checking KVM Access

# Check if KVM module is loaded
lsmod | grep kvm

# Check device permissions
ls -la /dev/kvm

# Add user to kvm group if needed
sudo usermod -aG kvm $USER
# Log out and back in for group change to take effect

Cargo Configuration

[dependencies]
capsa = { version = "0.1", features = ["linux-kvm"] }
tokio = { version = "1", features = ["full"] }

Supported Features

Feature	Status	Notes
Linux Direct Boot	Supported	bzImage format, fast boot
UEFI Boot	Not Supported	Use direct boot instead
virtio-fs Shares	Supported	High-performance file sharing
UserNat Networking	Supported	Userspace NAT with policies
Cluster Networking	Supported	Multi-VM communication
VM Sockets (vsock)	Supported	Host-guest communication
VM Pools	Supported	Pre-warmed VMs
Sandbox Mode	Supported	With guest agent

Boot Configuration

Linux Direct Boot

The primary boot method on Linux. Requires a kernel and initrd:

use capsa::{Capsa, LinuxDirectBootConfig};

let config = LinuxDirectBootConfig::new("path/to/bzImage", "path/to/initrd");

let vm = Capsa::vm(config)
    .cpus(2)
    .memory_mb(1024)
    .console_enabled()
    .build()
    .await?;

Kernel Command Line

Customize the kernel command line:

let vm = Capsa::vm(config)
    .cmdline_arg("root", "/dev/vda")
    .cmdline_flag("quiet")
    .build()
    .await?;

Default command line includes:

• console=hvc0 - virtio console
• reboot=t - test mode reboot
• panic=-1 - hang on panic for debugging

Shared Directories

Linux fully supports virtio-fs for sharing directories between host and guest:

use capsa::MountMode;

let vm = Capsa::vm(config)
    .share("/host/path", "share0", MountMode::ReadWrite)
    .build()
    .await?;

After the VM boots, mount the share in the guest:

mount -t virtiofs share0 /mnt

See the Shared Directories guide for details.

Troubleshooting

KVM Not Available

Error: Backend unavailable: KVM device /dev/kvm not accessible

Solutions:

1. Ensure KVM module is loaded: sudo modprobe kvm_intel or kvm_amd
2. Check permissions: sudo chmod 666 /dev/kvm (or use udev rules)
3. Add user to kvm group: sudo usermod -aG kvm $USER

Slow Boot

If VMs take a long time to boot:

1. Check kernel size - large kernels take longer to load
2. Consider using a minimal kernel configuration
3. Use VM pools to pre-warm VMs

Console Not Working

If console output doesn't appear:

1. Ensure console=hvc0 is in kernel command line
2. Check that .console_enabled() is set on builder
3. Verify virtio-console driver is in initrd

Example

use capsa::{Capsa, LinuxDirectBootConfig, MountMode, NetworkMode};
use std::time::Duration;

#[tokio::main]
async fn main() -> capsa::Result<()> {
    let config = LinuxDirectBootConfig::new(
        "/path/to/kernel",
        "/path/to/initrd"
    );

    let vm = Capsa::vm(config)
        .cpus(4)
        .memory_mb(2048)
        .console_enabled()
        .share("/host/path", "share0", MountMode::ReadWrite)
        .network(NetworkMode::user_nat().build())
        .vsock_listen(1024)
        .build()
        .await?;

    let console = vm.console().await?;
    console.wait_for_timeout("# ", Duration::from_secs(30)).await?;

    // Mount shared directory
    console.exec(
        "mount -t virtiofs share0 /mnt",
        Duration::from_secs(5)
    ).await?;

    // Your workload here...

    vm.stop().await?;
    Ok(())
}