How to configure USB Passthrough with XenServer

How to configure USB Passthrough with XenServer

book

Article ID: CTX235042

calendar_today

Updated On:

Description

This article describes the method to configure USB Pass-through with XenServer.
 

Instructions

XenServer 7.5 supports passing through individual, physical USB devices to a VM, instead of the whole USB controller.  This allows users to use the physical USB device as a local USB device inside the VM. 
In this article, we provide steps to configure USB Pass-through with XenServer. Before proceeding, pay attention to the following requirements and restrictions:
  • USB pass-through is supported only on the following HVM guests:
    • Windows
      •   Windows 7 SP1
      •   Windows 8.1
      •   Windows 10
      •   Windows Server 2008 SP2
      •   Windows Server 2008 R2 SP1
      •   Windows Server 2012
      •   Windows Server 2012 R2
      •   Windows Server 2016
    •    Linux
      •   RHEL 7
      •   Debian 8
  • XenServer 7.5 and above
  • XenServer Enterprise Edition (or access to XenServer through a XenDesktop/XenApp entitlement)
  • Ensure that the USB device to pass-through is trustworthy and can work stably in normal Linux environment (for example, CentOS 7). Plugging in untrustworthy USB devices to your computer may put your computer at risk. USB devices with modifiable behavior should only be assigned to trustworthy guest VMs.
  • BIOS must not be booted from USB devices.
  • USB pass-through must use qemu-upstream as the backend.
  • USB pass-through supports a maximum of 6 USBs to be passed through to a single VM.
  • Snapshot/Suspend/ Pool Migrate/ Storage Migrate operations are not supported when USB device is passed through to VM.
  • USB device pass through is blocked in a VM if HA is enabled on the pool and the VM has restart priority as “Restart”. The USB attach button is disabled and the following message is displayed: 'The virtual USB cannot be attached because the VM is protected by HA'. When configuring HA for a pool, if a VM is not agile, the “Restart” option is disabled with the following tooltip: 'The VM has one or more virtual USBs. Restart cannot be guaranteed'.

How to configure USB Pass-through with XenServer

Customers can configure USB Pass-through using XenCenter or the xe CLI, please perform the following steps to configure.

  • To configure USB Pass-through using XenCenter.

  1. Plug the USB devices to the XenServer host with Enterprise Edition license (or access to XenServer through a XenDesktop/XenApp entitlement). Then the USB tab appears in XenCenter with USB devices listed.
  1. ​Enable passthrough for a specific USB device.
  • To enable by using XenCenter, go to USB tab > choose the specific USB device > click Enable passthrough > choose Yes, Enable passthrough on the pop up window:
  1. Shut down the target guest VM that you want to pass the USB device through since hot plug is not supported.
  2. Attach the USB device to the VM.
  • To attach by using XenCenter, right click the VM, go to Properties > go to USB >  click Attach > choose the specific USB device you want to attach > click Attach:
And click OK to finish.

Note that you can attach multiple USB devices to a single VM, the maximum number of USB devices supported is 6.
  1. Start the VM to pass-through the USB device to the VM.
Note that you may need to install the device driver inside the VM for the device to work properly. With proper driver, you’ll be able to see the device from system Device Manager working properly.

User-added image

  • To enable by using xe CLI

  1. Plug the USB devices to the XenServer host with Enterprise Edition license (or access to XenServer through a XenDesktop/XenApp entitlement). 
  2. Run following command to enable passthrough for a specific USB device
xe pusb-param-set uuid=<pusb_uuid> passthrough-enabled=<true/false>

Check the following as an example, firstly get pusb uuid from command pusb-list and then enable passthrough through command pusb-param-set.

[root@xenserver ~]# xe pusb-list
uuid ( RO)            : 9c14c8b3-f30b-b5b8-2b01-201f703d2497
            path ( RO): 2-1.6
       vendor-id ( RO): 1f75
     vendor-desc ( RO): Innostor Technology Corporation
      product-id ( RO): 0903
    product-desc ( RO):
          serial ( RO): 000000000000000244
         version ( RO): 2.10
     description ( RO): Innostor Technology Corporation_000000000000000244


uuid ( RO)            : 10fbec89-4472-c215-5d55-17969b473ee6
            path ( RO): 2-1.1
       vendor-id ( RO): 0781
     vendor-desc ( RO): SanDisk Corp.
      product-id ( RO): 5591
    product-desc ( RO):
          serial ( RO): 4C530001151223117134
         version ( RO): 2.10
     description ( RO): SanDisk Corp._4C530001151223117134


[root@xenserver ~]# xe pusb-param-set uuid=10fbec89-4472-c215-5d55-17969b473ee6 passthrough-enabled=true
  1. Shut down the target guest VM that you want to pass the USB device through since hot plug is not supported.
  2. Attach the USB device to the VM, run the following command:
xe vusb-create usb-group-uuid=<usb_group_uuid> vm-uuid=<vm_uuid>

Check the following as an example, firstly get usb-group uuid from command usb-group-list and then attach the device to target VM through command vusb-create.

[root@xenserver ~]# xe usb-group-list PUSB-uuids=10fbec89-4472-c215-5d55-17969b473ee6
uuid ( RO)                : 1f731f6a-6025-8858-904d-c98548f8bb23
name-label ( RW): Group of 0781 5591 USBs
name-description ( RW):
...
[root@xenserver ~]# xe vusb-create usb-group-uuid=1f731f6a-6025-8858-904d-c98548f8bb23 vm-uuid=4feeb9b2-2176-b69d-b8a8-cf7289780a3f
aac4a96f-3fd9-0150-7138-fbd5a80e068a
  1. Start the target guest VM.
xe vm-start uuid=<vm_uuid>.

Detach the USB device from the VM

You can detach the USB device from the VM when VM is running:

  • To detach by using XenCenter, right click the VM, go to Properties > go to USB >  choose the USB device you want to detach > click Detach and click Yes on the pop up window:
Click OK to finish.
  • To detach by using xe CLI, run the following commands:
xe vusb-unplug uuid=<vusb_uuid>  (Unplugs USB from VM)
xe vusb-destroy uuid=<vusb_uuid> (Removes the VUSB list from VM)
Check the following as an example:
[root@xenserver ~]# xe vusb-unplug uuid=79d2953d-839d-e26f-501c-885b728a4f70
[root@xenserver ~]# xe vusb-destroy uuid=79d2953d-839d-e26f-501c-885b728a4f70
 

Additional Information

How to troubleshoot XenServer USB Passthrough related issues   


At times the default Emulation of USB parameter of VMs is set to False.So, during those cases, we will not be able to start the VMs after attaching the USB.
The VM start will fail with error " The server failed to handle your request, due to an internal error.  The given message may give details useful for debugging the problem.
message: xenopsd internal error: Device_common.QMP_Error(26, "{\"error\":{\"class\":\"GenericError\",\"desc\":\"Bus 'usb-bus.0' not found\",\"data\":{}},\"id\":\"qmp-000018-26\"}")   

To fix this you need to run the below command and then attach the USB.

xe vm-param-set uuid=<vm_uuid> platform:usb=True 



 
Powered by Wolken Software