hexz_cli::cmd::vm::snap

Function run

pub fn run(
    socket_path: PathBuf,
    overlay_path: PathBuf,
    base_hexz_path: PathBuf,
    output_path: PathBuf,
) -> Result<()>

Expand description

Executes the live snapshot command via QMP.

Connects to a running QEMU instance via its QMP socket, pauses execution, dumps memory state to a temporary file, creates a new snapshot that merges the overlay and memory dump, and resumes execution. This enables capturing a consistent point-in-time snapshot without shutting down the VM.

§Arguments

socket_path - Path to the QMP Unix socket (created with --qmp-socket)
overlay_path - Path to the overlay file containing modified disk blocks
base_hexz_path - Path to the base snapshot the VM was booted from
output_path - Path for the output snapshot file

§QMP Command Sequence

Connect to socket_path and read greeting
Send qmp_capabilities and wait for acknowledgment
Send stop to pause VM
Send migrate with URI exec:cat > <temp_file>
Poll query-migrate until status is “completed” or “failed”
Call commit::run() to create snapshot with overlay + memory
Send cont to resume VM (even if commit fails)

§Snapshot Parameters

The snapshot is created with:

Compression: LZ4 (fast decompression for quick resume)
Block size: 64 KiB (default)
Dictionary training: Enabled (improves memory compression)
Thin mode: Disabled (creates standalone snapshot)

§Errors

Returns an error if:

QMP socket cannot be connected (VM not running or socket path wrong)
QMP commands fail (protocol error, QEMU internal error)
Memory migration fails (disk full, I/O error)
Commit operation fails (compression error, write failure)

Note: VM resume is attempted even if errors occur, to prevent leaving the VM in a paused state.

§Examples

use std::path::PathBuf;
use hexz_cli::cmd::vm::snap;

// Create live snapshot of running VM
snap::run(
    PathBuf::from("/tmp/vm.qmp"),
    PathBuf::from("vm-state.overlay"),
    PathBuf::from("vm-base.hxz"),
    PathBuf::from("vm-checkpoint.hxz"),
)?;

run