Configuring a vSphere ESXi host to use a local USB device for VMkernel coredumps

Products

• VMware vSphere ESXi 6.0
• VMware vSphere ESXi 7.0
• VMware vSphere ESXi 8.0
• VMware vSphere ESXi 5.0
• VMware vSphere ESXi 5.5

Issue/Introduction

When an ESXi host fails with a purple diagnostic screen involving network or disk devices or drivers, it may not be possible to write diagnostic information via the preferred network or disk device. This article provides a method to configure the ESXi host to dump diagnostic information to a local USB storage device in the event of a purple diagnostic screen.

If network or disk connectivity is not suspect, it is more common to use one of those methods to collect diagnostic information from an ESXi host. For more information, see:

• Configuring an ESXi/ESX host to capture a VMkernel coredump from a purple diagnostic screen
• Configuring the Network Dump Collector service in vSphere 

Resolution

On ESXi 4.1 and higher, the USB arbitrator service takes control of local USB devices and passes them through for use by virtual machines. For more information on USB Passthrough, see USB Device Passthrough Configuration from an ESXi/ESX Host to a Virtual Machine 

To use a local USB storage device to save a VMkernel coredump during a purple diagnostic screen, the USB arbitrator service must be disabled. However, USB devices may be claimed by the USB arbitrator or used by the VMkernel, not both. Thus, using USB storage devices locally on a vSphere ESXi host prevents their use by virtual machines.

To use a local USB storage device to save future VMkernel coredump diagnostic information:

1. Open a console session to the vSphere ESXi host, either using SSH or the local ESXi Shell and log in an administrative user. For example, log in as the root user.
    
2. Validate that no virtual machines are using USB devices via passthrough.
    
3. Disable the USB Arbitrator service using the command:
   
   /etc/init.d/usbarbitrator stop
    
4. Connect the USB storage device to the ESXi host.
    
5. Perform a rescan of the storage. For more information, see Performing a rescan of the storage on an ESX/ESXi host (1003988).
    
6. Validate that the USB storage device appears on the ESXi host. For more information, see Identifying disks when working with VMware ESX/ESXi (1014953).
    
7. Create a new diagnostic partition on the USB storage device, and activate it for use by the VMkernel for storing diagnostic information. For more information, see the Creating and activating a diagnostic coredump partition on disk section in Configuring an ESX/ESXi host to capture a VMkernel coredump from a purple diagnostic screen . Note: proper GUID is 9D27538040AD11DBBF97000C2911D1B8
   
   Note: This service is started again during the next boot, and USB devices are made available for virtual machine passthrough. After reproducing a purple diagnostic screen failure and restarting the ESXi host, the USB arbitrator service must be stopped again to copy the contents out. For more information, see Extracting a core dump file from the diagnostic partition following a purple diagnostic screen error (broadcom.com)

To restore USB device access for passthrough to virtual machines without restarting:

1. Open a console session to the vSphere ESXi host, either using SSH or the local ESXi Shell and log in an administrative user. For example, log in as the root user.
    
2. Validate that the VMkernel is not using any USB devices.
    
3. Enable the USB arbitrator service using the command:
   
   /etc/init.d/usbarbitrator start
    
4. Restart the hostd management service. For more information, see Restarting the Management agents on an ESXi or ESX host.

Additional Information

• Configuring an ESXi/ESX host to capture a VMkernel coredump from a purple diagnostic screen
• Configuring the Network Dump Collector service in vSphere
• Configuring a diagnostic coredump partition on an ESXi host

Impact/Risks:
Caution: Disabling the USB arbitrator removes access to existing USB devices used for passthrough to virtual machines and prevents newly-added virtual machines from being passed through to virtual machines. Gracefully disconnect USB devices prior to using this method. For more information, see the Virtual Machine Functions that Can Result in Data Loss with USB Devices and Remove a USB Device from a Virtual Machine.