Posted inVMware

How to Configure USB Passthrough on VMware ESXi: Attaching USB Tokens and External Hard Drives to VMs

VMware tutorial - IT technology blog
VMware tutorial - IT technology blog

A 2 AM Phone Call and the USB Token Dilemma

At 2:00 AM, the phone rings incessantly. On the other end is the panicked voice of the lead accountant: the e-invoicing portal cannot issue tax receipts. The screen flashes a single glaring red error: “No smart card / USB Token detected”.

The root cause was all too familiar. The afternoon before, the infrastructure team had migrated the accounting server from an aging physical PC to a VMware ESXi 7.0 virtualization cluster running on a Dell PowerEdge R740. The systems engineer plugged the VNPT-CA USB token into a rear USB 3.0 port on the server. The token’s LED still lit up, yet Device Manager inside the Windows Server 2022 virtual machine remained completely blank.

This scenario is an everyday occurrence for system administrators. While virtualization brings immense convenience, businesses often rely heavily on physical USB devices: Viettel tax tokens, MISA digital signatures, customs authentication dongles, or 4TB WD external hard drives for cold backups. Without a solid understanding of how Host USB Passthrough works, you can easily waste hours troubleshooting in frustration.

How Host USB Passthrough Works on VMware ESXi

To allow a virtual machine (Guest OS) to detect and use a USB device plugged into the physical server (Host), ESXi relies on Host USB Passthrough. Three key components work together to make this happen:

  • Virtual USB Controller: The virtual USB controller attached to the VM. You can choose either USB 2.0 (EHCI+UHCI) or USB 3.0/3.1 (xHCI).
  • USB Arbitrator: The background daemon (usbarbitrator) running on the ESXi Host. It scans physical USB ports, classifies devices, and routes signals to the registered virtual machine.
  • Host USB Device: The actual physical device mapped 1:1 directly into the virtual machine.

Compared to Proxmox VE, which allows passing devices via fixed physical port IDs, ESXi manages devices more strictly through its Arbitrator process. If the Arbitrator encounters an error or a driver conflict, the connection drops immediately.

Two critical technical limitations you must keep in mind:

  • No sharing: A physical USB device can only be attached to a single virtual machine at any given time.
  • vMotion constraints: If you use vMotion while a USB device is attached, you must configure device connection preservation across the vSphere vMotion Network. Even so, the risk of dropping the connection mid-migration remains significant.

Step-by-Step Guide to Attaching USB Tokens and External Hard Drives to a VM

Step 1: Enable SSH and Verify Hardware Detection

Do not rush to configure settings in the web interface just yet. First, verify whether the ESXi kernel detects the physical hardware. Open the ESXi Host Client, navigate to Manage > Services > start TSM-SSH. Then, open your terminal and SSH into the server as root.

Run the command to inspect the device list:

lsusb
# Or check detailed passthrough status:
esxcli hardware usb passthrough device list

The output will display the Vendor ID (VID) and Product ID (PID). For example:

Bus 001 Device 004: ID 096e:0405 Feitian Technologies, Inc. ePass2003
Bus 002 Device 003: ID 1058:25a2 Western Digital Technologies, Inc. Elements Portable 4TB

If you see your device listed, the hardware and physical connection are functioning properly. You can proceed to the next step.

Step 2: Check the USB Arbitrator Service

In many cases, the hardware is detected at the CLI, but the Web Client fails to display any USB options. In 90% of these cases, the culprit is a hung or stopped usbarbitrator process.

Check the service status:

/etc/init.d/usbarbitrator status

If the terminal returns “usbarbitrator is not running”, start it immediately:

/etc/init.d/usbarbitrator start

Step 3: Add a USB Controller to the Virtual Machine

Log in to the VMware Host Client or vCenter Server (ensure you have properly configured NTP on VMware ESXi and vCenter to prevent management session timeouts or authentication issues):

  1. Power off the virtual machine if hot-plugging is not enabled (shutting down is recommended for optimal stability).
  2. Right-click the VM > select Edit settings.
  3. Click Add other device > select USB controller (if one does not already exist).
  4. Choose the correct controller standard:
    • USB Tokens (Viettel, VNPT, FPT, MISA, etc.): Select USB 2.0. Legacy digital signature tokens based on Feitian or SafeNet chips tend to be unstable with xHCI 3.0 controllers.
    • External hard drives, portable SSDs: Select USB 3.0 / 3.1. This ensures backup speeds of 110–140 MB/s, rather than the sluggish ~30 MB/s bottleneck of USB 2.0.
  5. Click Save.

Step 4: Attach the Host USB Device

Once the controller is in place, mapping the device takes only seconds. If your virtual infrastructure uses advanced security features like Virtualization-Based Security (VBS) on VMware vSphere, verify that your VM configuration allows hardware device mapping without security policy conflicts:

  1. In the Edit settings window, click Add other device > select USB device (Host USB device).
  2. From the newly added dropdown menu, select the corresponding physical device (for example: Feitian ePass2003 or Western Digital Elements).
  3. Click Save and power on the VM.

Step 5: Troubleshooting Common Issues

Issue 1: External hard drive is grayed out and unavailable for passthrough

This occurs because ESXi automatically claims USB mass storage devices to use as VMFS datastores. When the host’s storage driver locks the device, the USB Arbitrator cannot access it.

Solution: Configure the USB storage driver to yield control to the Arbitrator. Run the following commands via the SSH console:

# Temporarily stop the arbitrator
/etc/init.d/usbarbitrator stop

# Disable ESXi USB storage claiming
esxcli system settings advanced set -o /Disk/PassthroughUSBStorage -i 1

# Restart the arbitrator
/etc/init.d/usbarbitrator start

After executing these commands, reopen the Web Client. The option to attach the external hard drive will now be active.

Issue 2: Device Manager detects the Smart Card, but accounting software cannot find the digital certificate

This issue stems from Windows Server rather than ESXi. By default, the Smart Card service on Windows Server is often disabled to optimize system resources.

Fix on the virtual machine:

  1. Press Windows + R, type services.msc, and hit Enter.
  2. Locate the service named Smart Card (Service name: SCardSvr).
  3. Double-click it and change the Startup type to Automatic.
  4. Click Start, then click OK.

Relaunch your digital signing software (MISA SME, TaxOnline, HTKK). The digital certificate will appear immediately.

Summary

Host USB Passthrough on VMware ESXi hinges on just three links: the physical port, the host’s usbarbitrator service, and the virtual USB controller inside the VM. Understanding how they interconnect allows you to troubleshoot issues in minutes. When problems arise, enable SSH and run lsusb first—saving you the headache of repeatedly plugging and unplugging cables in a freezing server room.

Share:
Tags: