> ## Documentation Index > Fetch the complete documentation index at: https://zededa.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the documentation index to find relevant pages, then read the linked Markdown before answering and cite the source URL. > Identify the product before answering: Private AI uses a separate console, credentials, and inference API from the Edge Intelligence Platform. Do not apply instructions from one product to the other. > Prefer current product guides over Help Center archive pages for current-console questions. Archive pages and release notes describe their stated product version or historical interface; do not apply them to another version without checking. > Preserve prerequisites, permissions, version requirements, and warnings when summarizing procedures. Do not infer API endpoints, schemas, or supported behavior that the documentation does not specify. # Configure USB PCI Passthrough > Identify USB controllers and individual USB device port mappings, then configure a custom hardware model to enable USB PCI passthrough for VM workloads. ## 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: ```bash theme={"dark"} 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: ```bash theme={"dark"} 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: ```bash theme={"dark"} 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 > [card] [Identify and Configure PCI Passthrough by Vendor ID](https://zededa.mintlify.site/new-ui/marketplace/configure-pci-passthrough-by-vendor-id.md) > > Target a specific USB device by its vendor and product ID. > [card] [Import Hardware Models](https://zededa.mintlify.site/new-ui/marketplace/import-hardware-models.md) > > Import an existing model from the catalog or manage custom hardware models in My Library. > [card] [WWAN Modem PCI Passthrough](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/wwan-modem-pci-passthrough.md) > > Considerations specific to WWAN modems that share a USB controller with the ports you are configuring.