XCP-ng USB Passthrough

Feb 13, 2022 · 3 mins read
xcp-ng virtualization
XCP-ng USB Passthrough

In the video below, we show you how to enable USB passthrough for a VM in XCP-ng

The first thing we need to do is to find our USB device’s UUID

Depending on the device you may need to edit the USB policy

Next we need to enable passthrough for the device

Once that’s done we need the Group UUID for the device UUID

Next we need the VM’s UUID

With the Group UUID and VM UUID we then attach the USB device to the VM, BUT, this should be done when the VM is powered off

In contrast, to detach a USB device, the VM must be powered on

NOTE: The USB device’s UUID does not survive a reboot of the hypervisor requiring the USB device to be detached from the VM before the hypervisor reboots, then attached when it is back in operation

Useful links:
https://xcp-ng.org/docs/cli_reference.html#xe-command-reference
https://support.citrix.com/article/CTX235042
https://support.citrix.com/article/CTX119722

Steps taken

  1. Find the UUID
    SSH as root into the hyerpvisor the USB device is plugged into and will be running the VM Run the command
     xe pusb-list
    Then note down the device’s UUID, for example we get
     dc9cc587-af5b-4ada-8b67-677040f24570

  2. Update the USB Policy if the device is being blocked
    If it does not show in the list of devices, run the command
      lsusb
    Look for the device’s Vendor ID and Product ID, for example
     Bus 001 Device 010: ID 1cf1:0030 Dresden Elektronik
    For the above the VID is 1cf1 and the PID is 0030
    Edit the USB policy to allow the device to be used
     nano /etc/xensource/usb-policy.conf

     # USB Hubs (class 09) are always denied, independently of the rules in this file
     ALLOW:vid=1cf1 pid=0030 # Dresden Elektronik, ConBee II
     DENY: vid=17e9 # All DisplayLink USB displays

    In the above example we added a new a line after the comments and above the first DENY entry to allow our USB device to be used
    Run the following command to get the hypervisor UUID
     xe host-list
    For example we get, 6dfa4a8d-a1fc-4934-957a-823fe49b3674
    Then run the following command to parse the config file on that host
     xe pusb-scan host-uuid=6dfa4a8d-a1fc-4934-957a-823fe49b3674
    Now run a scan for USB devices with debug enabled
     /opt/xensource/libexec/usb_scan.py -d
    This should return a list of allowed devices, which includes the one we added
    Now we can find the UUID of the device
     xe pusb-list

  3. Enable paassthrough for the device
    We need to run a command to set the enable passthrough parameter, for example
     xe pusb-param-set uuid=dc9cc587-af5b-4ada-8b67-677040f24570 passthrough-enabled=true

  4. Find the Group UUID
    We need the group UUID to attach the USB device so run the following command to find that
     xe usb-group-list PUSB-uuids=dc9cc587-af5b-4ada-8b67-677040f24570
    For example we get, 2a78463d-9868-484c-bfe9-a7a90197d512

  5. Find the VM UUID
    To attach a USB device we need to know the VM’s UUID. To find that run the following command
     xe vm-list
    You should be able to identify the VM by it’s name
    For example the UUID might be, 481cfa4c-5d58-45aa-9621-1e1ec7726022

  6. Attach the USB device
    With the group UUID and VM UUID, we can now attach the device by running a final command
    BUT make sure the VM is turned off first
     xe vusb-create usb-group-uuid=2a78463d-9868-484c-bfe9-a7a90197d512 vm-uuid=481cfa4c-5d58-45aa-9621-1e1ec7726022
    This returns a VUSB UUID for example 70fee3d2-d442-4d21-91e5-788035017d2f

Power on the device and check the USB device is recognised. If not it may need drivers installing

Maintenance
The device’s UUID may not survive a reboot of the hypervisor and the VM will be missing the USB device as a result
Make sure to detach the USB device first
 xe vusb-unplug uuid=70fee3d2-d442-4d21-91e5-788035017d2f
 xe vusb-destroy uuid=70fee3d2-d442-4d21-91e5-788035017d2f
Power off the VM, reboot the hypervisor and repeat the above steps to re-attach the device with its new UUID

Sharing is caring!