WIXLIB

VMWARE TECHNICAL NOTEVMware Virtual DisksVirtual Disk Format 1.1Virtual machines created with VMware products typically use virtual disks. The virtual disks,stored as files on the host computer or on a remote storage device, appear to the guestoperating systems as standard disk drives.This technical note begins with a high-level introduction to the layout of the files that make up aVMware virtual disk of the type used by VMware Workstation 4, VMware Workstation 5, VMwareWorkstation 6, VMware Player, VMware Fusion, VMware GSX Server 3, VMware Server, andVMware ESX Server 3. It then drills down into the details of the data structures inside thosevirtual disk files.The document contains the following sections: Layout Basics on page 2 The Descriptor File on page 3 Simple Extents on page 7 Hosted Sparse Extents on page 7 ESX Server Sparse Extents on page 12 Stream-Optimized Compressed Sparse Extents on page 14 Glossary on page 18VMware, Inc. 3401 Hillview Ave., Palo Alto, CA 94304 www.vmware.comCopyright 1998-2007 VMware, Inc. All rights reserved. VMware, the VMware “boxes” logo and design, Virtual SMP andVMotion are registered trademarks or trademarks of VMware, Inc. in the United States and/or other jurisdictions. Microsoft,Windows and Windows NT are registered trademarks of Microsoft Corporation. Linux is a registered trademark of Linus Torvalds.All other marks and names mentioned herein may be trademarks of their respective companies.Revision: 20071113 Version: 1.1 Item: NP-ENG-Q205-099To ensure that readers of this specification have access to the most current version, readers may download copies of thisspecification from www.vmware.com and no part of this specification (whether in hardcopy or electronic form) may bereproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying,recording, or otherwise, without the prior written permission of VMware, Inc., except as otherwise permitted under copyrightlaw. Please note that the content in this specification is protected under copyright law even if it is not distributed with softwarethat includes an end user license agreement.This specification and the information contained herein is provided on an “AS-IS” basis, is subject to change without notice, andto the maximum extent permitted by applicable law, VMware, Inc., its subsidiaries and affiliates provide the document AS ISAND WITH ALL FAULTS, and hereby disclaim all other warranties and conditions, either express, implied or statutory, includingbut not limited to, any (if any) implied warranties, duties or conditions of merchantability, of fitness for a particular purpose, ofaccuracy or completeness of responses, of results, of workmanlike effort, of lack of viruses, and of lack of negligence, all withregard to the document. ALSO, THERE IS NO WARRANTY OR CONDITION OF TITLE, QUIET ENJOYMENT, QUIET POSSESSION,CORRESPONDENCE TO DESCRIPTION OR NON-INFRINGEMENT OF ANY INTELLECTUAL PROPERTY RIGHTS WITH REGARD TO THEDOCUMENT.IN NO EVENT WILL VMWARE, ITS SUBSIDIARIES OR AFFILIATES BE LIABLE TO ANY OTHER PARTY FOR THE COST OF PROCURINGSUBSTITUTE GOODS OR SERVICES, LOST PROFITS, LOSS OF USE, LOSS OF DATA, OR ANY INCIDENTAL, CONSEQUENTIAL, DIRECT,INDIRECT, OR SPECIAL DAMAGES WHETHER UNDER CONTRACT, TORT, WARRANTY, OR OTHERWISE, ARISING IN ANY WAY OUT OFTHIS OR ANY OTHER AGREEMENT RELATING TO THIS DOCUMENT, WHETHER OR NOT SUCH PARTY HAD ADVANCE NOTICE OFTHE POSSIBILITY OF SUCH DAMAGES.1

Virtual Disk Format 1.1Virtual machines created by VMware products other than VMware Workstation 4, VMwareWorkstation 5, VMware Workstation 6, VMware Fusion, VMware GSX Server 3, VMware Server,and VMware ESX Server 3 may use formats different from those described in this document. Keyareas that are not discussed in this technical note include the following: Virtual disks created in legacy mode in Workstation 5, or virtual disks created in ESX Server2 or earlier, GSX Server 3 or earlier, Workstation 4 or earlier, or VMware ACE Device-backed virtual disks Encryption Encrypted extents Encrypted descriptor files Defragmenting a virtual disk Shrinking a virtual disk Consolidating virtual disksLayout BasicsVMware virtual disks can be described at a high level by looking at two key characteristics. The virtual disk may use backing storage contained in a single file, or it may use storagethat consists of a collection of smaller files. All of the disk space needed for a virtual disk’s files may be allocated at the time the virtualdisk is created, or the virtual disk may start small and grow only as needed to accomodatenew data.A particular virtual disk may have any combination of these two characteristics.One common characteristic of recent-generation VMware virtual disks is that a text descriptordescribes the layout of the data in the virtual disk. This descriptor may be saved as a separate fileor may be embedded in a file that is part of a virtual disk. The section titled The Descriptor Fileon page 3 explains the information contained in the descriptor.The way a virtual disk uses storage space on a physical disk varies, depending on the type ofvirtual disk you select when you create the virtual machine.Initially, for example, a virtual disk consists of only the base disk. If you take a snapshot of a virtualmachine, its virtual disk includes both the base link and a delta link (referred to in some productdocumentation as a redo-log file). Changes the guest operating system has written to disk sinceyou took the snapshot are stored in the delta link. It is possible for more than one delta link to beassociated with a particular base disk.Think of the base disk and the delta links as links in a chain. The virtual disk consists of all the linksin the chain.Link ABase diskLink BDelta link 1Link CDelta link 2Links in the chain that makes up the virtual disk2

