• Skip to primary navigation
  • Skip to main content
  • Skip to primary sidebar

virtuallyGhetto

  • About
  • Privacy
  • VMware Cloud
  • Home Lab
  • Nested Virtualization
  • Automation
    • VMware Kickstart
    • VMware API/SDK/CLI
    • VMware vMA/VIMA
    • VMware OVF / OVFTOOL
  • Apple Mac
  • VCSA
  • VSAN
You are here: Home / ESXi / How to passthrough USB Keyboard/Mouse HID and CCID devices to VM in ESXi?

How to passthrough USB Keyboard/Mouse HID and CCID devices to VM in ESXi?

05/13/2020 by William Lam 43 Comments

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".

More from my site

  • Automated ESXi Installation to USB using Kickstart
  • Useful M.2 NVMe accessories for vSphere (VSAN/VMFS) Home Labs
  • Automating VM keystrokes using the vSphere API & PowerCLI
  • Project USB to SDDC – Part 3
  • Project USB to SDDC – Part 2
Share this...
  • Twitter
  • Facebook
  • Linkedin
  • Reddit
  • Pinterest

Filed Under: ESXi Tagged With: CCID, HID, usb

Reader Interactions

Comments

  1. Greg W says

    05/13/2020 at 7:04 am

    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”

    Reply
    • William Lam says

      05/13/2020 at 9:01 am

      That’s correct

      Reply
  2. Jeff says

    05/13/2020 at 7:41 am

    Is this method also conpatible with esxi 6.0 ?

    Reply
    • William Lam says

      05/13/2020 at 9:02 am

      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 🙂

      Reply
  3. Jeff says

    05/13/2020 at 8:26 am

    lsusb do not show any usb hid device in esxi 6.

    Reply
    • Yeahman says

      05/14/2020 at 1:37 am

      Same here 🙁 ..cannot see hid devices with lsusb

      Reply
      • William Lam says

        05/22/2020 at 7:32 am

        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 article

        Reply
  4. Ren says

    05/14/2020 at 12:56 pm

    How 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.

    Reply
    • William Lam says

      05/22/2020 at 7:32 am

      I’ve updated the article with an example lsusb command, see if that helps

      Reply
  5. Ren says

    05/22/2020 at 9:18 am

    lsusv -v returns nothing on mine…?

    Reply
  6. das1996 says

    06/04/2020 at 12:51 pm

    Where exactly in boot.cfg does the string in step 3 go?

    Reply
    • das1996 says

      06/04/2020 at 1:05 pm

      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?

      Reply
      • William Lam says

        06/04/2020 at 1:39 pm

        Which step are you referring to? The instructions are detailed in each step which includes where boot.cfg is located 🙂

        Reply
        • das1996 says

          06/04/2020 at 1:49 pm

          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.

          Reply
          • William Lam says

            06/04/2020 at 2:39 pm

            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

  7. das1996 says

    06/04/2020 at 2:47 pm

    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).

    Reply
    • William Lam says

      06/04/2020 at 2:56 pm

      correct

      Reply
      • Has says

        06/12/2020 at 12:49 pm

        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

        Reply
  8. Oliver Lis (@Oliverf0x) says

    06/18/2020 at 8:53 am

    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

    Reply
    • Neil says

      06/22/2020 at 9:14 am

      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.

      Reply
      • Oliver Lis (@Oliverf0x) says

        06/23/2020 at 2:25 am

        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).

        Reply
        • Oliver Lis (@Oliverf0x) says

          08/03/2020 at 6:57 am

          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 😉 ).

          Reply
  9. Al says

    06/26/2020 at 10:28 am

    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

    Reply
  10. jbperrin88jbperrin says

    07/02/2020 at 4:44 am

    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 ?

    Reply
    • William Lam says

      07/02/2020 at 6:15 am

      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.

      Reply
      • Alex says

        07/20/2020 at 12:41 am

        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 ?

        Reply
  11. Patrick says

    10/11/2020 at 2:12 pm

    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

    Reply
  12. das1996 says

    10/12/2020 at 10:16 pm

    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?

    Reply
  13. das1996 says

    10/13/2020 at 1:36 pm

    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.

    Reply
  14. das1996 says

    10/25/2020 at 7:04 pm

    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!

    Reply
    • colinhd8colin says

      10/28/2020 at 1:10 am

      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.

      Reply
      • das1996 says

        10/28/2020 at 8:58 am

        Second option. It’s a parameter of the kernelopt key.

        Reply
        • colin says

          10/28/2020 at 9:38 pm

          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

          Reply
  15. Mark says

    11/24/2020 at 7:23 am

    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

    Reply
    • Mark says

      11/24/2020 at 7:27 am

      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

      Reply
    • das1996 says

      11/24/2020 at 2:48 pm

      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?

      Reply
      • Mark says

        11/24/2020 at 11:10 pm

        Yes, it is listed in the USB devices, even without the edits from this thread. But It is listed as a HID device…

        Reply
      • das1996 says

        11/25/2020 at 9:07 am

        What about the vmx file edits?

        Reply
        • Mark says

          11/25/2020 at 11:36 pm

          Yes, I added them and also tried without.

          Reply
    • Peter says

      12/12/2020 at 12:47 am

      Exactly the same Problem :/ I bought a PCI-e USB Card an will try it passthrough

      Reply
      • Mark says

        12/12/2020 at 7:19 am

        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.

        Reply
  16. surfaraz says

    12/17/2020 at 5:41 pm

    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”

    Reply
  17. Bruce Bowman says

    01/10/2021 at 4:03 pm

    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?

    Reply

Thanks for the comment! Cancel reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Primary Sidebar

Author

William Lam is a Senior Staff Solution Architect working in the VMware Cloud team within the Cloud Services Business Unit (CSBU) at VMware. He focuses on Automation, Integration and Operation for the VMware Cloud Software Defined Datacenters (SDDC)

  • Email
  • GitHub
  • LinkedIn
  • RSS
  • Twitter
  • Vimeo

Sponsors

Privacy & Cookies: This site uses cookies. By continuing to use this website, you agree to their use.
To find out more, including how to control cookies, see here: Cookie Policy