ProxMenux LogoProxMenux

Post-Install: Virtualization

Settings post-install Proxmox~9 min

What this category covers

Two independent options. Install relevant guest agent is a safety net for when Proxmox itself runs nested inside another hypervisor. Enable VFIO IOMMU support is the one most users care about: it flips on the kernel features you need to pass a GPU, HBA or NIC straight into a VM with near-native performance.

Install relevant guest agent

Detects the virtualization environment the Proxmox host is running on (using systemd-detect-virt and dmidecode) and installs the matching guest-tools package so the outer hypervisor can communicate with Proxmox cleanly (graceful shutdown, clock sync, IP reporting, etc.).

Detected hostPackage installed
QEMU / KVMqemu-guest-agent
VMware (ESXi, Workstation)open-vm-tools
VirtualBoxvirtualbox-guest-utils
Bare metal (none)— no-op, nothing installed

Skip this on bare-metal Proxmox

If Proxmox runs directly on hardware (the common case), ticking this option is a no-op — the detector returns none and the script exits without changes. The option only matters for the minority of setups that run Proxmox as a guest for testing or labs.

Enable VFIO IOMMU support

Turns on IOMMU on the host and loads the kernel modules that make PCI passthrough possible (vfio, vfio_iommu_type1, vfio_pci). With this enabled, you can bind a physical device to a VM and the guest gets direct, near-bare-metal access to it.

Who needs this

  • You want to pass a GPU to a Windows gaming VM or a macOS VM.
  • You have a dedicated 10G NIC for a firewall/router VM (OPNsense, pfSense).
  • You want to pass an HBA directly to a TrueNAS/Unraid VM for ZFS on bare disks.
  • You're planning to use Coral TPU, a capture card, or an SDR dongle in a VM.

If none of those apply, you can safely skip this option. For passthrough to an LXC (not a VM), IOMMU is not required.

What ProxMenux does

The function is boot-loader aware: it detects whether Proxmox is on ZFS (systemd-boot) or LVM/ext4 (GRUB) and writes to the right file. It's also idempotent — if the parameters are already present, nothing is added.

Boot typeFile touchedPost-update step
systemd-boot (ZFS)/etc/kernel/cmdlineproxmox-boot-tool refresh
GRUB (LVM/ext4)/etc/default/grubupdate-grub

Kernel parameters added:

# Intel CPU → intel_iommu=on
# AMD CPU   → amd_iommu=on
# Plus these in both cases:
iommu=pt
pcie_acs_override=downstream,multifunction

About pcie_acs_override — know what you're enabling

pcie_acs_override=downstream,multifunction relaxes the PCIe Access Control Services check. It lets the kernel split apart IOMMU groups that the firmware reports as monolithic, which is sometimes the only way to pass through one device of a group without dragging the rest. The trade-off is reduced isolation between devices: a malicious or compromised VM with passthrough has a larger attack surface via DMA. Fine for a home lab; think twice before enabling on a host that runs untrusted workloads. If you don't need it, remove that token from /etc/kernel/cmdline or /etc/default/grub after the script runs and re-run the boot-loader update step.

Kernel modules added to /etc/modules:

vfio
vfio_iommu_type1
vfio_pci
vfio_virqfd   # only on kernels < 6.2 (merged into vfio in 6.2+)

Conflicting drivers blacklisted in /etc/modprobe.d/blacklist.conf:

nouveau
lbm-nouveau
radeon
nvidia
nvidiafb
options nouveau modeset=0

Blacklisting GPU drivers conflicts with host-side GPU usage

The blacklist ensures the host kernel never binds any GPU driver, so VFIO can claim the GPU cleanly. This is exactly what you want for passthrough to a VM — but it's the opposite of what you need to install NVIDIA drivers on the host (for LXC transcoding, for example). Pick one path per GPU:
  • GPU → VM: enable VFIO/IOMMU here, leave the GPU drivers blacklisted.
  • GPU → LXC (or host): skip this option, use the NVIDIA host install, do not blacklist nvidia/nouveau.
  • Two GPUs: one can go to a VM and the other to an LXC, but you'll need finer-grained configuration (bind only one card to vfio-pci by PCI ID). Default blacklist is too broad for this case — edit blacklist.conf afterwards.

Reboot required

IOMMU, VFIO modules, and the blacklist only take effect after a reboot + initramfs regeneration. The script triggers update-initramfs -u -k all and the boot-loader refresh, and sets the "reboot required" flag so Customizable prompts you at the end.

Verification after reboot

# IOMMU is actually on
dmesg | grep -E "DMAR|IOMMU" | head
# Expect lines like "IOMMU enabled" / "DMAR: IOMMU enabled"

# VFIO modules loaded
lsmod | grep vfio

# See your IOMMU groups — each "Group N" can be passed independently
for d in /sys/kernel/iommu_groups/*/devices/*; do
  n=${d#*/iommu_groups/*}; n=${n%%/*}
  printf 'Group %s  ' "$n"; lspci -nns "${d##*/}"
done | sort -V

Reversible from the Uninstall menu

Uninstall Optimizations reverts all the changes: strips the IOMMU tokens from /etc/kernel/cmdline or GRUB, removes the VFIO modules from /etc/modules, removes the driver blacklist entries, and rebuilds initramfs. A reboot is required to actually apply the reversion.

Related

ProxMenux Scripts: Previous
System
ProxMenux Scripts: Next
Network