Converting a memory checkpoint into a guest memory dump using the vmss2core tool
search cancel

Converting a memory checkpoint into a guest memory dump using the vmss2core tool

book

Article ID: 323788

calendar_today

Updated On:

Products

VMware Desktop Hypervisor VMware vSphere ESXi

Issue/Introduction

This article provides steps for using the vmss2core tool to debug guest operating systems and applications by converting a virtual machine checkpoint into a core / memory dump file. The checkpoint can either be a snapshot with memory (.vmsn) or a suspend state file (.vmss). A variety of core dump formats can be selected for use with standard debuggers (such as Microsofts Windows Debugger (WinDbg) or the GNU debugger (GDB)).

vmss2core is included with both VMware Workstation and VMware Fusion and supports a variety of guest operating system types by using the appropriate flags.

Environment

  • VMware vSphere ESXi
  • VMware ESX
  • VMware Workstation Pro
  • VMware Fusion Pro

Resolution

The vmss2core tool converts the suspend state (.vmss/.vmem files) of a virtual machine (VM) in suspended state, or a snapshot with memory (.vmsn/.vmem files) of a VM into a core/memory dump that can be used with the guest OS specific debugging tools for further analysis.
The exact steps depend on whether the virtual machine is running on an enterprise baremetal hypervisor, such as VMware ESXi/ESXi or a desktop hypervisor like VMWare Workstation or VMware Fusion).

Obtaining the Tool

To get the latest version of vmss2core, download and install the appropriate VMware product. For modern guest OS types, use the version bundled with either VMware Workstation Pro or VMware Fusion:



Scenario 1: For Virtual Machines Running on ESXi

After either creating a snapshot with memory of the VM, or suspending the VM, the specific file set will be located in the virtual machine folder (/vmfs/volumes/<datastore>/<vm_name>/)

  1. Collect the file set specific to the method used (.vmss/.vmem or .vmsn/.vmem) and copy the files to the system where vmss2core is located.
    Note: If the virtual machine is using encryption, make sure to decrypt the files before copying them. See Unable to convert a Windows 11 VM snapshot to a memory dump for more information.
  2. On the machine containing the copied files, run the command:
    # vmss2core <OS-option> <vm_name>.vmss <vm_name>.vmem
    or
    # vmss2core <OS-option> <vm_name>.vmsn <vm_name>.vmem
    while replacing <OS-option> with the corresponding setting for the OS type/version:

    OptionUse for Operating Systems
    -WMicrosoft Windows 7
    Microsoft Windows 10
    Windows Server 2008
    Windows Server 2008 R2
    -W8Microsoft Windows 8
    Microsoft Windows 8.1
    Microsoft Windows 11
    Microsoft Windows Server 2012
    Microsoft Windows Server 2016
    Microsoft Windows Server 2019
    Microsoft Windows Server 2025
    -NLinux operating systems


    For example, to create a Windows memory dump for a suspended Windows 11 VM called "test-vm", the command should be:
    # vmss2core.exe -W8 test-vm.vmss test-vm.vmem
    Note: When using vmss2core on Linux, the executable is named vmss2core-Linux64 instead, but works with the same syntax.



Scenario 2: For VMware Workstation 7.x and above or Fusion 3.x and above

Depending on the specific Desktop hypervisor used, the vmss2core tool can be found if different locations:

  • Microsoft Windows (32-bit) - C:\Program Files\VMware\VMware Workstation\
  • Microsoft Windows (64-bit) - C:\Program Files (x86)\VMware\VMware Workstation\
  • Linux - /usr/bin/
  • MacOS (when using VMware Fusion) - /Library/Application Support/VMware Fusion/

Copy the files (.vmss/.vmem or .vmsn/.vmem) to the specific folder and run the command as described above:

# vmss2core <OS-option> <vm_name>.vmss <vm_name>.vmem

or

# vmss2core <OS-option> <vm_name>.vmsn <vm_name>.vmem

while replacing <OS-option> with the corresponding setting for the OS type/version as per the table.
On Linux run:

# ./vmss2core-Linux64 <OS-option> <vm_name>.vmss <vm_name>.vmem

instead.

Additional Information

Troubleshooting

The vmss2core tool might to extract a guest memory- or core dump and instead respond with an error message like:

Error parsing Windows data.
Cannot create memory.dmp

This usually indiciates that the Windows guest OS Kernel had not been completely loaded yet. The OS needs to have loaded the kernel in order to get usable data for vmss2core.
Examples of a virtual machine in a boot state that would not have usable data:

  • The VM powers on, but fails to progress past the POST phase, getting stuck in the BIOS screen.
  • The VM cannot find a boot device.
  • Windows fails to boot, e.g. with:
    Windows failed to start. A recent hardware or software change might be the cause.
  • The Linux OS inside the VM experienced a panic while the kernel was loading.

For additional information refer to Suspending a virtual machine on ESX/ESXi to collect diagnostic information.

Note: For the vmss2core tool to successfully process snapshot files from a Windows virtual machine, features such as Virtualization-Based Security (VBS) and Hyper-V must be disabled. If either of these features is enabled, the tool will either produce a .core memory dump rather than a standard format, or fail with an error message "cannot create linear address fffff7800000000000000".
Powered by Wolken Software