HID

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.

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

Note1: This is not required for CCID devices or mouse devices as they are not claimed by ESXi

Note2: The USB quirks are given in sets of five parameters - vendorID:deviceID:minRevision:maxRevision:quirkName If you wish to specify multiple devices, you will need to ensure all five parameters are included. Here's an example for specifying two USB devices: CONFIG./USB/quirks=0x05fe:0x0011::0xffff:UQ_KBD_IGNORE:0x046d:0xc31d::0xffff:UQ_KBD_IGNORE

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

I am constantly amazed at the number of new use cases that can now be enabled with some of the new and updated capabilities of our vSphere Platform. I recently discovered a new vSphere API that was introduced in vSphere 6.5 called PutUsbScanCodes() which may sound a little strange but it enables some really slick Automation capabilities. This feature allows customers to send keyboard character keystrokes directly to a VM regardless of the underlying OS. In fact, the OS does not even have to be booted up for this to work which means there is no reliance on VMware Tools as this is happening at the Virtual Hardware layer.

You might ask, why would this be interesting? Lets take a look at a scenario that I had ran into years ago when I was a customer and why this feature would have really helped. At the time, there were several Virtual Appliance solutions that I needed to deploy, although I could automate the deployment, I could not automate the initial setup process. The reason for this is that before the OS is fully booted up, it required the user to interactively provide password on boot which can only be done using the VM Console. This meant solutions like the Guest Operations API was out of the question since VMware Tools is not running during this time. I suspect many of you have probably came across a similiar situation, where you are prompted for a password or some other manual input was required and the only solution is to be in front of the VM Console. Some other interesting use cases that this feature could help with are OS installations where automated deployments may not be possible due to the type of OS, automated filesystem check (fsck) or verification where manual intervention was the only option. The possibilities for this API is truly endless and I am sure there are many many more use cases where this feature could be used.

OK, so now that are you sold on the feature, lets take a look at how it works! I have built a PowerCLI script called VMKeystrokes.ps1 which demonstrates the use of this vSphere API.

The API takes in an array of scan code events or what is referred to as USB Human Interface Device (HID) Codes which is part of the USB specification for human interactions with a computer system. There was not any details on what exactly this even looked like, so it took me awhile to figure out the input and what the API was expecting. I found this online reference here which provided a mapping of keyboard keys to their respective scan codes which I have implemented a subset of the scan codes within my script. However, upon further inspection, these scan codes could not be used as-is and required a conversion to the appropriate HID format which can be seen in my code. There also a modifier type within the API that can be associated with a given scan code. One use for this is to send an upper-case character rather than a lower case.

Lets now go through a demonstration to see how the Set-VMKeystrokes function works. In my environment, I have a PhotonOS VM running and I want to automate the login via the console which means I want to pass in the username (root), hit return, pass in the password (VMware1!) and hit return.

[Read more...]

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

Automating VM keystrokes using the vSphere API & PowerCLI