FreeBSD VirtIO Operations: Trace Guest Devices from Hypervisor to Driver

VirtIO is a family of virtual device interfaces used by hypervisors to present network, storage, console, entropy, balloon, and other devices to a guest. FreeBSD provides drivers for several VirtIO device types, including vtnet(4) for networking and virtio_blk(4) and virtio_scsi(4) for storage. A guest-side diagnosis must distinguish what the hypervisor presents from what the FreeBSD kernel attaches and what the service stack configures afterward.

The word “VirtIO” alone is not enough to diagnose a missing interface or disk. A hypervisor can omit a device, attach a different model, configure a device but not connect it, or expose a feature the guest driver does not negotiate. Conversely, a driver can attach successfully while the interface has no address or the disk has no partition table. Walk the chain from virtual hardware to the guest’s application-facing resource.

Inventory the guest’s PCI devices and driver attachments

Start with the kernel’s hardware inventory and boot messages:

pciconf -lv
dmesg | grep -i -E 'virtio|vtnet|vtblk|vtscsi|balloon'
kldstat

pciconf -lv reports PCI devices and attached drivers visible to the guest. The exact names and ordering depend on the hypervisor. Kernel messages show whether a FreeBSD driver probed and attached; kldstat shows loaded kernel modules, but an in-kernel driver may not appear as a separate module. Preserve this output before changing the VM definition.

If a device is absent from pciconf, investigate the hypervisor configuration, virtual machine generation, bus assignment, and device connection state first. Loading another guest module cannot attach hardware that the virtual machine was never given. If the device is present but no driver attaches, check the installed virtio(4) and device-specific manuals for support on the guest release and for the required module or kernel configuration.

Do not compare a guest’s pciconf output directly with a physical host’s inventory. The guest sees an emulated or paravirtual device interface, not necessarily the host’s actual controller model. Confirm the hypervisor’s configured device type and any feature flags with the VM owner.

Follow a VirtIO network interface through the stack

When vtnet(4) attaches, identify the interface and inspect link and address state:

ifconfig -l
ifconfig -v vtnet0
netstat -rn

Replace vtnet0 with the detected name. A present interface does not prove that the virtual switch is connected, the guest has a carrier state, DHCP completed, or a default route exists. Check each layer separately: driver attachment, link state, address, route, DNS, and application connectivity.

The vtnet(4) manual documents checksum offload, segmentation, receive coalescing, VLAN handling, and jumbo-frame support when the hypervisor advertises the corresponding features. Do not assume that a feature is active because the guest driver supports it. Inspect the interface capabilities on the running system and compare with the virtual switch and host configuration. An offload mismatch can manifest as packet loss or checksum reports without implying a faulty NIC.

Use a bounded packet capture on the guest interface when needed, then compare it with the virtual switch or host-side capture. If packets leave the guest but no replies return, the fault may be beyond the FreeBSD driver. If no packets are emitted, verify addressing and the application. Avoid changing MTU, offloads, and virtual switch settings simultaneously; one controlled variable change gives a clearer result.

Diagnose virtual disks without confusing controllers

VirtIO storage may appear as a block device or through a SCSI HBA, depending on the VM’s configured controller. Inspect both CAM and GEOM views:

camcontrol devlist -v
geom disk list
gpart show
mount -p

virtio_blk(4) and virtio_scsi(4) are distinct driver paths. Device names such as vtbd0 or da0 are not portable identities and can change when the virtual machine’s device ordering changes. Before changing partitions or mounts, map the guest device back to the hypervisor disk identifier and record its capacity and serial-like metadata where available.

If a virtual disk is missing, confirm the host-side disk is attached and connected, then verify PCI enumeration, driver attachment, GEOM provider creation, partition presence, and mount state. A mounted filesystem that reports I/O errors requires both guest and hypervisor evidence. Do not run filesystem repair tools on a live filesystem or format a newly visible disk until its identity and intended contents are verified.

If the disk appears smaller or larger after a host-side resize, check the guest’s provider size before expanding partitions or filesystems. Virtual capacity changes do not automatically update every upper layer. Use a planned sequence: confirm the hypervisor’s intended size, rescan or reboot only as supported, verify the guest provider, then modify the partition and filesystem with their own documented tools.

Treat console, entropy, and balloon devices as separate paths

The FreeBSD virtio(4) manual describes additional device types such as console, entropy, and balloon. They have different operational contracts. A console device can provide a VM console channel but does not guarantee the guest has configured a getty or login service on it. An entropy device contributes to the guest’s random subsystem but does not replace system-wide entropy health checks. A balloon device allows memory to be returned to the hypervisor, but guest-visible behavior depends on the host’s memory management policy.

When a console is missing, verify both the presented VirtIO device and the guest’s console configuration. When entropy support is expected, inspect the boot messages and random subsystem using the appropriate FreeBSD interfaces rather than assuming that a device’s presence guarantees cryptographic readiness. When ballooning causes pressure, correlate guest memory statistics with host-level balloon and overcommit metrics; neither side alone describes the full memory state.

Avoid applying generic Linux VirtIO instructions to FreeBSD. Driver names, module configuration, console setup, and device management differ. Use the FreeBSD manuals for the guest and the hypervisor documentation for the host.

Use a controlled change sequence

For a planned virtual hardware change, save the current VM device definition and guest inventory. Add or change one device, boot in a maintenance window, and confirm the new PCI function and kernel attachment before modifying network or storage configuration. For storage, verify the virtual disk identity and contents before any destructive operation. For networking, confirm the hypervisor network path before altering guest routes or firewall policy.

If a VM fails to boot after changing its controller type, revert the hypervisor device change first. A FreeBSD boot issue may result from removing the controller that contained the root filesystem, even when an alternate VirtIO driver is supported. Keep a console path independent from the virtual network so that network misconfiguration does not remove the only recovery channel.

Record FreeBSD release, hypervisor version, virtual hardware type, device PCI identifiers, driver names, and the observed guest interface or disk names. This data allows a future incident responder to distinguish a guest driver regression from a host-side virtual device change.

Acceptance checks

For each configured VirtIO function, confirm it is presented by the host, visible in the guest, attached to the expected driver, and usable at the appropriate higher layer. A NIC check should include link, address, route, and a bounded connectivity test. A disk check should include device identity, capacity, partition, filesystem, and mount state. A console or balloon check should include both guest and host perspectives.

VirtIO reduces the cost of emulated-device access, but it does not erase the virtualization boundary. A driver can only operate the device model presented to it, and the hypervisor remains part of the failure domain. Troubleshoot both ends while preserving a known-good boot and rollback path.

Related:

Sources: