ProxMenux LogoProxMenux

Post-Install: Virtualization

Settings post-install Proxmox

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

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