Skip to content

USB Passthrough & Device Mappings

A VM can use USB devices plugged into its host, such as license dongles, security keys or serial adapters. A device mapping gives a PCI or USB device a name and says where it is on every host that has one, so HA and migration know which hosts the VM can run on.

Attach a USB device to a VM

  1. Open the VM → Configure → Passthrough Devices → Manage Devices….
  2. Under USB devices, tick devices from the list of those plugged into the VM's host. For a device that isn't plugged in yet, type its vendor:product ID in Add by ID (for example 1050:0407).
  3. Save. The result shows in Recent Tasks.

USB devices can be added and removed while the VM runs.

Device mappings

Use a mapping when the same kind of device sits in more than one host, for example the same GPU model in each host of a cluster, or a dongle you might move between hosts.

Create a mapping

  1. Settings → Device Mappings → + Add mapping.
  2. Give it a Name (for example RTX A2000), pick PCI or USB, and add an optional description.
  3. Tick each host that has the device and enter its address there: a PCI address such as 0000:01:00.0, or a USB ID such as 1050:0407. Find devices lists what the host has, so you can pick from it.
  4. Save.

The list shows each mapping's hosts and addresses and how many VMs use it.

Attach a mapping to a VM

Configure → Passthrough Devices → Manage Devices…, then tick it under Device mappings on this host. Only mappings that include the VM's current host are listed.

  • PCI mappings need the VM powered off to attach or remove.
  • A PCI mapping can be given to one VM per host.

How HA and migration use it

  • HA only restarts the VM on a surviving host that has the device, and points it at that host's address. If no surviving host has it, the failover for that VM is skipped and you get an alert.
  • Migration to a host without the device is refused. A cold migration re-points the device to the new host's address automatically.
  • The load balancer (CRS) never moves VMs that have PCI or USB devices attached.
  • Live migration of a VM with passthrough devices isn't possible. Migrate it powered off instead.

See also