Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+vmctl can run inside a container for CI/CD pipelines or isolated environments. The key requirement is access to /dev/kvm.
FROM rust:1.85-bookworm AS builder
+
+WORKDIR /build
+COPY . .
+RUN cargo build --release -p vmctl --features vm-manager/pure-iso
+
+FROM debian:bookworm-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ qemu-system-x86 \
+ qemu-utils \
+ openssh-client \
+ && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /build/target/release/vmctl /usr/local/bin/vmctl
+
+ENV XDG_DATA_HOME=/data
+ENTRYPOINT ["vmctl"]
+The pure-iso feature eliminates the need for genisoimage in the container.
docker build -t vmctl .
+
+docker run --rm \
+ --device /dev/kvm \
+ -v vmctl-data:/data \
+ vmctl list
+The --device /dev/kvm flag passes through KVM access. No --privileged or special capabilities are needed for user-mode networking.
For TAP networking, you'll need --cap-add NET_ADMIN and appropriate bridge configuration.
podman build -t vmctl .
+
+podman run --rm \
+ --device /dev/kvm \
+ -v vmctl-data:/data \
+ vmctl list
+Podman works identically for user-mode networking.
+Mount a volume at the XDG_DATA_HOME path (/data in the Dockerfile above) to persist VM state and cached images across container runs.
Mount your project directory to use VMFile.kdl:
+docker run --rm \
+ --device /dev/kvm \
+ -v vmctl-data:/data \
+ -v $(pwd):/workspace \
+ -w /workspace \
+ vmctl up
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+For advanced guest configuration, you can provide a complete cloud-config YAML file instead of using vmctl's built-in cloud-init generation.
+vm "custom" {
+ image-url "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
+
+ cloud-init {
+ user-data "cloud-config.yaml"
+ }
+}
+#cloud-config
+users:
+ - name: deploy
+ groups: sudo
+ shell: /bin/bash
+ sudo: ALL=(ALL) NOPASSWD:ALL
+ ssh_authorized_keys:
+ - ssh-ed25519 AAAA... your-key
+
+package_update: true
+packages:
+ - nginx
+ - certbot
+ - python3-certbot-nginx
+
+write_files:
+ - path: /etc/nginx/sites-available/default
+ content: |
+ server {
+ listen 80;
+ server_name _;
+ root /var/www/html;
+ }
+
+runcmd:
+ - systemctl enable nginx
+ - systemctl start nginx
+
+growpart:
+ mode: auto
+ devices: ["/"]
+By default, vmctl generates the NoCloud seed ISO by shelling out to genisoimage or mkisofs. If neither is available, you can build with the pure-iso feature:
cargo build --release -p vmctl --features vm-manager/pure-iso
+This uses the isobemak crate to generate ISO 9660 images entirely in Rust.
When you don't provide raw user-data, vmctl generates a cloud-config that:
+authorized_keys.hostname field or VM name).instance-id in the metadata.If you need more control than this, use raw user-data.
+ +Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+vmctl uses the tracing crate with RUST_LOG environment variable support:
# Default (info level)
+vmctl up
+
+# Debug logging
+RUST_LOG=debug vmctl up
+
+# Trace logging (very verbose)
+RUST_LOG=trace vmctl up
+
+# Target specific modules
+RUST_LOG=vm_manager::ssh=debug vmctl ssh myvm
+The serial console output is captured to console.log in the VM's work directory. This includes boot messages and cloud-init output:
vmctl log myvm --console
+Provisioner stdout/stderr is captured to provision.log:
vmctl log myvm --provision
+vmctl log myvm --console --tail 50
+Each VM's files are in ~/.local/share/vmctl/vms/<name>/:
ls ~/.local/share/vmctl/vms/myvm/
+Contents:
+overlay.qcow2 - Disk overlayseed.iso - Cloud-init ISOconsole.log - Serial outputprovision.log - Provisioner outputqmp.sock - QMP control socketconsole.sock - Console socketpidfile - QEMU PIDid_ed25519_generated - Auto-generated SSH keyid_ed25519_generated.pub - Public keyYou can interact with the QEMU Machine Protocol directly for advanced debugging:
+# Using socat
+socat - UNIX-CONNECT:~/.local/share/vmctl/vms/myvm/qmp.sock
+After connecting, send {"execute": "qmp_capabilities"} to initialize, then commands like:
{"execute": "query-status"}
+{"execute": "query-vnc"}
+{"execute": "human-monitor-command", "arguments": {"command-line": "info network"}}
+qemu-system-x86_64 is in your PATH./dev/kvm exists and is accessible.kvm group.genisoimage or mkisofs.--features vm-manager/pure-iso.vmctl log myvm --consolevmctl status myvm for SSH port).ssh -p <port> -i <key> user@127.0.0.1ip neigh show for the guest's MAC address.vmctl status myvm for the PID.kill -0 <pid> - if the process is alive, the QMP socket may be stale.vmctl destroy myvm.Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+vmctl includes experimental support for running VMs on illumos using the Propolis hypervisor (bhyve-based).
+propolis-server installed and runnablerpool)nebula-vm zone brand installedThe Propolis backend manages VMs as illumos zones:
+{pool}/images/{vm}@latest to {pool}/vms/{vm}.zoneadm -z {vm} boot, waits for propolis-server on 127.0.0.1:12400, then sends the instance spec and run command via REST API.zoneadm uninstall -F), deletes the zone config (zonecfg delete -F), and destroys the ZFS dataset.Uses illumos VNICs for exclusive-IP zone networking:
+network "vnic" {
+ name "vnic0"
+}
+cargo build --release -p vmctl --target x86_64-unknown-illumos
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+TAP networking gives VMs a real presence on a host network, with full Layer 2 connectivity.
+# Create bridge
+sudo ip link add br0 type bridge
+sudo ip link set br0 up
+
+# Assign an IP to the bridge (optional, for host-to-guest communication)
+sudo ip addr add 10.0.0.1/24 dev br0
+Provide IP addresses to guests:
+sudo dnsmasq \
+ --interface=br0 \
+ --bind-interfaces \
+ --dhcp-range=10.0.0.100,10.0.0.200,12h \
+ --no-daemon
+If you want guests to reach the internet:
+# Enable forwarding
+sudo sysctl -w net.ipv4.ip_forward=1
+
+# NAT outbound traffic
+sudo iptables -t nat -A POSTROUTING -s 10.0.0.0/24 ! -o br0 -j MASQUERADE
+vmctl create --name myvm --image ./image.qcow2 --bridge br0
+vm "myvm" {
+ image "image.qcow2"
+
+ network "tap" {
+ bridge "br0"
+ }
+
+ cloud-init {
+ hostname "myvm"
+ }
+
+ ssh {
+ user "ubuntu"
+ }
+}
+vmctl discovers TAP-networked guest IPs by:
+ip neigh show) for the guest's MAC address on the bridge.This happens automatically when you run vmctl ssh or provisioners.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+All backends implement the Hypervisor trait defined in crates/vm-manager/src/traits.rs:
+#![allow(unused)] +fn main() { +pub trait Hypervisor: Send + Sync { + fn prepare(&self, spec: &VmSpec) -> impl Future<Output = Result<VmHandle>>; + fn start(&self, vm: &VmHandle) -> impl Future<Output = Result<VmHandle>>; + fn stop(&self, vm: &VmHandle, timeout: Duration) -> impl Future<Output = Result<VmHandle>>; + fn suspend(&self, vm: &VmHandle) -> impl Future<Output = Result<VmHandle>>; + fn resume(&self, vm: &VmHandle) -> impl Future<Output = Result<VmHandle>>; + fn destroy(&self, vm: VmHandle) -> impl Future<Output = Result<()>>; + fn state(&self, vm: &VmHandle) -> impl Future<Output = Result<VmState>>; + fn guest_ip(&self, vm: &VmHandle) -> impl Future<Output = Result<String>>; + fn console_endpoint(&self, vm: &VmHandle) -> Result<ConsoleEndpoint>; +} +}
Located in crates/vm-manager/src/backends/qemu.rs.
Prepare:
+~/.local/share/vmctl/vms/<name>/.Start:
+qemu-system-x86_64 with KVM acceleration.host (passthrough).q35,accel=kvm.Stop:
+system_powerdown).IP Discovery:
+127.0.0.1 (SSH via forwarded port).ip neigh show), falls back to dnsmasq lease files by MAC address.Located in crates/vm-manager/src/backends/qmp.rs. Async JSON-over-Unix-socket client implementing the QEMU Machine Protocol.
Commands: system_powerdown, quit, stop, cont, query_status, query_vnc.
Located in crates/vm-manager/src/backends/propolis.rs.
nebula-vm brand.propolis-server via REST API.Located in crates/vm-manager/src/backends/noop.rs. All operations succeed immediately. Used for testing.
Located in crates/vm-manager/src/backends/mod.rs. Dispatches Hypervisor trait calls to the correct backend based on the VmHandle's BackendTag.
Construction:
+RouterHypervisor::new(bridge, zfs_pool) - Platform-aware, creates the appropriate backend.RouterHypervisor::noop_only() - Testing mode.Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+vm-manager/
+ Cargo.toml # Workspace root
+ crates/
+ vm-manager/ # Library crate
+ Cargo.toml
+ src/
+ lib.rs # Re-exports
+ traits.rs # Hypervisor trait, ConsoleEndpoint
+ types.rs # VmSpec, VmHandle, VmState, NetworkConfig, etc.
+ error.rs # VmError with miette diagnostics
+ vmfile.rs # VMFile.kdl parser and resolver
+ image.rs # ImageManager (download, cache, overlay)
+ ssh.rs # SSH connect, exec, streaming, upload
+ provision.rs # Provisioner runner
+ cloudinit.rs # NoCloud seed ISO generation
+ backends/
+ mod.rs # RouterHypervisor
+ qemu.rs # QEMU/KVM backend (Linux)
+ qmp.rs # QMP client
+ propolis.rs # Propolis/bhyve backend (illumos)
+ noop.rs # No-op backend (testing)
+ vmctl/ # CLI binary crate
+ Cargo.toml
+ src/
+ main.rs # CLI entry point, clap App
+ commands/
+ create.rs # vmctl create
+ start.rs # vmctl start, suspend, resume
+ stop.rs # vmctl stop
+ destroy.rs # vmctl destroy
+ list.rs # vmctl list
+ status.rs # vmctl status
+ console.rs # vmctl console
+ ssh.rs # vmctl ssh
+ image.rs # vmctl image (pull, list, inspect)
+ up.rs # vmctl up
+ down.rs # vmctl down
+ reload.rs # vmctl reload
+ provision_cmd.rs # vmctl provision
+ log.rs # vmctl log
+The library crate. Contains all business logic and can be used as a dependency by other Rust projects.
+Public re-exports from lib.rs:
RouterHypervisor (from backends)Hypervisor, ConsoleEndpoint (from traits)VmError, Result (from error)types: BackendTag, VmSpec, VmHandle, VmState, NetworkConfig, CloudInitConfig, SshConfigThe CLI binary. Depends on vm-manager and adds:
vms.json)Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+vm-manager uses miette for rich diagnostic error reporting. Every error variant includes:
+vm_manager::qemu::spawn_failed).help message telling the user what to do.Errors are defined with #[derive(thiserror::Error, miette::Diagnostic)].
| Code | Trigger | Help |
|---|---|---|
vm_manager::qemu::spawn_failed | QEMU process failed to start | Ensure qemu-system-x86_64 is installed, in PATH, and KVM is available (/dev/kvm) |
vm_manager::qemu::qmp_connect_failed | Can't connect to QMP socket | QEMU may have crashed before QMP socket ready; check work directory logs |
vm_manager::qemu::qmp_command_failed | QMP command returned an error | (varies) |
vm_manager::image::overlay_creation_failed | QCOW2 overlay creation failed | Ensure qemu-img is installed and base image exists and is readable |
vm_manager::network::ip_discovery_timeout | Guest IP not found | Guest may not have DHCP lease; check network config and cloud-init |
vm_manager::propolis::unreachable | Can't reach propolis-server | Ensure propolis-server is running and listening on expected address |
vm_manager::cloudinit::iso_failed | Seed ISO generation failed | Ensure genisoimage or mkisofs installed, or enable pure-iso feature |
vm_manager::ssh::failed | SSH connection or command failed | Check SSH key, guest reachability, and sshd running |
vm_manager::ssh::keygen_failed | Ed25519 key generation failed | Internal error; please report it |
vm_manager::image::download_failed | Image download failed | Check network connectivity and URL correctness |
vm_manager::image::format_detection_failed | Can't detect image format | Ensure qemu-img installed and file is valid disk image |
vm_manager::image::conversion_failed | Image format conversion failed | Ensure qemu-img installed and sufficient disk space |
vm_manager::vm::not_found | VM not in store | Run vmctl list to see available VMs |
vm_manager::vm::invalid_state | Operation invalid for current state | (varies) |
vm_manager::backend::not_available | Backend not supported on platform | Backend not supported on current platform |
vm_manager::vmfile::not_found | VMFile.kdl not found | Create VMFile.kdl in current directory or specify path with --file |
vm_manager::vmfile::parse_failed | KDL syntax error | Check VMFile.kdl syntax; see https://kdl.dev |
vm_manager::vmfile::validation | VMFile validation error | (custom hint per error) |
vm_manager::provision::failed | Provisioner step failed | Check provisioner config and VM SSH reachability |
vm_manager::io | General I/O error | (transparent) |
The library defines pub type Result<T> = std::result::Result<T, VmError> for convenience. CLI commands return miette::Result<()> for rich terminal output.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+vm-manager is structured as a two-crate Cargo workspace.
+┌─────────────────────────────────────────┐
+│ vmctl CLI │
+│ (crates/vmctl) │
+│ │
+│ Commands → VMFile parser → Hypervisor │
+└──────────────────┬──────────────────────┘
+ │
+┌──────────────────┴──────────────────────┐
+│ vm-manager library │
+│ (crates/vm-manager) │
+│ │
+│ ┌─────────────┐ ┌──────────────────┐ │
+│ │ Hypervisor │ │ Image Manager │ │
+│ │ Trait │ │ │ │
+│ └──────┬──────┘ └──────────────────┘ │
+│ │ │
+│ ┌──────┴──────────────────────┐ │
+│ │ RouterHypervisor │ │
+│ │ ┌──────┐ ┌────────┐ ┌────┐│ │
+│ │ │ QEMU │ │Propolis│ │Noop││ │
+│ │ └──────┘ └────────┘ └────┘│ │
+│ └─────────────────────────────┘ │
+│ │
+│ ┌───────────┐ ┌──────────────────┐ │
+│ │ SSH │ │ Cloud-Init │ │
+│ │ Module │ │ Generator │ │
+│ └───────────┘ └──────────────────┘ │
+│ │
+│ ┌───────────┐ ┌──────────────────┐ │
+│ │ Provision │ │ VMFile │ │
+│ │ Runner │ │ Parser │ │
+│ └───────────┘ └──────────────────┘ │
+└─────────────────────────────────────────┘
+vmctl uses Tokio with the multi-threaded runtime. Most operations are async, with one exception: SSH operations use ssh2 (libssh2 bindings), which is blocking. These are wrapped in tokio::task::spawn_blocking to avoid blocking the async executor.
The Hypervisor trait defines a platform-agnostic interface. The RouterHypervisor dispatches calls to the correct backend based on the BackendTag stored in each VmHandle:
QemuBackend.PropolisBackend.NoopBackend for testing.Conditional compilation (#[cfg(target_os = ...)]) ensures only the relevant backend is compiled.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+vmctl uses the ssh2 crate (Rust bindings to libssh2) for SSH operations. The SSH module is at crates/vm-manager/src/ssh.rs.
Establishes a TCP connection and authenticates via public key.
+Supports two authentication modes:
+Executes a command and collects the full stdout/stderr output. Blocking.
+Executes a command and streams stdout/stderr in real-time to provided writers. Uses non-blocking I/O:
+exec().This is used by the provisioner to show build output live.
+Transfers a file to the guest via SFTP. Creates the SFTP subsystem, opens a remote file, and writes the local file contents.
+Attempts to connect repeatedly until a timeout (typically 120 seconds for provisioning, 30 seconds for vmctl ssh). Uses exponential backoff starting at 1 second, capped at 5 seconds. Runs the blocking connect on tokio::task::spawn_blocking.
libssh2 is used for programmatic operations (provisioning, connectivity checks) because it can be controlled from Rust code. For interactive sessions (vmctl ssh), vmctl hands off to the system ssh binary for proper terminal handling (PTY allocation, signal forwarding, etc.).
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+vmctl persists VM state in a JSON file at $XDG_DATA_HOME/vmctl/vms.json (typically ~/.local/share/vmctl/vms.json). Falls back to /tmp if XDG_DATA_HOME is not set.
The store is a simple mapping from VM name to VmHandle.
VmHandle is serialized to JSON with all fields. Fields added in later versions have #[serde(default)] annotations, so older JSON files are deserialized without errors (missing fields get defaults).
Example stored handle:
+{
+ "id": "abc123",
+ "name": "myvm",
+ "backend": "qemu",
+ "work_dir": "/home/user/.local/share/vmctl/vms/myvm",
+ "overlay_path": "/home/user/.local/share/vmctl/vms/myvm/overlay.qcow2",
+ "seed_iso_path": "/home/user/.local/share/vmctl/vms/myvm/seed.iso",
+ "pid": 12345,
+ "qmp_socket": "/home/user/.local/share/vmctl/vms/myvm/qmp.sock",
+ "console_socket": "/home/user/.local/share/vmctl/vms/myvm/console.sock",
+ "vnc_addr": "127.0.0.1:5900",
+ "vcpus": 2,
+ "memory_mb": 2048,
+ "disk_gb": 20,
+ "network": {"type": "User"},
+ "ssh_host_port": 10042,
+ "mac_addr": "52:54:00:ab:cd:ef"
+}
+The store uses an atomic write pattern:
+.tmp file.This prevents corruption if the process is interrupted during a write.
+The store records the last known state but doesn't actively monitor QEMU processes. When vmctl queries a VM's state, it:
+kill(pid, 0) to verify the process is alive.running, paused, etc.).Stopped.Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Attach to a VM's serial console.
+vmctl console <NAME>
+| Argument | Description |
|---|---|
NAME | VM name (positional) |
Connects to the VM's serial console via a Unix socket (QEMU) or WebSocket (Propolis). You'll see the same output as a physical serial port: boot messages, kernel output, and a login prompt.
+Press Ctrl+] (0x1d) to detach from the console.
+vmctl console myvm
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Create a new VM and optionally start it.
+vmctl create [OPTIONS] --name <NAME>
+| Option | Type | Default | Description |
|---|---|---|---|
--name | string | required | VM name |
--image | path | Path to a local disk image | |
--image-url | string | URL to download an image from | |
--vcpus | integer | 1 | Number of virtual CPUs |
--memory | integer | 1024 | Memory in MB |
--disk | integer | Disk size in GB (overlay resize) | |
--bridge | string | Bridge name for TAP networking | |
--cloud-init | path | Path to cloud-init user-data file | |
--ssh-key | path | Path to SSH public key file | |
--start | flag | false | Start the VM after creation |
One of --image or --image-url must be provided. If --image-url is given, the image is downloaded and cached.
When --bridge is specified, TAP networking is used. Otherwise, user-mode (SLIRP) networking is used.
When --ssh-key is provided, a cloud-init ISO is generated that injects the public key. The SSH user defaults to "vm".
# Create from a URL with defaults
+vmctl create --name myvm --image-url https://example.com/image.img
+
+# Create with custom resources and start immediately
+vmctl create --name myvm \
+ --image-url https://example.com/image.img \
+ --vcpus 4 --memory 4096 --disk 40 \
+ --ssh-key ~/.ssh/id_ed25519.pub \
+ --start
+
+# Create from local image with TAP networking
+vmctl create --name myvm --image ./ubuntu.qcow2 --bridge br0
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Destroy a VM and clean up all associated resources.
+vmctl destroy <NAME>
+| Argument | Description |
|---|---|
NAME | VM name (positional) |
Stops the VM if it's running, then removes all associated files: QCOW2 overlay, cloud-init ISO, log files, SSH keys, sockets, and the work directory. Unregisters the VM from the store.
+This action is irreversible.
+vmctl destroy myvm
+vmctl down (declarative equivalent)
+ +Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Bring down VMs defined in VMFile.kdl.
+vmctl down [OPTIONS]
+| Option | Type | Default | Description |
|---|---|---|---|
--file | path | Path to VMFile.kdl (auto-discovered if omitted) | |
--name | string | Only bring down a specific VM | |
--destroy | flag | false | Destroy VMs instead of just stopping |
Without --destroy, VMs are stopped gracefully (30-second timeout). They can be restarted with vmctl up or vmctl start.
With --destroy, VMs are fully destroyed: all files removed, unregistered from the store. This is irreversible.
# Stop all VMs in VMFile.kdl
+vmctl down
+
+# Stop a specific VM
+vmctl down --name webserver
+
+# Destroy all VMs
+vmctl down --destroy
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Manage VM disk images.
+vmctl image <SUBCOMMAND>
+Download an image to the local cache.
+vmctl image pull [OPTIONS] <URL>
+| Argument/Option | Type | Description |
|---|---|---|
URL | string | URL to download (positional) |
--name | string | Name to save as in the cache |
List cached images.
+vmctl image list
+Output:
+NAME SIZE PATH
+noble-server-cloudimg-amd64.img 0.62 GB /home/user/.local/share/vmctl/images/noble-server-cloudimg-amd64.img
+Show image format and details.
+vmctl image inspect <PATH>
+| Argument | Description |
|---|---|
PATH | Path to image file (positional) |
# Download and cache an image
+vmctl image pull https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
+
+# List what's cached
+vmctl image list
+
+# Check format of a local image
+vmctl image inspect ./my-image.qcow2
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+List all registered VMs.
+vmctl list
+NAME BACKEND VCPUS MEM NETWORK PID SSH
+webserver qemu 2 2048 user 12345 10042
+database qemu 4 4096 tap 12346 -
+| Column | Description |
|---|---|
NAME | VM name |
BACKEND | Hypervisor backend (qemu, propolis, noop) |
VCPUS | Number of virtual CPUs |
MEM | Memory in MB |
NETWORK | Networking mode (user, tap, vnic, none) |
PID | QEMU process PID (or - if not running) |
SSH | SSH host port (or - if not available) |
vmctl list
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Show VM console and provision logs.
+vmctl log [OPTIONS] <NAME>
+| Argument | Description |
|---|---|
NAME | VM name (positional) |
| Option | Type | Default | Description |
|---|---|---|---|
--console | flag | false | Show only console log (boot / cloud-init output) |
--provision | flag | false | Show only provision log |
--tail, -n | integer | 0 | Show the last N lines (0 = all) |
By default (no flags), both console and provision logs are shown. The console log captures serial output (boot messages, cloud-init output). The provision log captures stdout/stderr from provisioner runs.
+Log files are located in the VM's work directory:
+console.log - Serial console outputprovision.log - Provisioning output# Show all logs
+vmctl log myvm
+
+# Show only provision output
+vmctl log myvm --provision
+
+# Show last 50 lines of console log
+vmctl log myvm --console --tail 50
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Re-run provisioners on running VMs from VMFile.kdl.
+vmctl provision [OPTIONS]
+| Option | Type | Default | Description |
|---|---|---|---|
--file | path | Path to VMFile.kdl (auto-discovered if omitted) | |
--name | string | Only provision a specific VM |
Re-runs all provision steps defined in the VMFile on already-running VMs. The VM must be running and have an ssh block in the VMFile.
vmctl waits up to 120 seconds for SSH to become available, then runs each provisioner in sequence, streaming output to the terminal and logging to provision.log.
Useful for iterating on provision scripts without recreating the VM.
+# Re-provision all VMs
+vmctl provision
+
+# Re-provision a specific VM
+vmctl provision --name builder
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Destroy and recreate VMs from VMFile.kdl.
+vmctl reload [OPTIONS]
+| Option | Type | Default | Description |
|---|---|---|---|
--file | path | Path to VMFile.kdl (auto-discovered if omitted) | |
--name | string | Only reload a specific VM | |
--no-provision | flag | false | Skip provisioning after reload |
For each VM: destroys the existing instance (if any), then creates, starts, and provisions a fresh VM from the current VMFile definition. Useful when you've changed the VMFile and want a clean slate.
+# Reload all VMs
+vmctl reload
+
+# Reload a specific VM
+vmctl reload --name webserver
+
+# Reload without provisioning
+vmctl reload --no-provision
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+SSH into a VM.
+vmctl ssh [OPTIONS] [NAME]
+| Argument | Description |
|---|---|
NAME | VM name (optional; inferred from VMFile.kdl if only one VM is defined) |
| Option | Type | Description |
|---|---|---|
--user | string | SSH username (overrides VMFile) |
--key | path | Path to SSH private key |
--file | path | Path to VMFile.kdl (for reading ssh user) |
vmctl searches for a private key in this order:
+id_ed25519_generated)--key~/.ssh/id_ed25519~/.ssh/id_ecdsa~/.ssh/id_rsa--user CLI flaguser field in VMFile's ssh block"vm"vmctl first verifies SSH connectivity using libssh2 (with a 30-second retry timeout), then hands off to the system ssh binary for full interactive terminal support. SSH options StrictHostKeyChecking=no and UserKnownHostsFile=/dev/null are set automatically.
For user-mode networking, vmctl connects to 127.0.0.1 on the forwarded host port. For TAP networking, it discovers the guest IP via ARP.
# SSH into the only VM in VMFile.kdl
+vmctl ssh
+
+# SSH into a specific VM
+vmctl ssh myvm
+
+# Override user and key
+vmctl ssh myvm --user root --key ~/.ssh/special_key
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Start an existing VM.
+vmctl start <NAME>
+| Argument | Description |
|---|---|
NAME | VM name (positional) |
Starts a VM that is in the Prepared or Stopped state. The VM must have been previously created with vmctl create or vmctl up.
vmctl start myvm
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Show detailed status of a VM.
+vmctl status <NAME>
+| Argument | Description |
|---|---|
NAME | VM name (positional) |
Displays all known information about the VM:
+vmctl status myvm
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Stop a running VM.
+vmctl stop [OPTIONS] <NAME>
+| Argument | Description |
|---|---|
NAME | VM name (positional) |
| Option | Type | Default | Description |
|---|---|---|---|
--timeout | integer | 30 | Graceful shutdown timeout in seconds |
Sends an ACPI power-down signal via QMP. If the guest doesn't shut down within the timeout, vmctl sends SIGTERM to the QEMU process, then SIGKILL as a last resort.
+# Stop with default 30-second timeout
+vmctl stop myvm
+
+# Give it more time to shut down gracefully
+vmctl stop myvm --timeout 120
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Suspend (pause) a running VM.
+vmctl suspend <NAME>
+| Argument | Description |
|---|---|
NAME | VM name (positional) |
Pauses the VM's vCPUs via QMP. The VM remains in memory but stops executing. Use vmctl resume to continue.
vmctl suspend myvm
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Bring up VMs defined in VMFile.kdl.
+vmctl up [OPTIONS]
+| Option | Type | Default | Description |
|---|---|---|---|
--file | path | Path to VMFile.kdl (auto-discovered if omitted) | |
--name | string | Only bring up a specific VM | |
--no-provision | flag | false | Skip provisioning steps |
For each VM in the VMFile:
+Images are downloaded and cached as needed. SSH keys are auto-generated when cloud-init is configured without an explicit key.
+# Bring up all VMs in ./VMFile.kdl
+vmctl up
+
+# Bring up a specific VM
+vmctl up --name webserver
+
+# Bring up without provisioning
+vmctl up --no-provision
+
+# Use a specific VMFile
+vmctl up --file path/to/VMFile.kdl
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+The main entry point for the vmctl CLI.
+vmctl <COMMAND>
+| Command | Description |
|---|---|
create | Create a new VM |
start | Start an existing VM |
stop | Stop a running VM |
destroy | Destroy a VM and clean up resources |
list | List all VMs |
status | Show detailed VM status |
console | Attach to serial console |
ssh | SSH into a VM |
suspend | Suspend (pause) a running VM |
resume | Resume a suspended VM |
image | Manage VM images |
up | Bring up VMs from VMFile.kdl |
down | Bring down VMs from VMFile.kdl |
reload | Destroy and recreate VMs from VMFile.kdl |
provision | Re-run provisioners from VMFile.kdl |
log | Show VM logs |
| Variable | Description |
|---|---|
RUST_LOG | Control log verbosity (e.g., RUST_LOG=debug vmctl up) |
XDG_DATA_HOME | Override data directory (default: ~/.local/share) |
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+vmctl uses cloud-init to configure guests on first boot. It generates a NoCloud seed ISO containing user-data and meta-data, which the guest's cloud-init agent picks up automatically.
+There are three ways to get SSH access to a VM:
+When you define a cloud-init block without an explicit ssh-key, vmctl generates a per-VM Ed25519 keypair:
cloud-init {
+ hostname "myvm"
+}
+
+ssh {
+ user "ubuntu"
+}
+The keys are stored in the VM's work directory:
+~/.local/share/vmctl/vms/<name>/id_ed25519_generated (private)~/.local/share/vmctl/vms/<name>/id_ed25519_generated.pub (public)This is the simplest option. No key management required.
+Point to your own public key file:
+cloud-init {
+ ssh-key "~/.ssh/id_ed25519.pub"
+}
+
+ssh {
+ user "ubuntu"
+ private-key "~/.ssh/id_ed25519"
+}
+Provide a complete cloud-config YAML file for full control:
+cloud-init {
+ user-data "./my-cloud-config.yaml"
+}
+In this mode, you're responsible for setting up SSH access yourself in the user-data.
+When vmctl needs to SSH into a VM (for vmctl ssh or provisioning), it searches for a private key in this order:
id_ed25519_generated)--key flag or private-key in VMFile ssh block~/.ssh/: id_ed25519, id_ecdsa, id_rsa--user CLI flaguser in VMFile ssh block"vm"When vmctl generates the cloud-config, it creates a user with:
+sudo accessauthorized_keysPress ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+vmctl stores all VM state under $XDG_DATA_HOME/vmctl/ (typically ~/.local/share/vmctl/):
~/.local/share/vmctl/
+ vms.json # VM registry (name -> handle mapping)
+ images/ # Downloaded image cache
+ vms/
+ <vm-name>/ # Per-VM working directory
+ overlay.qcow2 # Copy-on-write disk overlay
+ seed.iso # Cloud-init NoCloud ISO
+ qmp.sock # QEMU Machine Protocol socket
+ console.sock # Serial console socket
+ console.log # Boot/cloud-init log
+ provision.log # Provisioning output log
+ id_ed25519_generated # Auto-generated SSH private key
+ id_ed25519_generated.pub # Auto-generated SSH public key
+ pidfile # QEMU process PID
+vmctl never modifies the base image directly. Instead, it creates a QCOW2 copy-on-write overlay on top of the original. This means:
+If you specify disk in your VMFile, the overlay is resized to that size and the guest filesystem can be grown.
All hypervisor operations go through a RouterHypervisor that dispatches to the appropriate backend based on the platform:
QemuBackendPropolisBackendNoopBackendEach backend implements the same Hypervisor trait, so the CLI code is platform-agnostic.
When you run vmctl up, the following happens for each VM defined in VMFile.kdl:
If a VM is already running, vmctl up skips it. If it's stopped, it restarts and re-provisions.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+vmctl can work with local disk images or download them from URLs. Downloaded images are cached for reuse.
+Downloaded images are stored in ~/.local/share/vmctl/images/. If an image already exists in the cache, it won't be re-downloaded.
vmctl uses qemu-img to detect and convert image formats. Common formats:
The format is auto-detected from the file header.
+If a URL ends in .zst or .zstd, vmctl automatically decompresses the image after downloading. This is common for distribution cloud images.
vmctl never boots from the base image directly. Instead:
+This means multiple VMs can share the same base image efficiently.
+If you specify disk (in GB) in your VMFile or --disk on the CLI, the overlay is created with that size. The guest OS can then grow its filesystem to fill the available space (most cloud images do this automatically via cloud-init's growpart module).
# Download an image to the cache
+vmctl image pull https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
+
+# List cached images
+vmctl image list
+
+# Inspect a local image
+vmctl image inspect ./my-image.qcow2
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+vmctl supports two workflows for managing VMs.
+Use individual commands to create, configure, and manage VMs step by step:
+vmctl create --name myvm --image-url https://example.com/image.img --vcpus 2 --memory 2048 --start
+vmctl ssh myvm
+vmctl stop myvm
+vmctl destroy myvm
+This is useful for:
+Define your VMs in a VMFile.kdl and let vmctl converge to the desired state:
vm "myvm" {
+ image-url "https://example.com/image.img"
+ vcpus 2
+ memory 2048
+
+ cloud-init {
+ hostname "myvm"
+ }
+
+ ssh {
+ user "ubuntu"
+ }
+
+ provision "shell" {
+ inline "echo hello"
+ }
+}
+vmctl up # create + start + provision
+vmctl down # stop
+vmctl reload # destroy + recreate + provision
+vmctl provision # re-run provisioners only
+This is useful for:
+| Scenario | Approach |
|---|---|
| "I need a quick VM to test something" | Imperative |
| "My project needs a build VM with specific packages" | Declarative |
| "I want to script VM lifecycle in CI" | Either, depending on complexity |
| "Multiple VMs that work together" | Declarative |
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+vmctl supports several networking modes depending on your needs and permissions.
+network "user"
+QEMU's built-in user-mode networking. No root or special permissions required.
+How it works:
+10.0.2.x).Pros: Zero setup, no root needed. +Cons: No inbound connections (except forwarded ports), lower performance than TAP.
+network "tap" {
+ bridge "br0"
+}
+Creates a TAP device and attaches it to a host bridge. The guest appears as a real machine on the bridge's network.
+How it works:
+Pros: Real network presence, full inbound/outbound, better performance. +Cons: Requires bridge setup, may need root or appropriate capabilities.
+If no bridge name is specified, it defaults to br0.
network "vnic" {
+ name "vnic0"
+}
+Uses an illumos VNIC for exclusive-IP zone networking. Only available on the Propolis backend.
+network "none"
+No networking at all. Useful for isolated compute tasks or testing.
+vmctl discovers the guest IP differently depending on the network mode:
+| Mode | IP Discovery Method |
|---|---|
| User | Returns 127.0.0.1 (SSH via forwarded port) |
| TAP | Parses ARP table (ip neigh show), falls back to dnsmasq lease files by MAC address |
| VNIC | Zone-based discovery |
| None | Not available |
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Every VM in vmctl moves through a set of well-defined states.
+| State | Description |
|---|---|
Preparing | Backend is allocating resources (overlay, ISO, sockets) |
Prepared | Resources allocated, ready to boot |
Running | VM is booted and executing |
Stopped | VM has been shut down (gracefully or forcibly) |
Failed | An error occurred during a lifecycle operation |
Destroyed | VM and all its resources have been cleaned up |
prepare() start()
+[new] ──────────> Prepared ──────────> Running
+ │ │
+ suspend() │ │ stop(timeout)
+ ┌────────────┘ └──────────────┐
+ v v
+ Suspended ─── resume() ──> Stopped
+ │
+ start() │
+ Running <──────────┘
+
+Any state ── destroy() ──> Destroyed
+| Command | From State | To State |
|---|---|---|
vmctl create | (none) | Prepared |
vmctl start | Prepared, Stopped | Running |
vmctl stop | Running | Stopped |
vmctl suspend | Running | Suspended (paused vCPUs) |
vmctl resume | Suspended | Running |
vmctl destroy | Any | Destroyed |
vmctl up | (none), Stopped | Running (auto-creates if needed) |
vmctl down | Running | Stopped |
vmctl reload | Any | Running (destroys + recreates) |
vmctl stop sends an ACPI power-down signal via QMP. If the guest doesn't shut down within the timeout (default 30 seconds), vmctl sends SIGTERM, and finally SIGKILL as a last resort.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+vmctl is built from source using Rust's Cargo build system.
+Clone the repository and build the release binary:
+git clone https://github.com/user/vm-manager.git
+cd vm-manager
+cargo build --release -p vmctl
+The binary will be at target/release/vmctl. Copy it somewhere in your $PATH:
sudo cp target/release/vmctl /usr/local/bin/
+The vm-manager library crate has one optional feature:
| Feature | Description |
|---|---|
pure-iso | Use a pure-Rust ISO 9660 generator (isobemak) instead of shelling out to genisoimage/mkisofs. Useful in minimal or containerized environments. |
To build with it:
+cargo build --release -p vmctl --features vm-manager/pure-iso
+vmctl --help
+You should see the list of available subcommands.
+ +Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+vmctl requires several system tools depending on the backend and features you use.
+| Tool | Purpose | Install (Debian/Ubuntu) |
|---|---|---|
qemu-system-x86_64 | VM hypervisor | sudo apt install qemu-system-x86 |
qemu-img | Disk image operations | sudo apt install qemu-utils |
/dev/kvm | Hardware virtualization | Kernel module (usually built-in) |
| Tool | Purpose | Install |
|---|---|---|
genisoimage | ISO 9660 image creation | sudo apt install genisoimage |
mkisofs | Alternative ISO tool | sudo apt install mkisofs |
Or build with the pure-iso feature to avoid needing either.
# QEMU
+qemu-system-x86_64 --version
+
+# qemu-img
+qemu-img --version
+
+# KVM access
+ls -la /dev/kvm
+
+# ISO tools (one of these)
+genisoimage --version 2>/dev/null || mkisofs --version 2>/dev/null
+
+# Your user should be in the kvm group
+groups | grep -q kvm && echo "kvm: OK" || echo "kvm: add yourself to the kvm group"
+If /dev/kvm is not present, enable KVM in your BIOS/UEFI settings (look for "VT-x" or "AMD-V") and ensure the kvm kernel module is loaded:
sudo modprobe kvm
+sudo modprobe kvm_intel # or kvm_amd
+For the experimental Propolis backend:
+propolis-server instancerpool)nebula-vm zone brand installedPress ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+This guide walks you through creating your first VM in under a minute.
+Create and start a VM from an Ubuntu cloud image:
+vmctl create \
+ --name demo \
+ --image-url https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img \
+ --vcpus 2 \
+ --memory 2048 \
+ --start
+Wait a moment for the image to download and the VM to boot, then connect:
+vmctl ssh demo
+When you're done:
+vmctl destroy demo
+Create a VMFile.kdl in your project directory:
vm "demo" {
+ image-url "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
+ vcpus 2
+ memory 2048
+
+ cloud-init {
+ hostname "demo"
+ }
+
+ ssh {
+ user "ubuntu"
+ }
+}
+Bring it up:
+vmctl up
+vmctl will download the image (cached for future use), create a QCOW2 overlay, generate an Ed25519 SSH keypair, build a cloud-init ISO, and boot the VM.
+Connect:
+vmctl ssh
+Tear it down:
+vmctl down
+Or destroy it completely (removes all VM files):
+vmctl down --destroy
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+vmctl is a command-line tool for creating, managing, and provisioning virtual machines on Linux (QEMU/KVM) and illumos (Propolis/bhyve). It offers both imperative commands for one-off tasks and a declarative configuration format (VMFile.kdl) for reproducible VM environments.
Managing VMs with raw QEMU commands is tedious and error-prone. vmctl handles the plumbing: disk overlays, cloud-init ISOs, SSH key generation, network configuration, and process lifecycle. You describe what you want; vmctl figures out how.
+Think of it like this:
+| Docker world | vmctl world |
|---|---|
docker run | vmctl create --start |
docker-compose.yml | VMFile.kdl |
docker compose up | vmctl up |
docker compose down | vmctl down |
Create a VMFile.kdl:
vm "dev" {
+ image-url "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
+ vcpus 2
+ memory 2048
+
+ cloud-init {
+ hostname "dev"
+ }
+
+ ssh {
+ user "ubuntu"
+ }
+
+ provision "shell" {
+ inline "sudo apt-get update && sudo apt-get install -y build-essential"
+ }
+}
+Then:
+vmctl up # download image, create VM, boot, provision
+vmctl ssh # connect over SSH
+vmctl down # shut it down
+| Platform | Backend | Status |
|---|---|---|
| Linux | QEMU/KVM | Fully supported |
| illumos | Propolis/bhyve | Experimental |
vmctl is split into two crates:
+Both live in a Cargo workspace under crates/.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+vmctl is a command-line tool for creating, managing, and provisioning virtual machines on Linux (QEMU/KVM) and illumos (Propolis/bhyve). It offers both imperative commands for one-off tasks and a declarative configuration format (VMFile.kdl) for reproducible VM environments.
Managing VMs with raw QEMU commands is tedious and error-prone. vmctl handles the plumbing: disk overlays, cloud-init ISOs, SSH key generation, network configuration, and process lifecycle. You describe what you want; vmctl figures out how.
+Think of it like this:
+| Docker world | vmctl world |
|---|---|
docker run | vmctl create --start |
docker-compose.yml | VMFile.kdl |
docker compose up | vmctl up |
docker compose down | vmctl down |
Create a VMFile.kdl:
vm "dev" {
+ image-url "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
+ vcpus 2
+ memory 2048
+
+ cloud-init {
+ hostname "dev"
+ }
+
+ ssh {
+ user "ubuntu"
+ }
+
+ provision "shell" {
+ inline "sudo apt-get update && sudo apt-get install -y build-essential"
+ }
+}
+Then:
+vmctl up # download image, create VM, boot, provision
+vmctl ssh # connect over SSH
+vmctl down # shut it down
+| Platform | Backend | Status |
|---|---|---|
| Linux | QEMU/KVM | Fully supported |
| illumos | Propolis/bhyve | Experimental |
vmctl is split into two crates:
+Both live in a Cargo workspace under crates/.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+All types are defined in crates/vm-manager/src/types.rs and re-exported from the crate root.
The input specification for creating a VM.
++#![allow(unused)] +fn main() { +pub struct VmSpec { + pub name: String, + pub image_path: PathBuf, + pub vcpus: u16, + pub memory_mb: u64, + pub disk_gb: Option<u32>, + pub network: NetworkConfig, + pub cloud_init: Option<CloudInitConfig>, + pub ssh: Option<SshConfig>, +} +}
A runtime handle to a managed VM. Serializable to JSON for persistence.
++#![allow(unused)] +fn main() { +pub struct VmHandle { + pub id: String, + pub name: String, + pub backend: BackendTag, + pub work_dir: PathBuf, + pub overlay_path: Option<PathBuf>, + pub seed_iso_path: Option<PathBuf>, + pub pid: Option<u32>, + pub qmp_socket: Option<PathBuf>, + pub console_socket: Option<PathBuf>, + pub vnc_addr: Option<String>, + pub vcpus: u16, // default: 1 + pub memory_mb: u64, // default: 1024 + pub disk_gb: Option<u32>, + pub network: NetworkConfig, + pub ssh_host_port: Option<u16>, + pub mac_addr: Option<String>, +} +}
All optional fields default to None and numeric fields have sensible defaults for backward-compatible deserialization.
+#![allow(unused)] +fn main() { +pub enum VmState { + Preparing, + Prepared, + Running, + Stopped, + Failed, + Destroyed, +} +}
Implements Display with lowercase names.
+#![allow(unused)] +fn main() { +pub enum NetworkConfig { + Tap { bridge: String }, + User, // default + Vnic { name: String }, + None, +} +}
Serialized with #[serde(tag = "type")] for clean JSON representation.
+#![allow(unused)] +fn main() { +pub struct CloudInitConfig { + pub user_data: Vec<u8>, + pub instance_id: Option<String>, + pub hostname: Option<String>, +} +}
user_data is the raw cloud-config YAML content.
+#![allow(unused)] +fn main() { +pub struct SshConfig { + pub user: String, + pub public_key: Option<String>, + pub private_key_path: Option<PathBuf>, + pub private_key_pem: Option<String>, +} +}
Supports both file-based keys (private_key_path) and in-memory keys (private_key_pem).
+#![allow(unused)] +fn main() { +pub enum BackendTag { + Noop, + Qemu, + Propolis, +} +}
Serialized as lowercase strings. Implements Display.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+The Hypervisor trait is the core abstraction for VM lifecycle management. All backends implement it.
+#![allow(unused)] +fn main() { +pub trait Hypervisor: Send + Sync { + fn prepare(&self, spec: &VmSpec) -> impl Future<Output = Result<VmHandle>>; + fn start(&self, vm: &VmHandle) -> impl Future<Output = Result<VmHandle>>; + fn stop(&self, vm: &VmHandle, timeout: Duration) -> impl Future<Output = Result<VmHandle>>; + fn suspend(&self, vm: &VmHandle) -> impl Future<Output = Result<VmHandle>>; + fn resume(&self, vm: &VmHandle) -> impl Future<Output = Result<VmHandle>>; + fn destroy(&self, vm: VmHandle) -> impl Future<Output = Result<()>>; + fn state(&self, vm: &VmHandle) -> impl Future<Output = Result<VmState>>; + fn guest_ip(&self, vm: &VmHandle) -> impl Future<Output = Result<String>>; + fn console_endpoint(&self, vm: &VmHandle) -> Result<ConsoleEndpoint>; +} +}
Allocates resources for a VM based on the provided VmSpec. Creates the work directory, QCOW2 overlay, cloud-init ISO, and networking configuration. Returns a VmHandle in the Prepared state.
Boots the VM. Returns an updated VmHandle with runtime information (PID, VNC address, etc.).
Gracefully shuts down the VM. Tries ACPI power-down first, then force-kills after the timeout. Returns the handle in Stopped state.
Pauses and unpauses VM vCPUs without shutting down.
+Stops the VM (if running) and removes all associated resources. Takes ownership of the handle.
+Queries the current VM state by checking the process and QMP status.
+Discovers the guest's IP address. Method varies by network mode and backend.
+Returns the console connection details. Synchronous (not async).
++#![allow(unused)] +fn main() { +pub enum ConsoleEndpoint { + UnixSocket(PathBuf), // QEMU serial console + WebSocket(String), // Propolis console + None, // Noop backend +} +}
To add a new hypervisor backend:
+Hypervisor.RouterHypervisor with appropriate #[cfg] gates.BackendTag.RouterHypervisor's Hypervisor impl.Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+The image module handles downloading, caching, format detection, and overlay creation. Located in crates/vm-manager/src/image.rs.
+#![allow(unused)] +fn main() { +pub struct ImageManager { + client: reqwest::Client, + cache: PathBuf, // default: ~/.local/share/vmctl/images/ +} +}
+#![allow(unused)] +fn main() { +ImageManager::new() -> Self +}
Creates an ImageManager with the default cache directory.
++#![allow(unused)] +fn main() { +async fn download(&self, url: &str, destination: &Path) -> Result<()> +}
Downloads an image from a URL to a local path. Skips if the destination already exists. Auto-decompresses .zst/.zstd files. Logs progress every 5%.
+#![allow(unused)] +fn main() { +async fn pull(&self, url: &str, name: Option<&str>) -> Result<PathBuf> +}
Downloads an image to the cache directory and returns the cached path. If name is None, extracts the filename from the URL.
+#![allow(unused)] +fn main() { +fn list(&self) -> Result<Vec<CachedImage>> +}
Lists all images in the cache with their names, sizes, and paths.
++#![allow(unused)] +fn main() { +async fn detect_format(path: &Path) -> Result<String> +}
Runs qemu-img info --output=json and returns the format string (e.g., "qcow2", "raw").
+#![allow(unused)] +fn main() { +async fn create_overlay(base: &Path, overlay: &Path, size_gb: Option<u32>) -> Result<()> +}
Creates a QCOW2 overlay with the given base image as a backing file. Optionally resizes to size_gb.
+#![allow(unused)] +fn main() { +async fn convert(src: &Path, dst: &Path, format: &str) -> Result<()> +}
Converts an image between formats using qemu-img convert.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Located in crates/vm-manager/src/ssh.rs.
+#![allow(unused)] +fn main() { +pub fn connect(ip: &str, port: u16, config: &SshConfig) -> Result<Session> +}
Establishes an SSH connection and authenticates. Supports in-memory PEM keys and file-based keys.
++#![allow(unused)] +fn main() { +pub fn exec(sess: &Session, cmd: &str) -> Result<(String, String, i32)> +}
Executes a command and returns (stdout, stderr, exit_code).
+#![allow(unused)] +fn main() { +pub fn exec_streaming<W1: Write, W2: Write>( + sess: &Session, + cmd: &str, + stdout_writer: &mut W1, + stderr_writer: &mut W2, +) -> Result<(String, String, i32)> +}
Executes a command with real-time output streaming. Uses non-blocking I/O with 8KB buffers and 50ms polling interval. Both writes to the provided writers and collects the full output.
++#![allow(unused)] +fn main() { +pub fn upload(sess: &Session, local: &Path, remote: &str) -> Result<()> +}
Uploads a file via SFTP.
++#![allow(unused)] +fn main() { +pub async fn connect_with_retry( + ip: &str, + port: u16, + config: &SshConfig, + timeout: Duration, +) -> Result<Session> +}
Retries connection with exponential backoff (1s to 5s). Runs blocking SSH on tokio::task::spawn_blocking.
Located in crates/vm-manager/src/provision.rs.
+#![allow(unused)] +fn main() { +pub fn run_provisions( + sess: &Session, + provisions: &[ProvisionDef], + base_dir: &Path, + vm_name: &str, + log_dir: Option<&Path>, +) -> Result<()> +}
Runs all provisioners in sequence:
+exec_streaming./tmp/vmctl-provision-<step>.sh, makes it executable, runs it.Output is streamed to the terminal and appended to provision.log if log_dir is provided.
Aborts on the first non-zero exit code with VmError::ProvisionFailed.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+The vm-manager library can be used as a Rust dependency for building custom VM management tools.
[dependencies]
+vm-manager = { path = "crates/vm-manager" }
+# or from a git repository:
+# vm-manager = { git = "https://github.com/user/vm-manager.git" }
+The crate root re-exports the most commonly used types:
++#![allow(unused)] +fn main() { +use vm_manager::{ + // Hypervisor abstraction + Hypervisor, ConsoleEndpoint, RouterHypervisor, + // Error handling + VmError, Result, + // Core types + BackendTag, VmSpec, VmHandle, VmState, + NetworkConfig, CloudInitConfig, SshConfig, +}; +}
+use vm_manager::{RouterHypervisor, Hypervisor, VmSpec, NetworkConfig}; +use std::time::Duration; + +#[tokio::main] +async fn main() -> vm_manager::Result<()> { + // Create a hypervisor (platform-detected) + let hyp = RouterHypervisor::new(None, "rpool".into()); + + // Define a VM + let spec = VmSpec { + name: "example".into(), + image_path: "/path/to/image.qcow2".into(), + vcpus: 2, + memory_mb: 2048, + disk_gb: Some(20), + network: NetworkConfig::User, + cloud_init: None, + ssh: None, + }; + + // Lifecycle + let handle = hyp.prepare(&spec).await?; + let handle = hyp.start(&handle).await?; + + // ... use the VM ... + + hyp.stop(&handle, Duration::from_secs(30)).await?; + hyp.destroy(handle).await?; + + Ok(()) +}
| Feature | Effect |
|---|---|
pure-iso | Use pure-Rust ISO generation instead of genisoimage/mkisofs |
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+The VMFile module parses and resolves VMFile.kdl configuration files. Located in crates/vm-manager/src/vmfile.rs.
+#![allow(unused)] +fn main() { +pub struct VmFile { + pub base_dir: PathBuf, + pub vms: Vec<VmDef>, +} +}
+#![allow(unused)] +fn main() { +pub struct VmDef { + pub name: String, + pub image: ImageSource, + pub vcpus: u16, + pub memory_mb: u64, + pub disk_gb: Option<u32>, + pub network: NetworkDef, + pub cloud_init: Option<CloudInitDef>, + pub ssh: Option<SshDef>, + pub provisions: Vec<ProvisionDef>, +} +}
+#![allow(unused)] +fn main() { +pub enum ImageSource { + Local(String), + Url(String), +} +}
+#![allow(unused)] +fn main() { +pub enum ProvisionDef { + Shell(ShellProvision), + File(FileProvision), +} + +pub struct ShellProvision { + pub inline: Option<String>, + pub script: Option<String>, +} + +pub struct FileProvision { + pub source: String, + pub destination: String, +} +}
+#![allow(unused)] +fn main() { +pub fn discover(explicit: Option<&Path>) -> Result<PathBuf> +}
Finds the VMFile. If explicit is provided, uses that path. Otherwise, looks for VMFile.kdl in the current directory.
+#![allow(unused)] +fn main() { +pub fn parse(path: &Path) -> Result<VmFile> +}
Parses a VMFile.kdl into a VmFile struct. Validates:
vm block.+#![allow(unused)] +fn main() { +pub async fn resolve(def: &VmDef, base_dir: &Path) -> Result<VmSpec> +}
Converts a VmDef into a VmSpec ready for the hypervisor:
base_dir.+#![allow(unused)] +fn main() { +pub fn expand_tilde(s: &str) -> PathBuf +}
Expands ~ to the user's home directory.
+#![allow(unused)] +fn main() { +pub fn resolve_path(raw: &str, base_dir: &Path) -> PathBuf +}
Expands tilde and makes relative paths absolute against base_dir.
+#![allow(unused)] +fn main() { +pub fn generate_ssh_keypair(vm_name: &str) -> Result<(String, String)> +}
Generates an Ed25519 keypair. Returns (public_key_openssh, private_key_pem).
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+vmctl is a command-line tool for creating, managing, and provisioning virtual machines on Linux (QEMU/KVM) and illumos (Propolis/bhyve). It offers both imperative commands for one-off tasks and a declarative configuration format (VMFile.kdl) for reproducible VM environments.
Managing VMs with raw QEMU commands is tedious and error-prone. vmctl handles the plumbing: disk overlays, cloud-init ISOs, SSH key generation, network configuration, and process lifecycle. You describe what you want; vmctl figures out how.
+Think of it like this:
+| Docker world | vmctl world |
|---|---|
docker run | vmctl create --start |
docker-compose.yml | VMFile.kdl |
docker compose up | vmctl up |
docker compose down | vmctl down |
Create a VMFile.kdl:
vm "dev" {
+ image-url "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
+ vcpus 2
+ memory 2048
+
+ cloud-init {
+ hostname "dev"
+ }
+
+ ssh {
+ user "ubuntu"
+ }
+
+ provision "shell" {
+ inline "sudo apt-get update && sudo apt-get install -y build-essential"
+ }
+}
+Then:
+vmctl up # download image, create VM, boot, provision
+vmctl ssh # connect over SSH
+vmctl down # shut it down
+| Platform | Backend | Status |
|---|---|---|
| Linux | QEMU/KVM | Fully supported |
| illumos | Propolis/bhyve | Experimental |
vmctl is split into two crates:
+Both live in a Cargo workspace under crates/.
vmctl is built from source using Rust's Cargo build system.
+Clone the repository and build the release binary:
+git clone https://github.com/user/vm-manager.git
+cd vm-manager
+cargo build --release -p vmctl
+The binary will be at target/release/vmctl. Copy it somewhere in your $PATH:
sudo cp target/release/vmctl /usr/local/bin/
+The vm-manager library crate has one optional feature:
| Feature | Description |
|---|---|
pure-iso | Use a pure-Rust ISO 9660 generator (isobemak) instead of shelling out to genisoimage/mkisofs. Useful in minimal or containerized environments. |
To build with it:
+cargo build --release -p vmctl --features vm-manager/pure-iso
+vmctl --help
+You should see the list of available subcommands.
+vmctl requires several system tools depending on the backend and features you use.
+| Tool | Purpose | Install (Debian/Ubuntu) |
|---|---|---|
qemu-system-x86_64 | VM hypervisor | sudo apt install qemu-system-x86 |
qemu-img | Disk image operations | sudo apt install qemu-utils |
/dev/kvm | Hardware virtualization | Kernel module (usually built-in) |
| Tool | Purpose | Install |
|---|---|---|
genisoimage | ISO 9660 image creation | sudo apt install genisoimage |
mkisofs | Alternative ISO tool | sudo apt install mkisofs |
Or build with the pure-iso feature to avoid needing either.
# QEMU
+qemu-system-x86_64 --version
+
+# qemu-img
+qemu-img --version
+
+# KVM access
+ls -la /dev/kvm
+
+# ISO tools (one of these)
+genisoimage --version 2>/dev/null || mkisofs --version 2>/dev/null
+
+# Your user should be in the kvm group
+groups | grep -q kvm && echo "kvm: OK" || echo "kvm: add yourself to the kvm group"
+If /dev/kvm is not present, enable KVM in your BIOS/UEFI settings (look for "VT-x" or "AMD-V") and ensure the kvm kernel module is loaded:
sudo modprobe kvm
+sudo modprobe kvm_intel # or kvm_amd
+For the experimental Propolis backend:
+propolis-server instancerpool)nebula-vm zone brand installedThis guide walks you through creating your first VM in under a minute.
+Create and start a VM from an Ubuntu cloud image:
+vmctl create \
+ --name demo \
+ --image-url https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img \
+ --vcpus 2 \
+ --memory 2048 \
+ --start
+Wait a moment for the image to download and the VM to boot, then connect:
+vmctl ssh demo
+When you're done:
+vmctl destroy demo
+Create a VMFile.kdl in your project directory:
vm "demo" {
+ image-url "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
+ vcpus 2
+ memory 2048
+
+ cloud-init {
+ hostname "demo"
+ }
+
+ ssh {
+ user "ubuntu"
+ }
+}
+Bring it up:
+vmctl up
+vmctl will download the image (cached for future use), create a QCOW2 overlay, generate an Ed25519 SSH keypair, build a cloud-init ISO, and boot the VM.
+Connect:
+vmctl ssh
+Tear it down:
+vmctl down
+Or destroy it completely (removes all VM files):
+vmctl down --destroy
+vmctl stores all VM state under $XDG_DATA_HOME/vmctl/ (typically ~/.local/share/vmctl/):
~/.local/share/vmctl/
+ vms.json # VM registry (name -> handle mapping)
+ images/ # Downloaded image cache
+ vms/
+ <vm-name>/ # Per-VM working directory
+ overlay.qcow2 # Copy-on-write disk overlay
+ seed.iso # Cloud-init NoCloud ISO
+ qmp.sock # QEMU Machine Protocol socket
+ console.sock # Serial console socket
+ console.log # Boot/cloud-init log
+ provision.log # Provisioning output log
+ id_ed25519_generated # Auto-generated SSH private key
+ id_ed25519_generated.pub # Auto-generated SSH public key
+ pidfile # QEMU process PID
+vmctl never modifies the base image directly. Instead, it creates a QCOW2 copy-on-write overlay on top of the original. This means:
+If you specify disk in your VMFile, the overlay is resized to that size and the guest filesystem can be grown.
All hypervisor operations go through a RouterHypervisor that dispatches to the appropriate backend based on the platform:
QemuBackendPropolisBackendNoopBackendEach backend implements the same Hypervisor trait, so the CLI code is platform-agnostic.
When you run vmctl up, the following happens for each VM defined in VMFile.kdl:
If a VM is already running, vmctl up skips it. If it's stopped, it restarts and re-provisions.
vmctl supports two workflows for managing VMs.
+Use individual commands to create, configure, and manage VMs step by step:
+vmctl create --name myvm --image-url https://example.com/image.img --vcpus 2 --memory 2048 --start
+vmctl ssh myvm
+vmctl stop myvm
+vmctl destroy myvm
+This is useful for:
+Define your VMs in a VMFile.kdl and let vmctl converge to the desired state:
vm "myvm" {
+ image-url "https://example.com/image.img"
+ vcpus 2
+ memory 2048
+
+ cloud-init {
+ hostname "myvm"
+ }
+
+ ssh {
+ user "ubuntu"
+ }
+
+ provision "shell" {
+ inline "echo hello"
+ }
+}
+vmctl up # create + start + provision
+vmctl down # stop
+vmctl reload # destroy + recreate + provision
+vmctl provision # re-run provisioners only
+This is useful for:
+| Scenario | Approach |
|---|---|
| "I need a quick VM to test something" | Imperative |
| "My project needs a build VM with specific packages" | Declarative |
| "I want to script VM lifecycle in CI" | Either, depending on complexity |
| "Multiple VMs that work together" | Declarative |
Every VM in vmctl moves through a set of well-defined states.
+| State | Description |
|---|---|
Preparing | Backend is allocating resources (overlay, ISO, sockets) |
Prepared | Resources allocated, ready to boot |
Running | VM is booted and executing |
Stopped | VM has been shut down (gracefully or forcibly) |
Failed | An error occurred during a lifecycle operation |
Destroyed | VM and all its resources have been cleaned up |
prepare() start()
+[new] ──────────> Prepared ──────────> Running
+ │ │
+ suspend() │ │ stop(timeout)
+ ┌────────────┘ └──────────────┐
+ v v
+ Suspended ─── resume() ──> Stopped
+ │
+ start() │
+ Running <──────────┘
+
+Any state ── destroy() ──> Destroyed
+| Command | From State | To State |
|---|---|---|
vmctl create | (none) | Prepared |
vmctl start | Prepared, Stopped | Running |
vmctl stop | Running | Stopped |
vmctl suspend | Running | Suspended (paused vCPUs) |
vmctl resume | Suspended | Running |
vmctl destroy | Any | Destroyed |
vmctl up | (none), Stopped | Running (auto-creates if needed) |
vmctl down | Running | Stopped |
vmctl reload | Any | Running (destroys + recreates) |
vmctl stop sends an ACPI power-down signal via QMP. If the guest doesn't shut down within the timeout (default 30 seconds), vmctl sends SIGTERM, and finally SIGKILL as a last resort.
vmctl supports several networking modes depending on your needs and permissions.
+network "user"
+QEMU's built-in user-mode networking. No root or special permissions required.
+How it works:
+10.0.2.x).Pros: Zero setup, no root needed. +Cons: No inbound connections (except forwarded ports), lower performance than TAP.
+network "tap" {
+ bridge "br0"
+}
+Creates a TAP device and attaches it to a host bridge. The guest appears as a real machine on the bridge's network.
+How it works:
+Pros: Real network presence, full inbound/outbound, better performance. +Cons: Requires bridge setup, may need root or appropriate capabilities.
+If no bridge name is specified, it defaults to br0.
network "vnic" {
+ name "vnic0"
+}
+Uses an illumos VNIC for exclusive-IP zone networking. Only available on the Propolis backend.
+network "none"
+No networking at all. Useful for isolated compute tasks or testing.
+vmctl discovers the guest IP differently depending on the network mode:
+| Mode | IP Discovery Method |
|---|---|
| User | Returns 127.0.0.1 (SSH via forwarded port) |
| TAP | Parses ARP table (ip neigh show), falls back to dnsmasq lease files by MAC address |
| VNIC | Zone-based discovery |
| None | Not available |
vmctl can work with local disk images or download them from URLs. Downloaded images are cached for reuse.
+Downloaded images are stored in ~/.local/share/vmctl/images/. If an image already exists in the cache, it won't be re-downloaded.
vmctl uses qemu-img to detect and convert image formats. Common formats:
The format is auto-detected from the file header.
+If a URL ends in .zst or .zstd, vmctl automatically decompresses the image after downloading. This is common for distribution cloud images.
vmctl never boots from the base image directly. Instead:
+This means multiple VMs can share the same base image efficiently.
+If you specify disk (in GB) in your VMFile or --disk on the CLI, the overlay is created with that size. The guest OS can then grow its filesystem to fill the available space (most cloud images do this automatically via cloud-init's growpart module).
# Download an image to the cache
+vmctl image pull https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
+
+# List cached images
+vmctl image list
+
+# Inspect a local image
+vmctl image inspect ./my-image.qcow2
+vmctl uses cloud-init to configure guests on first boot. It generates a NoCloud seed ISO containing user-data and meta-data, which the guest's cloud-init agent picks up automatically.
+There are three ways to get SSH access to a VM:
+When you define a cloud-init block without an explicit ssh-key, vmctl generates a per-VM Ed25519 keypair:
cloud-init {
+ hostname "myvm"
+}
+
+ssh {
+ user "ubuntu"
+}
+The keys are stored in the VM's work directory:
+~/.local/share/vmctl/vms/<name>/id_ed25519_generated (private)~/.local/share/vmctl/vms/<name>/id_ed25519_generated.pub (public)This is the simplest option. No key management required.
+Point to your own public key file:
+cloud-init {
+ ssh-key "~/.ssh/id_ed25519.pub"
+}
+
+ssh {
+ user "ubuntu"
+ private-key "~/.ssh/id_ed25519"
+}
+Provide a complete cloud-config YAML file for full control:
+cloud-init {
+ user-data "./my-cloud-config.yaml"
+}
+In this mode, you're responsible for setting up SSH access yourself in the user-data.
+When vmctl needs to SSH into a VM (for vmctl ssh or provisioning), it searches for a private key in this order:
id_ed25519_generated)--key flag or private-key in VMFile ssh block~/.ssh/: id_ed25519, id_ecdsa, id_rsa--user CLI flaguser in VMFile ssh block"vm"When vmctl generates the cloud-config, it creates a user with:
+sudo accessauthorized_keysThis tutorial walks through the full lifecycle of a VM using individual vmctl commands.
+vmctl create \
+ --name tutorial \
+ --image-url https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img \
+ --vcpus 2 \
+ --memory 2048 \
+ --ssh-key ~/.ssh/id_ed25519.pub
+This downloads the image (cached for future use), creates a QCOW2 overlay, generates a cloud-init ISO with your SSH key, and registers the VM.
+vmctl start tutorial
+vmctl list
+NAME BACKEND VCPUS MEM NETWORK PID SSH
+tutorial qemu 2 2048 user 12345 10042
+For detailed info:
+vmctl status tutorial
+vmctl ssh tutorial
+vmctl waits for SSH to become available (cloud-init needs a moment to set up the user), then drops you into a shell.
+Pause the VM without shutting it down:
+vmctl suspend tutorial
+Resume it:
+vmctl resume tutorial
+The VM continues from exactly where it was, no reboot needed.
+vmctl stop tutorial
+This sends an ACPI power-down signal. If the guest doesn't shut down within 30 seconds, vmctl sends SIGTERM.
+To change the timeout:
+vmctl stop tutorial --timeout 60
+A stopped VM can be started again:
+vmctl start tutorial
+When you're done, clean up everything:
+vmctl destroy tutorial
+This stops the VM (if running), removes the overlay, cloud-init ISO, and all work directory files, and unregisters the VM from the store.
+This tutorial shows how to define VMs in a configuration file and manage them with vmctl up/down.
Create VMFile.kdl in your project directory:
vm "webserver" {
+ image-url "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
+ vcpus 2
+ memory 2048
+ disk 20
+
+ cloud-init {
+ hostname "webserver"
+ }
+
+ ssh {
+ user "ubuntu"
+ }
+
+ provision "shell" {
+ inline "sudo apt-get update && sudo apt-get install -y nginx"
+ }
+
+ provision "shell" {
+ inline "echo 'Hello from vmctl!' | sudo tee /var/www/html/index.html"
+ }
+}
+vmctl up
+vmctl will:
+VMFile.kdl in the current directory.vmctl ssh
+When there's only one VM in the VMFile, you don't need to specify the name.
+Edit VMFile.kdl to add another provisioner, then reload:
vmctl reload
+This destroys the existing VM and recreates it from scratch with the updated definition.
+To re-run just the provisioners without recreating:
+vmctl provision
+Stop the VM:
+vmctl down
+Or stop and destroy:
+vmctl down --destroy
+If your VMFile defines multiple VMs, use --name to target a specific one:
vmctl up --name webserver
+vmctl ssh --name webserver
+vmctl down --name webserver
+Provisioners run commands and upload files to a VM after it boots. They execute in order and stop on the first failure.
+Execute a command directly on the guest:
+provision "shell" {
+ inline "sudo apt-get update && sudo apt-get install -y curl"
+}
+Upload and execute a local script:
+provision "shell" {
+ script "scripts/setup.sh"
+}
+The script is uploaded to /tmp/vmctl-provision-<step>.sh on the guest, made executable, and run. Paths are relative to the directory containing VMFile.kdl.
Upload a file to the guest via SFTP:
+provision "file" {
+ source "config/nginx.conf"
+ destination "/tmp/nginx.conf"
+}
+provision.log in the VM's work directory.A common pattern is to combine file uploads with shell commands:
+vm "builder" {
+ image-url "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
+ vcpus 4
+ memory 4096
+
+ cloud-init {
+ hostname "builder"
+ }
+
+ ssh {
+ user "ubuntu"
+ }
+
+ // Stage 1: Install dependencies
+ provision "shell" {
+ inline "sudo apt-get update && sudo apt-get install -y build-essential"
+ }
+
+ // Stage 2: Upload source code
+ provision "file" {
+ source "src.tar.gz"
+ destination "/tmp/src.tar.gz"
+ }
+
+ // Stage 3: Build
+ provision "shell" {
+ inline "cd /tmp && tar xzf src.tar.gz && cd src && make"
+ }
+}
+To re-run provisioners on an already-running VM:
+vmctl provision
+Or for a specific VM:
+vmctl provision --name builder
+vmctl log builder --provision
+This tutorial walks through the real-world VMFile.kdl used in the vm-manager project itself to build software on OmniOS (an illumos distribution).
+Build a Rust binary (forger) on OmniOS. This requires:
vm "omnios-builder" {
+ image-url "https://downloads.omnios.org/media/stable/omnios-r151056.cloud.qcow2"
+ vcpus 4
+ memory 4096
+ disk 20
+
+ cloud-init {
+ hostname "omnios-builder"
+ }
+
+ ssh {
+ user "smithy"
+ }
+
+ provision "shell" {
+ script "scripts/bootstrap-omnios.sh"
+ }
+
+ provision "file" {
+ source "scripts/forger-src.tar.gz"
+ destination "/tmp/forger-src.tar.gz"
+ }
+
+ provision "shell" {
+ script "scripts/install-forger.sh"
+ }
+}
+bootstrap-omnios.sh)This script installs system packages and the Rust toolchain:
+gcc14, gnu-make, pkg-config, openssl, curl, git, and other build dependencies via IPS (pkg install).rustup.The file provisioner uploads a pre-packed tarball of the forger source code. This tarball is created beforehand with:
./scripts/pack-forger.sh
+The pack script:
+crates/forger, crates/spec-parser, and images/ into a staging directory.Cargo.toml.Cargo.lock for reproducible builds.scripts/forger-src.tar.gz.install-forger.sh)$HOME/forger.cargo build -p forger --release./usr/local/bin/forger.# Pack the source on the host
+./scripts/pack-forger.sh
+
+# Bring up the VM, provision, and build
+vmctl up
+
+# SSH in to test the binary
+vmctl ssh
+forger --help
+
+# Tear it down when done
+vmctl down --destroy
+VMFile.kdl is the declarative configuration format for vmctl. It uses KDL (KDL Document Language), a human-friendly configuration language.
vmctl looks for VMFile.kdl in the current directory by default. You can override this with --file:
vmctl up --file path/to/MyVMFile.kdl
+A VMFile contains one or more vm blocks, each defining a virtual machine:
vm "name" {
+ // image source (required)
+ // resources
+ // networking
+ // cloud-init
+ // ssh config
+ // provisioners
+}
+All paths in a VMFile are resolved relative to the directory containing the VMFile. Tilde (~) is expanded to the user's home directory.
// Relative to VMFile directory
+image "images/ubuntu.qcow2"
+
+// Absolute path
+image "/opt/images/ubuntu.qcow2"
+
+// Home directory expansion
+cloud-init {
+ ssh-key "~/.ssh/id_ed25519.pub"
+}
+vmctl validates the VMFile on parse and provides detailed error messages with hints:
+image or image-url, not both).inline or script.source and destination."user", "tap", or "none".The vm block is the top-level element in a VMFile. It defines a single virtual machine.
vm "name" {
+ // configuration nodes
+}
+The name is a required string argument. It must be unique across all vm blocks in the file.
vm "dev-server" {
+ image-url "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
+ vcpus 2
+ memory 2048
+ disk 20
+
+ cloud-init {
+ hostname "dev-server"
+ }
+
+ ssh {
+ user "ubuntu"
+ }
+}
+vmctl list, vmctl ssh, --name filtering, etc.~/.local/share/vmctl/vms/.Every VM must specify exactly one image source. The two options are mutually exclusive.
+image "path/to/image.qcow2"
+Points to a disk image on the host filesystem. The path is resolved relative to the VMFile directory, with tilde expansion.
+The file must exist at parse time. Supported formats are auto-detected by qemu-img (qcow2, raw, etc.).
image-url "https://example.com/image.qcow2"
+Downloads the image and caches it in ~/.local/share/vmctl/images/. If the image is already cached, it won't be re-downloaded.
URLs ending in .zst or .zstd are automatically decompressed after download.
image or image-url must be specified.Resource nodes control the VM's CPU, memory, and disk allocation.
+vcpus 2
+Number of virtual CPUs. Must be greater than 0.
+Default: 1
memory 2048
+Memory in megabytes. Must be greater than 0.
+Default: 1024 (1 GB)
disk 20
+Disk size in gigabytes. When specified, the QCOW2 overlay is created with this size, allowing the guest to use more space than the base image provides. Most cloud images auto-grow the filesystem via cloud-init.
+Default: not set (overlay matches base image size)
+The network node configures VM networking.
network "mode"
+// or
+network "mode" {
+ // mode-specific attributes
+}
+network "user"
+QEMU's SLIRP user-mode networking. No root required. SSH access is via a forwarded host port.
+network "tap"
+// or with explicit bridge:
+network "tap" {
+ bridge "br0"
+}
+TAP device attached to a Linux bridge. The guest appears on the bridge's network with a real IP.
+Default bridge: "br0"
network "none"
+No networking.
+If no network node is specified, user-mode networking is used.
The cloud-init block configures guest initialization via cloud-init's NoCloud datasource.
cloud-init {
+ hostname "myvm"
+ ssh-key "~/.ssh/id_ed25519.pub"
+ user-data "path/to/cloud-config.yaml"
+}
+All fields are optional.
+hostname "myvm"
+Sets the guest hostname via cloud-init metadata.
+ssh-key "~/.ssh/id_ed25519.pub"
+Path to an SSH public key file. The key is injected into the cloud-config's authorized_keys for the SSH user. Path is resolved relative to the VMFile directory.
user-data "cloud-config.yaml"
+Path to a raw cloud-config YAML file. When this is set, vmctl passes the file contents directly as user-data without generating its own cloud-config. You are responsible for user creation and SSH setup.
+Mutually exclusive with ssh-key in practice - if you provide raw user-data, vmctl won't inject any SSH keys.
When a cloud-init block is present but neither ssh-key nor user-data is specified, vmctl automatically:
This is the recommended approach for most use cases.
+The ssh block tells vmctl how to connect to the guest for provisioning and vmctl ssh.
ssh {
+ user "ubuntu"
+ private-key "~/.ssh/id_ed25519"
+}
+user "ubuntu"
+The SSH username to connect as. This should match the user created by cloud-init.
+Default: "vm" (used when the ssh block exists but user is omitted)
private-key "~/.ssh/id_ed25519"
+Path to the SSH private key for authentication. Path is resolved relative to the VMFile directory.
+Default: When omitted, vmctl uses the auto-generated key if available, or falls back to standard keys in ~/.ssh/.
The ssh block is required if you want to:
vmctl ssh with VMFile-based name inference.If you only use imperative commands and don't need provisioning, the ssh block is optional.
+Provision blocks define steps to run on the guest after boot. They execute in order and abort on the first failure.
+provision "shell" {
+ inline "sudo apt-get update && sudo apt-get install -y nginx"
+}
+Executes the command directly on the guest via SSH.
+provision "shell" {
+ script "scripts/setup.sh"
+}
+The script file is uploaded to /tmp/vmctl-provision-<step>.sh on the guest, made executable with chmod +x, and executed. The path is resolved relative to the VMFile directory.
A shell provisioner must have exactly one of inline or script. Specifying both or neither is an error.
provision "file" {
+ source "config/app.conf"
+ destination "/etc/app/app.conf"
+}
+Uploads a local file to the guest via SFTP.
+| Field | Description |
|---|---|
source | Local file path (relative to VMFile directory) |
destination | Absolute path on the guest |
provision.log in the VM's work directory.A VMFile can define multiple VMs. Each vm block is independent.
vm "web" {
+ image-url "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
+ vcpus 2
+ memory 2048
+
+ cloud-init {
+ hostname "web"
+ }
+
+ ssh {
+ user "ubuntu"
+ }
+
+ provision "shell" {
+ inline "sudo apt-get update && sudo apt-get install -y nginx"
+ }
+}
+
+vm "db" {
+ image-url "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
+ vcpus 2
+ memory 4096
+ disk 50
+
+ cloud-init {
+ hostname "db"
+ }
+
+ ssh {
+ user "ubuntu"
+ }
+
+ provision "shell" {
+ inline "sudo apt-get update && sudo apt-get install -y postgresql"
+ }
+}
+vmctl up brings up all VMs in order.vmctl down stops all VMs.vmctl ssh requires --name when multiple VMs are defined (or it will error).--name with any command to target a specific VM.vmctl up --name web # only bring up "web"
+vmctl provision --name db # re-provision only "db"
+vmctl down --name web # stop only "web"
+A complete VMFile.kdl demonstrating every available feature:
+// Development VM with all options specified
+vm "full-example" {
+ // Image source: URL (auto-cached)
+ image-url "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
+
+ // Resources
+ vcpus 4
+ memory 4096
+ disk 40
+
+ // Networking: user-mode (default, no root needed)
+ network "user"
+
+ // Cloud-init guest configuration
+ cloud-init {
+ hostname "full-example"
+ // ssh-key and user-data are omitted, so vmctl auto-generates an Ed25519 keypair
+ }
+
+ // SSH connection settings
+ ssh {
+ user "ubuntu"
+ // private-key is omitted, so vmctl uses the auto-generated key
+ }
+
+ // Provisioners run in order after boot
+ provision "shell" {
+ inline "sudo apt-get update && sudo apt-get install -y build-essential curl git"
+ }
+
+ provision "file" {
+ source "config/bashrc"
+ destination "/home/ubuntu/.bashrc"
+ }
+
+ provision "shell" {
+ script "scripts/setup-dev-tools.sh"
+ }
+}
+
+// Second VM demonstrating TAP networking and explicit keys
+vm "tap-example" {
+ image "~/images/debian-12-generic-amd64.qcow2"
+
+ vcpus 2
+ memory 2048
+
+ network "tap" {
+ bridge "br0"
+ }
+
+ cloud-init {
+ hostname "tap-vm"
+ ssh-key "~/.ssh/id_ed25519.pub"
+ }
+
+ ssh {
+ user "debian"
+ private-key "~/.ssh/id_ed25519"
+ }
+}
+
+// Minimal VM: just an image and defaults
+vm "minimal" {
+ image-url "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
+}
+Running vmctl up with this VMFile:
br0, injects your existing SSH key.Use --name to target specific VMs:
vmctl up --name full-example
+vmctl ssh --name tap-example
+vmctl down --name minimal
+The main entry point for the vmctl CLI.
+vmctl <COMMAND>
+| Command | Description |
|---|---|
create | Create a new VM |
start | Start an existing VM |
stop | Stop a running VM |
destroy | Destroy a VM and clean up resources |
list | List all VMs |
status | Show detailed VM status |
console | Attach to serial console |
ssh | SSH into a VM |
suspend | Suspend (pause) a running VM |
resume | Resume a suspended VM |
image | Manage VM images |
up | Bring up VMs from VMFile.kdl |
down | Bring down VMs from VMFile.kdl |
reload | Destroy and recreate VMs from VMFile.kdl |
provision | Re-run provisioners from VMFile.kdl |
log | Show VM logs |
| Variable | Description |
|---|---|
RUST_LOG | Control log verbosity (e.g., RUST_LOG=debug vmctl up) |
XDG_DATA_HOME | Override data directory (default: ~/.local/share) |
Create a new VM and optionally start it.
+vmctl create [OPTIONS] --name <NAME>
+| Option | Type | Default | Description |
|---|---|---|---|
--name | string | required | VM name |
--image | path | Path to a local disk image | |
--image-url | string | URL to download an image from | |
--vcpus | integer | 1 | Number of virtual CPUs |
--memory | integer | 1024 | Memory in MB |
--disk | integer | Disk size in GB (overlay resize) | |
--bridge | string | Bridge name for TAP networking | |
--cloud-init | path | Path to cloud-init user-data file | |
--ssh-key | path | Path to SSH public key file | |
--start | flag | false | Start the VM after creation |
One of --image or --image-url must be provided. If --image-url is given, the image is downloaded and cached.
When --bridge is specified, TAP networking is used. Otherwise, user-mode (SLIRP) networking is used.
When --ssh-key is provided, a cloud-init ISO is generated that injects the public key. The SSH user defaults to "vm".
# Create from a URL with defaults
+vmctl create --name myvm --image-url https://example.com/image.img
+
+# Create with custom resources and start immediately
+vmctl create --name myvm \
+ --image-url https://example.com/image.img \
+ --vcpus 4 --memory 4096 --disk 40 \
+ --ssh-key ~/.ssh/id_ed25519.pub \
+ --start
+
+# Create from local image with TAP networking
+vmctl create --name myvm --image ./ubuntu.qcow2 --bridge br0
+Start an existing VM.
+vmctl start <NAME>
+| Argument | Description |
|---|---|
NAME | VM name (positional) |
Starts a VM that is in the Prepared or Stopped state. The VM must have been previously created with vmctl create or vmctl up.
vmctl start myvm
+Stop a running VM.
+vmctl stop [OPTIONS] <NAME>
+| Argument | Description |
|---|---|
NAME | VM name (positional) |
| Option | Type | Default | Description |
|---|---|---|---|
--timeout | integer | 30 | Graceful shutdown timeout in seconds |
Sends an ACPI power-down signal via QMP. If the guest doesn't shut down within the timeout, vmctl sends SIGTERM to the QEMU process, then SIGKILL as a last resort.
+# Stop with default 30-second timeout
+vmctl stop myvm
+
+# Give it more time to shut down gracefully
+vmctl stop myvm --timeout 120
+Destroy a VM and clean up all associated resources.
+vmctl destroy <NAME>
+| Argument | Description |
|---|---|
NAME | VM name (positional) |
Stops the VM if it's running, then removes all associated files: QCOW2 overlay, cloud-init ISO, log files, SSH keys, sockets, and the work directory. Unregisters the VM from the store.
+This action is irreversible.
+vmctl destroy myvm
+vmctl down (declarative equivalent)
+List all registered VMs.
+vmctl list
+NAME BACKEND VCPUS MEM NETWORK PID SSH
+webserver qemu 2 2048 user 12345 10042
+database qemu 4 4096 tap 12346 -
+| Column | Description |
|---|---|
NAME | VM name |
BACKEND | Hypervisor backend (qemu, propolis, noop) |
VCPUS | Number of virtual CPUs |
MEM | Memory in MB |
NETWORK | Networking mode (user, tap, vnic, none) |
PID | QEMU process PID (or - if not running) |
SSH | SSH host port (or - if not available) |
vmctl list
+Show detailed status of a VM.
+vmctl status <NAME>
+| Argument | Description |
|---|---|
NAME | VM name (positional) |
Displays all known information about the VM:
+vmctl status myvm
+Attach to a VM's serial console.
+vmctl console <NAME>
+| Argument | Description |
|---|---|
NAME | VM name (positional) |
Connects to the VM's serial console via a Unix socket (QEMU) or WebSocket (Propolis). You'll see the same output as a physical serial port: boot messages, kernel output, and a login prompt.
+Press Ctrl+] (0x1d) to detach from the console.
+vmctl console myvm
+SSH into a VM.
+vmctl ssh [OPTIONS] [NAME]
+| Argument | Description |
|---|---|
NAME | VM name (optional; inferred from VMFile.kdl if only one VM is defined) |
| Option | Type | Description |
|---|---|---|
--user | string | SSH username (overrides VMFile) |
--key | path | Path to SSH private key |
--file | path | Path to VMFile.kdl (for reading ssh user) |
vmctl searches for a private key in this order:
+id_ed25519_generated)--key~/.ssh/id_ed25519~/.ssh/id_ecdsa~/.ssh/id_rsa--user CLI flaguser field in VMFile's ssh block"vm"vmctl first verifies SSH connectivity using libssh2 (with a 30-second retry timeout), then hands off to the system ssh binary for full interactive terminal support. SSH options StrictHostKeyChecking=no and UserKnownHostsFile=/dev/null are set automatically.
For user-mode networking, vmctl connects to 127.0.0.1 on the forwarded host port. For TAP networking, it discovers the guest IP via ARP.
# SSH into the only VM in VMFile.kdl
+vmctl ssh
+
+# SSH into a specific VM
+vmctl ssh myvm
+
+# Override user and key
+vmctl ssh myvm --user root --key ~/.ssh/special_key
+Suspend (pause) a running VM.
+vmctl suspend <NAME>
+| Argument | Description |
|---|---|
NAME | VM name (positional) |
Pauses the VM's vCPUs via QMP. The VM remains in memory but stops executing. Use vmctl resume to continue.
vmctl suspend myvm
+Resume a suspended VM.
+vmctl resume <NAME>
+| Argument | Description |
|---|---|
NAME | VM name (positional) |
Resumes a VM that was paused with vmctl suspend. The VM continues from exactly where it left off.
vmctl resume myvm
+Manage VM disk images.
+vmctl image <SUBCOMMAND>
+Download an image to the local cache.
+vmctl image pull [OPTIONS] <URL>
+| Argument/Option | Type | Description |
|---|---|---|
URL | string | URL to download (positional) |
--name | string | Name to save as in the cache |
List cached images.
+vmctl image list
+Output:
+NAME SIZE PATH
+noble-server-cloudimg-amd64.img 0.62 GB /home/user/.local/share/vmctl/images/noble-server-cloudimg-amd64.img
+Show image format and details.
+vmctl image inspect <PATH>
+| Argument | Description |
|---|---|
PATH | Path to image file (positional) |
# Download and cache an image
+vmctl image pull https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
+
+# List what's cached
+vmctl image list
+
+# Check format of a local image
+vmctl image inspect ./my-image.qcow2
+Bring up VMs defined in VMFile.kdl.
+vmctl up [OPTIONS]
+| Option | Type | Default | Description |
|---|---|---|---|
--file | path | Path to VMFile.kdl (auto-discovered if omitted) | |
--name | string | Only bring up a specific VM | |
--no-provision | flag | false | Skip provisioning steps |
For each VM in the VMFile:
+Images are downloaded and cached as needed. SSH keys are auto-generated when cloud-init is configured without an explicit key.
+# Bring up all VMs in ./VMFile.kdl
+vmctl up
+
+# Bring up a specific VM
+vmctl up --name webserver
+
+# Bring up without provisioning
+vmctl up --no-provision
+
+# Use a specific VMFile
+vmctl up --file path/to/VMFile.kdl
+Bring down VMs defined in VMFile.kdl.
+vmctl down [OPTIONS]
+| Option | Type | Default | Description |
|---|---|---|---|
--file | path | Path to VMFile.kdl (auto-discovered if omitted) | |
--name | string | Only bring down a specific VM | |
--destroy | flag | false | Destroy VMs instead of just stopping |
Without --destroy, VMs are stopped gracefully (30-second timeout). They can be restarted with vmctl up or vmctl start.
With --destroy, VMs are fully destroyed: all files removed, unregistered from the store. This is irreversible.
# Stop all VMs in VMFile.kdl
+vmctl down
+
+# Stop a specific VM
+vmctl down --name webserver
+
+# Destroy all VMs
+vmctl down --destroy
+Destroy and recreate VMs from VMFile.kdl.
+vmctl reload [OPTIONS]
+| Option | Type | Default | Description |
|---|---|---|---|
--file | path | Path to VMFile.kdl (auto-discovered if omitted) | |
--name | string | Only reload a specific VM | |
--no-provision | flag | false | Skip provisioning after reload |
For each VM: destroys the existing instance (if any), then creates, starts, and provisions a fresh VM from the current VMFile definition. Useful when you've changed the VMFile and want a clean slate.
+# Reload all VMs
+vmctl reload
+
+# Reload a specific VM
+vmctl reload --name webserver
+
+# Reload without provisioning
+vmctl reload --no-provision
+Re-run provisioners on running VMs from VMFile.kdl.
+vmctl provision [OPTIONS]
+| Option | Type | Default | Description |
|---|---|---|---|
--file | path | Path to VMFile.kdl (auto-discovered if omitted) | |
--name | string | Only provision a specific VM |
Re-runs all provision steps defined in the VMFile on already-running VMs. The VM must be running and have an ssh block in the VMFile.
vmctl waits up to 120 seconds for SSH to become available, then runs each provisioner in sequence, streaming output to the terminal and logging to provision.log.
Useful for iterating on provision scripts without recreating the VM.
+# Re-provision all VMs
+vmctl provision
+
+# Re-provision a specific VM
+vmctl provision --name builder
+Show VM console and provision logs.
+vmctl log [OPTIONS] <NAME>
+| Argument | Description |
|---|---|
NAME | VM name (positional) |
| Option | Type | Default | Description |
|---|---|---|---|
--console | flag | false | Show only console log (boot / cloud-init output) |
--provision | flag | false | Show only provision log |
--tail, -n | integer | 0 | Show the last N lines (0 = all) |
By default (no flags), both console and provision logs are shown. The console log captures serial output (boot messages, cloud-init output). The provision log captures stdout/stderr from provisioner runs.
+Log files are located in the VM's work directory:
+console.log - Serial console outputprovision.log - Provisioning output# Show all logs
+vmctl log myvm
+
+# Show only provision output
+vmctl log myvm --provision
+
+# Show last 50 lines of console log
+vmctl log myvm --console --tail 50
+vm-manager is structured as a two-crate Cargo workspace.
+┌─────────────────────────────────────────┐
+│ vmctl CLI │
+│ (crates/vmctl) │
+│ │
+│ Commands → VMFile parser → Hypervisor │
+└──────────────────┬──────────────────────┘
+ │
+┌──────────────────┴──────────────────────┐
+│ vm-manager library │
+│ (crates/vm-manager) │
+│ │
+│ ┌─────────────┐ ┌──────────────────┐ │
+│ │ Hypervisor │ │ Image Manager │ │
+│ │ Trait │ │ │ │
+│ └──────┬──────┘ └──────────────────┘ │
+│ │ │
+│ ┌──────┴──────────────────────┐ │
+│ │ RouterHypervisor │ │
+│ │ ┌──────┐ ┌────────┐ ┌────┐│ │
+│ │ │ QEMU │ │Propolis│ │Noop││ │
+│ │ └──────┘ └────────┘ └────┘│ │
+│ └─────────────────────────────┘ │
+│ │
+│ ┌───────────┐ ┌──────────────────┐ │
+│ │ SSH │ │ Cloud-Init │ │
+│ │ Module │ │ Generator │ │
+│ └───────────┘ └──────────────────┘ │
+│ │
+│ ┌───────────┐ ┌──────────────────┐ │
+│ │ Provision │ │ VMFile │ │
+│ │ Runner │ │ Parser │ │
+│ └───────────┘ └──────────────────┘ │
+└─────────────────────────────────────────┘
+vmctl uses Tokio with the multi-threaded runtime. Most operations are async, with one exception: SSH operations use ssh2 (libssh2 bindings), which is blocking. These are wrapped in tokio::task::spawn_blocking to avoid blocking the async executor.
The Hypervisor trait defines a platform-agnostic interface. The RouterHypervisor dispatches calls to the correct backend based on the BackendTag stored in each VmHandle:
QemuBackend.PropolisBackend.NoopBackend for testing.Conditional compilation (#[cfg(target_os = ...)]) ensures only the relevant backend is compiled.
vm-manager/
+ Cargo.toml # Workspace root
+ crates/
+ vm-manager/ # Library crate
+ Cargo.toml
+ src/
+ lib.rs # Re-exports
+ traits.rs # Hypervisor trait, ConsoleEndpoint
+ types.rs # VmSpec, VmHandle, VmState, NetworkConfig, etc.
+ error.rs # VmError with miette diagnostics
+ vmfile.rs # VMFile.kdl parser and resolver
+ image.rs # ImageManager (download, cache, overlay)
+ ssh.rs # SSH connect, exec, streaming, upload
+ provision.rs # Provisioner runner
+ cloudinit.rs # NoCloud seed ISO generation
+ backends/
+ mod.rs # RouterHypervisor
+ qemu.rs # QEMU/KVM backend (Linux)
+ qmp.rs # QMP client
+ propolis.rs # Propolis/bhyve backend (illumos)
+ noop.rs # No-op backend (testing)
+ vmctl/ # CLI binary crate
+ Cargo.toml
+ src/
+ main.rs # CLI entry point, clap App
+ commands/
+ create.rs # vmctl create
+ start.rs # vmctl start, suspend, resume
+ stop.rs # vmctl stop
+ destroy.rs # vmctl destroy
+ list.rs # vmctl list
+ status.rs # vmctl status
+ console.rs # vmctl console
+ ssh.rs # vmctl ssh
+ image.rs # vmctl image (pull, list, inspect)
+ up.rs # vmctl up
+ down.rs # vmctl down
+ reload.rs # vmctl reload
+ provision_cmd.rs # vmctl provision
+ log.rs # vmctl log
+The library crate. Contains all business logic and can be used as a dependency by other Rust projects.
+Public re-exports from lib.rs:
RouterHypervisor (from backends)Hypervisor, ConsoleEndpoint (from traits)VmError, Result (from error)types: BackendTag, VmSpec, VmHandle, VmState, NetworkConfig, CloudInitConfig, SshConfigThe CLI binary. Depends on vm-manager and adds:
vms.json)All backends implement the Hypervisor trait defined in crates/vm-manager/src/traits.rs:
+#![allow(unused)] +fn main() { +pub trait Hypervisor: Send + Sync { + fn prepare(&self, spec: &VmSpec) -> impl Future<Output = Result<VmHandle>>; + fn start(&self, vm: &VmHandle) -> impl Future<Output = Result<VmHandle>>; + fn stop(&self, vm: &VmHandle, timeout: Duration) -> impl Future<Output = Result<VmHandle>>; + fn suspend(&self, vm: &VmHandle) -> impl Future<Output = Result<VmHandle>>; + fn resume(&self, vm: &VmHandle) -> impl Future<Output = Result<VmHandle>>; + fn destroy(&self, vm: VmHandle) -> impl Future<Output = Result<()>>; + fn state(&self, vm: &VmHandle) -> impl Future<Output = Result<VmState>>; + fn guest_ip(&self, vm: &VmHandle) -> impl Future<Output = Result<String>>; + fn console_endpoint(&self, vm: &VmHandle) -> Result<ConsoleEndpoint>; +} +}
Located in crates/vm-manager/src/backends/qemu.rs.
Prepare:
+~/.local/share/vmctl/vms/<name>/.Start:
+qemu-system-x86_64 with KVM acceleration.host (passthrough).q35,accel=kvm.Stop:
+system_powerdown).IP Discovery:
+127.0.0.1 (SSH via forwarded port).ip neigh show), falls back to dnsmasq lease files by MAC address.Located in crates/vm-manager/src/backends/qmp.rs. Async JSON-over-Unix-socket client implementing the QEMU Machine Protocol.
Commands: system_powerdown, quit, stop, cont, query_status, query_vnc.
Located in crates/vm-manager/src/backends/propolis.rs.
nebula-vm brand.propolis-server via REST API.Located in crates/vm-manager/src/backends/noop.rs. All operations succeed immediately. Used for testing.
Located in crates/vm-manager/src/backends/mod.rs. Dispatches Hypervisor trait calls to the correct backend based on the VmHandle's BackendTag.
Construction:
+RouterHypervisor::new(bridge, zfs_pool) - Platform-aware, creates the appropriate backend.RouterHypervisor::noop_only() - Testing mode.vmctl persists VM state in a JSON file at $XDG_DATA_HOME/vmctl/vms.json (typically ~/.local/share/vmctl/vms.json). Falls back to /tmp if XDG_DATA_HOME is not set.
The store is a simple mapping from VM name to VmHandle.
VmHandle is serialized to JSON with all fields. Fields added in later versions have #[serde(default)] annotations, so older JSON files are deserialized without errors (missing fields get defaults).
Example stored handle:
+{
+ "id": "abc123",
+ "name": "myvm",
+ "backend": "qemu",
+ "work_dir": "/home/user/.local/share/vmctl/vms/myvm",
+ "overlay_path": "/home/user/.local/share/vmctl/vms/myvm/overlay.qcow2",
+ "seed_iso_path": "/home/user/.local/share/vmctl/vms/myvm/seed.iso",
+ "pid": 12345,
+ "qmp_socket": "/home/user/.local/share/vmctl/vms/myvm/qmp.sock",
+ "console_socket": "/home/user/.local/share/vmctl/vms/myvm/console.sock",
+ "vnc_addr": "127.0.0.1:5900",
+ "vcpus": 2,
+ "memory_mb": 2048,
+ "disk_gb": 20,
+ "network": {"type": "User"},
+ "ssh_host_port": 10042,
+ "mac_addr": "52:54:00:ab:cd:ef"
+}
+The store uses an atomic write pattern:
+.tmp file.This prevents corruption if the process is interrupted during a write.
+The store records the last known state but doesn't actively monitor QEMU processes. When vmctl queries a VM's state, it:
+kill(pid, 0) to verify the process is alive.running, paused, etc.).Stopped.vmctl uses the ssh2 crate (Rust bindings to libssh2) for SSH operations. The SSH module is at crates/vm-manager/src/ssh.rs.
Establishes a TCP connection and authenticates via public key.
+Supports two authentication modes:
+Executes a command and collects the full stdout/stderr output. Blocking.
+Executes a command and streams stdout/stderr in real-time to provided writers. Uses non-blocking I/O:
+exec().This is used by the provisioner to show build output live.
+Transfers a file to the guest via SFTP. Creates the SFTP subsystem, opens a remote file, and writes the local file contents.
+Attempts to connect repeatedly until a timeout (typically 120 seconds for provisioning, 30 seconds for vmctl ssh). Uses exponential backoff starting at 1 second, capped at 5 seconds. Runs the blocking connect on tokio::task::spawn_blocking.
libssh2 is used for programmatic operations (provisioning, connectivity checks) because it can be controlled from Rust code. For interactive sessions (vmctl ssh), vmctl hands off to the system ssh binary for proper terminal handling (PTY allocation, signal forwarding, etc.).
vm-manager uses miette for rich diagnostic error reporting. Every error variant includes:
+vm_manager::qemu::spawn_failed).help message telling the user what to do.Errors are defined with #[derive(thiserror::Error, miette::Diagnostic)].
| Code | Trigger | Help |
|---|---|---|
vm_manager::qemu::spawn_failed | QEMU process failed to start | Ensure qemu-system-x86_64 is installed, in PATH, and KVM is available (/dev/kvm) |
vm_manager::qemu::qmp_connect_failed | Can't connect to QMP socket | QEMU may have crashed before QMP socket ready; check work directory logs |
vm_manager::qemu::qmp_command_failed | QMP command returned an error | (varies) |
vm_manager::image::overlay_creation_failed | QCOW2 overlay creation failed | Ensure qemu-img is installed and base image exists and is readable |
vm_manager::network::ip_discovery_timeout | Guest IP not found | Guest may not have DHCP lease; check network config and cloud-init |
vm_manager::propolis::unreachable | Can't reach propolis-server | Ensure propolis-server is running and listening on expected address |
vm_manager::cloudinit::iso_failed | Seed ISO generation failed | Ensure genisoimage or mkisofs installed, or enable pure-iso feature |
vm_manager::ssh::failed | SSH connection or command failed | Check SSH key, guest reachability, and sshd running |
vm_manager::ssh::keygen_failed | Ed25519 key generation failed | Internal error; please report it |
vm_manager::image::download_failed | Image download failed | Check network connectivity and URL correctness |
vm_manager::image::format_detection_failed | Can't detect image format | Ensure qemu-img installed and file is valid disk image |
vm_manager::image::conversion_failed | Image format conversion failed | Ensure qemu-img installed and sufficient disk space |
vm_manager::vm::not_found | VM not in store | Run vmctl list to see available VMs |
vm_manager::vm::invalid_state | Operation invalid for current state | (varies) |
vm_manager::backend::not_available | Backend not supported on platform | Backend not supported on current platform |
vm_manager::vmfile::not_found | VMFile.kdl not found | Create VMFile.kdl in current directory or specify path with --file |
vm_manager::vmfile::parse_failed | KDL syntax error | Check VMFile.kdl syntax; see https://kdl.dev |
vm_manager::vmfile::validation | VMFile validation error | (custom hint per error) |
vm_manager::provision::failed | Provisioner step failed | Check provisioner config and VM SSH reachability |
vm_manager::io | General I/O error | (transparent) |
The library defines pub type Result<T> = std::result::Result<T, VmError> for convenience. CLI commands return miette::Result<()> for rich terminal output.
The vm-manager library can be used as a Rust dependency for building custom VM management tools.
[dependencies]
+vm-manager = { path = "crates/vm-manager" }
+# or from a git repository:
+# vm-manager = { git = "https://github.com/user/vm-manager.git" }
+The crate root re-exports the most commonly used types:
++#![allow(unused)] +fn main() { +use vm_manager::{ + // Hypervisor abstraction + Hypervisor, ConsoleEndpoint, RouterHypervisor, + // Error handling + VmError, Result, + // Core types + BackendTag, VmSpec, VmHandle, VmState, + NetworkConfig, CloudInitConfig, SshConfig, +}; +}
+use vm_manager::{RouterHypervisor, Hypervisor, VmSpec, NetworkConfig}; +use std::time::Duration; + +#[tokio::main] +async fn main() -> vm_manager::Result<()> { + // Create a hypervisor (platform-detected) + let hyp = RouterHypervisor::new(None, "rpool".into()); + + // Define a VM + let spec = VmSpec { + name: "example".into(), + image_path: "/path/to/image.qcow2".into(), + vcpus: 2, + memory_mb: 2048, + disk_gb: Some(20), + network: NetworkConfig::User, + cloud_init: None, + ssh: None, + }; + + // Lifecycle + let handle = hyp.prepare(&spec).await?; + let handle = hyp.start(&handle).await?; + + // ... use the VM ... + + hyp.stop(&handle, Duration::from_secs(30)).await?; + hyp.destroy(handle).await?; + + Ok(()) +}
| Feature | Effect |
|---|---|
pure-iso | Use pure-Rust ISO generation instead of genisoimage/mkisofs |
The Hypervisor trait is the core abstraction for VM lifecycle management. All backends implement it.
+#![allow(unused)] +fn main() { +pub trait Hypervisor: Send + Sync { + fn prepare(&self, spec: &VmSpec) -> impl Future<Output = Result<VmHandle>>; + fn start(&self, vm: &VmHandle) -> impl Future<Output = Result<VmHandle>>; + fn stop(&self, vm: &VmHandle, timeout: Duration) -> impl Future<Output = Result<VmHandle>>; + fn suspend(&self, vm: &VmHandle) -> impl Future<Output = Result<VmHandle>>; + fn resume(&self, vm: &VmHandle) -> impl Future<Output = Result<VmHandle>>; + fn destroy(&self, vm: VmHandle) -> impl Future<Output = Result<()>>; + fn state(&self, vm: &VmHandle) -> impl Future<Output = Result<VmState>>; + fn guest_ip(&self, vm: &VmHandle) -> impl Future<Output = Result<String>>; + fn console_endpoint(&self, vm: &VmHandle) -> Result<ConsoleEndpoint>; +} +}
Allocates resources for a VM based on the provided VmSpec. Creates the work directory, QCOW2 overlay, cloud-init ISO, and networking configuration. Returns a VmHandle in the Prepared state.
Boots the VM. Returns an updated VmHandle with runtime information (PID, VNC address, etc.).
Gracefully shuts down the VM. Tries ACPI power-down first, then force-kills after the timeout. Returns the handle in Stopped state.
Pauses and unpauses VM vCPUs without shutting down.
+Stops the VM (if running) and removes all associated resources. Takes ownership of the handle.
+Queries the current VM state by checking the process and QMP status.
+Discovers the guest's IP address. Method varies by network mode and backend.
+Returns the console connection details. Synchronous (not async).
++#![allow(unused)] +fn main() { +pub enum ConsoleEndpoint { + UnixSocket(PathBuf), // QEMU serial console + WebSocket(String), // Propolis console + None, // Noop backend +} +}
To add a new hypervisor backend:
+Hypervisor.RouterHypervisor with appropriate #[cfg] gates.BackendTag.RouterHypervisor's Hypervisor impl.All types are defined in crates/vm-manager/src/types.rs and re-exported from the crate root.
The input specification for creating a VM.
++#![allow(unused)] +fn main() { +pub struct VmSpec { + pub name: String, + pub image_path: PathBuf, + pub vcpus: u16, + pub memory_mb: u64, + pub disk_gb: Option<u32>, + pub network: NetworkConfig, + pub cloud_init: Option<CloudInitConfig>, + pub ssh: Option<SshConfig>, +} +}
A runtime handle to a managed VM. Serializable to JSON for persistence.
++#![allow(unused)] +fn main() { +pub struct VmHandle { + pub id: String, + pub name: String, + pub backend: BackendTag, + pub work_dir: PathBuf, + pub overlay_path: Option<PathBuf>, + pub seed_iso_path: Option<PathBuf>, + pub pid: Option<u32>, + pub qmp_socket: Option<PathBuf>, + pub console_socket: Option<PathBuf>, + pub vnc_addr: Option<String>, + pub vcpus: u16, // default: 1 + pub memory_mb: u64, // default: 1024 + pub disk_gb: Option<u32>, + pub network: NetworkConfig, + pub ssh_host_port: Option<u16>, + pub mac_addr: Option<String>, +} +}
All optional fields default to None and numeric fields have sensible defaults for backward-compatible deserialization.
+#![allow(unused)] +fn main() { +pub enum VmState { + Preparing, + Prepared, + Running, + Stopped, + Failed, + Destroyed, +} +}
Implements Display with lowercase names.
+#![allow(unused)] +fn main() { +pub enum NetworkConfig { + Tap { bridge: String }, + User, // default + Vnic { name: String }, + None, +} +}
Serialized with #[serde(tag = "type")] for clean JSON representation.
+#![allow(unused)] +fn main() { +pub struct CloudInitConfig { + pub user_data: Vec<u8>, + pub instance_id: Option<String>, + pub hostname: Option<String>, +} +}
user_data is the raw cloud-config YAML content.
+#![allow(unused)] +fn main() { +pub struct SshConfig { + pub user: String, + pub public_key: Option<String>, + pub private_key_path: Option<PathBuf>, + pub private_key_pem: Option<String>, +} +}
Supports both file-based keys (private_key_path) and in-memory keys (private_key_pem).
+#![allow(unused)] +fn main() { +pub enum BackendTag { + Noop, + Qemu, + Propolis, +} +}
Serialized as lowercase strings. Implements Display.
The image module handles downloading, caching, format detection, and overlay creation. Located in crates/vm-manager/src/image.rs.
+#![allow(unused)] +fn main() { +pub struct ImageManager { + client: reqwest::Client, + cache: PathBuf, // default: ~/.local/share/vmctl/images/ +} +}
+#![allow(unused)] +fn main() { +ImageManager::new() -> Self +}
Creates an ImageManager with the default cache directory.
++#![allow(unused)] +fn main() { +async fn download(&self, url: &str, destination: &Path) -> Result<()> +}
Downloads an image from a URL to a local path. Skips if the destination already exists. Auto-decompresses .zst/.zstd files. Logs progress every 5%.
+#![allow(unused)] +fn main() { +async fn pull(&self, url: &str, name: Option<&str>) -> Result<PathBuf> +}
Downloads an image to the cache directory and returns the cached path. If name is None, extracts the filename from the URL.
+#![allow(unused)] +fn main() { +fn list(&self) -> Result<Vec<CachedImage>> +}
Lists all images in the cache with their names, sizes, and paths.
++#![allow(unused)] +fn main() { +async fn detect_format(path: &Path) -> Result<String> +}
Runs qemu-img info --output=json and returns the format string (e.g., "qcow2", "raw").
+#![allow(unused)] +fn main() { +async fn create_overlay(base: &Path, overlay: &Path, size_gb: Option<u32>) -> Result<()> +}
Creates a QCOW2 overlay with the given base image as a backing file. Optionally resizes to size_gb.
+#![allow(unused)] +fn main() { +async fn convert(src: &Path, dst: &Path, format: &str) -> Result<()> +}
Converts an image between formats using qemu-img convert.
Located in crates/vm-manager/src/ssh.rs.
+#![allow(unused)] +fn main() { +pub fn connect(ip: &str, port: u16, config: &SshConfig) -> Result<Session> +}
Establishes an SSH connection and authenticates. Supports in-memory PEM keys and file-based keys.
++#![allow(unused)] +fn main() { +pub fn exec(sess: &Session, cmd: &str) -> Result<(String, String, i32)> +}
Executes a command and returns (stdout, stderr, exit_code).
+#![allow(unused)] +fn main() { +pub fn exec_streaming<W1: Write, W2: Write>( + sess: &Session, + cmd: &str, + stdout_writer: &mut W1, + stderr_writer: &mut W2, +) -> Result<(String, String, i32)> +}
Executes a command with real-time output streaming. Uses non-blocking I/O with 8KB buffers and 50ms polling interval. Both writes to the provided writers and collects the full output.
++#![allow(unused)] +fn main() { +pub fn upload(sess: &Session, local: &Path, remote: &str) -> Result<()> +}
Uploads a file via SFTP.
++#![allow(unused)] +fn main() { +pub async fn connect_with_retry( + ip: &str, + port: u16, + config: &SshConfig, + timeout: Duration, +) -> Result<Session> +}
Retries connection with exponential backoff (1s to 5s). Runs blocking SSH on tokio::task::spawn_blocking.
Located in crates/vm-manager/src/provision.rs.
+#![allow(unused)] +fn main() { +pub fn run_provisions( + sess: &Session, + provisions: &[ProvisionDef], + base_dir: &Path, + vm_name: &str, + log_dir: Option<&Path>, +) -> Result<()> +}
Runs all provisioners in sequence:
+exec_streaming./tmp/vmctl-provision-<step>.sh, makes it executable, runs it.Output is streamed to the terminal and appended to provision.log if log_dir is provided.
Aborts on the first non-zero exit code with VmError::ProvisionFailed.
The VMFile module parses and resolves VMFile.kdl configuration files. Located in crates/vm-manager/src/vmfile.rs.
+#![allow(unused)] +fn main() { +pub struct VmFile { + pub base_dir: PathBuf, + pub vms: Vec<VmDef>, +} +}
+#![allow(unused)] +fn main() { +pub struct VmDef { + pub name: String, + pub image: ImageSource, + pub vcpus: u16, + pub memory_mb: u64, + pub disk_gb: Option<u32>, + pub network: NetworkDef, + pub cloud_init: Option<CloudInitDef>, + pub ssh: Option<SshDef>, + pub provisions: Vec<ProvisionDef>, +} +}
+#![allow(unused)] +fn main() { +pub enum ImageSource { + Local(String), + Url(String), +} +}
+#![allow(unused)] +fn main() { +pub enum ProvisionDef { + Shell(ShellProvision), + File(FileProvision), +} + +pub struct ShellProvision { + pub inline: Option<String>, + pub script: Option<String>, +} + +pub struct FileProvision { + pub source: String, + pub destination: String, +} +}
+#![allow(unused)] +fn main() { +pub fn discover(explicit: Option<&Path>) -> Result<PathBuf> +}
Finds the VMFile. If explicit is provided, uses that path. Otherwise, looks for VMFile.kdl in the current directory.
+#![allow(unused)] +fn main() { +pub fn parse(path: &Path) -> Result<VmFile> +}
Parses a VMFile.kdl into a VmFile struct. Validates:
vm block.+#![allow(unused)] +fn main() { +pub async fn resolve(def: &VmDef, base_dir: &Path) -> Result<VmSpec> +}
Converts a VmDef into a VmSpec ready for the hypervisor:
base_dir.+#![allow(unused)] +fn main() { +pub fn expand_tilde(s: &str) -> PathBuf +}
Expands ~ to the user's home directory.
+#![allow(unused)] +fn main() { +pub fn resolve_path(raw: &str, base_dir: &Path) -> PathBuf +}
Expands tilde and makes relative paths absolute against base_dir.
+#![allow(unused)] +fn main() { +pub fn generate_ssh_keypair(vm_name: &str) -> Result<(String, String)> +}
Generates an Ed25519 keypair. Returns (public_key_openssh, private_key_pem).
vmctl can run inside a container for CI/CD pipelines or isolated environments. The key requirement is access to /dev/kvm.
FROM rust:1.85-bookworm AS builder
+
+WORKDIR /build
+COPY . .
+RUN cargo build --release -p vmctl --features vm-manager/pure-iso
+
+FROM debian:bookworm-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ qemu-system-x86 \
+ qemu-utils \
+ openssh-client \
+ && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /build/target/release/vmctl /usr/local/bin/vmctl
+
+ENV XDG_DATA_HOME=/data
+ENTRYPOINT ["vmctl"]
+The pure-iso feature eliminates the need for genisoimage in the container.
docker build -t vmctl .
+
+docker run --rm \
+ --device /dev/kvm \
+ -v vmctl-data:/data \
+ vmctl list
+The --device /dev/kvm flag passes through KVM access. No --privileged or special capabilities are needed for user-mode networking.
For TAP networking, you'll need --cap-add NET_ADMIN and appropriate bridge configuration.
podman build -t vmctl .
+
+podman run --rm \
+ --device /dev/kvm \
+ -v vmctl-data:/data \
+ vmctl list
+Podman works identically for user-mode networking.
+Mount a volume at the XDG_DATA_HOME path (/data in the Dockerfile above) to persist VM state and cached images across container runs.
Mount your project directory to use VMFile.kdl:
+docker run --rm \
+ --device /dev/kvm \
+ -v vmctl-data:/data \
+ -v $(pwd):/workspace \
+ -w /workspace \
+ vmctl up
+TAP networking gives VMs a real presence on a host network, with full Layer 2 connectivity.
+# Create bridge
+sudo ip link add br0 type bridge
+sudo ip link set br0 up
+
+# Assign an IP to the bridge (optional, for host-to-guest communication)
+sudo ip addr add 10.0.0.1/24 dev br0
+Provide IP addresses to guests:
+sudo dnsmasq \
+ --interface=br0 \
+ --bind-interfaces \
+ --dhcp-range=10.0.0.100,10.0.0.200,12h \
+ --no-daemon
+If you want guests to reach the internet:
+# Enable forwarding
+sudo sysctl -w net.ipv4.ip_forward=1
+
+# NAT outbound traffic
+sudo iptables -t nat -A POSTROUTING -s 10.0.0.0/24 ! -o br0 -j MASQUERADE
+vmctl create --name myvm --image ./image.qcow2 --bridge br0
+vm "myvm" {
+ image "image.qcow2"
+
+ network "tap" {
+ bridge "br0"
+ }
+
+ cloud-init {
+ hostname "myvm"
+ }
+
+ ssh {
+ user "ubuntu"
+ }
+}
+vmctl discovers TAP-networked guest IPs by:
+ip neigh show) for the guest's MAC address on the bridge.This happens automatically when you run vmctl ssh or provisioners.
vmctl includes experimental support for running VMs on illumos using the Propolis hypervisor (bhyve-based).
+propolis-server installed and runnablerpool)nebula-vm zone brand installedThe Propolis backend manages VMs as illumos zones:
+{pool}/images/{vm}@latest to {pool}/vms/{vm}.zoneadm -z {vm} boot, waits for propolis-server on 127.0.0.1:12400, then sends the instance spec and run command via REST API.zoneadm uninstall -F), deletes the zone config (zonecfg delete -F), and destroys the ZFS dataset.Uses illumos VNICs for exclusive-IP zone networking:
+network "vnic" {
+ name "vnic0"
+}
+cargo build --release -p vmctl --target x86_64-unknown-illumos
+For advanced guest configuration, you can provide a complete cloud-config YAML file instead of using vmctl's built-in cloud-init generation.
+vm "custom" {
+ image-url "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
+
+ cloud-init {
+ user-data "cloud-config.yaml"
+ }
+}
+#cloud-config
+users:
+ - name: deploy
+ groups: sudo
+ shell: /bin/bash
+ sudo: ALL=(ALL) NOPASSWD:ALL
+ ssh_authorized_keys:
+ - ssh-ed25519 AAAA... your-key
+
+package_update: true
+packages:
+ - nginx
+ - certbot
+ - python3-certbot-nginx
+
+write_files:
+ - path: /etc/nginx/sites-available/default
+ content: |
+ server {
+ listen 80;
+ server_name _;
+ root /var/www/html;
+ }
+
+runcmd:
+ - systemctl enable nginx
+ - systemctl start nginx
+
+growpart:
+ mode: auto
+ devices: ["/"]
+By default, vmctl generates the NoCloud seed ISO by shelling out to genisoimage or mkisofs. If neither is available, you can build with the pure-iso feature:
cargo build --release -p vmctl --features vm-manager/pure-iso
+This uses the isobemak crate to generate ISO 9660 images entirely in Rust.
When you don't provide raw user-data, vmctl generates a cloud-config that:
+authorized_keys.hostname field or VM name).instance-id in the metadata.If you need more control than this, use raw user-data.
+vmctl uses the tracing crate with RUST_LOG environment variable support:
# Default (info level)
+vmctl up
+
+# Debug logging
+RUST_LOG=debug vmctl up
+
+# Trace logging (very verbose)
+RUST_LOG=trace vmctl up
+
+# Target specific modules
+RUST_LOG=vm_manager::ssh=debug vmctl ssh myvm
+The serial console output is captured to console.log in the VM's work directory. This includes boot messages and cloud-init output:
vmctl log myvm --console
+Provisioner stdout/stderr is captured to provision.log:
vmctl log myvm --provision
+vmctl log myvm --console --tail 50
+Each VM's files are in ~/.local/share/vmctl/vms/<name>/:
ls ~/.local/share/vmctl/vms/myvm/
+Contents:
+overlay.qcow2 - Disk overlayseed.iso - Cloud-init ISOconsole.log - Serial outputprovision.log - Provisioner outputqmp.sock - QMP control socketconsole.sock - Console socketpidfile - QEMU PIDid_ed25519_generated - Auto-generated SSH keyid_ed25519_generated.pub - Public keyYou can interact with the QEMU Machine Protocol directly for advanced debugging:
+# Using socat
+socat - UNIX-CONNECT:~/.local/share/vmctl/vms/myvm/qmp.sock
+After connecting, send {"execute": "qmp_capabilities"} to initialize, then commands like:
{"execute": "query-status"}
+{"execute": "query-vnc"}
+{"execute": "human-monitor-command", "arguments": {"command-line": "info network"}}
+qemu-system-x86_64 is in your PATH./dev/kvm exists and is accessible.kvm group.genisoimage or mkisofs.--features vm-manager/pure-iso.vmctl log myvm --consolevmctl status myvm for SSH port).ssh -p <port> -i <key> user@127.0.0.1ip neigh show for the guest's MAC address.vmctl status myvm for the PID.kill -0 <pid> - if the process is alive, the QMP socket may be stale.vmctl destroy myvm.