Enabling VMX debug logging for a Virtual Machine
search cancel

Enabling VMX debug logging for a Virtual Machine

book

Article ID: 423881

calendar_today

Updated On:

Products

VMware vSphere ESXi VMware vSphere ESXi 8.0

Issue/Introduction

By default, VMware ESXi does not generate verbose debug logs to preserve system performance. However, when troubleshooting complex virtual machine issues—such as unexpected crashes, power-on failures, or specific instruction set errors—Broadcom Technical Support may require debug-level information.

This article provides the standard procedure for enabling VMX debug logging at the Virtual Machine level.

Note: Enabling debug logging performs extra error checking which can result in a noticeable decrease in VM performance. It is recommended to disable this feature once troubleshooting is complete.

Environment

 

  • VMware vSphere ESXi 7.x

  • VMware vSphere ESXi 8.x

  • VMware vSphere ESXi 9.x

 

 

Resolution

Follow these steps to enable or disable VMX debug logging via the ESXi Command Line Interface (CLI).

1. Preparation
Power off the Virtual Machine. The .vmx configuration file cannot be reliably reloaded if the VM is in a Powered On or Suspended state.

2. Identify the VMID
Establish an SSH connection to the ESXi host where the VM resides and locate the VMID.

# vim-cmd vmsvc/getallvm

Example Output:

Vmid    Name       File                                  Guest OS             Version
4       TEST_VM    [datastore1] TEST_VM/TEST_VM.vmx      windows2019_64Guest  vmx-19

3. Snapshot and Backup of VM Configuration
Before making any manual changes to the configuration file, ensure you have both a point-in-time recovery option and a file-level backup.

A. Take a VM Snapshot: Create a snapshot to preserve the current state of the virtual machine. This allows for a quick revert if the VM fails to power on after the edit.
Action: Right-click the VM > Snapshots > Take Snapshot.
Note: Deselect "Snapshot the virtual machine's memory" to speed up the process while the VM is powered off.

B. Backup the Configuration File (.vmx): Navigate to the VM directory via the ESXi CLI and create a copy of the configuration file. This is crucial in case the .vmx file becomes corrupted during the manual edit.

cd /vmfs/volumes/DATASTORE_NAME/VM_NAME/
cp VM_NAME.vmx VM_NAME.vmx.backup

4. Enable Debugging in the .vmx File
Use the vi editor to add the debug parameter to the configuration file.

# vi VM_NAME.vmx

  1. Press i to enter Insert mode.

  2. Add the following line to the file: vmx.buildType=debug

  3. Press Esc, then type :wq! and press Enter to save and exit.

Example:
encoding = "UTF-8"
config.version = "8"
virtualHW.version = "19"
nvram = "TEST_VM.nvram"
svga.present = "TRUE"
vmx.buildType=debug   <------
pciBridge0.present = "TRUE"

5. Reload the VM Configuration
For the changes to take effect in the hypervisor, reload the VM configuration using the VMID identified in Step 2.

vim-cmd vmsvc/reload <Vmid>

Example: vim-cmd vmsvc/reload 4

6. Power On and Reproduce the Issue
Power on the VM and proceed to reproduce the issue you are investigating.

vim-cmd vmsvc/power.on <Vmid>

7. Verify Debug Status
Check the vmware.log file within the VM directory to confirm the debug binary is active.

grep -i "debug" vmware.log

Expected Output Snippet:

vmx - Command line: "/bin/vmx-debug"
vmx - DICT vmx.buildType = "debug"
vmx - You are running this virtual machine with debugging enabled. Debugging performs extra error checking to help diagnose problems, but it also lowers performance.

How to Disable Debug Logging

To revert to standard logging:

  1. Power off the VM.

  2. Edit the .vmx file and remove the vmx.buildType = "debug" line (or set the value to "release").

  3. Reload the VM configuration using vim-cmd vmsvc/reload <Vmid>.

Powered by Wolken Software