Converting a snapshot file to memory dump using the vmss2core tool

Products

• VMware Desktop Hypervisor
• VMware vSphere ESXi

Issue/Introduction

• This article provides steps to convert a snapshot file to a memory dump using the vmss2core tool.
  
  
• Developers can use this tool to debug guest operating systems and applications by converting a virtual machine checkpoint into a core dump file.
  
  
• The checkpoint can either be a snapshot (.vmsn) or a suspend file (.vmss), and a variety of core dump formats can be selected for use with standard debuggers (such as WinDbg or GDB).
  
  
• vmss2core is included with VMware Workstation and Fusion and supports different guest OS types through appropriate flags.

Environment

• VMware Fusion
• VMware Workstation
• VMware vSphere ESXi

Resolution

The vmss2core tool converts a suspended virtual machine's snapshot (.vmss/.vmem files) into a core dump for analysis. The exact steps depend on whether the virtual machine is running on an enterprise host (ESXi) or a desktop hypervisor (Workstation/Fusion).

Obtaining the Tool

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

• Download vmss2core: 
• Download VMware Workstation Pro
• Download VMware Fusion

Note: The -W, -W8, and -N flags always refer to the Guest OS running inside the virtual machine, not the Host OS where the tool is executed.

Scenario 1: For Virtual Machines Running on ESXi

1. 1. 1. Suspend the virtual machine and Extract Files
         
         
         1. 1. Connect to the ESXi host via SSH.
               
               
            2. Find the target virtual machine's World ID by running the appropriate command:
               
               
               • ESXi 6.7 and above:
                 
                 esxcli vm process list
                 
                 
               • Older ESXi versions:
                 
                 vm-support -x
                 
                 
            3. Suspend the virtual machine using the World ID:
               
               vm-support -Z <world_ID>
               
               (Note: If this command is unsupported on the ESXi version, suspend the virtual machine using the vSphere GUI per Broadcom KB 326327).
               
               
            4. Copy the resulting .vmss file (and the .vmem file, if it exists) from the ESXi host over to the system where the vmss2core tool is located.
               
               
               
      2. Run the Conversion command
         
         On the machine containing the copied files, run the command corresponding to the Guest OS:

• • • • • Default Windows core dump:
          
          vmss2core virtual_machine_name.vmss virtual_machine_name.vmem
          
          
        • Windows 8, 8.1, 11, or Server 2012, 2016, 2019, 2025:
          
          vmss2core -W8 virtual_machine_name.vmss
          
          
        • Linux:
          
          ./vmss2core-Linux64 -N virtual_machine_name.vmss
          
          

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

1. 1. 1. Locate the Tool
         
         Open the terminal or command prompt and navigate to the directory based on the Host OS:
         
         
         • • Windows (32-bit): C:\Program Files\VMware\VMware Workstation\
             
             
           • Windows (64-bit): C:\Program Files (x86)\VMware\VMware Workstation\
             
             
           • Linux: /usr/bin/
             
             
           • macOS (Fusion): /Library/Application Support/VMware Fusion/
             
             
      2. Run the Conversion command
         
         Choose the command that matches the virtual machine's Guest OS:

• • • • • Windows Vista, 7, 10, or Server 2008:
          
          vmss2core.exe -W virtual_machine_name.vmss virtual_machine_name.vmem
          
          
        • Windows 8, 8.1, 11, or Server 2012, 2016, 2019, 2025:
          
          vmss2core.exe -W8 virtual_machine_name.vmss virtual_machine_name.vmem
          
          
        • Windows Server 2022:
          
          vmss2core.exe -N virtual_machine_name.vmss virtual_machine_name.vmem
          
          
        • Linux:
          
          ./vmss2core-Linux64 -N virtual_machine_name.vmss

Additional Information

 Troubleshooting

• If vmss2core tool returns an output including this message, it means that the files does not contain usable data:
  
  Error parsing Windows data.
Cannot create memory.dmp

• 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 boot message states:
    
    Windows failed to start. A recent hardware or software change might be the cause.
    
    
  • The virtual machine boots up and does not progress past the BIOS boot screen.
    
    
• Examples of a virtual machine that would have usable data:
  
  
  • The virtual machine booted with a Windows Blue Screen error (BSOD).
    
    
  • The virtual machine booted and a Linux kernel panic occurred.
    
    
  • The virtual machine is frozen after the OS boots.

For additional information, refer:

Debugging Virtual Machines with the Checkpoint to Core Tool Guide.

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 instead produce a .core memory dump rather than a standard format.