Skip to content

This is the multi-page printable view of this section. .

Return to the regular view of this page.

Documentation

Learn how to define and manage KVM virtual machines with ansible-vms.

Complete guide to defining and managing KVM virtual machines with Ansible and libvirt.

1 - Getting Started

Install dependencies and create your first KVM virtual machine.

Requirements

  • Host OS: Debian 12 (Bookworm)
  • Packages: qemu-kvm, libvirt-daemon-system, libvirt-clients, ovmf, swtpm

Installation

# Clone the repository
git clone https://github.com/mars-base/ansible-vms.git
cd ansible-vms

# Install Python dependencies
uv sync  # or: pip install -r requirements.txt

# Setup configuration files
cp ansible.cfg.example ansible.cfg  # edit with your host name
cp hosts.ini.example hosts.ini      # edit with your host name
cp vms.csv.example vms.csv          # edit with your VM definitions

Quick Start

# Install required packages on KVM host
uv run ansible-playbook playbooks/install-dependencies.yaml

# Create VMs defined in vms.csv
uv run ansible-playbook playbooks/create-vm.yaml

Project Structure

ansible-vms/
├── ansible.cfg.example          # Ansible config template
├── hosts.ini.example            # Inventory template
├── vms.csv                      # VM definitions (CSV-driven)
├── pyproject.toml               # Python dependencies (uv)
├── requirements.txt             # pip dependencies
├── group_vars/
│   ├── all/                     # Global variables
│   └── kvm_hosts/               # KVM host variables
├── host_vars/                   # Per-host variables
├── playbooks/
│   ├── create-vm.yaml           # Create VMs from vms.csv
│   ├── destroy-vm.yaml          # Destroy VMs
│   ├── list-vms.yaml            # List VMs
│   ├── snapshot-vm.yaml         # Manage VM snapshots
│   ├── setup-user.yaml          # Setup user accounts on Linux VMs
│   ├── start-vm.yaml            # Start VMs
│   ├── stop-vm.yaml             # Stop VMs
│   └── restart-vm.yaml          # Restart VMs
├── roles/
│   └── create_vm/               # VM creation role (libvirt XML)
├── scripts/                     # Helper scripts
├── tools/                       # Utility scripts (vm-console, vm-login)
└── var/                         # Runtime data (logs, facts cache)

Next Steps

2 - VM Definition (vms.csv)

Configure virtual machines as rows in vms.csv.

VMs are defined in vms.csv file. Each row represents a VM with the following fields:

Field Description Example
name VM name win11-dev
host KVM host (inventory name) local
type OS type: windows / linux / macos windows
memory_mb Memory in MB 8192
vcpus CPU cores 4
os OS variant win11
disk_gb System disk size 80
data_disk_gb Data disk size (0 for none) 10
base_image Base qcow2 image path /path/to/base.qcow2
bridge Network bridge br0
mac MAC address 52:54:00:xx:xx:xx
firmware efi or empty (BIOS) efi
autostart Auto-start on boot (default: false) true
storage_dir VM storage path (optional, default: /var/lib/libvirt/images) /data/vms
ip Static IP address (optional, empty = DHCP). Linux: applied via cloud-init at create; macOS: applied later via configure-macos-network.yaml, see macOS VMs 192.168.1.100
netmask Subnet CIDR (optional, default: 22) 24
gateway Default gateway (required if ip is set) 192.168.1.1
dns DNS servers, comma-separated (required if ip is set) 8.8.8.8,8.8.4.4

Example vms.csv

name,host,type,memory_mb,vcpus,os,disk_gb,data_disk_gb,base_image,bridge,mac,firmware,autostart,storage_dir,ip,netmask,gateway,dns
win11-dev,local,windows,8192,4,win11,80,10,/home/user/images/win11-base.qcow2,br0,52:54:00:12:34:56,efi,true,/var/lib/libvirt/images,,,,
debian12-dev,local,linux,2048,2,debian12,20,0,/home/user/images/debian-12.qcow2,br0,52:54:00:12:34:57,,true,/var/lib/libvirt/images,192.168.1.100,24,192.168.1.1,"8.8.8.8,8.8.4.4"

Key Points

  • MAC addresses: Each VM needs a unique MAC address for stable DHCP leases
  • Autostart: Only debian12-01 is configured with autostart=true (starts on host boot)
  • Storage: VMs can use custom storage paths or default /var/lib/libvirt/images
  • Static IP: Linux VMs via cloud-init; macOS VMs via configure-macos-network.yaml over SSH (no cloud-init on macOS) — see macOS VMs
  • Idempotent: The create-vm playbook checks if VM exists before creating, safe to run multiple times

3 - VM Lifecycle

List, start, stop, restart, and destroy virtual machines.

All playbooks are idempotent (safe to run multiple times).

List VMs

# List all VMs with status and IP
uv run ansible-playbook playbooks/list-vms.yaml

Output example:

win11-dev            192.168.1.101   windows  4 vCPU 8192 MB    win11  shut off
win10-dev            192.168.1.102   windows  4 vCPU 8192 MB    win10  running
debian12-dev         192.168.1.103   linux    2 vCPU 2048 MB    debian12 running

Start VM

# Start specific VM
uv run ansible-playbook playbooks/start-vm.yaml -e vm_name=debian12-dev

Stop VM

# Graceful shutdown
uv run ansible-playbook playbooks/stop-vm.yaml -e vm_name=win11-dev

Uses virsh shutdown which sends ACPI shutdown signal. For Windows VMs with QEMU guest agent configured, this triggers a clean shutdown.

Restart VM

# Stop then start VM
uv run ansible-playbook playbooks/restart-vm.yaml -e vm_name=debian12-dev

Destroy VM

# Permanently delete VM (requires confirmation)
uv run ansible-playbook playbooks/destroy-vm.yaml -e vm_name=win11-dev -e confirm=true

Deletes: domain definition, disk images (qcow2), OVMF VARS, cloud-init ISO, TPM state.

Warning: This is destructive and irreversible. The confirm=true flag is required.

4 - Base Images

Download Linux, Windows and macOS base images for VMs.

Linux Base Images

The Linux VMs use official cloud images pre-configured with cloud-init support.

Debian

Download the latest Debian 12 (Bookworm) image:

wget -O debian-12-genericcloud-amd64.qcow2 \
  https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2

Alternative versions: Browse https://cloud.debian.org/images/cloud/ for bookworm, bullseye, trixie, etc.

Ubuntu

Download the latest Ubuntu 24.04 LTS (Noble) image:

wget -O ubuntu-24.04-server-cloudimg-amd64.img \
  https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img

Download the latest Ubuntu 26.04 LTS (Resolute) image:

wget -O ubuntu-26.04-server-cloudimg-amd64.img \
  https://cloud-images.ubuntu.com/resolute/current/resolute-server-cloudimg-amd64.img

Important: Ubuntu cloud images require the virtio network driver. The VM templates in this project already use virtio, so no additional configuration is needed.

Note: Always verify the downloaded image checksum against the official SHA256SUMS file to avoid corrupted images causing boot failures.

Alternative versions: Browse https://cloud-images.ubuntu.com/ for other Ubuntu releases.

Fedora

Download the latest Fedora 44 Cloud Base image:

wget -O Fedora-Cloud-Base-Generic-44-1.7.x86_64.qcow2 \
  https://download.fedoraproject.org/pub/fedora/linux/releases/44/Cloud/x86_64/images/Fedora-Cloud-Base-Generic-44-1.7.x86_64.qcow2

