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

  1. [Xubuntu official site](https://xubuntu.org/)
  2. [Arch Linux Wiki: GnuPG](https://wiki.archlinux.org/title/GnuPG)
  3. [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)