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" }
tokio = { version = "1", features = ["full"] }

Supported Features

Feature	Status	Notes
Sandbox Mode	Supported	With guest agent
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

The easiest way to use Capsa on Linux:

let vm = capsa::sandbox()
    .build()
    .await?;

let agent = vm.agent().await?;

let result = agent.exec("uname").arg("-a").run().await?;
println!("Kernel: {}", result.stdout);

Raw VMs

For custom kernels, use Linux Direct Boot:

let boot = LinuxDirectBoot::new("path/to/bzImage", "path/to/initrd");

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

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

Kernel Command Line

Customize the kernel command line:

let vm = capsa::vm(boot)
    .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:

let vm = capsa::vm(boot)
    .virtio_fs(VirtioFsShare::new("/host/path", "share0")?)
    .build()
    .await?;

In raw VMs, mount the share in the guest:

mount -t virtiofs share0 /mnt

In sandbox mode, shares are automatically mounted.

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