Virtual Hard Disk version 2 (VHDX) image format

Summary

A commonly image format used in Microsoft virtualization products is the Virtual Hard Disk version 2 (VHDX) Image format. This specification is based on available documentation and was enhanced by analyzing test data.

This document is intended as a working document of the data format specification for the libvhdi project.

Document information

Author(s):	Joachim Metz <joachim.metz@gmail.com>
Abstract:	This document contains information about the Virtual Hard Disk version 2 (VHDX) Image format
Classification:	Public
Keywords:	Virtual Hard Disk, VHDX, Virtual PC, Virtual Server, Hyper-V Server

License

Copyright (C) 2020, Joachim Metz <joachim.metz@gmail.com>.
Permission is granted to copy, distribute and/or modify this document under the
terms of the GNU Free Documentation License, Version 1.3 or any later version
published by the Free Software Foundation; with no Invariant Sections, no
Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included
in the section entitled "GNU Free Documentation License".

Revision history

Version	Author	Date	Comments
0.0.1	J.B. Metz	October 2020	Initial version
0.0.2	J.B. Metz	December 2020	Additional information

1. Overview

A commonly image format used in Microsoft virtualization products is the Virtual Hard Disk version 2 (VHDX) Image format. This specification is based on available documentation and was enhanced by analyzing test images.

A VHDX image file consist of the following distinguishable elements:

file (type) identifier
2x image headers
2x region tables
log or metadata journal
block allocation table (BAT) region
metadata region
- metadata table
- metadata items
image (content) data

The elements are stored in 64 KiB (65536 bytes) aligned blocks

TODO: determine if the header with the largest sequence number was written the latest?

Characteristics	Description
Byte order	big-endian
Character strings	Unicode strings are stored in UTF-16 litte-endian without the byte order mark (BOM).

1.1. Test versions

The following versions of programs were used to generate test data to that was used for the information in this document:

Diskpart on Windows 10 (2004)

2. File (type) identifier

The file (type) identifier is 64 KiB (65536 bytes) of size and consists of:

Offset	Size	Value	Description
0	8	"vhdxfile"	Signature
8	512		Creator application and version UTF-16 little-endian string with end-of-string character
520	65016		Unknown (reserved)

3. Image header

The image header is 4 KiB (4096 bytes) of size and consists of:

Offset	Size	Value	Description
0	4	"head"	Signature
4	4		Checksum Contains a CRC-32C (or CRC32-C), which uses the Castagnoli polynomial (0x1edc6f41) of the 4 KiB image header where the checksum value is set to 0
8	8		Sequence number
16	16		Unknown (file write identifier) Contains a GUID
32	16		Unknown (data write identifier) Contains a GUID
48	16		Unknown (log identifier) Contains a GUID
64	2		Log format version
66	2	1	Format version
68	4		Unknown (log size) According to `[MS-VHDX]` this value must be a multitude of 1 MiB
72	8		Unknown (log offset) According to `[MS-VHDX]` this value must be a multitude of 1 MiB and greater than or equal to 1 MiB
80	4016	0	Unknown (reserved) According to `[MS-VHDX]` this value must be set to 0

4. Region table

The region table is stored in a block of 64 KiB (65536 bytes) and consists of:

region table header
0 or more region table entries
Unknown (reserved)

TODO: determine if 0 entries is actually supported

4.1. Region table header

The region table header is 16 bytes of size and consists of:

Offset	Size	Value	Description
0	4	"regi"	Signature
4	4		Checksum Contains a CRC-32C (or CRC32-C), which uses the Castagnoli polynomial (0x1edc6f41) of the 64 KiB region table where the checksum value is set to 0
8	4		Number of table entries According to `[MS-VHDX]` this value must be less than or equal to 2047
12	4	0	Unknown (reserved) According to `[MS-VHDX]` this value must be set to 0

4.2. Region table entry

The region table entry is 32 bytes of size and consists of:

Offset	Size	Description
0	16	Region type identifier Contains a GUID See section: Region type identifiers
16	8	Region data offset Contains an offset relative to the start of the file According to `[MS-VHDX]` this value must be a multitude of 1 MiB and greater than or equal to 1 MiB
24	4	Region data size According to `[MS-VHDX]` this value must be a multitude of 1 MiB
28	4	Is required flag Contains 1 to indicate the region is required to be supported by the implementation

4.3. Region type identifiers

Value	Identifier	Description
2dc27766-f623-4200-9d64-115e9bfd4a08		Block allocation table (BAT) region
8b7ca206-4790-4b9a-b8fe-575f050f886e		Metadata region

5. Metadata region

The metadata region contains:

metadata table
metadata items

5.1. Metadata table

The metadata table is stored in a block of 64 KiB (65536 bytes) and consists of:

metadata table header
0 or more metadata table entries
Unknown (reserved)

TODO: determine if 0 entries is actually supported

5.1.1. Metadata table header

The metadata table header is 32 bytes of size and consists of:

Offset	Size	Value	Description
0	8	"metadata"	Signature
8	2	0	Unknown (reserved) According to `[MS-VHDX]` this value must be set to 0
10	2		Number of table entries According to `[MS-VHDX]` this value must be less than or equal to 2047
12	20	0	Unknown (reserved) According to `[MS-VHDX]` this value must be set to 0

5.1.2. Metadata table entry

The metdata table entry is 32 bytes of size and consists of:

Offset	Size	Description
0	16	Metadata item identifier Contains a GUID See section: Metadata item identifiers
16	4	Metadata item offset Contains an offset relative to the start of the metadata region According to `[MS-VHDX]` this value must be greater than 64 KiB
20	4	Metadata item size
24	8	Unknown

TODO: describe last 8 bytes

Value	Identifier	Description
0x00000001	IsUser
0x00000002	IsVirtualDisk
0x00000004	IsRequired

5.2. Metadata items

5.2.1. Metadata item identifiers

Value	Identifier	Description
2fa54224-cd1b-4876-b211-5dbed83bf4b8		Virtual disk size
8141bf1d-a96f-4709-ba47-f233a8faab5f		Logical sector size
a8d35f2d-b30b-454d-abf7-d3d84834ab0c		Parent locator
beca12ab-b2e6-4523-93ef-c309e000c746		Virtual disk identifier
caa16737-fa36-4d43-b3b6-33f0aa44e76b		File parameters
cda348c7-445d-4471-9cc9-e9885251c556		Physical sector size

5.2.2. File parameters metadata item

The file parameters metadata item is 8 bytes of size and consists of:

Offset	Size	Value	Description
0	4		Block size According to `[MS-VHDX]` this value must be a power of 2 and greater than or equal to 1 MiB and not greater than 256 MiB
4.0	1 bit		Blocks remain allocated This flag is used to indicate the file is a fixed-size image
4.1	1 bit		Has parent Value that indicates if the VHDX file contains a differential image that has a parent
4.2	30 bits	0	Unknown (reserved) According to `[MS-VHDX]` this value must be set to 0

5.2.3. Logical sector size metadata item

The logical sector size metadata item is 4 bytes of size and consists of:

Offset	Size	Value	Description
0	4		Logical sector size According to `[MS-VHDX]` this value must be either 512 or 4096

5.2.4. Parent locator metadata item

The parent locator metadata item is variable of size and consits of:

parent locator header
0 or more parent locator entry
parent locator key and value data

TODO: determine if 0 entries is actually supported

Parent locator header

The parent locator header is 20 bytes of size and consists of:

Offset	Size	Value	Description
0	16		Parent locator type indicator Contains the GUID: b04aefb7-d19e-4a81-b789-25b8e9445913
16	2	0	Unknown (reserved) According to `[MS-VHDX]` this value must be set to 0
18	2		Number of entries (or key-value pairs)

Parent locator entry

The parent locator entry is 12 bytes of size and consists of:

