This is an opionated repo that can be used to provision a fleet of VMs on a linux host machine using libvirt.
- Step 1 : Make sure that the Linux host has been setup as defined SETUP.md
- You might want to run the doctor script to check if the host and the environment variables have been set up properly.
- Step 2 : Use the Lifecycle scripts to create and manage the virtual machines
The linux host machine should have various software and environment (system level) setup for the repo to work
- Libvirt related setup : SETUP.md
- Cockpit for web based gui
- Libvirt should be setup in a way that the following directories should be setup as storage pools
export SANDBOX_HOME="${SANDBOX_HOME:-$HOME/projects}"
export LIBVIRT_HOME="${STORAGE_POOL_HOME:-$SANDBOX_HOME/libvirt}"
export STORAGE_POOL_IMAGES="${LIBVIRT_HOME}/images"
export STORAGE_POOL_ISOS="${LIBVIRT_HOME}/isos"
export STORAGE_POOL_DISKS="${LIBVIRT_HOME}/disks"
export STORAGE_POOL_SNAPSHOTS="${LIBVIRT_HOME}/snapshots"
export STORAGE_POOL_CLOUD_INIT_ISOS="${LIBVIRT_HOME}/cloud-init"
export DEFAULT_CLOUD_IMG="noble-server-cloudimg-amd64"
Storage pools
- `images/` → pool `default` — read-only golden cloud `.img` files. Never modify the base image directly; VMs are qcow2 overlays.
- `isos/` → pool `iso-pool` — reserved for installer ISOs, currently unused (cloud-image flow only).
- `disks/` → pool `disk-pool` — flat, per-VM `<vmname>.qcow2` + `<vmname>.state.yaml`.
- `snapshots/` → pool `snapshot-pool` — reserved for *external* snapshots; currently unused (internal qcow2 snapshots were chosen instead — don't build external-snapshot logic without revisiting this decision).
- `cloud-init/` → pool `cloudinit-pool` — generated seed ISOs `<vmname>-seed.iso`.
Each VM would have a yaml file that would contain details of the VM. The same yaml files are used to check if there is already existing VM with the same name (during initialisation). The libvirt folder on the host would look broadly something like the following :-
├── libvirt
│ ├── cloud-init
│ │ ├── vir-testing-001-seed.iso
│ │ └── vir-testing-002-seed.iso
│ ├── disks
│ │ ├── vir-testing-001.qcow2
│ │ ├── vir-testing-001.state.yaml
│ │ ├── vir-testing-002.qcow2
│ │ └── vir-testing-002.state.yaml
│ ├── images
│ │ └── noble-server-cloudimg-amd64.img
│ ├── isos
│ └── snapshots
- Copy
env.sampleto.envin the repo root and uncomment/edit whatever you want to override:cp env.sample .env - Environment variables are resolved with the following precedence, lowest to highest:
- System-level environment variables (see above)
.envin the repo root, if present -- overrides #1- Parameters passed to a script (e.g.
--ramon00_init_vm.sh), or the value entered at a prompt in-i/--interactivemode -- overrides both #1 and #2
.envis gitignored, so host- or checkout-specific overrides never get committedscripts/lib/common.shloads.envautomatically (every script sourcescommon.sh); nothing else to run
- Two tiers: VM/fleet scripts (create, run, and manage individual VMs or the whole fleet) and host-administration scripts (set up and manage the Linux host itself). See lifecycle_vms.md and lifecycle_host.md for the full contract of each script. Every VM-tier script (and
84in the host tier) also accepts-h/--helpfor its own flag reference. - All scripts live in
scripts/and are run from the repo root (e.g../scripts/00_init_vm.sh myvm). Shared helpers for the VM tier are inscripts/lib/common.sh. - Scripts that support both a fire-and-forget mode and a prompted/confirmed mode take a single
-i/--interactiveflag rather than being split into separate files -- see below.
# For a paricular VM
- `scripts/00_init_vm.sh <vmname> [-i|--interactive] [options]`
# Without -i: flag/env-driven -- RAM, CPU, disk size etc. all have defaults, override with flags
# With -i: prompts for any field not passed as a flag, showing the resolved default
- `scripts/01_start_vm.sh` # Starts the VM
- `scripts/02_stop_vm.sh`
- `scripts/03_reboot_vm.sh`
- `scripts/04_destroy_vm.sh`
- `scripts/05_status_vm.sh` # Gives the status and info
- `scripts/06_doctor_vm.sh <vmname>` # Per-VM diagnostics: libvirt/state consistency + guest Tailscale/UFW/Docker/cloud-init
- `scripts/11_configure_vm.sh <vmname> [-i|--interactive] [options]` # Docker, Tailscale, UFW
# Without -i: fire-and-forget -- runs every step unconditionally, no prompts
# With -i: confirms before each step, streams output live
- `scripts/12_resize_vm.sh <vmname> [-i|--interactive] [options]` # CPUs, RAM, disk, autostart
# Without -i: only the fields you pass change, no prompts
# With -i: shows current config, prompts for any field not passed as a flag, confirms once
- Snapshots (not yet built, see PLAN.md Phase 6)
- `scripts/21_snapshot_vm.sh`
- `scripts/22_restore_vm.sh`
# Testing setups
- `scripts/09_doctor_host.sh` # Host-level diagnostic tests
- `scripts/08_test.sh` # End-to-end smoke test: doctor -> init -> lifecycle -> destroy, against ephemeral test VMs
# Managing multiple VMs (Managing the fleet)
- `scripts/50_list_vms.sh` # Will list all the vms and their statuses
- `scripts/51_info_vms.sh` # Dumps full state.yaml detail for every VM (no vmname arg)
Set up and manage the Linux host itself, not any individual VM -- see lifecycle_host.md for the full contract, including a "Common Usage Patterns" section. Numbered 80+, no vmname arg, most require sudo (unlike the VM-tier scripts above).
- `scripts/80_host_check_specs.sh` # Read-only: KVM support, CPU/RAM/disk/network specs
- `scripts/81_host_setup_initial_dependencies.sh` # Installs packages, yq, joins libvirt/kvm groups
- `scripts/82_host_setup_bootstrap_script.sh` # Installs /etc/profile.d/sandbox.sh
- `scripts/83_host_configure_libvirt_storage_pools.sh` # Defines/starts the 5 libvirt storage pools (idempotent)
- `scripts/84_host_change_libvirt_storage_pools.sh <path>` # Moves LIBVIRT_HOME + all managed VMs to a new location
- `scripts/85_host_check_libvirt_config.sh` # Read-only: env vars, tool versions, pool/net/domain list
- Naming convention of virtual machines :
vir-ubuntu-01and then additional numbers. The name should always suggest that it is a virtual machine
- Usage
- Linux host setup
- VM/fleet lifecycle scripts : Note that this contains a "Common Usage Patterns" section and also details all the VM/fleet scripts.
- Host administration scripts : Also has its own "Common Usage Patterns" section, covering host bootstrap and storage-pool setup/migration.
- Development
- Implmentation Plan, Roadmap and Implentation Logs : Mentions the various additional things that I can implement in this repo
- Design Decisions and Policies
- Additional Documentation