Note: Fedora uses wheel group for sudo privileges (not sudo). The setup-user playbook automatically detects this and uses the correct group.

Alternative versions: Browse https://fedoraproject.org/cloud/download/ for other Fedora releases.

Rocky Linux

Download the latest Rocky Linux 10 Cloud Base image:

wget -O Rocky-10-GenericCloud-Base.latest.x86_64.qcow2 \
  https://dl.rockylinux.org/pub/rocky/10/images/x86_64/Rocky-10-GenericCloud-Base.latest.x86_64.qcow2

Note: Rocky Linux uses wheel group for sudo privileges (same as RHEL/CentOS). The setup-user playbook automatically detects this and uses the correct group.

Alternative versions: Browse https://rockylinux.org/download for other Rocky Linux releases.

Configuration

Set the image path in vms.csv base_image field:

# Debian
my-debian-vm,local,linux,...,/path/to/debian-12-genericcloud-amd64.qcow2,...

# Ubuntu
my-ubuntu-vm,local,linux,...,/path/to/ubuntu-24.04-server-cloudimg-amd64.img,...

# Fedora
my-fedora-vm,local,linux,...,/path/to/Fedora-Cloud-Base-Generic-44-1.7.x86_64.qcow2,...

# Rocky Linux
my-rocky-vm,local,linux,...,/path/to/Rocky-10-GenericCloud-Base.latest.x86_64.qcow2,...

The image is automatically configured via cloud-init on first boot (SSH keys, user, packages, etc. from group_vars/kvm_hosts/vms_all.yaml).

Windows Base Image

The Windows qcow2 base image is built with packer-windows-kubevirt. It uses Packer + QEMU to produce a sysprep-generalized Windows image with:

  • virtio drivers pre-installed (vioscsi, viostor, netkvm, vioserial, viorng, balloon, viofs)
  • QEMU Guest Agent + Cloudbase-Init
  • WinRM HTTPS (port 5986) + RDP (port 3389) enabled
  • EFI boot with secure boot keys

Build your own custom image:

git clone https://github.com/mars-base/packer-windows-kubevirt
cd packer-windows-kubevirt
packer build <template>

Then set the output path in vms.csv base_image field.

Windows VM Features

When type=windows, the domain XML template includes:

  • Hyper-V enlightenments (relaxed, vapic, spinlocks, synic, stimer, etc.) for nested WSL2
  • VMX passthrough for nested virtualization (WSL2/Hyper-V inside guest)
  • EFI + vTPM 2.0 (OVMF secure boot + emulated TPM)
  • virtio-scsi disk bus + virtio NIC
  • Localtime clock with hypervclock

macOS Base Image

macOS guests use a self-contained qcow2 base image built by hand on the KVM host with OSX-KVM. Unlike the Linux and Windows images, it is neither downloaded nor built with Packer:

  • macOS Sonoma 14.8.9 (x86_64), 4 vCPU / 8 GB, account admin / admin, Remote Login enabled
  • OpenCore boot disk + blessed OVMF NVRAM template for keyboard-free cold boot
  • 64 GiB virtual size, ~29 GiB actual usage, no backing file — ready to be used as a backing image

Each macOS VM gets its own system-disk overlay backed by macos-sonoma-base.img, an OpenCore overlay and a per-VM copy of the blessed OVMF VARS file. Set the image path in the vms.csv base_image field.

The full build walkthrough (installer download, bless, NVRAM validation, image conversion) is in macOS Base Image.

5 - Network

Bridge networking, DHCP, and static IP configuration for VMs.

VMs connect to the local network via a bridge (default br0). Two IP assignment modes are supported:

DHCP Mode (default)

When ip field is empty, VMs receive IP addresses from the LAN’s DHCP server — same subnet as the host.

LAN (192.168.1.0/24, DHCP, gateway 192.168.1.1)
├── KVM Host (192.168.1.100, br0)
└── VM (192.168.1.x, DHCP via br0, virtio NIC)

Each VM is assigned a pinned MAC address in vms.csv, so its DHCP lease is stable. To look up a VM’s IP:

ip neigh show dev br0 | grep -i <MAC>

Or use the list-vms playbook which does this automatically.

Static IP Mode (Linux VMs)

For Linux VMs, you can configure static IP addresses by filling in the ip, netmask, gateway, and dns fields in vms.csv.

LAN (192.168.1.0/24, DHCP, gateway 192.168.1.1)
├── KVM Host (192.168.1.100, br0)
└── VM (192.168.1.150, static IP, virtio NIC)

Example vms.csv configuration

name,host,type,memory_mb,vcpus,os,disk_gb,data_disk_gb,base_image,bridge,mac,firmware,autostart,storage_dir,ip,netmask,gateway,dns
web-server,local,linux,4096,2,debian12,40,100,/path/to/debian-12.qcow2,br0,52:54:00:aa:bb:cc,,true,/var/lib/libvirt/images,192.168.1.150,24,192.168.1.1,"8.8.8.8,1.1.1.1"

Notes

  • Static IP configuration only works for Linux VMs (cloud-init network-config)
  • Windows VMs do not support static IP configuration through this method
  • When ip is empty or omitted, the VM will use DHCP (default behavior)
  • The IP address is permanent and persists across reboots
  • Ensure the static IP is outside the DHCP pool to avoid conflicts

Generated network configuration

Cloud-init will generate a netplan configuration at /etc/netplan/50-cloud-init.yaml:

network:
  version: 2
  ethernets:
    ens3:
      addresses:
      - 192.168.1.150/24
      routes:
      - to: default
        via: 192.168.1.1
      nameservers:
        addresses:
        - 8.8.8.8
        - 1.1.1.1

Verification

After VM creation, verify the static IP is active:

# Check IP address
ssh root@192.168.1.150 "ip addr show ens3 | grep inet"

# Check gateway
ssh root@192.168.1.150 "ip route | grep default"

# Check DNS
ssh root@192.168.1.150 "grep nameserver /etc/resolv.conf"

Bridge Configuration

The KVM host requires a network bridge (br0) so VMs can access the LAN directly. Pick the method matching the host’s network manager: nmcli if NetworkManager is active (most desktops), ifupdown for classic server configs. Check with systemctl is-active NetworkManager.

Method 1: nmcli (NetworkManager)

First find the current connection profile, its IP config, and the NIC to bridge:

nmcli -f NAME,DEVICE,TYPE,STATE connection show
nmcli -f ipv4.method,ipv4.addresses,ipv4.gateway,ipv4.dns connection show "<existing profile name>"

Create the bridge carrying the same static IP (or use ipv4.method auto for DHCP on br0), then attach the NIC as a bridge port, then disable the old profile so it doesn’t reclaim the NIC:

# 1. Create bridge br0 with the host's IP config
sudo nmcli connection add type bridge ifname br0 con-name br0 \
    ipv4.method manual ipv4.addresses 192.168.1.100/24 \
    ipv4.gateway 192.168.1.1 ipv4.dns 192.168.1.1 \
    bridge.stp no

# 2. Attach the physical NIC as a bridge port
sudo nmcli connection add type bridge-slave ifname eth0 con-name br0-port-eth0 master br0

# 3. Stop the old profile from auto-activating
sudo nmcli connection modify "<existing profile name>" connection.autoconnect no

