Configure USB PCI Passthrough

​

Introduction

PCI passthrough gives a virtual machine (VM) direct, exclusive access to a physical hardware device on the node. For USB devices, PCI passthrough is configured at the hardware model level by adding USB adapter entries that EVE-OS (Edge Virtualization Engine) enforces when the hardware model is assigned to a node. EVE-OS supports two modes of USB passthrough:

• USB Controller passthrough passes through an entire USB host controller and all devices connected to it. All physical ports on that controller become exclusively available to the VM.
• USB Device passthrough (also called USB Device splitting) passes through individual USB ports independently, letting you assign different ports to different VMs.

This article explains how to identify the USB controller and per-port device mappings on an EVE-OS node, and how to create a custom hardware model with the correct USB adapter entries in Edge Infrastructure Services.

​

Prerequisites

• You have a cluster or CSP administrator role. Creating custom hardware models is available to cluster and CSP administrators only. Enterprise users with SysAdmin or SysManager roles can import existing catalog models but cannot create or edit hardware models.
• The target node runs EVE-OS and is enrolled in Edge Infrastructure Services.
• You have SSH access to the node, or access to the EVE-OS console.
• lspci and lsusb are available on the node.
• The VM workload uses the QEMU hypervisor (the open-source machine emulator used by EVE-OS for VM-type edge containers). USB passthrough is only supported on QEMU-based VM edge containers.

​

Considerations

Review these points before configuring USB passthrough.

• Controller passthrough includes all ports. If you configure a USB Controller for passthrough, every USB port on that controller is passed through together. No other VM or the host can use those ports while passthrough is active.
• USB Device splitting allows per-port assignment. To assign individual ports to different VMs, add separate USB Device I/O members for each port rather than using a USB Controller entry.
• WWAN modems might share a USB controller. If a WWAN modem is connected through the same USB controller you intend to pass through, that modem will also be passed through to the VM. If the WWAN modem is already in use, assigning the USB Controller simultaneously causes a PCI passthrough conflict error.
• IOMMU groups affect PCI passthrough. IOMMU groups are sets of devices the CPU and chipset group together for memory isolation. The CPU and chipset group PCIe devices into IOMMU groups. Devices in the same IOMMU group are passed through together when using PCI passthrough. Verify the IOMMU group membership of the USB controller before assigning it.
• Changes apply to all nodes that reference the hardware model. Updates to a hardware model are automatically reflected on every node in the enterprise that uses that hardware model. Test configuration changes in a lab environment before applying them to production nodes.
• USB hubs cannot be passed through. You cannot pass through a USB hub. Pass through individual downstream devices or use USB Device splitting by port.
• Thunderbolt and USB4 are not supported. Devices connected via Thunderbolt or USB4 ports cannot be passed through using this method.
• USB passthrough requires QEMU. This feature is not supported for container or unikernel workload types.

​

Identify the USB Controller

Use lspci to locate the USB host controller’s PCI address and IOMMU group on the node.

1. Connect to the EVE-OS node via SSH or the console.
2. Run the following command to list PCI devices with driver and IOMMU group information:
   lspci -kv
   
3. Locate the USB controller entry in the output. It is typically labeled USB controller or xHCI Host Controller. For example:
   00:14.0 USB controller: Intel Corporation 200 Series/Z370 Chipset Family USB 3.0 xHCI Controller
           Kernel driver in use: xhci_hcd
           Kernel modules: xhci_pci
   
4. Record the PCI address (for example, 00:14.0) and any IOMMU group information shown. If IOMMU group details are not shown by lspci, check /sys/kernel/iommu_groups/ on the node.
5. Note any other devices that share the same IOMMU group as the USB controller, as they will be passed through together.

​

Identify USB Device Bus:Port Mappings

USB ports have separate mappings for USB 2.0 and USB 3.0 connections. Even a single physical port on the hardware may appear as two distinct bus:port addresses depending on which USB version the connected device uses. Identify both mappings for each physical port you want to pass through independently.

​

List USB devices

