hexz_cli/cmd/vm/mod.rs
1//! Virtual machine operation commands for snapshot-based VMs.
2//!
3//! This module provides commands for managing virtual machines backed by Hexz
4//! snapshots, enabling instant boot, live snapshotting, and layered storage.
5//!
6//! # Available Commands
7//!
8//! ## VM Lifecycle (feature = "fuse")
9//!
10//! - [`boot`]: Boot a VM from a snapshot
11//! - Mounts snapshot via FUSE
12//! - Launches QEMU/Firecracker hypervisor
13//! - Supports persistent overlays for writes
14//!
15//! - [`install`]: Install OS from ISO to create a new snapshot
16//! - Creates virtual disk
17//! - Runs installer in VM
18//! - Packs result into Hexz archive
19//!
20//! ## Snapshot Management
21//!
22//! - [`snap`]: Create live snapshot via QMP (QEMU Machine Protocol)
23//! - Captures running VM state without downtime
24//! - Uses dirty block tracking for efficiency
25//!
26//! - [`commit`]: Commit overlay changes to new snapshot
27//! - Merges overlay deltas with base snapshot
28//! - Optionally flattens entire chain
29//! - Supports thin snapshots (reference base)
30//!
31//! ## Filesystem Operations (feature = "fuse")
32//!
33//! - [`mount`]: Mount snapshot as read-only or read-write filesystem
34//! - FUSE-based transparent decompression
35//! - Copy-on-write overlay for writes
36//! - NBD export support
37//!
38//! - [`unmount`]: Unmount FUSE filesystem
39//!
40//! # Workflow Example
41//!
42//! ```bash
43//! # 1. Install OS from ISO
44//! hexz vm install --iso ubuntu.iso --disk-size 20G --output ubuntu.st
45//!
46//! # 2. Boot with persistent overlay
47//! hexz vm boot ubuntu.st --persist overlay.bin
48//!
49//! # (Make changes in VM, then shut down)
50//!
51//! # 3. Commit changes to new snapshot
52//! hexz vm commit ubuntu.st overlay.bin ubuntu-v2.st --message "Installed updates"
53//!
54//! # 4. Boot new snapshot
55//! hexz vm boot ubuntu-v2.st
56//! ```
57//!
58//! # Live Snapshot with QMP
59//!
60//! ```bash
61//! # Boot with QMP socket
62//! hexz vm boot ubuntu.st --qmp-socket /tmp/qmp.sock --persist overlay.bin
63//!
64//! # Create live snapshot (VM keeps running)
65//! hexz vm snap --socket /tmp/qmp.sock --base ubuntu.st \
66//! --overlay overlay.bin --output checkpoint.st
67//! ```
68//!
69//! # Thin Snapshots
70//!
71//! Thin snapshots only store deltas and reference the base:
72//!
73//! ```bash
74//! hexz vm commit base.st overlay.bin delta.st --thin
75//! # delta.st is small, but requires base.st to boot
76//! ```
77//!
78//! # Feature Requirements
79//!
80//! - `fuse`: boot, install, mount, unmount
81//! - Core commands (snap, commit) always available
82
83#[cfg(feature = "fuse")]
84pub mod boot;
85
86#[cfg(feature = "fuse")]
87pub mod install;
88
89pub mod commit;
90#[cfg(unix)]
91pub mod snap;
92
93#[cfg(feature = "fuse")]
94pub mod mount;
95
96#[cfg(feature = "fuse")]
97pub mod unmount;