About a month back I had received an interesting tidbit from Darius Davis (VMware Engineer) after helping a customer solve an interesting problem and Darius thought this could be a useful blog post to share. Funny enough, a couple of weeks after that conversation, a simliar issue was being faced by another customer and luckily I was able to share with them the solution and also validate the specific configuration that was needed.
The customer that Darius was helping out had two VMs running on ESXi which they wanted to configure several passthrough devices. In addition to a PCI passthrough of a GPU, they also wanted to passthrough independent USB keyboard and mouse to each individual VM. PCI passthrough to a VM is nothing new but passing through a USB keyboard/mouse also known as Human Interface Devices (HID) to a VM is generally not expected. The physical ESXi host just assumes these type of USB devices are meant for it to consume.
In addition to HID USB devices, there are also Chip Card Interface Devices (CCID) USB devices like a smart card reader which customers may also want to passthrough to a VM. The latter use case was what I ended up helping the customer out with. To passthrough HID/CCID USB devices, the following steps are required which will include changes to the ESXi host.
Step 1 - Add the following two VM Advanced Settings for all USB CCID/HID devices that you wish to enable passthrough:
HID USB Devices:
usb.generic.allowHID = "TRUE"
usb.quirks.device0 = "0xXXXX:0xYYYY allow"
CCID USB Devices:
usb.generic.allowCCID = "TRUE"
usb.quirks.device0 = "0xXXXX:0xYYYY allow"
where 0xXXXX = vendorId and 0xYYYY = deviceId (e.g 0x03f0:0x0024) which was retrieved from the previous step
To list all USB devices and get their vendor and device ID, you can use the lsusb command found within the ESXi Shell and below is an example listing out both my USB Mouse and Keyboard.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
lsusb -v | grep -E '(^Bus|HID)' Bus 001 Device 001: ID 0e0f:8003 VMware, Inc. Root Hub Bus 002 Device 001: ID 0e0f:8003 VMware, Inc. Root Hub Bus 001 Device 003: ID 8087:0026 Intel Corp. Bus 001 Device 004: ID 0781:5591 SanDisk Corp. Ultra Flair Bus 001 Device 002: ID 05fe:0011 Chic Technology Corp. Browser Mouse iConfiguration 4 HID Mouse HID Device Descriptor: bcdHID 1.00 Bus 001 Device 005: ID 046d:c31d Logitech, Inc. Media Keyboard K200 HID Device Descriptor: bcdHID 1.10 HID Device Descriptor: bcdHID 1.10 |
Step 2 - We need to make the USB arbitrator service aware of these USB device quirks by adding the usb.quirks.deviceN string to /etc/vmware/config file. In my example above, I want to enable passthrough for both my Mouse and Keyboard device, so the following entries would be appended:
usb.quirks.device0 = "0x05fe:0x0011 allow"
usb.quirks.device1 = "0x046d:0xc31d allow"
Step 3 - Lastly, we need to add the following string to the ESXi boot option to disable the VMkernel from claiming HID USB devices.
CONFIG./USB/quirks=0xXXXX:0xYYYY::0xffff:UQ_KBD_IGNORE
where 0xXXXX = vendorId and 0xYYYY = deviceId (e.g 0x03f0:0x0024)
The easiest way to append this to the boot option is by editing /bootbank/boot.cfg rather than manually typing this during the initial boot up (SHIFT+O)
Note: This is not required for CCID devices or mouse devices as they are not claimed by ESXi
Step 4 - A system reboot of your ESXi host will be required for the changes to go into effect. Once your ESXi host is available, you can use the vSphere H5 Client or Embedded ESXi Host Client to attach the USB devices. For vCenter Server, click on "Add New Device" and select "Host USB Device" and for ESXi, click on "Add other device" and select "USB Device".
Thanks for sharing. So for additional devices you would increase deviceX number, like this:?
usb.quirks.device0 = “X:Y allow”
usb.quirks.device1 = “X:Y allow”
That’s correct
Is this method also conpatible with esxi 6.0 ?
Jeff,
I’m not sure, probably easiest to give it a try. I’m sure you know, 6.0 is already EOL and you or the customer should think about upgrading to a supported version 🙂
lsusb do not show any usb hid device in esxi 6.
Same here 🙁 ..cannot see hid devices with lsusb
Apologies for the delay, I was waiting to hear back from Engr. It looks like a few additional steps were required which I’ve manually confirmed myself. I’ve also included an example of using
lsusb
to help list out the HID/CCID devices. Please see the updated articleHow do i identify which usb port in esxi is which port i use in linux ? I passed thru all usb ports to a vm for home automation donhle but the dongle only uses 1 port. Can’t figure out whats what.
I’ve updated the article with an example
lsusb
command, see if that helpslsusv -v returns nothing on mine…?
Where exactly in boot.cfg does the string in step 3 go?
Also, which vendorID & deviceID go in there? That of the keyboard, mouse, both? If both, then multiple lines are used (since 2 different xxxx:yyyy values)?
Maybe post an example using your keyboard/mouse from earlier?
Which step are you referring to? The instructions are detailed in each step which includes where boot.cfg is located 🙂
Thanks for the quick reply.
STEP 3
I know where boot.cfg is located, but _WHERE_ in boot.cfg does that string go?
Also, it’s unclear what vendor/device id’s are used?
Where is 0x03f0:0x0024 coming from? You reference a previous step but I don’t see it.
Re: boot.cfg – This is the kernelopt line just like any other kernel setting. Assuming readers have basic understanding of ESXi
Re: Vendor/Device ID – Its immediately below the section where it says how to retrieve these IDs via lsusb
My current kernelopt looks like this:
kernelopt=installerDiskDumpSlotSize=2560 no-auto-partition
So with your addition it should look like
kernelopt=installerDiskDumpSlotSize=2560 no-auto-partition CONFIG./USB/quirks=0xXXXX:0xYYYY::0xffff:UQ_KBD_IGNORE
In case your software word wraps, the above is all on a single line, with a space between the n (in partition) and C (in CONFIG).
correct
Hi
I have tried this and had no luck – did anyone else have any luck getting this to work?
I am using ESXI 6.7 update 3
Just tried that on my 7.0 Host, because if you Passtrough an USB PCIe Card to a VM which has USB Devices/Cables attached, the corresponding VM doesn’t boot (stuck before BIOS/UEFI).
If you remove the USB Devices/Cables before the VM starts, and connect it after the VM is powered On everything works..
Sooo 🙂
The lsusb -v | grep -E ‘(^Bus|HID)’ command gave me the following interesting Devices:
Bus 001 Device 010: ID 1e7d:2e22 ROCCAT
HID Device Descriptor:
bcdHID 1.00
HID Device Descriptor:
bcdHID 1.11
can’t get device qualifier: Resource temporarily unavailable
Bus 001 Device 011: ID 046d:c223 Logitech, Inc. G11/G15 Keyboard / USB Hub
Bus 001 Device 012: ID 046d:c226 Logitech, Inc. G15 Refresh Keyboard
HID Device Descriptor:
bcdHID 1.10
HID Device Descriptor:
bcdHID 1.10
can’t get device qualifier: Resource temporarily unavailable
Bus 001 Device 013: ID 046d:c227 Logitech, Inc. G15 Refresh Keyboard
HID Device Descriptor:
bcdHID 1.11
can’t get device qualifier: Resource temporarily unavailable
Bus 001 Device 014: ID 046d:0a5b Logitech, Inc. G933 Wireless Headset Dongle
HID Device Descriptor:
bcdHID 1.11
My Mouse is the entry called ROCCAT with the ID 1e7d:2e22 – easy.
And my Keyboard is 046d:c226 (the other entries are the integrated USB Hub and LCD Display on this Keyboard).
Making the change to the boot.cfg was easy:
kernelopt=autoPartition=FALSE CONFIG./USB/quirks=0x046d:0xc226::0xffff:UQ_KBD_IGNORE
And voila!
The Keyboard entry is listed and works within the VM!.
But the mouse isn’t available from the list of USB Host Devices…
I tried adding another CONFIG./USB/quirks entry with the IDs from my mouse after the Keyboard-Entry removes the Keyboard from the USB Host List but the mouse is available 🙁
Trying something like this also didn’t worked:
CONFIG./USB/quirks=0x046d:0xc226:0x1e7d:0x2e22::0xffff:UQ_KBD_IGNORE
It seems like only the last CONFIG./ entry is used. Is there a way to add two devices? Or did something with the behavior for a mouse changed within 7.0?
Another simple Dell Mouse also doesn’t get recognized
I believe Quirks can be chained in the boot.cfg file like so: CONFIG./USB/quirks=0x2047:0x0318::0xffff:UQ_KBD_IGNORE:0x0557:0x2419::0xffff:UQ_KBD_IGNORE:0x2588:0x0001::0xffff:UQ_KBD_IGNORE
Use a single : as the separator. Everything has to be on the same line.
Thank you for this hint!
Now the Mouse and Keyboard are given to the VM 🙂
https://imgur.com/a/lk6p4EH
When i’m at home after work i can try this out, but i expect that it will work.
And with that i can update my ESXi with the VR-VM to 7.0 🙂
(Downgraded to 6.7 because of the USB PCIe Passtrough).
Just wanted to give an update.
Passing my Devices (Keyboard, G930 Headset and Mouse, 3d printer) worked.
But after some minutes the USB reconnecting party started and the VM got pretty laggy and no inputs where recognized by the Keyboard or mouse.
After the vm was responsive again the headset was “lost” so i went back to the passtroughed USB PCIe “solution” (even tough i need to detach and re-attach the devices, but maybe we get a solution to that 😉 ).
I can get the mouse to show up, but never the keyboard, I changed the keyboard and made the changes accordingly. does this method work on 6.7 U3?
I dont think the boot.cfg is taking the input to ignore the keyboard input (CONFIG./USB/quirks=0x033a:0x0318::0xffff:UQ_KBD_IGNORE) i put it right after no-auto-partition
Hi there !
I’m using ESXI 6.7 on intel NUC6I7KYK.
I’m successfully passthrough iGPU but still no luck with keyboard and mouse.
I’ve try your way …. still failed !
Bus 001 Device 005: ID 1f75:0917 Innostor Technology Corporation (esxi host installed THERE)
Bus 001 Device 004: ID 8087:0a2b Intel Corp.
Bus 001 Device 003: ID 046d:c52b Logitech, Inc. Unifying Receiver (logitech wireless keyboard)
Bus 001 Device 002: ID c0f4:01b0 (other wired keyboard)
Bus 001 Device 001: ID 0e0f:8003 VMware, Inc. Root Hub
Can’t passthrough complete PCI USB (maybe cause the esxi host is in a usb key ..)
cat /etc/vmware/config
libdir = “/usr/lib/vmware”
authd.proxy.nfc = “vmware-hostd:ha-nfc”
authd.proxy.nfcssl = “vmware-hostd:ha-nfcssl”
authd.proxy.vpxa-nfcssl = “vmware-vpxa:vpxa-nfcssl”
authd.proxy.vpxa-nfc = “vmware-vpxa:vpxa-nfc”
authd.fullpath = “/sbin/authd”
usb.quirks.device0 = “0x046d:0xc52b allow”
usb.quirks.device1 = “0xc0f4:0x01b0 allow”
cat /bootbank/boot.cfg
bootstate=0
title=Loading VMware ESXi
++++
CONFIG./USB/quirks=0x046d:0xc52b::0xffff:UQ_KBD_IGNORE
CONFIG./USB/quirks=0xc0f4:0x01b0::0xffff:UQ_KBD_IGNORE
and also add to VMX file :
usb.generic.allowHID = “TRUE”
usb.generic.allowLastHID = “TRUE”
usb.quirks.device0 = “0x046d:0xc52b allow”
usb.quirks.device1 = “0xc0f4:0x01b0 allow”
Can you please , help me ?
It doesn’t matter if ESXi is using on a USB device. Can you debug by first attempting the keyboard before proceeding the mouse? Also, you don’t need to specify mouse entry in Step 3 as mentioned.
esxi 6.5U3 on Asus Z370-A. I did it with the mouse, but it didn’t work with the keyboard. how can debug ? what logs to check ? Can you please , help me ?
I am loocking for a way to connect an usb webcam to a virtual server. I tired it with the mentioned settings, but I still get only a black screen from the webcam. Do you have any idea how that can be done?
Thanks and regards
Has anyone been successful passing through a logitech unifying receiver?
Bus 001 Device 003: ID 046d:c52b Logitech, Inc. Unifying Receiver
Seems no matter what, I can’t get it to show up as a passthrough device.
Tried kernel option “UQ_HID_IGNORE” instead of KBD still with no success. The dongle identifies itself as both, a keyboard, mouse and some unidentified device.
Thoughts?
My current esxi box has an additional asmedia usb controller, so for quite some time i’ve been passing it through to windows to allow for the wireless keyboard/mouse connectivity.
I had hoped the steps in this blog would work to passthrough the logitech receiver but no go.
At some point i’ll upgrade the server to a board without the additional usb controller. One option is to buy a pcie card, but seems thats a bit of a crapshoot too in terms of stability.
I was reading elsewhere about USB over IP. https://blog.rylander.io/2016/12/01/passthrough-usb-keyboard-and-mouse-to-vm-on-esxi/
While his case use isn’t identical to mine, it was worth exploring virtualhere (https://www.virtualhere.com/home) .
In essence it’s a client/server relationship where the usb device runs on some other device. The client/server interact over ip. The free version allows for a single usb device per server. Perfect in my case as its just the dongle.
The server turned out to be an access point running asusmerlin firmware in the same room as the esxi box. The AP already does a few other things so entware was already installed. Just a matter of installing the generic arm version of the server, pointing the config file to the vid/pid of the dongle and setting up the daemon to auto start when the ap is rebooted.
On the windows side the client installs a virtual usb driver. There’s options to allow it to autoconnect when the program starts (just place in the windows startup folder).
Keyboard response seems fairly real time (AP is wired to rest of network) without any issues. We’ll see how it works over the next week. Hopefully it proves stable.
Decided to give this another shot on a test machine (esxi 7 update 1). Followed all the steps. It works! I’m not sure what was differently before. It boiled down to several steps
1) /bootbank/boot.cfg kernel option edit –
CONFIG./USB/quirks=0x046d:0xc52b::0xffff:UQ_KBD_IGNORE
2) /etc/vmware/config edits
usb.quirks.device0 = “0x046d:0xc52b allow”
3) .vmx edits (2)
usb.quirks.device0 = “0x046d:0xc52b allow”
usb.generic.allowHID = “TRUE”
4) Add logitech receiver as a usb device in vm editor.
Thanks again!
Hi das1996:
About the kernel option, is it like this:
kernelopt=autoPartition=FALSE
modules=jumpstrt.gz — useropts.gz — features.gz — k.b00 — uc_intel.b00 — uc_amd.b00 — uc_hygon.b00 — procfs.b00 — vmx.v00 — vim.v00 — tpm.v00 — sb.v00 — s.v00 — mellanox.v00 — mft
build=7.0.1-0.0.16850804
updated=4
CONFIG./USB/quirks=0x1d57:0xfa21::0xffff:UQ_KBD_IGNORE
or:
kernelopt=autoPartition=FALSE CONFIG./USB/quirks=0x1d57:0xfa21::0xffff:UQ_KBD_IGNORE
Thanks.
Second option. It’s a parameter of the kernelopt key.
Finally i successfully passthrough the usb device to vm. Thanks everyone for their help.
And this is my step:
1) for mouse:
a) /etc/vmware/config edit –
usb.quirks.device0 = “0x045e:0x0782 allow”
2) for logitech unifying receiver
a) /etc/vmware/config edit –
usb.quirks.device1 = “0x046d:0xc52b allow”
b) append CONFIG./USB/quirks=0x046d:0xc52b::0xffff:UQ_KBD_IGNORE to kernelopt in the file of /bootbank/boot.cfg
P.S. both of them no need to edit the .vmx file. Test it for esxi 6.7 u3.
Thanks and regards
Hi! I´m trying to add an EATON UPS Elipse Eco to a Ubuntu 20 VM which runs a NUT server.
Hardware is SuperMicro X11SCH-LN4F board with Xeon E-2236, ESXi 6.7.0 Update 3 (Build 17167734) Nov 2020 Update
Here´s my lsusb output:
Bus 001 Device 003: ID 0463:ffff MGE UPS Systems UPS
Bus 001 Device 006: ID 0781:5581 SanDisk Corp. Ultra
Bus 001 Device 005: ID 0557:2419 ATEN International Co., Ltd
Bus 001 Device 004: ID 0557:7000 ATEN International Co., Ltd Hub
Bus 001 Device 002: ID 0451:16a8 Texas Instruments, Inc. CC2531 ZigBee
Bus 001 Device 001: ID 0e0f:8003 VMware, Inc. Root Hub
Somehow it does not seem to work. The vm says “can’t add hid device: -71
Here are the lines I added in the config files:
/etc/vmware/config
usb.quirks.device0 = “0x0463:0xffff allow”
/bootbank/boot.cfg
CONFIG./USB/quirks=0x0463:0xffff::0xffff:UQ_KBD_IGNORE
also tried
CONFIG./USB/quirks=0x0463:0xffff::0xffff:UQ_HID_IGNORE
I didn’t have to do anything special to pass a cyber powersystems ups to its monitoring software. Is the device showing up in the usb device list when you edit the vm?
Yes, it is listed in the USB devices, even without the edits from this thread. But It is listed as a HID device…
What about the vmx file edits?
Yes, I added them and also tried without.
Exactly the same Problem :/ I bought a PCI-e USB Card an will try it passthrough
Same here, but I want to get rid of this usb card and use the built-in USB ports, so I don’t block the PCIe Slot.
I have followed the instructions and got the mouse working, but cannot passthrough keyboard on esxi 6.5u2. Am i doing something wrong, please see below;
edit /etc/vmware/config
=======================
usb.quirks.device0 = “0x145f:0x01e5 allow”
usb.quirks.device1 = “0x0461:0x4d51 allow”
edit bootbank/boot.cfg
======================
kernelopt=autoPartition=FALSE CONFIG./USB/quirks=0x0461:0x4d51::0xffff:UQ_KBD_IGNORE
kernelopt=autoPartition=FALSE CONFIG./USB/quirks=0x145f:0x01e5::0xffff:UQ_KBD_IGNORE
edit vm.vmx
===========
usb.generic.allowHID = “TRUE”
usb.quirks.device0 = “0x145f:0x01e5 allow”
usb.quirks.device1 = “0x0461:0x4d51 allow”
I have tried the steps as well. ReRunning vi /etc/vmware/config and vi bootbank/boot.cfg shows everything is correct. I am only tryng to pass a Logitech unifying device from main motherboard to a VM.
After esxi reboot(multiple) there is no unifying device as an additional usb option to add in vm settings. Are the above steps only for pci?