How to troubleshoot XenServer USB Passthrough related issues
Article ID: CTX235040
Updated On:
Description
This article describes common error scenarios as well as general troubleshooting tips for XenServer USB Passthrough feature.
Instructions
Here are some common error scenarios you might encounter while using USB Passthrough with XenServer.Common error scenario #1: The USB tab doesn’t appear on XenCenter after plugging USB devices on XenServer host.
USB Passthrough feature requires XenServer Enterprise Edition (or access to XenServer through a XenDesktop/XenApp entitlement), ensure proper license is used. Otherwise, the USB tab won’t appear.Common error scenario #2: Some USB devices aren’t listed under XenCenter USB tab after plugging them on XenServer host.
XenServer introduces pusb-scan to scan the USB devices available on the host, which calls USB scanner script (/opt/xensource/libexec/usb_scan.py) to get all USB information of the system and parses the USB policy file (/etc/xensource/usb-policy.conf) to get the list of USB devices.Some of the USB devices are blocked by the USB policy file, for example, keyboard, USB hub, etc. Check the policy file (/etc/xensource/usb-policy.conf) for detailed rules. If a USB device is blocked by the USB policy file, then you’ll not be able to view it on XenServer USB tab.
Perform the following steps to check if your USB device is blocked by USB policy rules:
- Ensure the USB device is enumerated on XenServer Control Domain by running command lsusb, locate the USB device and get its product-id: vendor-id information.
[root@xenserver ~]# lsusb
Bus 001 Device 002: ID 1a40:0101 Terminus Technology Inc. Hub
Bus 001 Device 003: ID 0424:2514 Standard Microsystems Corp. USB 2.0 Hub
Bus 005 Device 002: ID 0624:0294 Avocent Corp. Dell 03R874 KVM dongle
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 005 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 006 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 007 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 008 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 001 Device 004: ID 090c:1000 Silicon Motion, Inc. - Taiwan (formerly Feiya Technology Corp.) Flash Drive
Bus 001 Device 006: ID 13fe:4200 Kingston Technology Company Inc.
Bus 001 Device 005: ID 1a40:0101 Terminus Technology Inc. Hub
Bus 001 Device 008: ID 090c:3259 Silicon Motion, Inc. - Taiwan (formerly Feiya Technology Corp.)
Bus 001 Device 002: ID 1a40:0101 Terminus Technology Inc. Hub
Bus 001 Device 003: ID 0424:2514 Standard Microsystems Corp. USB 2.0 Hub
Bus 005 Device 002: ID 0624:0294 Avocent Corp. Dell 03R874 KVM dongle
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 005 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 006 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 007 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 008 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 001 Device 004: ID 090c:1000 Silicon Motion, Inc. - Taiwan (formerly Feiya Technology Corp.) Flash Drive
Bus 001 Device 006: ID 13fe:4200 Kingston Technology Company Inc.
Bus 001 Device 005: ID 1a40:0101 Terminus Technology Inc. Hub
Bus 001 Device 008: ID 090c:3259 Silicon Motion, Inc. - Taiwan (formerly Feiya Technology Corp.)
- Manually run USB scanner script (usb_scan.py) with -d option to get more diagnostic information:
[root@xenserver ~]# /opt/xensource/libexec/usb_scan.py -d
[{"product-desc": "Flash Drive", "product-id": "1000", "description": "Silicon Motion, Inc. - Taiwan (formerly Feiya Technology Corp.)_Flash Drive", "vendor-desc": "Silicon Motion, Inc. - Taiwan (formerly Feiya Technology Corp.)", "version": "2.00", "vendor-id": "090c", "path": "1-1.1", "serial": ""}, {"product-desc": "", "product-id": "4200", "description": "Kingston Technology Company Inc._070D77B14E25DF17", "vendor-desc": "Kingston Technology Company Inc.", "version": "2.00", "vendor-id": "13fe", "path": "1-1.2", "serial": "070D77B14E25DF17"}, {"product-desc": "", "product-id": "4200", "description": "Kingston Technology Company Inc._070D77B15EED0F33", "vendor-desc": "Kingston Technology Company Inc.", "version": "2.00", "vendor-id": "13fe", "path": "1-1.3", "serial": "070D77B15EED0F33"}, {"product-desc": "", "product-id": "4200", "description": "Kingston Technology Company Inc._070D77B24DED0F62", "vendor-desc": "Kingston Technology Company Inc.", "version": "2.00", "vendor-id": "13fe", "path": "1-1.4", "serial": "070D77B24DED0F62"}, {"product-desc": "", "product-id": "4200", "description": "Kingston Technology Company Inc._070D77B07225DF51", "vendor-desc": "Kingston Technology Company Inc.", "version": "2.00", "vendor-id": "13fe", "path": "1-3.2.2", "serial": "070D77B07225DF51"}, {"product-desc": "", "product-id": "4200", "description": "Kingston Technology Company Inc._070D77B07025DF44", "vendor-desc": "Kingston Technology Company Inc.", "version": "2.00", "vendor-id": "13fe", "path": "1-3.2.3", "serial": "070D77B07025DF44"}]
[{"product-desc": "Flash Drive", "product-id": "1000", "description": "Silicon Motion, Inc. - Taiwan (formerly Feiya Technology Corp.)_Flash Drive", "vendor-desc": "Silicon Motion, Inc. - Taiwan (formerly Feiya Technology Corp.)", "version": "2.00", "vendor-id": "090c", "path": "1-1.1", "serial": ""}, {"product-desc": "", "product-id": "4200", "description": "Kingston Technology Company Inc._070D77B14E25DF17", "vendor-desc": "Kingston Technology Company Inc.", "version": "2.00", "vendor-id": "13fe", "path": "1-1.2", "serial": "070D77B14E25DF17"}, {"product-desc": "", "product-id": "4200", "description": "Kingston Technology Company Inc._070D77B15EED0F33", "vendor-desc": "Kingston Technology Company Inc.", "version": "2.00", "vendor-id": "13fe", "path": "1-1.3", "serial": "070D77B15EED0F33"}, {"product-desc": "", "product-id": "4200", "description": "Kingston Technology Company Inc._070D77B24DED0F62", "vendor-desc": "Kingston Technology Company Inc.", "version": "2.00", "vendor-id": "13fe", "path": "1-1.4", "serial": "070D77B24DED0F62"}, {"product-desc": "", "product-id": "4200", "description": "Kingston Technology Company Inc._070D77B07225DF51", "vendor-desc": "Kingston Technology Company Inc.", "version": "2.00", "vendor-id": "13fe", "path": "1-3.2.2", "serial": "070D77B07225DF51"}, {"product-desc": "", "product-id": "4200", "description": "Kingston Technology Company Inc._070D77B07025DF44", "vendor-desc": "Kingston Technology Company Inc.", "version": "2.00", "vendor-id": "13fe", "path": "1-3.2.3", "serial": "070D77B07025DF44"}]
- Check /var/log/user.log to get policy parse result, looking for “found matching rule” lines. Below log entries demonstrate the USB device (PID: 3259, VID:090c) being blocked by USB policy rule.
May 7 15:33:34 xrtuk-04-01 usb_scan.py DEBUG: policy check: 1-3.2.1
May 7 15:33:34 xrtuk-04-01 usb_scan.py DEBUG: check 1-3.2.1:1.0 props[vid] against {'vid': '17e9', 'allow': False}
May 7 15:33:34 xrtuk-04-01 usb_scan.py DEBUG: check 1-3.2.1:1.0 props[class] against {'class': '02', 'allow': False}
May 7 15:33:34 xrtuk-04-01 usb_scan.py DEBUG: check 1-3.2.1:1.0 props[pid] against {'pid': '3259', 'vid': '090c', 'allow': False}
May 7 15:33:34 xrtuk-04-01 usb_scan.py DEBUG: check 1-3.2.1:1.0 props[vid] against {'pid': '3259', 'vid': '090c', 'allow': False}
May 7 15:33:34 xrtuk-04-01 usb_scan.py DEBUG: found matching rule: {'pid': '3259', 'vid': '090c', 'allow': False}
May 7 15:33:34 xrtuk-04-01 usb_scan.py DEBUG: deny 1-3.2.1:1.0
If your USB device is blocked by USB policy rules and you want to allow it, you can manually edit the USB policy file (/etc/xensource/usb-policy.conf) to add an “ALLOW:” policy. Note the following:
May 7 15:33:34 xrtuk-04-01 usb_scan.py DEBUG: check 1-3.2.1:1.0 props[vid] against {'vid': '17e9', 'allow': False}
May 7 15:33:34 xrtuk-04-01 usb_scan.py DEBUG: check 1-3.2.1:1.0 props[class] against {'class': '02', 'allow': False}
May 7 15:33:34 xrtuk-04-01 usb_scan.py DEBUG: check 1-3.2.1:1.0 props[pid] against {'pid': '3259', 'vid': '090c', 'allow': False}
May 7 15:33:34 xrtuk-04-01 usb_scan.py DEBUG: check 1-3.2.1:1.0 props[vid] against {'pid': '3259', 'vid': '090c', 'allow': False}
May 7 15:33:34 xrtuk-04-01 usb_scan.py DEBUG: found matching rule: {'pid': '3259', 'vid': '090c', 'allow': False}
May 7 15:33:34 xrtuk-04-01 usb_scan.py DEBUG: deny 1-3.2.1:1.0
If your USB device is blocked by USB policy rules and you want to allow it, you can manually edit the USB policy file (/etc/xensource/usb-policy.conf) to add an “ALLOW:” policy. Note the following:
- USB Hubs (Class 09) are always denied, independently of the rules in usb-policy.conf.
- When you change the USB policy file, run command 'xe pusb-scan' to confirm the file can be parsed correctly and refresh the device list on XenCenter USB tab.
Common error scenario #3: Attaching USB device failed with error “The VM has too many VUSBs”.
- This happens because USB pass-through supports a maximum of 6 USB devices to be passed through to a single VM. Ensure no more than 6 USB devices are attached to the VM.
Common error scenario #4: USB device is attached to a VM but can’t be used inside the VM.
Perform the following steps to troubleshoot:- Ensure the USB device is passed through to the target VM.
- On supported Linux guest VMs, run command lsusb to enumerate all USB devices. If lsusb command is not installed, run yum install usbutils to install.
- On supported Windows guest VMs, check if the device can be displayed on the Device Manager.
If the USB device is not passed through to the target VM, check /var/log/xensource.log for possible causes.
- Ensure the USB driver is installed successfully:
- On supported Linux guest VMs, run command lsusb and lsusb -t to get device driver information. Check following as an example:
If no driver is used, the line will look like this:
|__ Port 1: Dev 2, If 0, Class=Video, Driver=, 480M
- On supported Windows guest VMs, check the device on Device Manager. If driver is not installed, the status would like the following:
If the USB device driver fails to install, check the system logs (Linux: messages, Windows: C:\windows\inf\setupapi.dev.log ) for possible causes and involve device vendor when necessary.
Troubleshooting Tips
New xe command lines
The XAPI toolstack (XenAPI) is extended to support this new feature, provides three new metadata related to PUSB (Physical USB Device), USB_group (Group of USB Device) and VUSB (Virtual USB Device). The available commands are listed as below, refer to xe help [command] for usage instructions.
For a general troubleshooting purpose, you can:
- Go through How to configure USB Passthrough with XenServer document to ensure the system requirements and configuration steps are correctly performed.
- Collect Server Status Report for further investigation, and look for “usb*”, “USB*” lines in /var/log/xensource.log and /var/log/user.log.
Issue/Introduction
This article describes common error scenarios as well as general troubleshooting tips for XenServer USB Passthrough feature.
Additional Information
Was this article helpful?
Yes
No
Powered by
