Skip to content

Windows VirtIO Pre-Staging

v0.9.8

The classic V2P pain point: a Windows guest comes off ESXi on the LSI / VMXNET3 driver stack. Boot it on Proxmox virtio-scsi-pci + virtio-net without prep and it's BSOD 0x0000007B INACCESSIBLE_BOOT_DEVICE. The traditional workaround is "boot in IDE/E1000, install drivers, reboot, switch to VirtIO" - three reboots and a manual Safe-Mode session per VM. Not viable at scale.

v0.9.8 ships offline VirtIO injection: with the migration target paused, PegaProx mounts the Windows boot disk's NTFS partition, copies the matching VirtIO drivers in, edits the SYSTEM hive's Services + CriticalDeviceDatabase entries directly, and unmounts cleanly. First boot lands straight on virtio-scsi-pci + virtio-net.

What gets injected

viostor

VirtIO block storage driver - covers VirtIO single-queue disks.

vioscsi

VirtIO SCSI controller driver - required for virtio-scsi-pci (the Proxmox default).

NetKVM

VirtIO paravirtual network driver - needed for model=virtio NICs.

Balloon

VirtIO memory balloon for dynamic memory management with the host.

pvpanic

QEMU panic notifier - Windows BSOD notifies the host so HA can act.

vioserial

VirtIO serial - required for qemu-guest-agent communication.

viorng

VirtIO RNG - random-number passthrough from host. Speeds up TLS / Active Directory key generation.

How the injection works

Disk attach (storage-aware)

For LVM/iSCSI: device-mapper path opened directly. For ZFS zvol: /dev/zvol/.... For Ceph RBD: rbd map creates a loop. For qcow2 (NFS/CIFS/CephFS): qemu-nbd --connect exposes a block device. All routes converge on a regular block-device path.

NTFS sanity

ntfsfix clears any "Fast Startup" hibrid-state (Windows hybrid sleep leaves NTFS half-mounted; mount-rw without this can corrupt the FS). Bootloader partition is identified by GPT GUID / MBR boot flag.

Mount + driver copy

NTFS mounted read-write. Drivers extracted from the virtio-win.iso you provide (matching the guest's Windows version: 10/11/Server 2016/2019/2022/2025) and copied to C:\Windows\System32\drivers + C:\Windows\INF.

Hive edit via python3-hivex

The SYSTEM hive (C:\Windows\System32\config\SYSTEM) is opened with hivex. Per-driver Services entries are written to the active ControlSet with Start=0 (boot-start) so the kernel loads them before the storage stack initializes. Matching CriticalDeviceDatabase entries are added so PnP knows to use them. Hive is closed cleanly with the original timestamp preserved.

Unmount + verify

NTFS unmounted, FS journal flushed, qemu-nbd / rbd unmap / dm-remove released. Migration resumes. Windows boot lands in normal mode on VirtIO without any driver-install dialog.

Safety rails

  • Fast-Startup/hibernation clear: ntfsfix + the remove_hiberfile mount option clear the NTFS dirty bit and hiberfile before the RW mount, preventing corruption from Windows hybrid-sleep.
  • RW sanity check: after mounting, a touch/rm test confirms the FS is genuinely writable before any edit; the run aborts otherwise.
  • Boot-safe driver registration: only viostor / vioscsi are set Start=0 (boot-start), and only if their .sys was actually copied - a missing miniport at Start=0 would BSOD INACCESSIBLE_BOOT_DEVICE, so absent drivers are skipped.
  • VM-running guard: injection refuses to run if the target QEMU process is alive (prevents live-FS corruption on the sshfs_boot path).
  • Opt-in: the toggle defaults to OFF in the migration wizard. Always explicit, never hidden behind "auto".

Requirements

  • A virtio-win.iso on the target node - drop it in /var/lib/vz/template/iso/, on any pvesm-managed ISO storage, or point virtio_iso_path at it. If it is not found, injection is skipped (the VM still boots via the ESXi-compatible drivers).
  • python3-hivex (Debian: apt install python3-hivex)
  • ntfs-3g + ntfsprogs (Debian: apt install ntfs-3g ntfsprogs)
  • qemu-utils for qemu-nbd on qcow2 targets (already required for Proxmox)
  • rbd CLI for Ceph targets (provided by ceph-common)

Limitations

  • Windows only. Linux guests don't need it (modern kernels include VirtIO drivers since > 2.6.30).
  • Windows XP / 2003 / 2008 R2 - not supported (drivers exist but signing/PnP is brittle, manual is safer).
  • BitLocker-encrypted system volumes need to be unsealed first - PegaProx surfaces this in pre-flight checks.