From 53b7540e9f25a57f8fbd25f9215011e1716c4950 Mon Sep 17 00:00:00 2001 From: mattrowe-opennebula Date: Thu, 29 Oct 2026 12:45:02 +0100 Subject: [PATCH 1/2] M #~: Minor changes Host config --- .../host_configuration.md | 36 ++++++++++--------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/content/product/cluster_configuration/pci_passthrough_sriov/host_configuration.md b/content/product/cluster_configuration/pci_passthrough_sriov/host_configuration.md index a8a54a00c..ce684f3bb 100644 --- a/content/product/cluster_configuration/pci_passthrough_sriov/host_configuration.md +++ b/content/product/cluster_configuration/pci_passthrough_sriov/host_configuration.md @@ -9,18 +9,18 @@ tags: ['AI','NVIDIA'] weight: "2" --- -This guide describes the common host configuration required to enable PCI passthrough in OpenNebula. These requirements apply independently of the type of PCI device being assigned to virtual machines. Device-specific configuration is covered in the corresponding guides. -The guide assumes a Linux host running the OpenNebula KVM hypervisor. While the examples use common Linux utilities and a GRUB-based bootloader, equivalent procedures can be used with other Linux distributions and bootloaders. +This guide describes the common Host configuration required to enable PCI passthrough in OpenNebula. These requirements apply independently of the type of PCI device being assigned to virtual machines. Device-specific configuration is covered in the corresponding guides. +The guide assumes a Linux Host running the OpenNebula KVM hypervisor. While the examples use common Linux utilities and a GRUB-based bootloader, equivalent procedures can be used with other Linux distributions and bootloaders. ## Prerequisites -Before configuring PCI passthrough, verify that the host satisfies the following requirements: +Before configuring PCI passthrough, verify that the Host satisfies the following requirements: * Hardware-assisted virtualization enabled in the system firmware. * An IOMMU implementation supported by the processor: * Intel VT-d * AMD-Vi * Arm SMMUv3 -* OpenNebula host packages installed, including KVM, QEMU, and libvirt support. +* OpenNebula Host packages installed, including KVM, QEMU, and libvirt support. --- @@ -95,7 +95,7 @@ arm-smmu-v3 ... ## Step 2. Configure VFIO Device Binding -PCI devices assigned to virtual machines must be managed by a VFIO driver instead of their native host driver. OpenNebula supports any mechanism that binds devices to VFIO. The recommended approach is to use the **driverctl** utility, which provides persistent per-device driver overrides using the Linux kernel `driver_override` interface. +PCI devices assigned to virtual machines must be managed by a VFIO driver instead of their native Host driver. OpenNebula supports any mechanism that binds devices to VFIO. The recommended approach is to use the **driverctl** utility, which provides persistent per-device driver overrides using the Linux kernel `driver_override` interface. For Linux Containers, the PCI device driver shouldn’t be changed. Skip this section entirely if using passthrough in Linux Containers. @@ -165,7 +165,7 @@ driverctl set-override 0000:43:00.0 vfio-pci Many PCI devices expose multiple functions. For example, GPUs often expose both a graphics controller and an audio controller. Repeat the command for every PCI function that will be assigned to the virtual machine. The override is persistent and is automatically restored after reboot. {{< alert title="Note" type="primary" >}} -Once a device is bound to a VFIO driver, it is no longer available to the host operating system until the override is removed. +Once a device is bound to a VFIO driver, it is no longer available to the Host operating system until the override is removed. {{< /alert >}} ### Verification @@ -196,7 +196,7 @@ driverctl list-overrides ### Removing an Override -To restore the default host driver: +To restore the default Host driver: ```shell driverctl unset-override 0000:43:00.0 @@ -258,7 +258,7 @@ hugepages=1024 default_hugepagesz=1G hugepagesz=1G The appropriate Huge Page size depends on the processor architecture and workload. On x86 platforms, common Huge Page sizes are 2 MB and 1 GB. -Regenerate the bootloader configuration using the appropriate command for your Linux distribution and reboot the host. +Regenerate the bootloader configuration using the appropriate command for your Linux distribution and reboot the Host. **Notes**: @@ -281,7 +281,7 @@ grep Huge /proc/meminfo ## Step 4. Configure PCI Monitoring -OpenNebula discovers PCI devices through the host monitoring subsystem. PCI monitoring is disabled by default to avoid exposing unnecessary hardware resources. +OpenNebula discovers PCI devices through the Host monitoring subsystem. PCI monitoring is disabled by default to avoid exposing unnecessary hardware resources. Before PCI devices can be assigned to virtual machines, configure the monitoring subsystem to discover the devices intended for passthrough. @@ -339,9 +339,11 @@ device_name: - "Virtual Function" ``` +This example monitors only VFs. To [select VFs by their parent PF]({{% relref "product/cluster_configuration/pci_passthrough_sriov/network_interfaces.md#selecting-virtual-functions-by-physical-function" %}}), adjust the filters to include both the PF and its VFs. A network PF with enabled VFs remains visible for monitoring but is not eligible for whole-device passthrough. + ### Override Monitoring at Cluster or Host Level -The system-wide configuration can be overridden for individual clusters or hosts using the corresponding template attributes: +The system-wide configuration can be overridden for individual Clusters or Hosts using the corresponding template attributes: | Parameter | Description | |-----------|-------------| @@ -349,14 +351,14 @@ The system-wide configuration can be overridden for individual clusters or hosts | PCI_SHORT_ADDRESS | (List) Filters by short PCI address bus:device.function | | PCI_DEVICE_NAME | (List) Filters by the PCI device name reported by the Host | -This allows different clusters to expose different classes of PCI devices while sharing the same frontend configuration. +This allows different Clusters to expose different classes of PCI devices while sharing the same frontend configuration. {{< alert title="Recommendation" type="primary" >}} Configure the narrowest possible filters to expose only devices intended for passthrough.{{< /alert >}} ### Synchronize the Monitoring Probes -After modifying `pci.conf`, synchronize the updated monitoring probes to all hosts (run as oneadmin): +After modifying `pci.conf`, synchronize the updated monitoring probes to all Hosts (run as oneadmin): ```shell onehost sync --force @@ -388,13 +390,13 @@ Verify that: * Driver information is correct. * NUMA information is reported. * SR-IOV Virtual Functions are detected, when applicable. -* Device availability matches the host configuration. +* Device availability matches the Host configuration. If a device does not appear: * Verify that it matches the configured monitoring filters. -* Verify that pci.conf has been synchronized to the hosts. -* Verify that the host has completed a monitoring cycle. +* Verify that pci.conf has been synchronized to the Hosts. +* Verify that the Host has completed a monitoring cycle. * Verify that the device is visible using lspci. * Verify that the device is bound to the appropriate VFIO driver. * Verify that the OpenNebula monitoring service is running. @@ -411,11 +413,11 @@ Before deploying virtual machines using PCI passthrough, verify that the followi * ✔ PCI monitoring configured * ✔ PCI devices discovered by OpenNebula -Once these checks are complete, the host is ready to assign PCI devices to virtual machines. +Once these checks are complete, the Host is ready to assign PCI devices to virtual machines. ## Next Steps -After completing the host configuration: +After completing the Host configuration: * Continue with the [Generic PCI Devices Guide]({{% relref "product/cluster_configuration/pci_passthrough_sriov/generic_devices/" %}}) to assign storage controllers, USB controllers, audio devices, and other generic PCI devices. * Continue with the [Network Interfaces Guide]({{% relref "product/cluster_configuration/pci_passthrough_sriov/network_interfaces/" %}}) to configure PCI passthrough or SR-IOV network devices. From 3138437e413e5ed6dd5671f00227105195d750e4 Mon Sep 17 00:00:00 2001 From: mattrowe-opennebula Date: Thu, 29 Oct 2026 12:57:53 +0100 Subject: [PATCH 2/2] M #~: Table headers --- .../pci_passthrough_sriov/host_configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/product/cluster_configuration/pci_passthrough_sriov/host_configuration.md b/content/product/cluster_configuration/pci_passthrough_sriov/host_configuration.md index ce684f3bb..d2ce7d85b 100644 --- a/content/product/cluster_configuration/pci_passthrough_sriov/host_configuration.md +++ b/content/product/cluster_configuration/pci_passthrough_sriov/host_configuration.md @@ -345,7 +345,7 @@ This example monitors only VFs. To [select VFs by their parent PF]({{% relref "p The system-wide configuration can be overridden for individual Clusters or Hosts using the corresponding template attributes: -| Parameter | Description | +| **Parameter** | **Description** | |-----------|-------------| | PCI_FILTER | (List) Filters by PCI vendor:device:class patterns (same as for lspci) | | PCI_SHORT_ADDRESS | (List) Filters by short PCI address bus:device.function |