GPU Passthrough

Overview#

GPU passthrough assigns an entire NVIDIA GPU to a single KVM virtual server. The guest operating system (OS) gets direct, exclusive access to the physical GPU. It can use all of the GPU’s memory and compute power, and SolusVM does not partition the GPU.

You configure GPUs on a compute resource for passthrough, and then create plans that offer a GPU model. When a customer creates a server from a GPU plan, SolusVM finds a matching compute resource with a free GPU of that model. SolusVM then attaches the GPU to the server automatically.

To share a GPU between several servers instead, see Virtual GPUs (vGPUs).

Prerequisites#

Before you configure GPU passthrough, ensure that you meet the following requirements:

• Your SolusVM version is 2.0.0-44576 or newer.
• The server uses the i440fx machine type. SolusVM rejects other machine types, such as q35.
• You have an NVIDIA GPU on each compute resource that will host passthrough servers, and you have installed the NVIDIA CUDA or GRID drivers on it. For steps, see Preparing the compute resource.
• You have enabled IOMMU in the BIOS or UEFI settings of the compute resource and in the kernel.
• The vfio-pci kernel module is available on the compute resource. SolusVM automatically configures the PCI memory space that the GPU needs.
• The GPU has its own IOMMU group. SolusVM does not support GPUs that share their slot with other functions, such as HDMI audio or USB-C controllers.
• The compute resource does not load the nvidia_drm module with a modeset value of 1.
• No processes on the compute resource use the GPU.

NVIDIA driver options#

GPU passthrough relies on the nvidia-smi tool on the compute resource. It works with either NVIDIA host driver:

• CUDA (data center) drivers — You can only use GPUs for passthrough.
• GRID (vGPU) drivers — You can use each GPU for passthrough or for vGPU. vGPU also requires a GPU that supports SR-IOV-based vGPU partitioning.

Each GPU works in one mode at a time. A compute resource with several GPUs can have some GPUs in passthrough mode and others in vGPU mode.

Preparing the compute resource#

Install NVIDIA drivers#

If you want to use GPUs for both passthrough and vGPU, install the NVIDIA GRID drivers and enable IOMMU. Otherwise, install the NVIDIA CUDA drivers.

To install the NVIDIA CUDA drivers:

1. Run the following command to install the necessary OS updates:

   apt-get update && apt-get upgrade && apt-get dist-upgrade

2. Reboot the compute resource.

3. Run the following command to download the necessary linux-headers packages:

   apt-get install linux-headers-$(uname -r)

4. Download the NVIDIA data center (CUDA) driver for your GPU model from the NVIDIA website and install it.

5. Reboot the compute resource.

6. Run the following command to ensure that your system can detect the NVIDIA driver:

   nvidia-smi

Enable IOMMU#

To enable IOMMU:

1. Enable IOMMU (Intel® VT-d or AMD-Vi) in the BIOS or UEFI settings of the compute resource.

2. Open the /etc/default/grub file and add the following parameters to the GRUB_CMDLINE_LINUX_DEFAULT variable:

   • On Intel CPUs, add intel_iommu=on iommu=pt nvidia-drm.modeset=0.
   • On AMD CPUs, add amd_iommu=on iommu=pt nvidia-drm.modeset=0.

3. Run the following command to apply the changes:

   update-grub

4. Reboot the compute resource.

Verify the configuration#

To check the passthrough requirements:

1. Run the following command to check the IOMMU groups:

   ls /sys/kernel/iommu_groups

   The output must not be empty.

2. Run the following command to ensure that the vfio-pci module is available:

   modinfo vfio-pci

3. Run the following command to ensure that the nvidia_drm module does not hold the GPU:

   cat /sys/module/nvidia_drm/parameters/modeset

   The output must be N. If the file does not exist, the compute resource does not load the nvidia_drm module, which also works.

4. Run the following command to find the PCI address of the GPU:

   lspci -D | grep -i nvidia

5. Run the following command to list the devices in the IOMMU group of the GPU:

   ls /sys/bus/pci/devices/0000:01:00.0/iommu_group/devices

   Replace 0000:01:00.0 with the PCI address of your GPU. The output must only contain the GPU itself, plus PCI bridges on some systems.

Configuring GPUs for passthrough#

After you prepare the compute resource, set each GPU that you want to offer to passthrough mode.

To configure a GPU for passthrough:

1. Go to Compute Resources and click the compute resource’s name.
2. Go to the GPUs tab.
3. Click Refresh to detect the GPUs on the compute resource.
4. Click the icon next to a GPU.
5. Select Passthrough in Allocation mode and click Apply.

SolusVM moves the GPU from the NVIDIA driver to the vfio-pci driver. The setting persists across compute resource reboots.

Creating plans with GPU passthrough#

To offer passthrough GPUs to customers, create a plan that includes a GPU model. SolusVM only places servers that use this plan on compute resources that have a free GPU of that model.

To create a plan with GPU passthrough:

1. Go to Compute Resources > Plans.
2. Create or edit a KVM plan.
3. Select Passthrough in Offer GPU.
4. Select the model of GPU to offer in GPU model.
5. Click Save.

To allow customers to select a GPU when ordering through WHMCS, see GPU.

Attaching or detaching a GPU#

After customers create servers from GPU plans, you can attach or detach a passthrough GPU on a server. Unlike vGPU, you do not need to shut down the server first. SolusVM stops the server, applies the change, and starts the server again if it was running. For the vGPU steps, see Attaching or Detaching a vGPU.

To attach a passthrough GPU to an existing server:

1. Go to Virtual Servers and click the server’s name.
2. Go to the GPU tab.
3. Click Attach GPU.
4. Select Passthrough in Connection type.
5. Select a free GPU and click Attach.

To detach the GPU, click Detach on the same tab.

Guest OS requirements#

Install the standard NVIDIA driver for the GPU model inside the guest OS. Unlike vGPU, passthrough does not require an NVIDIA vGPU license. The guest driver does not have to match the driver version on the compute resource.

Troubleshooting#

The following errors can occur when you configure or attach a passthrough GPU: