Skip to main content

Module snap

hexz_cli::cmd::vm

Module snap 

Source
Expand description

Live snapshot creation via QEMU QMP (QEMU Machine Protocol).

This command creates a live snapshot of a running VM by connecting to its QMP control socket, pausing the VM, dumping memory state via QEMU’s migration mechanism, and then creating a new snapshot that includes both the overlay (modified disk blocks) and the captured memory dump.

§QMP Protocol Integration

QEMU Machine Protocol (QMP) is a JSON-based protocol for controlling QEMU:

Connection Sequence:

  1. Connect to Unix socket (created with --qmp-socket during boot)
  2. Receive QMP greeting banner
  3. Send qmp_capabilities to negotiate features
  4. Send commands and receive JSON responses

Commands Used:

  • stop: Pauses VM execution (sets state to “paused”)
  • migrate: Triggers memory dump to file via exec:cat > <path>
  • query-migrate: Polls migration status (“active”, “completed”, “failed”)
  • cont: Resumes VM execution after snapshot is complete

QMP Message Format:

// Command (sent by client)
{"execute": "stop"}

// Response (received from QEMU)
{"return": {}}

// Status query response
{"return": {"status": "completed", "total": 4294967296}}

§Snapshot Format

The live snapshot captures both persistent and volatile state:

Disk State (from overlay):

  • Modified blocks since VM boot
  • 4 KiB granularity tracked in .meta file
  • Merged with base snapshot during commit

Memory State (from QEMU migration):

  • Full RAM dump in QEMU migration format
  • Includes CPU registers, device state, page tables
  • Compressed with LZ4 by default for fast resume

The resulting snapshot is a “thick” snapshot (default) containing all state needed to resume the VM independently of the base snapshot.

§Use Cases

  • Checkpoint and Restore: Save VM state for later resume
  • Testing and Development: Create snapshots before risky operations
  • Migration: Capture running VM for transfer to another host
  • Debugging: Preserve exact VM state for post-mortem analysis
  • Backup: Create consistent backups while VM is running

§Workflow

  1. Connect to QMP: Opens Unix socket to running QEMU instance
  2. Negotiate Capabilities: Establishes QMP protocol version
  3. Pause VM: Sends stop command to freeze execution
  4. Dump Memory: Uses migrate command with exec: URI to save RAM
  5. Poll Status: Repeatedly checks migration progress until complete
  6. Create Snapshot: Calls commit to merge overlay + memory
  7. Resume VM: Sends cont command to unpause execution

§Performance Characteristics

  • Pause Time: Typically 50-200 ms for stop command
  • Memory Dump: ~500-1000 MB/s (depends on storage bandwidth)
  • Snapshot Creation: ~200-500 MB/s (LZ4 compression)
  • Total Downtime: Typically 2-10 seconds for 4-8 GB VM

§Error Handling

If snapshot creation fails after pausing the VM, the command:

  1. Attempts to resume the VM with cont command
  2. Returns the snapshot error to the caller
  3. Leaves overlay files intact for retry

This ensures the VM is not left in a paused state even on failure.

§Common Usage Patterns

# Create live snapshot of running VM
hexz vm snap \
  --socket /tmp/vm.qmp \
  --overlay vm-state.overlay \
  --base vm-base.st \
  --output vm-checkpoint.st

# Resume from snapshot later
hexz vm boot vm-checkpoint.st --ram 4G

Functions§

run
Executes the live snapshot command via QMP.