1. Run the following command to list connected USB devices with their bus and device addresses:
   lsusb
   
   For example, output may show:
   Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
   Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
   Bus 001 Device 002: ID 0bda:5411 Realtek Semiconductor Corp. USB2.0 Hub
   
2. Connect a device to each physical port you want to map, one at a time, and run lsusb after each connection to identify which bus and device address the port uses.

​

Find the port number for each device

1. Run the following command to display the USB device tree with port numbers:
   lsusb -tv
   
2. Locate each device in the tree. The output shows the port number for each device under its parent hub. For example:
   /:  Bus 02.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/6p, 10000M
       |__ Port 3: Dev 2, If 0, Class=Mass Storage, Driver=usb-storage, 5000M
   
   In this example, the device is on Bus 2, Port 3 at USB 3.0 speed (5000M).
3. Repeat for USB 2.0 by connecting a USB 2.0 device or checking which bus the port also appears on. Each physical port typically has a USB 2.0 address on one bus and a USB 3.0 address on another.
4. Record the bus number and port number for each physical port at each USB version. For example, for a device with two physical USB 3.2 ports:

   Physical port	USB 2.0 bus:port	USB 3.0 bus:port
   Port 1	Bus 1, Port 2	Bus 2, Port 2
   Port 2	Bus 1, Port 3	Bus 2, Port 3

​

Create a Hardware Model with USB Passthrough

After identifying the USB controller and port mappings, create a custom hardware model from the Catalog view with the corresponding USB adapter entries. The Create Model button is available in the Catalog view only and only to cluster and CSP administrators.

1. In the sidebar, select Marketplace.
2. Select Catalog.
3. Select the Hardware filter tab.
4. Select the Create Model floating action button.
5. Complete the fields:

   Field	Description
   Name	A unique identifier for the hardware model. Required.
   Title	A display name for the model. Required.
   Brand	Select an existing brand. Required.
   Architecture	AMD64 or ARM64, matching the node’s architecture.
   CPUs	Number of CPUs on the hardware.
   Memory GB	Memory in gigabytes.
   Storage GB	Storage in gigabytes.

6. To add the USB controller, select Add I/O and complete the fields:

   Field	Value
   Adapter Type	USB Controller
   Physical label	A label identifying the controller, for example usb-controller-pci-00-14-0.
   Logical label	The name EVE-OS uses to identify this adapter, for example usb-controller-0.
   Assign group	Optional. Group this adapter with related adapters if required.

7. To add individual USB Device entries for each physical port and USB version, select Add I/O for each entry and complete the fields:

   Field	Value
   Adapter Type	USB Device
   Physical label	A label identifying the specific bus and port, for example usb-bus1-port2 for the USB 2.0 mapping of physical port 1.
   Logical label	A descriptive name, for example usb-port1-20 (for USB 2.0) or usb-port1-30 (for USB 3.0).
   Assign group	Optional.

   Add one USB Device entry for the USB 2.0 mapping and one for the USB 3.0 mapping of each physical port.
8. Select Create to save the hardware model.

The model is created with the Global origin type and appears in the catalog. Tenant enterprises can then import it into their own My Library and assign it to nodes.

​

What the GUI supports

The Create Model dialog identifies adapters by physical and logical labels. It does not have fields for PCI address, IOMMU group, or usbaddr values. EVE-OS uses the label values you enter to match adapters when the hardware model is assigned to a node. Use descriptive labels that capture the bus, port, and USB version so the entries remain identifiable. For advanced configuration using PCI addresses or usbaddr fields, use the ZEDEDA API or ZCLI.

​

Verify the Configuration

After creating the hardware model, verify that the I/O adapter entries are correct.

1. In My Library, select the Hardware filter tab and open the hardware model.
2. Select the Adapters tab on the hardware model detail page.
3. Confirm that the adapter table shows:
   • One USB Controller entry.
   • One USB Device entry per physical port per USB version.
4. Review the physical and logical labels to confirm they match the bus:port mappings you recorded.

If you need to correct an entry, edit the hardware model and update the relevant I/O member fields.

​

Next Steps