Converting a guest to virtio - the migration that makes a VM unbootable

The previous lesson covered what virtio is and why an emulated guest runs at a fraction of the speed. This one is about the change itself, because “switch the disk controller to virtio” is one click on the hypervisor and a rebuild on the guest if you get the order wrong.

Confirm the model from the PCI IDs

The hypervisor configuration and the guest’s view disagree more often than you would expect - after a migration, a template clone, or a restore from an older backup. Trust the guest:

$ lspci -nnk | grep -iEA2 'ethernet|scsi|ide|sata'

00:03.0 Ethernet controller [0200]: Intel Corporation 82540EM Gigabit Ethernet [8086:100e]
Kernel driver in use: e1000
00:01.1 IDE interface [0101]: Intel Corporation 82371SB PIIX3 IDE [8086:7010]
Kernel driver in use: ata_piix

PCI vendor 1af4 is the virtio range. Vendor 8086 on a KVM guest means QEMU is emulating an Intel device, and every register access is being trapped and simulated. On VMware the equivalent pairing is vmxnet3 and pvscsi (good) against e1000 and LSI Logic (emulated).

Two more confirmations worth keeping in a build check:

lsblk -o NAME,TYPE,TRAN     # TRAN should read virtio (or nvme in cloud)
ethtool -i eth0 | head -3   # driver: virtio_net, not e1000

Why the conversion breaks the boot

Changing the controller changes two things the guest depends on at boot, and neither of them lives in the running system:

• The driver must be in the initramfs. The kernel has to reach the root filesystem before it can load modules from it. If virtio_blk or virtio_scsi is not baked into the initramfs, the guest boots, finds no root device, and drops to an (initramfs) prompt. The disk is present and unreachable.
• The device name changes. /dev/sda becomes /dev/vda under virtio-blk. Any /etc/fstab entry, bootloader parameter, or LVM filter that names a device path rather than a UUID= breaks in the same reboot.

1. While still on the old controller, confirm the drivers are in the initramfs.
2. If they are missing, add them and rebuild the initramfs - this is safe on the old path, because an unused driver costs nothing.
3. Convert every device reference to UUID= and verify with findmnt --verify.
4. Snapshot the guest, and make sure you have console access that does not depend on the guest network.
5. Change the controller on the hypervisor, then boot and verify with lspci and lsblk.

# lsinitrd /boot/initramfs-$(uname -r).img | grep -c virtio

0

The Debian-family equivalent is lsinitramfs /boot/initrd.img-$(uname -r) | grep -c virtio.

Rebuild with the drivers explicitly included:

# RHEL family
dracut --force --add-drivers "virtio_blk virtio_scsi virtio_net virtio_pci"

# Debian family: list them in /etc/initramfs-tools/modules, then
update-initramfs -u -k all

Recovering a guest that will not boot after the change

From the (initramfs) prompt, establish which of the two failures you have:

# is there a virtio block device at all?
ls /dev/vd* /sys/block
# is the driver loaded?
cat /proc/modules | grep virtio

If /dev/vda exists and the boot still failed, the root device reference is wrong - an old /dev/sda in the bootloader or in /etc/fstab. If nothing appears at all, the driver is missing.

The fastest recovery for a missing driver is to change the controller back on the hypervisor, boot on the old path, fix the initramfs properly, and convert again. Editing an initramfs from a rescue image works, but it is a longer route with more ways to be wrong under time pressure.

Knowledge check