# 4. Switch over (brief link interruption; do this from the local console
#    or accept the drop if connected remotely)
sudo nmcli connection up br0
sudo nmcli connection down "<existing profile name>"

Both connections persist across reboots. To roll back: nmcli connection up "<existing profile name>" and restore connection.autoconnect yes.

Method 2: ifupdown (/etc/network/interfaces)

/etc/network/interfaces example:

# Physical NIC — manual mode, no IP (managed by bridge)
auto eth0
iface eth0 inet manual
    pre-up ip link set $IFACE up
    post-down ip link set $IFACE down

# Bridge br0 — static IP, bridges eth0
auto br0
iface br0 inet static
    address 192.168.1.100
    netmask 255.255.255.0
    gateway 192.168.1.1
    dns-nameservers 8.8.8.8 8.8.4.4
    bridge_ports eth0
    bridge_stp off
    bridge_fd 0
    bridge_maxwait 0

Replace eth0 with your actual NIC name (check with ip link). After editing:

sudo systemctl restart networking

Verify the bridge is up:

ip addr show br0
bridge link show

6 - Data Disks

Attach, resize, mount, and manage extra data disks.

macOS VMs: the playbooks in this document do not apply to macOS guests. macOS disks sit on q35’s built-in SATA controller (not hotpluggable, and no virtio-blk driver), and macOS guests have no Python for Ansible. The data disk is instead created automatically at VM-create time from the data_disk_gb column (see macOS VMs); each playbook detects type=macos and aborts with a diskutil pointer.

Attach Data Disk

# Attach data disk to a running VM (hot-plug, no reboot needed)
uv run ansible-playbook playbooks/attach-data-disk.yaml -e vm_name=debian12-dev

Reads data_disk_gb from vms.csv. The VM must have data_disk_gb > 0 defined in CSV. Hot-plugs the disk to the running VM using virsh attach-disk --config --live (persistent + immediate effect).

Inside the VM, format and mount the new disk:

mkfs.ext4 /dev/vdb
mkdir -p /data
mount /dev/vdb /data

Resize Data Disk

# Resize data disk (reads target size from vms.csv)
uv run ansible-playbook playbooks/resize-data-disk.yaml -e vm_name=debian12-dev

Reads target data_disk_gb from vms.csv. The playbook will:

  1. Check if target size is larger than current (shrinking not supported)
  2. If VM is running → graceful shutdown and wait for stop
  3. Resize qcow2 file with qemu-img resize
  4. If VM was running → automatically start VM again

After resize, expand the filesystem inside the VM:

# Linux VM
resize2fs /dev/vdb

# Windows VM (PowerShell)
$maxSize = (Get-PartitionSupportedSize -DriveLetter E).SizeMax
Resize-Partition -DriveLetter E -Size $maxSize

Note: If VM is already shut off, the playbook resizes the disk directly without auto-starting it.

Mount Disk

# Format and mount data disk inside VM (requires VM in hosts.ini)
uv run ansible-playbook playbooks/mount-disk.yaml -e "HOSTS=debian13-01" -e "mount_point=/data"

Format and mount data disk inside Linux VM. Requires the VM to be defined in hosts.ini.

Parameters

  • disk_device: disk device path (default: /dev/vdb)
  • mount_point: mount point (required, e.g. /data)
  • disk_format: filesystem type (default: ext4)
  • need_partition: create GPT partition (default: false, raw disk mount)
  • format_force: force reformat (default: false)
  • auto_mount: add to fstab (default: true)

Examples

# With GPT partition (default)
uv run ansible-playbook playbooks/mount-disk.yaml -e "HOSTS=debian13-01" -e "mount_point=/data"

# Raw disk without partition
uv run ansible-playbook playbooks/mount-disk.yaml -e "HOSTS=debian13-01" -e "mount_point=/data" -e "need_partition=false"

# Force reformat (WARNING: destroys data)
uv run ansible-playbook playbooks/mount-disk.yaml -e "HOSTS=debian13-01" -e "mount_point=/data" -e "format_force=true"

The playbook will:

  1. Install parted if needed
  2. Create GPT partition table (if need_partition=true)
  3. Format disk with specified filesystem
  4. Add fstab entry with UUID
  5. Mount and verify

Tags: -t partition, -t format, -t mount (run specific steps only)

Extra Disks (add / list / delete)

Add as many extra virtio-blk disks as needed at runtime, independent of the data_disk_gb column (which stays reserved for the single disk create-vm.yaml builds). Disks are named <vm>-extra<N>.qcow2 in the VM’s storage dir; both the next free index and the next free host target (vdX) are auto-detected from live and persistent config, so repeated runs never collide.

Linux guests only: virtio-blk hot-plug works on a running VM (--config --live, visible immediately, no reboot); a shut-off VM gets the disk via --config only, visible on next boot.

Add

# one 10G disk (index/letter picked automatically)
uv run ansible-playbook playbooks/add-extra-disk-linux.yaml -e vm_name=debian12-01 -e extra_size=10G

# four 2G disks in one run
uv run ansible-playbook playbooks/add-extra-disk-linux.yaml -e vm_name=debian12-01 -e count=4 -e extra_size=2G

# override the target directory (default: VM's storage dir from vms.csv)
uv run ansible-playbook playbooks/add-extra-disk-linux.yaml -e vm_name=debian12-01 -e extra_dir=/data/disks

List

uv run ansible-playbook playbooks/list-extra-disks.yaml -e vm_name=debian12-01

Shows each disk’s index, virtual size, and its target in the live domain and/or persistent config:

extra1.qcow2: 2G, live=vdc, config=vdc
extra2.qcow2: 2G, live=vdd, config=vdd

Delete

Detaches the disk (live + config on a running VM — virtio-blk hot-unplug) and deletes the qcow2 file. Destroys data, so confirm=true is required:

uv run ansible-playbook playbooks/delete-extra-disk.yaml -e vm_name=debian12-01 -e extra_index=2 -e confirm=true

Identifying a disk inside the guest

The guest kernel assigns its own vdX names, which usually differ from the host target. Each extra disk carries a serial <vm>-extra<N> — match on it:

lsblk -o NAME,SERIAL,SIZE
# vdc  debian12-01-extra1  2G

Format/mount afterwards with mount-disk.yaml (pass the guest device name, e.g. -e disk_device=/dev/vdc).

7 - Snapshots

Create, list, restore, and delete VM snapshots.

Create, list, restore, and delete VM snapshots using libvirt’s built-in snapshot support.

Usage

# Create snapshot (default: shutdown VM first for disk consistency, then restore previous state)
uv run ansible-playbook playbooks/snapshot-vm.yaml -e vm_name=debian12-01 -e snap_action=create

# Create snapshot without shutdown (live snapshot, VM continues running)
uv run ansible-playbook playbooks/snapshot-vm.yaml -e vm_name=debian12-01 -e snap_action=create -e halt=false

# Create snapshot with custom name and description
uv run ansible-playbook playbooks/snapshot-vm.yaml -e vm_name=debian12-01 -e snap_action=create -e snapshot_name=before-upgrade -e snapshot_desc="pre-upgrade snapshot"

# List all snapshots
uv run ansible-playbook playbooks/snapshot-vm.yaml -e vm_name=debian12-01 -e snap_action=list

# Restore to snapshot (requires confirmation, restores VM state at snapshot time)
uv run ansible-playbook playbooks/snapshot-vm.yaml -e vm_name=debian12-01 -e snap_action=restore -e snapshot_name=before-upgrade -e confirm=true

