Deploy a VM with GPU Passthrough¶

MFCloud supports whole-card PCIe GPU passthrough via VFIO — a physical GPU is bound directly to one VM, with near-native performance. This is a standard platform capability, not a separate licensed add-on.

Whole-card passthrough, not SR-IOV slicing

This guide covers 1 GPU → 1 VM passthrough. To split a single Intel GPU into multiple virtual functions (SR-IOV) for several VMs — the console automates the node setup for this — see Share one GPU across VMs (vGPU / SR-IOV).

Prerequisites¶

A GPU in a node's PCIe slot, with IOMMU enabled in the host's BIOS/firmware (Above 4G Decoding and the platform's VT-d/AMD-Vi equivalent).
The GPU bound to vfio-pci on the host (not its native driver) — see Prepare the node.
A node added to MFCloud (Hosts → Add Host) with the GPU installed.

1. Prepare the node¶

On the node, confirm the IOMMU is active and identify the GPU's PCI address:

dmesg | grep -iE 'DMAR|IOMMU'        # expect IOMMU enabled
lspci -nnk | grep -iA3 'VGA\|3D\|Display'

Bind the GPU to vfio-pci so the host driver never claims it — add a modprobe.d config pinning it by vendor:device ID, then rebuild initramfs and reboot:

cat > /etc/modprobe.d/vfio.conf <<EOF
options vfio-pci ids=<vendor:device>
EOF
echo -e "vfio\nvfio_pci\nvfio_iommu_type1" > /etc/modules-load.d/vfio.conf
dracut -f
reboot

After reboot, confirm the driver switched over:

lspci -nnk -s <bus:slot.func>   # "Kernel driver in use: vfio-pci"

2. Deploy the VM with the right settings¶

Inventory → Virtual Machines → Deploy VM, then set:

Field	Value	Why
Machine/Chipset	Q35	i440FX's MMIO window is too small for a modern GPU's VRAM BAR — Q35 is required.
Boot Firmware	UEFI	Required alongside Q35; also needed if you want Secure Boot in the guest.
Hardware Passthrough (PCIe)	select the GPU	Pulled from a live `lspci` scan of the node — only shows up if step 1 succeeded.
OS Type	match the guest OS	Windows guests additionally need the VirtIO driver ISO staged on the node — see Install a Windows VM.

If you're attaching a GPU to an existing VM instead of a fresh deploy, the same Q35/UEFI requirement applies — set those in VM Settings → Advanced before attaching, and the VM must be powered off to add/remove the passthrough device.

3. Install the GPU driver in the guest¶

Passthrough only gets the device onto the guest's PCI bus — Windows/Linux still need the vendor driver to actually use it:

The device will initially show as a generic/basic adapter (Windows: "Microsoft Basic Display Adapter", Code 31 — "Windows cannot load the drivers required for this device"). This is expected until the real driver is installed.
Install the vendor's GPU driver package inside the guest.
Some large-VRAM GPUs use Resizable BAR — they boot at a small default BAR (e.g. 256MB) and only map their full VRAM once the driver performs its own link/BAR negotiation at load time. Don't worry if the BAR looks small before the driver is installed.

Troubleshooting¶

Symptom	Cause & fix
GPU doesn't appear in the Hardware Passthrough picker	It's not bound to `vfio-pci` yet, or the node's hardware scan can't reach it — re-check step 1.
"UEFI requires ACPI" or the VM won't boot after attaching a GPU	Machine type is still `pc`/i440FX. Switch to Q35 + UEFI in VM Settings (offline only).
Guest shows the GPU but Code 31 / "Basic Display Adapter"	Expected before the vendor driver is installed — see step 3.
Host becomes unresponsive / crashes when the GPU driver loads or resets the card	This points to a host-side IOMMU/PCIe issue, not a passthrough configuration problem. Enable persistent journaling and kdump on the node before retrying, so the next attempt leaves diagnosable logs instead of a blank slate after a reboot.
BAR still shows the small default size after the driver is installed	Confirm `Above 4G Decoding` is enabled in the host BIOS — without it, the platform may not have enough address space to ever hand the device a large enough window.