Offset	Size	Description
0	4	Key data offset Contains the offset relative from the start of the parent locator header
4	4	Value data offset Contains the offset relative from the start of the parent locator header
8	2	Key data size
10	2	Value data size

Parent locator key and value data

A parent locator key or value is stored as UTF-16 little-endian string without end-of-string character.

Known keys are:

Value	Description
absolute_win32_path	The value contains an absolute drive Windows path "\\?\c:\file.vhdx"
parent_linkage	The value contains a string of a GUID This GUID should correspond to the data write identifier of the parent file
parent_linkage2	The value contains a string of a GUID
relative_path	The value contains a relative Windows path "..\file.vhdx"
volume_path	The value contains an absolute volume Windows path with "\\?\Volume{%GUID%}\file.vhdx"

5.2.5. Physical sector size metadata item

The physical sector size metadata item is 4 bytes of size and consists of:

Offset	Size	Value	Description
0	4		Physical sector size According to `[MS-VHDX]` this value must be either 512 or 4096

5.2.6. Virtual disk identifier metadata item

The virtual disk identifier metadata item is 16 bytes of size and consists of:

Offset	Size	Value	Description
0	16		Virtual disk identifier Contains a GUID

Note	In contrast to VHD (version 1) the virtual disk identifier does not change between a differential image and its parent. The data write identifier seems to be used instead.

5.2.7. Virtual disk size metadata item

The virtual disk size metadata item is 8 bytes of size and consists of:

Offset	Size	Value	Description
0	8		Virtual disk size

6. Block allocation table (BAT) region

The block allocation table (BAT) region contains the block allocation table. The entries of this table describe the location of either blocks containing image content data (or payload blocks) or blocks containing a sector bitmap.

The size of an individual sector bitmap block is 1 MiB which allows for 2^23 sectors to be represented by the bitmap.

Block allocation table (BAT) entries are grouped in chunks. The size of a chunk can be calculated as following:

number of entries per chunk = ( 2^23 * logical sector size ) / block size

The block allocation table (BAT) consists of:

one or more chunks containing:
number of entries per chunk x BAT entry describing image content data
1 x BAT entry describing the a sector bitmap

Unused BAT entries are filled with 0-byte values.

The block allocation table (BAT) of:

a fixed-size image does not contain sector bitmap entries;
a dynamic-size image does contain sector bitmap entries, although according to [MS-VHDX] are not used;
a differential image does contain sector bitmap entries.

6.1. Block allocation table (BAT) entry

The block allocation table (BAT) entry is 64 bits of size and consists of:

Offset	Size	Value	Description
0.0	3 bits		Block state
0.3	17 bits	0	Unknown (reserved) According to `[MS-VHDX]` this value must be set to 0
2.4	44 bits		Block offset Contains the offset relative from the start of the file as a multitude of 1 MiB

6.2. Block states

6.2.1. Payload block states

Value	Identifier	Description
0	PAYLOAD_BLOCK_NOT_PRESENT	Block is new and therefore not (yet) stored in the file
1	PAYLOAD_BLOCK_UNDEFINED	Block is not stored in the file
2	PAYLOAD_BLOCK_ZERO	Block is sparse and therefore filled with 0-byte values
3	PAYLOAD_BLOCK_UNMAPPED	Block has been unmapped

6	PAYLOAD_BLOCK_FULLY_PRESENT	Block is stored in the file
7	PAYLOAD_BLOCK_PARTIALLY_PRESENT	Block is stored in the parent

6.2.2. Sector bitmap block states

Value	Identifier	Description
0	SB_BLOCK_NOT_PRESENT	Block is new and therefore not (yet) stored in the file

6	SB_BLOCK_PRESENT	Block is stored in the file

6.3. Sector bitmap

In differential disk images the sector bitmap indicates which sectors are stored within the image (bit set to 1) or in the parent (bit set to 0).

The bitmap is stored in a 1 MiB block.

The bitmap is stored on a per-byte basis with the LSB represents the first bit in the bitmap.