# Delete snapshot
uv run ansible-playbook playbooks/snapshot-vm.yaml -e vm_name=debian12-01 -e snap_action=delete -e snapshot_name=before-upgrade

Parameters

  • vm_name: VM name (required)
  • snap_action: create / list / restore / delete (required)
  • snapshot_name: snapshot name (auto-generated for create; required for restore/delete)
  • snapshot_desc: description (optional, create only)
  • halt: shutdown VM before snapshot for disk consistency, then restore to previous state (optional, create only, default: true)
  • confirm: safety flag (required for restore and delete)

Behavior

  • halt=true (default): If VM is running → shutdown → snapshot → start (restore running state). If VM is off → snapshot → remain off (preserve off state).
  • halt=false: Create snapshot while VM is running (live snapshot). Faster but may have incomplete disk writes.
  • Restore returns the VM to the exact state at snapshot time (running or off depending on snapshot state).

8 - User Accounts

Create Linux user accounts with SSH key and passwordless sudo.

Create user account on Linux VMs with SSH key and passwordless sudo. Auto-skips non-Linux hosts.

Usage

# Create user on single VM
uv run ansible-playbook playbooks/setup-user.yaml -e "HOSTS=debian12-01" -e "username=admin"

# Create user on multiple VMs (host group)
uv run ansible-playbook playbooks/setup-user.yaml -e "HOSTS=vms" -e "username=admin"

# Specify SSH public key
uv run ansible-playbook playbooks/setup-user.yaml -e "HOSTS=debian12-01" -e "username=admin" -e "ssh_pubkey=/path/to/id_rsa.pub"

Parameters

  • HOSTS: target host or group (default: vms)
  • username: user name to create (default: admin)
  • ssh_pubkey: SSH public key file path (default: ~/.ssh/id_rsa.pub)
  • user_shell: login shell (default: /bin/bash)
  • user_groups: user groups, comma-separated (auto-detected: wheel for Fedora/RHEL, sudo for Debian/Ubuntu)
  • passwordless_sudo: enable passwordless sudo (default: true)

Behavior

  • Auto-detects OS via gather_facts: true
  • Linux hosts: creates user, configures SSH key, enables passwordless sudo
  • Non-Linux hosts (Windows, etc.): skipped with message showing detected OS
  • Idempotent: safe to run multiple times on same host

9 - VM Console

Access the VM display console via SPICE or VNC.

VMs use different graphics backends based on OS type:

  • Windows VMs: SPICE graphics (port 5900+)
  • Linux VMs: VNC graphics (port 5900+)

Connect to VM console

# Method 1: virt-viewer (recommended, auto-detects SPICE/VNC)
virt-viewer <vm-name>

# Method 2: Get display port manually
virsh vncdisplay <linux-vm-name>    # Returns :0, :1, etc.
virsh domdisplay <windows-vm-name>  # Returns spice://127.0.0.1:5900

Remote access via SSH tunnel

# On your local machine
ssh -L 5900:127.0.0.1:5900 user@kvm-host-ip
# Then connect to spice://127.0.0.1:5900 or vnc://127.0.0.1:5900 locally

Example

View Windows VM boot process:

virt-viewer win10-dev1  # Opens SPICE console to watch Windows boot

10 - Remote Desktop

RDP access to Windows virtual machines.

Windows VMs support RDP (Remote Desktop Protocol) on port 3389.

Find VM IP address

virsh domifaddr <vm-name>

Connect via RDP

Install: sudo apt install remmina remmina-plugin-rdp

GUI: supports RDP, VNC, SPICE, SSH Features: clipboard sharing, folder redirection, multi-monitor

Other options

  • xfreerdp: xfreerdp /v:<vm-ip> /u:Administrator
  • Windows: built-in “Remote Desktop Connection” (mstsc.exe)
  • macOS: “Microsoft Remote Desktop” from App Store

Example

# Linux: open Remmina and connect to 10.241.20.45
remmina -c rdp://10.241.20.45

# Or use xfreerdp
xfreerdp /v:10.241.20.45 /u:Administrator /p:<password>

11 - Firewall

Manage the host firewall with nftables on Debian and RedHat family hosts.

The nftables role manages the KVM host firewall. It supports Debian-family hosts (Debian, Ubuntu) and RedHat-family hosts (Fedora, Rocky Linux).

On Ubuntu, ufw is installed and enabled on some images; it is disabled by default (nftables_disable_ufw) so the two managers do not fight over the ruleset. On Fedora and Rocky, firewalld is stopped and masked by default (nftables_disable_firewalld) for the same reason.

Usage

# Copy the variable template and fill in live values
cp group_vars/nftables/main.yml.example group_vars/nftables/main.yml

# Add hosts to the [nftables] group in hosts.ini, then apply:
uv run ansible-playbook playbooks/nftables.yaml

# Or target hosts directly via HOSTS pattern
uv run ansible-playbook playbooks/nftables.yaml -e HOSTS=<pattern>

nftables_ssh_sources must contain at least one entry unless nftables_ssh_allow_all is true, and should include the Ansible control node. The role refuses to apply an empty list otherwise. Existing SSH sessions survive the reload (established/related is accepted), but new ones are dropped unless the source is listed.

What the role does

  1. Validates inputs before touching the host (OS family, IPv4/CIDR format of nftables_ssh_sources, non-empty SSH ports, set names).
  2. Installs nftables (apt on Debian family, dnf on RedHat family); on Debian family, removes netfilter-persistent / iptables-persistent by default.
  3. Disables conflicting managers: ufw --force disable on Ubuntu (when active); stops and masks firewalld on Fedora/Rocky.
  4. Renders the ruleset to /etc/nftables.conf (Debian family) or /etc/sysconfig/nftables.conf (RedHat family), validated with nft -c -f before writing; reloads via nft -f when the content changes.
  5. Enables the nftables service at boot.

The rendered config defines two independent tables, inet _filter and inet _nat, deleting and recreating only these on reload — unrelated tables (for example Docker’s) are left untouched.

Variables

Variable Description Default
nftables_ssh_sources Source IPv4 addresses/CIDRs allowed to establish SSH — (required unless allow-all)
nftables_ssh_allow_all Accept SSH from any source false
nftables_ssh_ports Host SSH port list; list every port sshd listens on [22]
nftables_sets Named address sets (name + subnet list) []
nftables_rules Rules inserted verbatim into filter_default, filter_forward, nat_prerouting, nat_postrouting []
filter_forward_default_policy FORWARD chain default policy drop
net_postrouting_default_policy POSTROUTING chain default policy accept
nftables_remove_iptables_persistent Remove netfilter-persistent / iptables-persistent true
nftables_disable_ufw Disable ufw when installed and active true
nftables_disable_firewalld Stop and mask firewalld on RedHat family when installed true

Example

nftables_ssh_sources:
  - 10.0.0.0/8
  - 192.168.10.0/24
nftables_ssh_ports:
  - 22

nftables_sets:
  - name: cloud_inner
    subnet:
      - "10.5.0.0/16"

nftables_rules:
  - chain: filter_default
    rules:
      - ip saddr $cloud_inner counter jump nolimit
      - tcp dport 50001-50999 counter jump nolimit
  # dnat port 52001 to 192.168.1.2:8080
  - chain: nat_prerouting
    rules:
      - tcp dport 52001 counter dnat ip to 192.168.1.2:8080
  - chain: nat_postrouting
    rules:
      - ip daddr 192.168.1.2 tcp dport 8080 counter masquerade

