Skip to main content

​
Introduction

USB passthrough gives a virtual machine (VM) direct access to a specific USB device connected to a node. When multiple USB devices of the same type are connected, you can target a specific device by its vendor ID and product ID (the pair of identifiers assigned by the device manufacturer). This article explains how to find a USB device’s vendor and product ID using lsusb on an EVE-OS (Edge Virtualization Engine) node, how to add the device as a USB Device I/O member in a custom hardware model, and what the GUI supports versus what requires the API. For the full workflow to identify USB controllers and configure USB PCI passthrough, see Configure USB PCI Passthrough.

​
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.
  • lsusb is available on the node.
  • You have an existing custom hardware model in the catalog, or you will create one as part of this procedure. See Import Hardware Models.

​
Identify the USB Device by Vendor and Product ID

Every USB device exposes a vendor ID (VID) and product ID (PID) that uniquely identify its manufacturer and device type. Use lsusb to list connected USB devices and locate the correct IDs.
  1. Connect to the EVE-OS node via SSH or the console.
  2. Run the following command to list all connected USB devices:
  3. Review the output. Each line follows this format:
    For example:
    In this example:
    • 045e is the vendor ID (Microsoft Corp.).
    • 0823 is the product ID (Classic IntelliMouse).
    • Bus 003 Device 033 is the current bus and device address (these may change across reboots).
  4. Record the vendor ID and product ID for the target device.
  5. To confirm the physical port the device is connected to, run the following command to show the USB tree with port mappings:
    Locate the device by its vendor ID and product ID in the tree output to identify which port it occupies.

​
Add the Device to a Hardware Model

After identifying the USB device, add it as a USB Device I/O member in a custom hardware model. The hardware model GUI uses physical and logical labels to identify the device, not vendor or product IDs directly. This step requires a cluster or CSP administrator role; only cluster and CSP administrators can create hardware models. When naming labels, include the vendor ID and product ID in the physical or logical label so the device remains identifiable in the UI.
  1. In the sidebar, select Marketplace.
  2. Select Catalog.
  3. Select the Hardware filter tab.
  4. Select an existing hardware model to update, or select Create Model to create a new one. For instructions on creating a hardware model, see Import Hardware Models.
  5. In the I/O Members section, select Add I/O.
  6. Set the Adapter Type to USB Device.
  7. In the Physical label field, enter a label that identifies the physical port and device. Include the vendor ID and product ID for reference. For example:
  8. In the Logical label field, enter the name that EVE-OS uses to identify this adapter. For example:
  9. Optionally, set Assign group to group this adapter with related adapters.
  10. Select Create to save the hardware model.

​
Label-based identification

The Create Model dialog does not have vendor ID or product ID input fields. The GUI identifies USB Device adapters by their physical and logical labels. When assigning the hardware model to a node, EVE-OS matches the USB Device entry to a connected device by port position, not by vendor ID. Vendor ID-level filtering (the usbproduct field) is available through the ZEDEDA API and ZCLI for advanced use cases where you need to restrict passthrough to a specific vendor and product combination regardless of port position. Contact your ZEDEDA account team for API documentation.

​
Caveats

  • USB hubs are not supported for passthrough. You cannot pass through a USB hub device itself. Pass through the individual devices connected downstream from the hub.
  • Port numbers might differ between USB 2.0 and USB 3.0. The same physical port on a device might appear as separate bus:port addresses depending on which USB version the device negotiates. Identify both mappings if you need version-specific passthrough.
  • USB passthrough requires QEMU. This feature is only supported on VM-type edge containers using the QEMU hypervisor (the open-source machine emulator used by EVE-OS for VM workloads). Container and unikernel workloads do not support USB passthrough.
  • Thunderbolt and USB4 are not supported. Devices connected via Thunderbolt or USB4 ports cannot be passed through using this method.
  • Device address is not stable across reboots. The Bus and Device numbers shown by lsusb might change when the node reboots or when devices are reconnected. Use port position (from lsusb -tv) rather than device address for reliable identification.
  • Changes to a hardware model apply to all nodes that use it. Updates to a hardware model are automatically reflected on every node in the enterprise that references that hardware model. Test changes in a lab environment before applying them to production nodes.

​
Next Steps

Configure USB PCI Passthrough

The full procedure to identify USB controllers and configure USB Device splitting for individual port passthrough.

Import Hardware Models

Import an existing model from the catalog or create a custom hardware model from scratch.