unixshells/clone

Purpose and Entry Points

Clone is a Linux/KVM virtual-machine monitor optimized for high-density, isolated workloads. It cold-boots templates, snapshots them, then forks copy-on-write VM instances using Shadow Clone memory mappings. The primary CLI and single-binary entry point is src/main.rs; VM runtime orchestration begins in src/vmm/mod.rs. Supporting in-guest binaries are crates/guest-agent/src/main.rs and crates/clone-init/src/main.rs.

VM Boot and Hardware Model

The VMM constructs guest memory, KVM state, vCPU threads, MMIO devices, serial I/O, and lifecycle state in src/vmm/mod.rs, src/vmm/vcpu.rs, and src/vmm/serial.rs. Boot preparation loads kernel/initrd images, builds guest page tables and ACPI metadata, and optionally verifies measured boot hashes through src/boot/mod.rs, src/boot/acpi.rs, and src/boot/measured.rs.

Snapshot, Shadow Fork, and Migration

Template snapshots capture memory and CPU/register state; forked VMs map snapshot memory privately so pages diverge only on write. Template identity and fork-specific guest state are handled by src/boot/template.rs and src/boot/identity.rs, with lifecycle coordination in src/vmm/mod.rs. Pre-copy live migration transfers memory and final CPU state over TCP in src/migration/mod.rs, separating source and receiver command paths exposed by the CLI/control layer.

Memory Efficiency

Guest memory management combines sparse/overcommitted allocation, cross-VM KSM eligibility, split regions around x86 PCI MMIO space, and virtio-balloon reclamation. These mechanisms reside in src/memory/mod.rs, src/memory/overcommit.rs, and src/memory/balloon.rs; guest-facing balloon transport is src/virtio/balloon.rs. This is the central boundary between guest-visible RAM and host physical-memory consumption.

Devices, Storage, and Host Integration

Virtio transports provide block, networking, filesystem sharing, vsock, and balloon devices through src/virtio/mod.rs, src/virtio/mmio.rs, and src/virtio/queue.rs. Backends include raw/qcow2 disks in src/storage/mod.rs and src/storage/qcow2.rs, TAP/bridge/NAT host networking in src/net/mod.rs, and inline virtio-fs in src/virtio/fs.rs. PCI ECAM and VFIO passthrough are implemented in src/pci/mod.rs and src/pci/vfio.rs, requiring host devices bound to vfio-pci.

Control Plane and Guest Communication

The CLI supports direct per-VM operation and a multi-VM daemon. Unix-socket protocol, daemon orchestration, synchronization server, metrics, and optional jailer are grouped in src/control/protocol.rs, src/control/daemon.rs, and src/control/jailer.rs. Host-to-guest exec, heartbeat, shutdown, and post-fork recovery cross userspace vsock via src/vmm/agent_listener.rs, src/virtio/vsock.rs, and crates/guest-agent/src/main.rs.

Root Filesystems and Runtime Boundaries

src/rootfs.rs creates boot plumbing for disk-rootfs mode, including the minimal init and agent; src/rootfs_create.rs builds/imports Alpine, Ubuntu, Debian, and Docker-derived images. The VMM runs on Linux with /dev/kvm; networking needs /dev/net/tun, while KVM, Linux memory APIs, namespaces/capabilities, seccomp BPF, and VFIO are material host-kernel dependencies. The project intentionally has no libvirt, QEMU, or external virtiofs daemon dependency.