Introduction
A .vmss file is the suspended state file of a VMware
virtual machine: it stores the state of a machine that has been suspended, so that it can resume. ESX
writes the same kind of file when it suspends a machine. The guest's memory is kept in the file or in a
.vmem file beside it. The format is not published by VMware;
this page follows Volatility's VMware address space (after Nir Izraeli's vmsnparser) and its wiki page
"VMware Snapshot File", both read in full for this page.
Structure
All numbers are little-endian. The file starts with a header, then an array of group records; each group points to a run of tags; the guest memory and other data are tag data.
0Header magic, a value, the group count12 bytes12Group table one 80-byte record for each groupcount × 80…Tags of each group, ending with a (0, 0) tagvaries…Memory pages inside the Memory tag's datavaries
Header
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
0 | 4 | uint32 | Magic | 0xBED2BED0, 0xBAD1BAD1, 0xBED2BED2 or 0xBED3BED3. Volatility derives the storage format version from the low nibble (magic & 0xF): 0, 1, 2 or 3. |
4 | 4 | uint32 | Unknown | Volatility's structure names nothing here (its 3.x reader unpacks the value and discards it); the meaning is not known. |
8 | 4 | uint32 | Group count | The number of group records. |
Group record (80 bytes)
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
0 | 64 | text | Name | The group name, UTF-8, null-padded (for example Checkpoint, cpu, memory). |
64 | 8 | uint64 | Tags offset | The file offset of the group's first tag. |
72 | 8 | uint64 | Unknown | Part of the 80 bytes (Volatility 3 unpacks it as an unused value); not named. |
Tag
| Part | Size | Description |
|---|---|---|
| Flags | 1 | Bits 0 to 5: the data length, 0 to 63; 62 and 63 mean a long tag (below). Bits 6 and 7: the number of 32-bit indices, 0 to 3. |
| Name length | 1 | The length of the name in bytes. |
| Name | name length | The tag name, UTF-8. |
| Indices | 4 each | Tell tags of the same name within a group apart: CR[0][3] is control register 3 of CPU 0. |
| Data | data length | For a short tag, immediately after the indices; 1, 2, 4 and 8 bytes are numbers. |
| Long tag | 2 × size, 2, padding, data | With length 62 or 63: the size on disk and the size in memory (32-bit in version 0, 64-bit later), then a 16-bit padding length and that many padding bytes, then the data. The next tag follows the data. |
| End | 2 | A tag with flags 0 and name length 0 ends the group. |
Volatility 2 adds the padding length to the offset of the data; Volatility 3 skips the two bytes and notes "as it seems", so the handling of non-zero padding is not settled.
The memory group
Volatility's wiki: with less than 4 GB of memory there is one run, in the group memory as the
tag Memory with indices [0][0]; with more there are several, described by the tags
regionsCount, regionPPN[i], regionPageNum[i] and
regionSize[i] (all in 4,096-byte pages). Region i belongs at guest physical address
regionPPN × 4096; in the .vmss it is stored at regionPageNum × 4096 from the start
of the Memory tag's data. For a .vmem file, Volatility 3 maps the
physical address onto regionPageNum × 4096 in the .vmem.
Not described
Unknown
- Reference: the bytes 4 to 7 of the header and bytes 72 to 79 of each group record.
- Reference: the meaning of every tag the sources do not print (the CPU, device and memory-manager state), and how the saved device state is encoded. VMware has not published it.
- Viewer: such tags are shown by name, indices and raw value, labelled unknown; the memory runs open as files, and an embedded configuration text or PNG opens in its own viewer.
Links
Software
- VMware Workstation Pro – VMware's desktop virtual machine software (Windows, Linux)
- VMware Fusion – VMware's virtual machine software for the Mac (macOS)
- Volatility 3 – memory forensics framework that reads .vmss and .vmem files (Python)
Reference
- VMware Snapshot File – Volatility's description of the header, groups and tags
- Contents of the virtual machine bundle in Fusion – VMware's table of the files of a machine