KVM in Practice | Stop Reinstalling: Build a Golden Base Image for KVM/QEMU VMs
Motivation
When working across multiple development environments, installing and configuring each VM from scratch is wasteful. A *golden-image* is a pre-configured, sealed VM disk that serves as the starting point for every new VM. It holds common setups such as SSH server, GPG public keys, RDP server, and core tools—e.g. tmux, git, etc.
The key requirements for VM-based developments are:
- The *guest* should survive host OS reinstallation (no dependency on libvirt state)
- The *guest* should be portable with minimal dependencies—a single `.qcow2` file, no backing chains
- New VMs should be fast to clone—ready in under a minute
Architecture
The golden image is a single `.qcow2` file that is never booted directly once created. Instead, it is cloned via `qemu-img convert` to create fully independent disk images for each new VM:
golden-ubuntu2404-base.qcow2 <- sealed, never booted again | +-- vm-project-a.qcow2 <- full independent clone +-- vm-project-b.qcow2 <- full independent clone
Method
Phase 1: Build the Golden Image
First, install Ubuntu 24.04 LTS (I personally prefer Xubuntu 24.04 *Minimal* [1], which is a sweet spot between the GUI function-rich GNOME desktop version and a headless Ubuntu Server) via CLI `virt-install` or GUI virt-manager, remember to set the firmware to UEFI (OVMF) for better future-proofing. Boot it and install the core tools:
sudo apt update
sudo apt install -y \
openssh-server \
tmux \
git \
xrdp \
curl
Then, configure the SSH server—`sudo nano /etc/ssh/sshd_config` and append the following line:
StreamLocalBindUnlink yes
This enables automatic removal of stale Unix socket files when a new connection is made. Without it, socket files accumulate on the remote host and must be cleared manually before an agent-forwarded connection can be established [2]. Enable and start the SSH server by running:
sudo systemctl enable ssh sudo systemctl start ssh
Next, configure the RDP server (xrdp) for optional GUI access [3]. xrdp encrypts RDP sessions using TLS and needs to read the SSL private key (`ssl-cert-snakeoil.key`), which on Ubuntu is readable only by root and the `ssl-cert` group. Add the xrdp user to that group so it can open its TLS listener socket:
sudo adduser xrdp ssl-cert
If you installed a desktop version of Ubuntu, xrdp will automatically use the existing desktop session. Enable and start the xrdp service:
sudo systemctl enable xrdp sudo systemctl start xrdp
Finally, configure your most commonly used tools, e.g. tmux, git, etc. per your preferences. You may also want to add your GPG public keys to the image so that any new VM can immediately use them for git commit signing, etc. (given agent forwarding is working).
Optionally, create a `system-card.txt` file in the home directory to document the installed software and configurations for future reference.
Phase 2: Seal the Golden Image
Inside the VM, clean up before shutdown:
# Clean up package caches sudo apt autoremove -y && sudo apt clean # Reset machine-id so each clone gets a unique identity sudo truncate -s 0 /etc/machine-id # Validate everything is clean before sealing systemctl --failed # must be empty systemctl status ssh # must be active (running) systemctl status xrdp # must be active (running) history -c && sudo shutdown now
After VM guest shutdown, on the host, store the image safely:
# Undefine the VM sudo virsh undefine vm-ubuntu2404-base --nvram # Move the base image to external storage (e.g. NAS, USB drive, etc.) sudo mv \ /var/lib/libvirt/images/vm-ubuntu2404-base.qcow2 \ /mnt/datastore/cabinet/vm-guest-img/ # Protect against accidental writes sudo chown root:root /mnt/datastore/cabinet/vm-guest-img/vm-ubuntu2404-base.qcow2 sudo chmod 400 /mnt/datastore/cabinet/vm-guest-img/vm-ubuntu2404-base.qcow2
Phase 3: Clone and Launch a New VM
When you need a new VM, first clone from the golden image:
# Full clone --- completely independent, no backing chain
sudo qemu-img convert -O qcow2 \
/mnt/datastore/cabinet/vm-guest-img/vm-ubuntu2404-base.qcow2 \
/var/lib/libvirt/images/vm-new-project.qcow2
Do basic preparations for the new image:
# Set proper ownership for libvirt sudo chown libvirt-qemu:kvm /var/lib/libvirt/images/vm-new-project.qcow2 # Optional: Increase disk size sudo qemu-img resize /var/lib/libvirt/images/vm-new-project.qcow2 64G
Define and start the VM:
virt-install \
--name vm-new-project \
--import \
--disk path=/var/lib/libvirt/images/vm-new-project.qcow2,format=qcow2 \
--os-variant ubuntu24.04 \
--ram 8192 --vcpus 4 \
--boot uefi \
--network bridge=br0 \
--video virtio,accel3d=no \
--graphics spice \
--noautoconsole
Note some key flags:
- `--import` skips the OS installer entirely
- `--boot uefi` is required if the golden image was installed with UEFI firmware (OVMF)
- `--network bridge=br0` connects the VM to the same network as the host for easy SSH/RDP access; adjust as needed for your network setup
Phase 4: Post-Clone Setup
After the VM starts, set a unique hostname to avoid conflicts on the network:
sudo hostnamectl set-hostname vm-new-project
Optionally, resize the root partition to use the full disk if you increased the disk size in Phase 3:
# Use `lsblk` to identify the root partition (e.g. /dev/vda2) sudo growpart /dev/vda 2 sudo resize2fs /dev/vda2
Optionally, regenerate SSH host keys, especially if you want to ensure each VM has unique host keys:
sudo ssh-keygen -A sudo systemctl restart ssh
Restart the VM to ensure all changes take effect.
References
- [Xubuntu official site](https://xubuntu.org/)
- [Arch Linux Wiki: GnuPG](https://wiki.archlinux.org/title/GnuPG)
- [Install and configure xrdp to use Remote Desktop with Ubuntu](https://docs.azure.cn/en-us/virtual-machines/linux/use-remote-desktop?tabs=azure-cli)