USB Network Native Driver for ESXi Documentation (2024)

Summary
Contributors
Changelog
Requirements
Instructions

Summary

USB has become one the most widely adopted connection type in the world & USB network adapters are also popular among Edge computing platforms. In some platforms, there is either limited or no PCI/PCIe slots for I/O expansion & in some cases, an Ethernet port is not even available. Another advantage of a USB-based network adapter is that it can be hot-plugged into an system without a reboot which means no impact to the workload, same is true for hot-remove.

This Fling supports the most popular USB network adapter chipsets found in the market. The ASIX USB 2.0 gigabit network ASIX88178a, ASIX USB 3.0 gigabit network ASIX88179, Realtek USB 3.0 gigabit network RTL8152/RTL8153 and Aquantia AQC111U. These are relatively inexpensive devices that many of our existing vSphere customers are already using and are familiar with.

Contributors

Songtao Zhen
William Lam

Changelog

Sep 21, 2023 - v1.13

Added support for ESXi 8.0 Update 2

ESXi80U2-VMKUSB-NIC-FLING-67561870-component-22416446.zip (md5: bf62144b4e695c3d00cb614a4ecfb2c3)

Note:

This is ONLY for ESXi 8.0 Update 2, for other ESXi versions (including update releases), please ensure you are using the correct version of driver.

Apr 26, 2023 - v1.12

Added support for ESXi 8.0 Update 1
Added support for new DLINK RTL8156 device (0x2001:0xb301)
Fixed 2.5GbE link speed issue for RTL8156 adapter
Updated maximum supported USB Network devices to 12 and persists setting over module parameters

ESXi800-VMKUSB-NIC-FLING-64098182-component-21668107.zip (md5: 4a35899f77ce4635d0cfa76a7975504d)
ESXi80U1-VMKUSB-NIC-FLING-64098092-component-21669994.zip (md5: 9c41b5f488ec5cee325207e16b047c10)

Note 1:

This is ONLY for ESXi 8.0 & 8.0 Update 1, for other ESXi versions (including update releases), please ensure you are using the correct version of driver.

Note 2:

Known performance issue with RTL8156, TX up to 2.35Gbps while RX up to 2.15Gbps

Nov 23, 2022 - v1.11

Added support for ESXi 8.0

ESXi800-VMKUSB-NIC-FLING-61054763-component-20826251.zip (md5: 55087041545d2500c1b22deb65107f22)

Note:

This is ONLY for ESXi 8.0, for other ESXi versions (including update releases), please ensure you are using the correct version of driver.

Requirements

Vendor	Chipset	VendorID	ProductID
AQUANTIA	AQC111U	0xe05a	0x20f4
AQUANTIA	Aquantia Pacific	0x2eca	0xc101
ASIX	AX88179	0x0b95	0x1790
ASIX	AX88178a	0x0b95	0x178a
CISCO LINKSYS	RTL8153	0x13b1	0x0041
DLINK	RTL8156	0x2001	0xb301
DLINK	AX88179	0x2001	0x4a00
INSYDE SOFTWARE CORP	Insyde Software Corp.	0x0b1f	0x03ee
LENOVO	RTL8153	0x17ef	0x3062
LENOVO	RTL8153	0x17ef	0x3069
LENOVO	RTL8153	0x17ef	0x720a
LENOVO	AX88179	0x17ef	0x304b
LENOVO	RTL8153	0x17ef	0x7205
NVIDIA	RTL8153	0x0955	0x09ff
Qualcomm	NA	0x1A56	0x3100
Qualcomm	NA	0x0b05	0x1976
REALTEK	RTL8152	0x0bda	0x8152
REALTEK	RTL8156	0x0bda	0x8156
REALTEK	RTL8153	0x045e	0x07c6
REALTEK	RTL8153	0x0bda	0x8153
SITECOMEU	AX88179	0x0df6	0x0072
SUPERMICRO	Supermicro computer Inc	0x15d9	0x1b83
TP-LINK	RTL8153	0x2357	0x0601
TRENDNET	AQC111U	0xe05a	0x20f4

Instructions

Custom ESXi Image Profile/ISO

See this blog post for creating custom ESXi ISO or Image Profile using vSphere Lifecycle Manager

Manual

Step 1 - Download the ZIP file for the specific version of your ESXi host and upload to ESXi host using SCP or Datastore Browser
Step 2 - Place the ESXi host into Maintenance Mode using the vSphere UI or CLI (e.g. esxcli system maintenanceMode set -e true)
Step 3 - Install the ESXi Offline Bundle (6.5/6.7) or Component (7.0)