Built-in chains

  • deny — drop
  • nolimit — accept
  • switch — kill switch; point rules at it to toggle:
sudo nft flush chain inet _filter switch
sudo nft add rule inet _filter switch counter jump deny

Notes

  • With nftables_sets and nftables_rules empty, only loopback, established/related traffic, DHCP replies, ICMP and SSH from nftables_ssh_sources are accepted.
  • The role replaces the distro-shipped /etc/nftables.conf with its own template. On a host that was already running the distro config, the leftover empty inet filter table is removed only when it provably cannot filter traffic (no rules, no drop/reject policies).
  • On Fedora and Rocky, nftables.service’s ExecReload begins with flush ruleset, which would wipe foreign tables. The role therefore reloads by running nft -f <config> directly instead of systemctl reload nftables.
  • Masking firewalld also blocks D-Bus activation, so firewall-cmd cannot bring it back. Restore with systemctl unmask firewalld.

12 - macOS VMs

Run keyboard-free Hackintosh macOS guests alongside Linux and Windows VMs.

macOS guests run alongside Linux/Windows VMs. See macOS Base Image for how the base image was built from scratch with kholia/OSX-KVM.

How macOS differs from Linux/Windows

Aspect Linux/Windows macOS
Video qxl/virtio/spice vmware-svga via qemu:commandline
SMC — isa-applesmc,osk=... via qemu:commandline
Boot system disk directly OpenCore overlay (order 1) → macOS disk (order 2)
Firmware distro OVMF or SeaBIOS persistent OVMF + a pre-blessed NVRAM template
Network libvirt <interface> bridge, virtio NIC pinned to root-bus slot=0x05
IP config cloud-init no cloud-init — DHCP by default
Shutdown virsh shutdown (ACPI) macOS ignores ACPI — shut down from the desktop or via SSH

Assets

Shared read-only templates live in macos_asset_dir (default /home/fish/bucket/kvm/macos/):

File Purpose
macos-sonoma-base.img Sonoma 14.8.9 base image, admin/admin, Remote Login enabled
OpenCore.qcow2 OpenCore boot disk (SIP disabled, auto-boot)
OVMF_VARS-blessed.fd Pre-blessed NVRAM template — what makes keyboard-free cold boot possible

Copying assets to another host

The three files are self-contained — copy them into the new host’s macos_asset_dir and macOS VMs can be created there. The blessed Preboot volume UUID, APFS layout and boot.efi path all travel with the files.

The new host additionally needs:

  1. apt install ovmf — the template also references the host’s /usr/share/OVMF/OVMF_CODE_4M.fd (the persistent distro build). Do not use OSX-KVM’s bundled non-persistent copy, or the bless is invisible and cold boot stops at Apple’s disk picker (see Constraint 1 below)
  2. Matching topology — q35 + built-in SATA at 1f:2 + system disk on port 2 are hardcoded in domain-macos.xml.j2, so using the same ansible-vms role satisfies this automatically
  3. QEMU >= 8.2.2 and a similar libvirt version (for qemu:commandline)

No need to copy: BaseSystem.img, fetch-macOS-v2.py, boot-macos-install.sh — only used when re-creating the base image.

Configure (vms.csv)

Add a row with type=macos. disk_gb must equal the base image’s virtual size (64). macOS uses DHCP, so leave ip/netmask/gateway/dns empty (set them only if you want a static IP — see Static IP). The VNC port is auto-assigned by libvirt (list-vms shows the actual port).

Data disk: set the data_disk_gb column (8th) to a size > 0 to attach an extra SATA disk (sdc) on the same built-in AHCI controller — macOS sees it natively, no kext needed. Like Linux/Windows guests, the SATA bus can not be hotplugged, so set it at create time (or cold-attach + reboot); the column is ignored on an already-created VM.

macos-sonoma-01,local,macos,8192,4,macos-sonoma,64,0,/home/fish/bucket/kvm/macos/macos-sonoma-base.img,br0,52:54:00:ff:00:01,efi,false,/home/fish/bucket/kvm/macos,,,,,

Create

uv run ansible-playbook playbooks/create-vm.yaml -e vm_name=macos-sonoma-01

Builds the two overlays (system disk + OpenCore), seeds the per-VM NVRAM from the blessed template, and defines/starts the domain. Cold boot needs zero keyboard input; the login window appears in ~40s.

Network: DHCP by default (upstream router on br0). Look up the IP with:

uv run ansible-playbook playbooks/list-vms.yaml

The IP column lists every VM’s address (e.g. 192.168.100.45 for macOS), and the VNC column shows 127.0.0.1:<port>.

Ansible against macOS guests must use -m raw — the guest has no Python interpreter.

Static IP (optional)

To switch a macOS VM from DHCP to a custom static IP, do it in two steps:

  1. Define the network in vms.csv first — fill the ip, netmask (CIDR prefix, e.g. 22), gateway and dns columns (all four are required; configure-macos-network.yaml asserts this before touching the guest):

    ...,efi,false,/home/fish/bucket/kvm/macos,192.168.100.45,24,192.168.100.1,192.168.100.53,
  2. Run the playbook against the current (DHCP) address:

    uv run ansible-playbook playbooks/configure-macos-network.yaml -e vm_name=macos-sonoma-01 -e boot_ip=192.168.100.45

    boot_ip is the DHCP address the VM answers on right now (find it with list-vms). The playbook logs in over SSH, locates the BSD interface by the VM’s MAC, applies networksetup -setmanual/-setdnsservers, and verifies the new static IP answers on port 22. After that, update (or add) the VM’s entry in hosts.ini with the static IP.

Start

uv run ansible-playbook playbooks/start-vm.yaml -e vm_name=macos-sonoma-01

Stop

uv run ansible-playbook playbooks/stop-vm.yaml -e vm_name=macos-sonoma-01

macOS ignores ACPI shutdown, so the playbook only prints a notice:

  • from the desktop: Apple menu → Shut Down
  • or via SSH: ssh admin@<ip> 'sudo shutdown -h now'

virsh shutdown is a no-op on macOS guests — do not use it.

Destroy

uv run ansible-playbook playbooks/destroy-vm.yaml -e vm_name=macos-sonoma-01 -e confirm=true

Stop the VM first (see above). The shared base image and assets are never touched.

Snapshots

macOS domains boot via pflash OVMF with a RAW NVRAM file, so libvirt refuses full (memory-included) snapshots. The snapshot playbook automatically falls back to disk-only snapshots for macOS:

# snapshot a running VM (disk-only)
uv run ansible-playbook playbooks/snapshot-vm.yaml -e vm_name=macos-sonoma-01 -e snap_action=create -e snapshot_name=my-snap -e halt=false

# revert (VM must be shut off first; playbook tells you)
uv run ansible-playbook playbooks/snapshot-vm.yaml -e vm_name=macos-sonoma-01 -e snap_action=restore -e snapshot_name=<snap> -e confirm=true

Limitations to know:

  • NVRAM is not part of the snapshot — boot state never reverts
  • With halt=true the playbook aborts with a notice: macOS ignores ACPI, so shut it down yourself first (desktop or SSH) if you want a consistent snapshot
  • APFS on AHCI has no TRIM, so space reclaimed by deleting snapshots is limited

Template constraints (domain-macos.xml.j2)

Four details must match the validated hand-built config; each violation looks like a different, unrelated bug:

  1. Persistent OVMF: the host’s /usr/share/OVMF/OVMF_CODE_4M.fd, not OSX-KVM’s non-persistent bundled build
  2. Bless topology match: disks sit on q35’s built-in AHCI (PCI 1f:2); never add a second ich9-ahci device
  3. NIC pinned to root-bus slot=0x05: macOS’s virtio-net driver only binds at a fixed root-bus position — if libvirt auto-places the NIC on a pcie-root-port child, the guest never sees it
  4. <seclabel type='none'/>: an external (disk-only) snapshot nests the shared OpenCore.qcow2 / base image one level deeper in the backing chain (… → .inited → overlay → base). libvirt’s virt-aa-helper only allows files named in the XML (source + one backingStore), so the deeper shared assets are AppArmor-denied and the VM won’t boot. Disabling per-domain AppArmor is safe here — the qemu:commandline custom devices already put this domain outside the standard confined-qemu model.

Full rationale and the bless procedure: macOS Base Image.

13 - macOS Base Image

Build macos-sonoma-base.img from scratch with OSX-KVM on Debian 12.

On a Debian 12 KVM host, install macOS Sonoma by hand using the kholia/OSX-KVM approach, then freeze the resulting disk into a self-contained qcow2 template image for deriving macOS VMs.

  • Output: /home/fish/bucket/kvm/macos/macos-sonoma-base.img
  • Guest: macOS Sonoma 14.8.9 (x86_64), 4 vCPU / 8 GB, account admin / admin, Remote Login enabled
  • OSX-KVM repo (hereafter “repo”): /home/fish/bucket/OSX-KVM
  • Recorded: 2026-09-10 (updated 2026-09-20)

Prerequisites

  • Host QEMU >= 8.2.2 (10.0.2 here), libvirt >= 9 (11.3.0 here, from bookworm-backports)
  • /dev/kvm available
  • OSX-KVM repo cloned to the repo path
  • VNC client: a VNC viewer on the host’s DISPLAY=:0, or ssh -L forwarding and connect locally
  • Disk space: the base image is ~29G actual; installation needs extra space

OVMF choice (important)

During installation you can use OSX-KVM’s bundled OVMF (non-persistent; does not affect the install):

  • OVMF_CODE_4M.fd (3.5M)
  • OVMF_VARS-1920x1080.fd (128K) — must be the version without the -exp suffix

When blessing + integrating with libvirt you must switch to the host distro’s persistent OVMF:

  • code: /usr/share/OVMF/OVMF_CODE_4M.fd
  • vars: the 540672-byte persistent VARS file (copied from the VARS written to disk after a real bless)

OSX-KVM’s bundled OVMF is the RAM-backed / EmuVariable variant; it never reads or writes the on-disk VARS file. The efi-boot-device variable written by bless cannot persist, and cold boot always stops at Apple Startup Manager.

1. Download and convert the installer media

cd /home/fish/bucket/OSX-KVM

# Download the recovery image from Apple's CDN (interactive version pick; choose Sonoma)
./fetch-macOS-v2.py
# Output: BaseSystem.dmg (753M) + BaseSystem.chunklist

# Convert to raw (QEMU needs raw; it cannot mount a dmg directly)
sudo -n apt install -y dmg2img    # if not installed
dmg2img -i BaseSystem.dmg BaseSystem.img
# Output: BaseSystem.img (~3G), installer + Recovery environment

2. Create the install directory and disk

WORK=/home/fish/bucket/kvm/macos-new
mkdir -p $WORK

# Create the target install disk (qcow2; size as needed)
qemu-img create -f qcow2 $WORK/macos-sonoma-new.qcow2 64G

# Copy the OVMF VARS template (the install phase can use OSX-KVM's non-persistent version)
cp /home/fish/bucket/OSX-KVM/OVMF_VARS-1920x1080.fd $WORK/install-OVMF_VARS.fd

qcow2 can be enlarged later: qemu-img resize xxx.qcow2 128G + inside the guest diskutil apfs resizeContainer diskN 0. Starting small does not limit you.

3. Boot the install VM

Using the boot-macos-install.sh script (in /home/fish/bucket/OSX-KVM/):

#!/bin/bash
# Install macOS Sonoma onto a fresh disk
set -euo pipefail
D=/home/fish/bucket/kvm
M=$D/macos-new
OSX=/home/fish/bucket/OSX-KVM
sudo -n qemu-system-x86_64 \
  -enable-kvm -m 8192 -smp 4,cores=2,sockets=1 \
  -cpu Skylake-Client,-hle,-rtm,kvm=on,vendor=GenuineIntel,+invtsc,vmware-cpuid-freq=on,+ssse3,+sse4.2,+popcnt,+avx,+aes,+xsave,+xsaveopt,check \
  -machine q35 \
  -device qemu-xhci,id=xhci \
  -device usb-kbd,bus=xhci.0 -device usb-tablet,bus=xhci.0 \
  -device isa-applesmc,osk="ourhardworkbythesewordsguardedpleasedontsteal(c)AppleComputerInc" \
  -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE_4M.fd \
  -drive if=pflash,format=raw,file=$M/install-OVMF_VARS.fd \
  -smbios type=2 \
  -drive id=OpenCoreBoot,if=none,snapshot=on,format=qcow2,file=$OSX/OpenCore/OpenCore.qcow2 \
  -device ide-hd,bus=ide.0,drive=OpenCoreBoot \
  -drive id=Installer,if=none,format=raw,file=$OSX/BaseSystem.img \
  -device ide-hd,bus=ide.1,drive=Installer \
  -drive id=MacHDD,if=none,format=qcow2,file=$M/macos-sonoma-new.qcow2 \
  -device ide-hd,bus=ide.2,drive=MacHDD \
  -netdev user,id=net0,hostfwd=tcp::2222-:22 \
  -device virtio-net-pci,netdev=net0 \
  -device vmware-svga -vnc 127.0.0.1:83

Start it:

cd /home/fish/bucket/OSX-KVM
sudo -n bash boot-macos-install.sh

Key points:

  • All three disks attach to q35’s built-in AHCI (ide.0 / ide.1 / ide.2); do not add an ich9-ahci device — this keeps the disk controller at PCI 1f:2, which is the prerequisite for bless to land correctly (see “Technical background: PCI topology and bless”)
  • snapshot=on protects the OpenCore disk from modification during installation
  • usb-tablet gives the VNC client absolute pointer positioning (clicks land accurately)
  • VNC display :83 (port 5983)
  • Uses the host’s persistent OVMF CODE (/usr/share/OVMF/OVMF_CODE_4M.fd) so post-bless variables persist to disk

4. Complete the installation over VNC

Connect VNC:

DISPLAY=:0 setsid nohup vncviewer 127.0.0.1:5983 Shared=false &

Installation flow (fully manual clicking; prefer the mouse when the keyboard is unreliable):

  1. OpenCore picker: arrow-key to macOS Base System, press Enter to enter Recovery
  2. Recovery main window → double-click Reinstall macOS Sonoma → Continue (bottom right)
  3. License page → Agree
  4. Target disk page: if only macOS Base System (2.87G, the Recovery itself) is listed, the target disk is unpartitioned. Click Back to return to Recovery
  5. Open Disk Utility → menu View -> Show All Devices → select QEMU HARDDISK Media (the whole virtual disk)
  6. Erase: Name Macintosh HD / Format APFS / Scheme GUID Partition Map, then close Disk Utility
  7. Enter Reinstall macOS Sonoma again; Macintosh HD now appears → Continue
  8. Wait for the install (tens of minutes to an hour+); on Restart → click it
  9. Back at the OpenCore picker → choose Macintosh HD → first-boot sequence
  10. Setup Assistant:
    • Language: English only (smaller language packs)
    • Region: any (US/Australia are neutral; avoid odd timezones like American Samoa)
    • Keyboard: default
    • Migration: Not Now
    • Do not install Xcode CLI tools (saves ~1.5G)
    • Account: Full Name / Account Name admin, password admin