Virtual Disk Format 1.1Each link in the chain is made up of one or more extents.Extent 0Extent 1Extent 2Extent 3Extents that make up a linkAn extent is a region of physical storage, often a file, that is used by the virtual disk.In the links diagram above, links B and C are necessarily made up of extents that begin small andgrow over time, referred to as sparse extents. Link A can be made up of extents of any kind —sparse, preallocated, or even backed directly by a physical device.The Descriptor FileFor a more detailed view of how these elements of a virtual disk come together in practice, lookat the following example text descriptor file, called test.vmdk. It describes a link in a virtualdisk that is split into files no larger than 2GB each and that starts small and grows as data isadded. The descriptor file is not case-sensitive.Lines beginning with # are comments and are ignored by the VMware program that opens thedisk.% cat test.vmdk# Disk DescriptorFileversion 1CID fffffffeparentCID ffffffffcreateType "twoGbMaxExtentSparse"# Extent descriptionRW 4192256 SPARSE "test-s001.vmdk"RW 4192256 SPARSE "test-s002.vmdk"RW 2101248 SPARSE "test-s003.vmdk"# The Disk Data Base#DDBddb.adapterType "ide"ddb.geometry.sectors "63"ddb.geometry.heads "16"ddb.geometry.cylinders "10402"The HeaderThe first section of the descriptor is the header. It provides the following information about thevirtual disk: versionThe number following version is the version number of the descriptor. The default valueis 1. CIDThis line shows the content ID. It is a random 32-bit value updated the first time thecontent of the virtual disk is modified after the virtual disk is opened.Every link header contains both a content ID and a parent content ID (described below).If a link has a parent — as is true of links B and C in the diagram of links in a chain — theparent content ID is the content ID of the parent link.3

Virtual Disk Format 1.1If a link has no parent — as is true of link A in the diagram of links in a chain — the parentcontent ID is set to CID NOPARENT (defined below).The purpose of the content ID is to check the following: In the case of a base disk with a delta link, that the parent link has not changed since thetime the delta link was created. If the parent link has changed, the delta link must beinvalidated. That the bottom-most link was not modified between the time the virtual machine wassuspended and the time it was resumed or between the time you took a snapshot ofthe virtual machine and the time you reverted to the snapshot. parentCIDThis line shows the content ID of the parent link — the previous link in the chain — if thereis one. If the link does not have any parent (in other words, if the link is a base disk), theparent’s content ID is set to the following value:#define CID NOPARENT( 0x0) createTypeThis line describes the type of the virtual disk. It can be one of the following: monolithicSparse vmfsSparse monolithicFlat vmfs twoGbMaxExtentSparse twoGbMaxExtentFlat fullDevice vmfsRaw partitionedDevice vmfsRawDeviceMap vmfsPassthroughRawDeviceMap streamOptimizedThe first six terms are used to describe various types of virtual disks. Terms that includemonolithic indicate that the data storage for the virtual disk is contained in a single file.Terms that include twoGbMaxExtent indicate that the data storage for the virtual diskconsists of a collection of smaller files. Terms that include sparse indicate that the virtualdisks start small and grow to accommodate data. Some product documentation refers tothese virtual disks as growable disks. Terms that include flat indicate that all spaceneeded for the virtual disks is allocated at the time they are created. Some productdocumentation refers to these virtual disks as preallocated disks.Terms that include vmfs indicate that the disk is an ESX Server disk.The terms fullDevice, vmfsRaw, and partitionedDevice are used when thevirtual machine is configured to make direct use of a physical disk — either a full disk orpartitions on a disk — rather than store data in files managed by the host operatingsystem.4

Virtual Disk Format 1.1The terms vmfsRawDeviceMap and vmfsPassthroughRawDeviceMap are usedin headers for disks that use ESX Server raw device mapping.The term streamOptimized is used to describe disks that have been optimized forstreaming. parentFileNameHintThis line, present only if the link is a delta link, contains the path to the parent of the deltalink.The ExtentsEach line of the second section describes one extent. The extents are enumerated beginningwith the one accessible at offset 0 from the virtual machine’s point of view. The format of the linelooks like one of the following examples:RW 4192256 SPARSE "test-s001.vmdk"AccessType of extentFilenameSize in sectorsRW 1048576 FLAT "test-f001.vmdk" 0AccessType of extentFilenameOffsetSize in sectorsThe extent descriptions provide the following key information: Access — may be RW, RDONLY, or NOACCESS Size in sectors — a sector is 512 bytes Type of extent — may be FLAT, SPARSE, ZERO, VMFS, VMFSSPARSE, VMFSRDM, orVMFSRAW. Filename — shows the path to the extent (relative to the location of the descriptor)Note: If the type of the virtual disk, shown in the header, is fullDevice orpartitionedDevice, then the filename should point to an IDE or SCSI block device. If thetype of the virtual disk is vmfsRaw, the filename should point to a file in /vmfs/devices/disks/. Offset — the offset value is specified only for flat extents and corresponds to the offset inthe file or device where the guest operating system’s data is located. For preallocatedvirtual disks, this number is zero. For device-backed virtual disks (physical or raw disks), itmay be non-zero.5