For (7.0+) - Run the following command on ESXi Shell to install ESXi Component:

esxcli software component apply -d /path/to/the component zip

For (6.5/6.7) - Run the following command on ESXi Shell to install ESXi Offline Bundle:

esxcli software vib install -d /path/to/the offline bundle zip

Step 4 - Plug-in the USB NIC and reboot for the change to go into effect. Once the host has rebooted, ESXi should automatically pickup and claim the USB NIC (e.g. vusb0)

Note:

Secure Boot can not be enabled if you need to use Option 2 to persist USB NIC bindings.

Multiple USB NIC Bindings

When multiple USB NICs are connected and used with ESXi, an ESXi PSOD may occur. To prevent the PSOD, the USB driver parameter usbBusFullScanOnBootEnabled=0 is now the default value and will prevent ESXi from performing a full USB bus rescan during bootup.

The implication is that to persist the USB NIC bindings, you will need to use Option 2 in the Persisting USB NIC Bindings section below. For customers who only have a single USB NIC and does not wish to add the additional persistent script or wish to enable Secure Boot, then you can configure usbBusFullScanOnBootEnabled=1 by using Option 1 in the Persisting USB NIC Bindings section below.

Persisting USB NIC Bindings

Option 1:

Run the following ESXCLI command which will enable the driver parameter to perform a full USB bus scan during startup:

esxcli system module parameters set -p "usbBusFullScanOnBootEnabled=1" -m vmkusb_nic_fling

Option 2:

Currently there is a limitation in ESXi where USB NIC bindings are picked up much later in the boot process and to ensure settings are preserved upon a reboot, the following needs to be added to /etc/rc.local.d/local.sh based on your configurations.

Standard Virtual Switch (VSS):

 vusb0_status=$(esxcli network nic get -n vusb0 | grep 'Link Status' | awk '{print $NF}') count=0 while [[ $count -lt 20 && "${vusb0_status}" != "Up" ]] do sleep 10 count=$(( $count + 1 )) vusb0_status=$(esxcli network nic get -n vusb0 | grep 'Link Status' | awk '{print $NF}') done esxcfg-vswitch -R

Distributed Virtual Switch (VDS):

 VDS_0_NAME=vDS VDS_0_PORT_ID=10 VDS_1_NAME=vDS-NSX VDS_1_PORT_ID=2 vusb0_status=$(esxcli network nic get -n vusb0 | grep 'Link Status' | awk '{print "v0:" $NF}') && vusb1_status=$(esxcli network nic get -n vusb1 | grep 'Link Status' | awk '{print "v1:" $NF}') count=0 while [[ $count -lt 40 ]] && [[ "${vusb0_status}" != "v0:Up" || "${vusb1_status}" != "v1:Up" ]] do sleep 5 count=$(( $count + 1 )) vusb0_status=$(esxcli network nic get -n vusb0 | grep 'Link Status' | awk '{print "v0:" $NF}') && vusb1_status=$(esxcli network nic get -n vusb1 | grep 'Link Status' | awk '{print "v1:" $NF}') done if [ "${vusb0_status}" = "v0:Up" ]; then esxcfg-vswitch -P vusb0 -V ${VDS_0_PORT_ID} ${VDS_0_NAME} fi if [ "${vusb1_status}" = "v1:Up" ]; then esxcfg-vswitch -P vusb1 -V ${VDS_1_PORT_ID} ${VDS_1_NAME} fi

Note:

The vusbX vmkernel interface may not show up in either ESXi Embedded Host Client and/or vSphere HTML5 UI, this does not mean there is an issue. ESXi was never designed to support USB-based NICs for Management Network and the UI may not properly detect these devices when using the UI. It is recommended to use the ESXi Shell for any operations requiring configuration of vusbX devices.

Persisting VMkernel to USB NIC mappings

When multiple USB NICs are connected, it is possible that the mapping between vmkX to physical MAC Address of the USB NIC could random change upon rebooting ESXi. To ensure this does not happen, customers can specify the mapping by adding custom parameter to USB NIC module.

Here is an example where we are mapping vusb0 to 70:88:6b:85:c0:53 and vusb1 to 58:ef:68:7f:2b:f7:

esxcli system module parameters set -p "vusb0_mac=70:88:6b:85:c0:53 vusb1_mac=58:ef:68:7f:2b:f7" -m vmkusb_nic_fling

USB Network Native Driver for ESXi Documentation (2024)

Summary

Contributors

Changelog

Requirements

Instructions

Multiple USB NIC Bindings

Persisting USB NIC Bindings

Persisting VMkernel to USB NIC mappings

References