Pitfalls:

  • On first boot the vmware-svga driver produces a grey screen for a few minutes — not a hang
  • Keyboard navigation in the Recovery main window is unreliable (Tab moves focus, but Space/Return won’t activate list items); list rows need a mouse double-click
  • Scripted clicking over VNC (hand-written RFB PointerEvents) is unreliable on QEMU (BrokenPipe); a real VNC client is easiest

5. Size optimization (after install, before bless)

Via SSH or in Terminal:

# Disable hibernation (saves the ~4G sleepimage)
sudo pmset -a hibernatemode 0
sudo rm -f /var/vm/sleepimage

# Clear caches
sudo rm -rf /Library/Caches/* ~/Library/Caches/*

# Clear logs
sudo rm -rf /var/log/*.gz /var/log/*.old /private/var/log/asl/*.asl

6. Enable Remote Login (SSH)

System Settings → General → Sharing → Remote Login on; click the i on the right → allow All users.

macOS has Remote Login off by default; disable the Network Firewall or allow ssh to avoid kex_exchange_identification: Connection closed.

7. Bless + clean shutdown

This is the key step for keyboard-free cold boot (see “Technical background: PCI topology and bless”).

Inside the macOS guest:

# Confirm SIP is disabled (OpenCore csr-active-config sets NVRAM Protections=disabled)
csrutil status

# Write efi-boot-device into OVMF NVRAM
sudo bless --mount / --setBoot --verbose

# Clean shutdown so OVMF flushes the variables to disk
sudo shutdown -h now

Never hard-kill QEMU — the qcow2 gets dirty and may need journal recovery.

Wait for SSH to drop and the QEMU process to exit on its own (pgrep -f qemu-system returns nothing).

8. Verify and promote the NVRAM template

# Verify the device path written by bless
virt-fw-vars -i $WORK/install-OVMF_VARS.fd -p | grep -E 'efi-boot-device|Boot0080'
# Boot0080 devpath must read as ... PCI(dev=1f:2)/SATA(port=1)/Partition(nr=2)/.../boot.efi

# Promote to the shared template
cp $WORK/install-OVMF_VARS.fd /home/fish/bucket/kvm/macos/OVMF_VARS-blessed.fd

9. Produce the base image

sudo qemu-img convert -f qcow2 -O qcow2 \
  $WORK/macos-sonoma-new.qcow2 \
  /home/fish/bucket/kvm/macos/macos-sonoma-base.img
sudo chown libvirt-qemu:libvirt-qemu /home/fish/bucket/kvm/macos/macos-sonoma-base.img

Verify:

qemu-img info /home/fish/bucket/kvm/macos/macos-sonoma-base.img
# Expect: file format: qcow2, virtual size: 64 GiB, **no backing file line**

The result is a read-only template. Derive new VMs from it as backing:

qemu-img create -f qcow2 -b /home/fish/bucket/kvm/macos/macos-sonoma-base.img \
  -F qcow2 <vm-name>.qcow2

Note: macOS APFS on AHCI SATA does not support TRIM (QEMU only supports it on virtio-blk/scsi/nvme), so fstrim and sparse reclamation from qemu-img convert are limited. A lean Sonoma install measures ~29G as the floor; it cannot be meaningfully reduced online.


Technical background: PCI topology and bless

This is the most common trap in macOS-on-KVM; understanding it avoids a lot of dead-end debugging.

The problem

Apple boot.efi draws its own Startup Manager (disk picker): if the persisted efi-boot-device / efi-boot-device-data variables in OVMF are missing, or the encoded device path does not match the current PCI topology, it stops and waits for keyboard input.

And libvirt keyboard injection into macOS guests (send-key / QMP input-send-event) was measured unresponsive across three USB controllers (default xhci, xhci pinned to bus0, ich9-ehci1 + ich9-uhci1) — pixel-level screenshot diff AE=0 — while the identical device config works under bare qemu.

So the correct approach is to make cold boot itself require no keyboard input.

PCI topology matching

The q35 machine type ships with an ICH9 AHCI controller fixed at PCI 1f:2; libvirt’s <controller type='sata'> uses this built-in controller.

The -device ich9-ahci,id=sata in OSX-KVM’s tutorial scripts adds a second controller at 02:0. A bless under the 02:0 topology produces an efi-boot-device device-path that does not match inside a libvirt domain on 1f:2 — the picker appears again.

This topology mismatch was once misdiagnosed as “libvirt’s keyboard is broken, blocking integration”; the root cause was always just the device path mismatch.

The correct approach

The install script (boot-macos-install.sh) adds no extra ich9-ahci; disks attach directly to q35’s built-in AHCI bus (ide.0 / ide.1 / ide.2), naturally at 1f:2. Bless in this topology writes a device path of PCI(dev=1f:2)/SATA(port=N)/..., which matches any libvirt domain also using 1f:2.

OpenCore config.plist notes

The NVRAM > Delete list must not contain efi-boot-device / efi-boot-device-data (keep only boot-args and ForceDisplayRotationInEFI), otherwise every boot erases them and breaks bless persistence.

libvirt EFI domain lifecycle pitfall

virsh undefine on a domain with nvram requires --nvram, and that deletes the VARS file. Because this VARS is a pre-baked template (not libvirt’s auto-generated blank one), you must re-cp OVMF_VARS-blessed.fd to the target path before manually re-defining:

destroy -> undefine --nvram -> cp blessed template -> define -> start

The create-vm role re-seeds the VARS on every creation, so the normal role path is unaffected; only manual XML re-definition needs this ordering.

Technical background: key decisions

  • Sonoma over the latest macOS: OSX-KVM’s combination of Intel emulation (Skylake-Client + OpenCore) + Sonoma is the most mature; Intel support narrows starting with Tahoe
  • Keep snapshot=on on OpenCore.qcow2: EFI disk changes never land, avoiding cross-boot pollution
  • Never share the OVMF_VARS .fd: each VM must get its own copy, or NVRAM conflicts arise

Appendix A: OpenCore boot disk

OpenCore/OpenCore.qcow2 is a pre-built OpenCore boot disk. Key settings:

  • SIP disabled: csr-active-config set to NVRAM Protections disabled
  • Auto-boot: Misc > Boot skips the picker (auto-selects the macOS disk after bless)
  • NVRAM > Delete list: deletes only boot-args and ForceDisplayRotationInEFI, and must not delete efi-boot-device / efi-boot-device-data

Attach at install time:

-drive id=OpenCoreBoot,if=none,snapshot=on,format=qcow2,file=$OSX/OpenCore/OpenCore.qcow2
-device ide-hd,bus=ide.0,drive=OpenCoreBoot

snapshot=on ensures install-time changes never land on the OpenCore disk, keeping the boot disk clean.

Appendix B: OSX-KVM repo asset inventory

Repo: kholia/OSX-KVM Local path: /home/fish/bucket/OSX-KVM

File Size Purpose
fetch-macOS-v2.py – Download macOS recovery images from Apple’s CDN (interactive version pick)
BaseSystem.dmg 753M Original Apple recovery image download
BaseSystem.img 3.0G Raw installer after dmg2img, attached directly to the VM
OpenCore/OpenCore.qcow2 – Patched OpenCore boot disk (SIP disabled, auto-boot)
OVMF_CODE_4M.fd 3.5M OSX-KVM’s bundled OVMF CODE (non-persistent)
OVMF_VARS-1920x1080.fd 128K OSX-KVM’s bundled OVMF VARS template (non-persistent)

Repo scripts

Script Description
boot-macos-install.sh Base image install boot script (step 3 above)
boot-macos-ctrl4.sh Bless experiment script using q35’s built-in AHCI (1f:2), no extra ich9-ahci
boot-macos-experiment.sh Early experimental install script (128G + extra ich9-ahci 02:0), reference only
boot-macos-ctrl.sh / ctrl2 / ctrl3 Iterations, no longer needed
boot-macOS-headless.sh OSX-KVM’s original GUI boot script

Appendix C: Disk layout

/home/fish/bucket/OSX-KVM/          # open-source project dir (git clone)
+-- fetch-macOS-v2.py               # installer media downloader
+-- BaseSystem.dmg / BaseSystem.img # macOS Sonoma installer media
+-- OpenCore/OpenCore.qcow2         # OpenCore boot disk (shared, read-only)
+-- OVMF_CODE_4M.fd                 # non-persistent OVMF (install phase only)
+-- OVMF_VARS-1920x1080.fd          # non-persistent OVMF VARS (install phase only)
+-- boot-macos-install.sh           # base install boot script
+-- boot-macos-ctrl4.sh             # bless experiment script

/home/fish/bucket/kvm/macos/        # ansible-vms managed assets dir
+-- macos-sonoma-base.img           # official base image (backing for every VM)
+-- OpenCore.qcow2                  # OpenCore boot disk (copied from OSX-KVM)
+-- OVMF_CODE_4M.fd                 # host persistent OVMF CODE (copied from /usr/share/OVMF)
+-- OVMF_VARS-blessed.fd            # blessed NVRAM template (the key to keyboard-free cold boot)
+-- <vm-name>/                      # per-VM working dir
    +-- <vm-name>.qcow2             # system disk overlay (backing -> base)
    +-- <vm-name>-OpenCore.qcow2    # OpenCore overlay (backing -> shared OpenCore)
    +-- <vm-name>-OVMF_VARS.fd      # per-VM NVRAM copied from the blessed template

/home/fish/bucket/kvm/macos-new/    # base image install scratch dir
+-- macos-sonoma-new.qcow2          # install disk (converted to base when done)
+-- install-OVMF_VARS.fd            # install-phase VARS copy (promoted to blessed)

Appendix D: Asset flow

fetch-macOS-v2.py -> BaseSystem.dmg -> dmg2img -> BaseSystem.img
                                                    |
boot-macos-install.sh (boots the install VM with three disks)
    +-- OpenCore.qcow2          (ide.0, snapshot=on)
    +-- BaseSystem.img          (ide.1, installer)
    +-- macos-sonoma-new.qcow2  (ide.2, target disk)
                                                    |
install complete + bless + shutdown
    -> install-OVMF_VARS.fd promoted to OVMF_VARS-blessed.fd
                                                    |
qemu-img convert -> macos-sonoma-base.img
                                                    |
create-vm.yaml automation: each new VM derives an overlay backed by the base

Measured run log (2026-09-20, this build)

A full execution of the steps above, recording key commands and verification results for future reproduction.

Install-phase network pitfall and fix

The install VM uses QEMU user-net (slirp NAT); inside the guest ipconfig getifaddr en0 returns 10.0.2.15 — a NAT-internal address the host can neither ping nor SSH. Fix: add hostfwd=tcp::2222-:22 to the -netdev user,id=net0 line of boot-macos-install.sh; the host then reaches the guest via ssh -p 2222 admin@127.0.0.1, with no network topology change and no manual typing in VNC.

# Host-side verification (after install, with Remote Login enabled)
sshpass -p admin ssh -p 2222 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
  admin@127.0.0.1 'sw_vers; ipconfig getifaddr en0'
# ProductVersion: 14.8.9   10.0.2.15

Size optimization (step 5)

sshpass -p admin ssh -p 2222 ... admin@127.0.0.1 '
  echo admin | sudo -S -p "" pmset -a hibernatemode 0
  echo admin | sudo -S -p "" rm -f /var/vm/sleepimage
  echo admin | sudo -S -p "" rm -rf /Library/Caches/* ~/Library/Caches/*
  echo admin | sudo -S -p "" sh -c "find /var/log -name *.gz -delete; rm -rf /private/var/log/asl/*.asl"
'

Bless verification (step 7)

sshpass -p admin ssh -p 2222 ... admin@127.0.0.1 \
  'echo admin | sudo -S -p "" bless --mount / --setBoot --verbose'

Key output (confirming a UUID-addressed preboot volume and correct topology):

Setting EFI NVRAM:
    efi-boot-device='<array>...UUID</key><string>98FA02AF-D0A8-4E55-8B63-F9FC985A4251</string>...
    \System\Library\CoreServices\boot.efi</string></dict></array>'

After shutdown (shutdown -h now; rc=255 is the normal SSH disconnect, not an error), you must wait for the QEMU process to exit on its own on the host (verify with pgrep/ps, not pgrep matching your own just-run shell command), or the VARS file may not be fully flushed.

NVRAM verification (step 8)

virt-fw-vars -i /home/fish/bucket/kvm/macos-new/install-OVMF_VARS.fd -p \
  | grep -iE 'Boot00|efi-boot-device'

Expect Boot0080, with devpath reading PciRoot()/PCI(dev=1f:2)/SATA(port=2)/... — exactly what was measured this run (port=2 corresponds to the install disk on ide.2, matching the topology future libvirt domains use, see “Technical background: PCI topology and bless”):

Boot0080 : boot entry: title="" devpath=PciRoot()/PCI(dev=1f:2)/SATA(port=2)/Partition(nr=2)/Media(subtype=0x3)/FilePath(\...\boot.efi)
efi-boot-device      : blob: 444 bytes
efi-boot-device-data : blob: 264 bytes

Producing the base image (step 9)

sudo qemu-img convert -f qcow2 -O qcow2 \
  /home/fish/bucket/kvm/macos-new/macos-sonoma-new.qcow2 \
  /home/fish/bucket/kvm/macos/macos-sonoma-base.img
sudo chown libvirt-qemu:libvirt-qemu /home/fish/bucket/kvm/macos/macos-sonoma-base.img
# Measured duration: 4 min 24 s

Final artifact verification:

qemu-img info /home/fish/bucket/kvm/macos/macos-sonoma-base.img
# file format: qcow2
# virtual size: 64 GiB
# disk size: 29.1 GiB      (no backing file line, self-contained)

Re-confirmed: shrinking the virtual disk from 128G to 64G kept the actual footprint at 29.1G (vs 28.9G measured for the earlier 128G virtual disk — essentially identical). This backs the conclusion stated at the top of this document: the base image cannot be shrunk by adjusting virtual disk size; 29G is the inherent floor for macOS APFS-on-AHCI without TRIM support (see the “Size optimization” and “Technical background” sections).