Virtual Disk Programming Guide
`
`vSphere Storage APIs for Data Protection (VADP) 6.0
`Virtual Disk Development Kit (VDDK) 6.0
`
`This document supports the version of each product listed and
`supports all subsequent versions until the document is replaced
`by a new edition. To check for more recent editions of this
`document, see http://www.vmware.com/support/pubs.
`
`EN-001430-04
`
`WIZ, Inc. EXHIBIT - 1055
`WIZ, Inc. v. Orca Security LTD.
`
`

`

`Virtual Disk Programming Guide
`
`You can find the most up-to-date technical documentation on the VMware Web site at:
`
`http://www.vmware.com/support/
`
`The VMware Web site also provides the latest product updates.
`
`If you have comments about this documentation, submit your feedback to:
`docfeedback@vmware.com 
`
`Copyright © 2008–2016 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and
`intellectual property laws. VMware products are covered by one or more patents listed at
`http://www.vmware.com/go/patents.
`VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks
`and names mentioned herein may be trademarks of their respective companies.
`
`VMware, Inc.
`3401 Hillview Ave.
`Palo Alto, CA 94304
`www.vmware.com
`
`2
`
`
`
`VMware, Inc.
`
`

`

`Contents
`
`About This Book 9
`
`11
`
`1 Introduction to the Virtual Disk API
`About the Virtual Disk API 11
`VDDK Components 11
`Virtual Disk Library 12
`Disk Mount Library 12
`Virtual Disk Utilities 12
`12
`Backup and Restore on vSphere
`Backup Design for vCloud Director 12
`Use Cases for the Virtual Disk Library 12
`Developing for VMware Platform Products 12
`Managed Disk and Hosted Disk 13
`Advanced Transports
`14
`VDDK and VADP Compared 14
`Platform Product Compatibility 14
`Redistributing VDDK Components 14
`
`15
`
`2 Installing the Development Kit
`Prerequisites 15
`Development Systems 15
`Programming Environments 15
`Visual Studio on Windows 15
`C++ and C on Linux 15
`Java Development for VADP 15
`VMware Platform Products 15
`Storage Device Support
`16
`Installing the VDDK Package
`16
`Repackaging VDDK Libraries 17
`How to Find VADP Components
`
`17
`
`19
`
`3 Virtual Disk Interfaces
`VMDK File Location 19
`Virtual Disk Types 19
`Persistence Disk Modes 20
`VMDK File Naming 20
`Thin Provisioned Disk 21
`Internationalization and Localization 21
`Virtual Disk Internal Format 21
`Grain Directories and Grain Tables 21
`Data Structures in Virtual Disk API
`21
`Credentials and Privileges for VMDK Access
`Adapter Types 23
`Virtual Disk Transport Methods
`Local File Access 23
`SAN Transport 23
`HotAdd Transport 24
`
`23
`
`22
`
`VMware, Inc.
`
`
`
`3
`
`

`

`Virtual Disk Programming Guide
`
`About the HotAdd Proxy 25
`NBD and NBDSSL Transport
`25
`NFC Session Limits 26
`SSL Certificates and Security 26
`
`28
`
`4 Virtual Disk API Functions
`27
`27
`Virtual Disk Library Functions
`Alphabetic Table of Functions
`Start Up 28
`Initialize the Library 29
`Connect to a Workstation or Server 29
`VMX Specification 29
`Disk Operations 30
`Create a New Hosted Disk 30
`Open a Local or Remote Disk 30
`Read Sectors From a Disk 30
`Write Sectors To a Disk 30
`Close a Local or Remote Disk 30
`Get Information About a Disk 31
`Free Memory from Get Information 31
`Metadata Handling 31
`Read Metadata Key from Disk 31
`Get Metadata Table from Disk 31
`Write Metadata Table to Disk 31
`Check and Repair Sparse Disk Metadata 31
`Cloning a Virtual Disk 31
`Compute Space Needed for Clone
`Clone a Disk by Copying Data 32
`Disk Chaining and Redo Logs
`32
`Create Child from Parent Disk 32
`Attach Child to Parent Disk 33
`Opening in a Chain 33
`Redo Logs and Linked Clone Backup 34
`Error Handling 34
`Return Error Description Text
`Free Error Description Text 34
`Administrative Disk Operations 34
`Rename an Existing Disk 34
`Grow an Existing Local Disk 34
`Defragment an Existing Disk 35
`Shrink an Existing Local Disk 35
`Unlink Extents to Remove Disk 35
`Shut Down 35
`Disconnect from Server 35
`Clean Up and Exit
`35
`35
`Advanced Transport APIs
`Initialize Virtual Disk API 36
`Location of Log Files 37
`List Available Transport Methods 38
`Connect to VMware vSphere
`38
`Get Selected Transport Method 38
`Prepare For Access and End Access 39
`SAN Mode on Linux Uses Direct Mode
`Clean Up After Disconnect 39
`Updating Applications for Advanced Transport 40
`
`31
`
`34
`
`39
`
`4
`
`
`
`VMware, Inc.
`
`

`

`Contents
`
`Algorithm for vSphere Backup 40
`Backup and Recovery Example 40
`Multithreading Considerations 42
`Multiple Threads and VixDiskLib 42
`Capabilities of Library Calls 42
`Support for Managed Disk 42
`Support for Hosted Disk 42
`
`43
`
`43
`
`5 Virtual Disk API Sample Code
`Compiling the Sample Program 43
`Visual C++ on Windows 43
`SLN and VCPROJ Files
`C++ on Linux Systems
`44
`Makefile 44
`Library Files Required 44
`Usage Message 44
`Walk‐Through of Sample Program 45
`Include Files 45
`Definitions and Structures 45
`Dynamic Loading 46
`Wrapper Classes 46
`Command Functions 46
`DoInfo() 46
`47
`DoCreate()
`DoRedo() 47
`Write by DoFill() 47
`DoReadMetadata()
`47
`DoWriteMetadata()
`47
`DoDumpMetadata()
`47
`DoDump()
`48
`DoTestMultiThread() 48
`DoClone()
`48
`SSL Certificate Thumbprint
`
`48
`
`6 Practical Programming Tasks
`49
`Scan VMDK for Virus Signatures 49
`Creating Virtual Disks 50
`Creating Local Disk 50
`Creating Remote Disk 51
`Special Consideration for ESXi Hosts 51
`VMDK File Versions 51
`Working with Virtual Disk Data 52
`Reading and Writing Local Disk 52
`Reading and Writing Remote Disk 52
`Deleting a Disk (Unlink) 52
`Effects of Deleting a Virtual Disk 52
`Renaming a Disk 52
`Effects of Renaming a Virtual Disk 53
`Managing Child Disks 53
`Creating Redo Logs
`53
`Virtual Disk in Snapshots 53
`Windows 2000 Read‐Only File System 53
`RDM Disks and Virtual BIOS 54
`Restoring RDM Disks 54
`
`VMware, Inc.
`
`
`
`5
`
`

`

`Virtual Disk Programming Guide
`
`54
`
`Restoring the Virtual BIOS or UEFI
`Interfacing With VMware vSphere
`55
`The VIX API 55
`Virus Scan all Hosted Disk 55
`The vSphere Web Services API 55
`Virus Scan All Managed Disk 56
`Read and Write VMDK Using vSphere API
`
`56
`
`57
`
`58
`
`7 Backing Up Virtual Disks in vSphere
`Design and Implementation Overview 57
`The Backup Process
`57
`Communicating With the Server 58
`Information Containers as Managed Objects
`More About Managed Objects 58
`Managed Object References 59
`Unique ID for a Different vCenter 59
`Gathering Status and Configuration Information 59
`PropertyCollector Data 59
`Useful Property Information 60
`Doing a Backup Operation 60
`Prerequisites for Backup 60
`Create a Temporary Snapshot on the Target Virtual Machine
`Changed Block Tracking 61
`Extract Backup Data from the Target Virtual Machine
`Delete the Temporary Snapshot
`61
`The Restore Process 61
`Doing a Restore Operation 62
`Prerequisites for Restore
`62
`Restoring an Existing Virtual Machine to a Previous State 62
`Creating a New Virtual Machine
`63
`Accessing Files on Virtual Disks 63
`More VADP Details 64
`Low Level Backup Procedures 64
`Communicating with the Server 64
`The PropertyCollector 64
`64
`PropertyCollector Arguments
`Getting the Data from the PropertyCollector 67
`Identifying Virtual Disks for Backup and Restore 68
`Creating a Snapshot 69
`Backing Up a Virtual Disk 69
`Deleting a Snapshot 70
`Changed Block Tracking on Virtual Disks
`Enabling Changed Block Tracking 71
`Gathering Changed Block Information 71
`Troubleshooting 73
`Limitations on Changed Block Tracking 73
`Checking for Namespace 73
`Low Level Restore Procedures 73
`Restoring a Virtual Machine and Disk 73
`Creating a Virtual Machine 74
`Using the VirtualMachineConfigInfo 80
`Editing or Deleting a Device
`80
`Restoring Virtual Disk Data 80
`Raw Device Mapping (RDM) Disks
`
`60
`
`61
`
`70
`
`80
`
`6
`
`
`
`VMware, Inc.
`
`

`

`Contents
`
`81
`
`Restore of Incremental Backup Data 81
`Restore Fails with Direct Connection to ESXi Host
`Tips and Best Practices 81
`Best Practices for SAN Transport 82
`Best Practices for HotAdd Transport 82
`Best Practices for NBDSSL Transport 83
`General Backup and Restore
`83
`Backup and Restore of Thin‐Provisioned Disk 83
`Virtual Machine Configuration 83
`About Changed Block Tracking 84
`HotAdd and SCSI Controller IDs 84
`Windows Backup Implementations 84
`Disabling Automount in Windows Proxy 84
`Security and Remote Desktop 85
`Working with Microsoft Shadow Copy 85
`Application‐Consistent Backup and Restore
`The VMware VSS Implementation 87
`Linux Backup Implementation 87
`
`86
`
`8 Backing Up vApps in vCloud Director 89
`Introduction to Tenant vApps 89
`Prerequisites 90
`Other Information 90
`Conceptual Overview 90
`The Backup Process
`91
`The Restore Process 91
`Use Cases Overview 92
`Managing Credentials 92
`Finding a vApp 93
`93
`Inventory Traversal
`Using the Query Service 93
`Protecting Specified vApps 93
`Recovering an Older Version of a vApp 93
`Recovering a Deleted vApp 93
`Recovering a Single Virtual Machine 93
`Backing Up vCloud Director 93
`vCloud API Operations
`94
`Getting Access to vCloud Director 94
`Inventory Access
`94
`Admin Views 95
`Admin Extensions 95
`Retrieving Catalog information 98
`Retrieving vApp Configuration 99
`Methods To Retrieve vApp Configuration 99
`Virtual Machine Information 100
`Preventing Updates to a vApp During Backup or Restore
`Associating vCloud Resources with vSphere Entities 101
`Restoring vApps 103
`Conclusion 104
`
`100
`
`A Virtual Disk Mount API
`105
`The VixMntapi Library 105
`Types and Structures
`105
`Operating System Information 105
`Disk Volume Information 106
`
`VMware, Inc.
`
`
`
`7
`
`

`

`Virtual Disk Programming Guide
`
`106
`Function Calls
`106
`VixMntapi_Init()
`106
`VixMntapi_Exit()
`107
`VixMntapi_OpenDiskSet()
`107
`VixMntapi_OpenDisks()
`VixMntapi_GetDiskSetInfo() 107
`VixMntapi_FreeDiskSetInfo() 108
`VixMntapi_CloseDiskSet()
`108
`VixMntapi_GetVolumeHandles() 108
`VixMntapi_FreeVolumeHandles()
`108
`VixMntapi_GetOsInfo()
`108
`VixMntapi_FreeOsInfo()
`109
`VixMntapi_MountVolume() 109
`VixMntapi_DismountVolume()
`109
`VixMntapi_GetVolumeInfo()
`109
`VixMntapi_FreeVolumeInfo()
`109
`Programming with VixMntapi
`110
`File System Support
`110
`Read‐Only Mount on Linux 110
`Sample VixMntapi Code 111
`Restrictions on Virtual Disk Mount 111
`
`113
`
`B Errors Codes and Open Source
`Recent Changes 113
`Finding Error Code Documentation 113
`Association With VIX API Errors 113
`Interpreting Errors Codes 113
`Troubleshooting Dynamic Libraries
`Open Source Components 114
`
`114
`
`Glossary 115
`
`Index 117
`
`8
`
`
`
`VMware, Inc.
`
`

`

`About This Book
`
`The VMware® Virtual Disk Programming Guide introduces the Virtual Disk Development Kit (VDDK) and the 
`vSphere Storage APIs – Data Protection (VADP). For VDDK it describes how to develop software using a 
`virtual disk library that provides a set of system‐call style interfaces for managing virtual disks on ESXi hosts. 
`For VADP it describes how to write backup and restore software managed by vCenter Server® for vSphere.
`To view this version or previous versions of this book and other public VMware API and SDK documentation, 
`go to http://www.vmware.com/support/pubs/sdk_pubs.html.
`
`Revision History
`Table 1 summarizes the significant changes in each version of this guide.
`
`Table 1. Revision History
`Revision
`Description
`
`2016‐03‐25
`2016‐02‐02
`2015‐07‐13
`2015‐05‐05
`2014‐12‐26
`2014‐04‐08
`2013‐11‐08
`2013‐10‐14
`2013‐09‐22
`2012‐12‐21
`2012‐10‐05
`2011‐11‐18
`2011‐08‐22
`2010‐10‐12
`2010‐08‐05
`2009‐05‐29
`2008‐04‐11
`2008‐01‐31
`
`Removed statement that disks not associated with a virtual machine can be mounted.
`Fallback to NBD, SCSI order for disk mount, no linked clone SAN restore, EUC non‐support.
`Clarified connection port and RAID support, more whitelist details, added Linux freeze and thaw.
`Documented whitelist and blacklist for device path selection, corrected install procedures.
`Revision for VDDK 6.0. Virtual volumes support. SSL certificate checking now mandatory.
`VDDK 5.5.1 supports GPT. Snapshot quiesce and memory are incompatible. Describe VMDK version 3.
`Fixed several errors involving roles and licensing, physical or virtual proxy, and log level.
`Corrections regarding 32‐bit Windows and PackageCode. Removed Reparent and Combine APIs.
`Final version for the vSphere 5.5 release, with new chapter on vApp backup for vCloud Director.
`Bug fix version of the vSphere 5.1 manual: numeric change ID policy, mount restrictions.
`Final version of this manual for the vSphere 5.1 release.
`Bug fix version for 4Q 2011 refresh of the VMware vSphere Documentation Center.
`Final version for the VDDK 5.0 release, subsuming Designing Backup Solutions technical note.
`Bug fix revision for the VDDK 1.2.1 release
`Version for vSphere 4.1 and the VDDK 1.2 public release.
`Final version for the VDDK 1.1 public release.
`Updated version for release 1.0 of the Virtual Disk Development Kit.
`Initial version of the Virtual Disk Development Kit for partner release.
`
`VMware, Inc.
`
`
`
`9
`
`

`

`Virtual Disk Programming Guide
`
`Intended Audience
`This guide is intended for developers who are creating applications that manage virtual storage, especially 
`backup and restore applications. It assumes knowledge of C and C++ programming. For VADP development, 
`this guide assumes knowledge of Java.
`
`Supported Platform Products
`You can develop VDDK programs using either Linux or Windows, and test them using VMware Workstation 
`or ESXi and vSphere. To develop and test VADP programs, you need a vCenter Server and ESXi hosts, 
`preferably with shared cluster storage.
`
`Document Feedback
`VMware welcomes your suggestions for improving our developer documentation. Send your feedback to 
`docfeedback@vmware.com.
`
`VMware Technical Publications
`VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitions 
`of terms as they are used in VMware technical documentation go to http://www.vmware.com/support/pubs.
`To access the current versions of VMware manuals, go to http://pubs.vmware.com/vsphere‐50/index.jsp.
`
`10
`
`
`
`VMware, Inc.
`
`

`

`1
`
`Introduction to the Virtual Disk API
`
`1
`
`
`
`
`
`
`
`
`
`This chapter presents the following topics:
`“About the Virtual Disk API” on page 11
`“VDDK Components” on page 11
`“Use Cases for the Virtual Disk Library” on page 12
`“Developing for VMware Platform Products” on page 12
`The virtual disk development kit (VDDK) is an SDK to help developers create applications that access storage 
`on virtual machines. The VDDK package is based on the virtual disk API, introduced in this chapter.
`The VMware Storage APIs – Data Protection (VADP) use the virtual disk API and a subset of vSphere APIs to 
`take snapshots of virtual machines running on ESXi, enabling full or incremental backup and restore. VADP 
`replaces VMware Consolidated Backup (VCB).
`
`About the Virtual Disk API
`The virtual disk API, or VixDiskLib, is a set of function calls to manipulate virtual disk files in VMDK format 
`(virtual machine disk). Function call semantics are patterned after C system calls for file I/O. Using the virtual 
`disk API, you can write programs to manage VMDK files directly from your software applications. 
`These library functions can manipulate virtual disks on VMware Workstation or similar products (hosted disk) 
`or virtual disks residing on file system volumes of an ESXi host managed by vCenter Server (managed disk). 
`Hosted is a term meaning that the virtualization platform and disk are hosted by a guest operating system 
`such as Windows or Linux.
`The VDDK package installs on either Windows or Linux, so you can write VDDK and VADP applications 
`using either system. Applications can manipulate the virtual disks of any operating system that runs on a 
`supported VMware platform product. You may repackage VDDK binaries into your software application after 
`signing a redistribution agreement. See the VDDK Release Notes for a list of supported platform products and 
`development systems.
`The VDDK and VADP enable you to develop applications that work effectively across multiple virtual disks 
`from a central location.
`
`VDDK Components
`The virtual disk development kit includes the following components:
`The virtual disk library, a set of C function calls to manipulate VMDK files
`The disk mount library, a set of C function calls to remote mount VMDK file systems
` C++ code samples that can be compiled with Visual Studio or the GNU C compiler
`PDF manuals and online HTML reference
`
`
`
`
`
`
`
`VMware, Inc.
`
`
`
`11
`
`

`

`Virtual Disk Programming Guide
`
`
`
`
`
`Virtual Disk Library
`VixDiskLib is a standalone wrapper library to help you develop solutions that integrate into VMware platform 
`products. The virtual disk library has the following capabilities:
`It allows programs to create, convert, expand, defragment, shrink, and rename virtual disk files.
`It can create redo logs (parent‐child disk chaining, or deltas) and it can delete VMDK files.
`It permits random read/write access to data anywhere in a VMDK file, and reads metadata. 
`It can connect to remote vSphere storage using advanced transports, SAN or HotAdd.
`For Windows, the virtual disk kernel‐mode driver should be 64‐bit. User libraries could be 32‐bit because 
`Windows On Windows 64 can run 32‐bit programs without alteration. VMware provides only 64‐bit libraries.
`
`
`
`
`
`Disk Mount Library
`The virtual disk mount library, vixMntapi, allows programmatic access of virtual disks as if they were 
`mounted disk partitions. For more information see Appendix A, “Virtual Disk Mount API,” on page 105. The 
`vixMntapi library is packaged in the VDDK with vixDiskLib.
`
`Virtual Disk Utilities
`The Virtual Disk Development Kit used to include two command‐line utilities for managing virtual disk files: 
`disk mount and virtual disk manager. They were last delivered in the VDDK 5.0 release. For more information 
`see the old Disk Mount and Virtual Disk Manager User’s Guide, still available on the Web.
`
`Backup and Restore on vSphere
`The VMware Storage APIs – Data Protection (VADP) is a collection of APIs that are useful for developing or 
`extending backup software so it can protect virtual machines running on ESXi hosts in VMware based 
`datacenters. For more information see Chapter 7, “Backing Up Virtual Disks in vSphere,” on page 57.
`
`Backup Design for vCloud Director
`With VMware vCloud®, the self‐service capabilities of vCloud Director provide three levels of data protection. 
`Backup providers can offer vApp protection at the system level, the tenant level, or the end‐user level. For 
`information about vCloud data protection, see the technical note Backup Design for vCloud Tenant vApps.
`
`Use Cases for the Virtual Disk Library
`The library provides access to virtual disks, enabling a range of use cases for application vendors including: 
`Back up a particular volume, or all volumes, associated with a virtual machine.
` Connect a backup proxy to vSphere and back up all virtual machines on a storage cluster.
`Read virtual disk and run off‐line anti‐virus scanning, or package analysis, of virtual machines.
` Write to virtual disk to perform off‐line centralized patching of virtual machines.
` Manipulate virtual disks to defragment, expand, convert, rename, or shrink the file system image.
`Perform data recovery or virus cleaning on corrupt or infected off‐line virtual machines.
`
`
`
`
`
`
`
`Developing for VMware Platform Products
`In a VMware based data center, commercial backup software is likely to access virtual disks remotely, perhaps 
`from a backup proxy. The proxy can be a virtual machine or a physical machine with backup‐restore software 
`installed and access to alternate storage such as a tape autochanger or equivalent.
`
`12
`
`
`
`VMware, Inc.
`
`

`

`Chapter 1 Introduction to the Virtual Disk API
`
`At a given point in time, during the backup window, backup software:
`1
`Snapshots virtual machines in a cluster, one by one, or in parallel. Virtual machines run off the snapshot.
`2
`Copies the quiesced base disk, or (for incremental backup) only changed blocks, to backup media.
`3
`Records the configuration of virtual machines.
`4
`Reverts and deletes snapshots, so virtual machines retain any changes made during the backup window.
`In the above procedure, the virtual disk library is used in the second step only. The other steps use a portion 
`of the vSphere API (called VADP) to snapshot and save configuration of virtual machines. The virtual disk in 
`a cluster is “managed” by vSphere.
`
`Managed Disk and Hosted Disk
`Analogous to a hard disk drive, virtual disk files represent the storage volumes of a virtual machine. Each is 
`named with .vmdk suffix. On a system running VMware Workstation, file systems of each guest OS are kept 
`in VMDK files hosted on the system’s physical disk. VMDK files can be accessed directly on the host. 
`With the virtual machine file system (VMFS) on ESXi hosts, VMDK files again represent storage volumes of 
`virtual machines. They are on VMFS, which often resides on shared storage in a cluster. The vCenter Server 
`manages the cluster storage so it can migrate (vMotion) virtual machines from one ESXi host to another 
`without moving VMDK files. VMFS storage is therefore called managed disk.
`VMFS disk can reside on a storage area network (SAN) attached to ESXi hosts by Fibre Channel, iSCSI, or SAS 
`connectors. It can also reside on network attached storage (NAS), or on directly attached disk. 
`Figure 1‐1 depicts the arrangement of managed disk (in this case VMDK on a SAN‐hosted VMFS file system) 
`and hosted disk (VMDK files on physical disk).
`
`Figure 1-1. Managed Disk and Hosted Disk
`
`ESX1
`
`ESX2
`
`ESX3
`
`VM1
`DB
`
`VM2
`Mail
`
`VM3
`Java
`
`VM4
`File
`
`VM5
`DB
`
`VM6
`Web
`Server
`
`cluster
`
`SAN
`
`VMDK
`
`VMDK
`
`VMDK
`
`VMDK
`
`VMDK
`
`VMDK
`
`VMFS1 (LUN1)
`
`Workstation
`
`Guest OS
`
`Guest OS
`
`Guest OS
`
`VMDK
`
`VMDK
`
`VMDK
`
`The VDDK supports both managed disk and hosted disk, although some functions are not supported for 
`managed disk, and other facilities are not supported for hosted disk. Exceptions are noted in documentation.
`
`VMware, Inc.
`
`
`
`13
`
`

`

`Virtual Disk Programming Guide
`
`Advanced Transports
`With managed disk, VDDK applications can make use of advanced transports to perform many I/O operations 
`directly on the SAN, rather than over the LAN. This improves performance and saves network bandwidth.
`
`VDDK and VADP Compared
`The Virtual Disk Development Kit (VDDK) includes a set of C library routines for manipulating virtual disk 
`(VixDiskLib) and for mounting virtual disk partitions (VixMntapi). The VDDK focuses on efficient access and 
`transfer of data on virtual disk storage.
`The vSphere Storage APIs for Data Protection (VADP) is a marketing term for a subset of the vSphere API 
`that enables backup and restore applications. The snapshot‐based VADP framework allows efficient, off‐host, 
`centralized backup of virtual machine storage. After taking a snapshot to quiesce virtual disk, software can 
`then back up storage using VDDK library routines.
`The vSphere API is an XML‐based Web service that provides the interfaces for vCenter Server management of 
`virtual machines running on ESXi hosts.
`Developers need both VDDK and VADP to write data protection software. VADP is presented in Chapter 7, 
`“Backing Up Virtual Disks in vSphere,” on page 57.
`
`Platform Product Compatibility
`To support a new release of vSphere, in most cases you should update and recompile your software with a 
`corresponding new release of VDDK. This is because VDDK is continually updated to support new features 
`in vSphere. As of 5.0, the version number of VDDK matches the version number of vSphere.
`Since its inception in 2008, VDDK has been backward compatible with virtual platform products such as 
`VMware Workstation, ESXi, and vCenter Server. VMware Fusion was never supported.
`
`Redistributing VDDK Components
`After you use the VDDK to develop software applications that run on VMware platform products, you might 
`need to repackage library components that are compiled into your software.
`To qualify for VDDK redistribution, you must be in the VMware TAP program at Select level or above, and 
`sign a redistribution agreement. Contact your VMware alliance manager to request the VDDK redistribution 
`agreement. VMware would like to know how you use the VDDK, in what products you plan to redistribute it, 
`your company name, and your contact information.
`
`14
`
`
`
`VMware, Inc.
`
`

`

`3Vi
`
`Virtual Disk Interfaces
`
`3
`
`
`
`
`
`VMware offers many options for virtual disk layout, encapsulated in library data structures described here.
`“VMDK File Location” on page 19
`“Virtual Disk Types” on page 19
`“Data Structures in Virtual Disk API” on page 21
`“Virtual Disk Transport Methods” on page 23
`
`
`
`
`
`VMDK File Location
`On ESXi hosts, virtual machine disk (VMDK) files are usually located under one of the /vmfs/volumes, 
`perhaps on shared storage. Storage volumes are visible from the vSphere Client, in the inventory for hosts and 
`clusters. Typical names are datastore1 and datastore2. To see a VMDK file, click Summary > Resources > 
`Datastore, right‐click Browse Datastore, and select a virtual machine.
`On Workstation, VMDK files are stored in the same directory with virtual machine configuration (VMX) files, 
`for example /path/to/disk on Linux or C:\My Documents\My Virtual Machines on Windows. 
`VMDK files store data representing a virtual machine’s hard disk drive. Almost the entire portion of a VMDK 
`file is the virtual machine’s data, with a small portion allotted to overhead.
`
`
`
`
`
`
`
`Virtual Disk Types
`The following disk types are defined in the virtual disk library: 
`VIXDISKLIB_DISK_MONOLITHIC_SPARSE – Growable virtual disk contained in a single virtual disk file. 
`This is the default type for hosted disk, and the only setting in the Chapter 5 sample program. 
`VIXDISKLIB_DISK_MONOLITHIC_FLAT – Preallocated virtual disk contained in a single virtual disk file. 
`This takes time to create and occupies a lot of space, but might perform better than sparse.
`VIXDISKLIB_DISK_SPLIT_SPARSE – Growable virtual disk split into 2GB extents (s sequence). These 
`files can to 2GB, then continue growing in a new extent. This type works on older file systems. 
`VIXDISKLIB_DISK_SPLIT_FLAT – Preallocated virtual disk split into 2GB extents (f sequence). These 
`files start at 2GB, so they take a while to create, but available space can grow in 2GB increments.
`VIXDISKLIB_DISK_VMFS_FLAT – Preallocated virtual disk compatible with ESX 3 and later. Also known 
`as thick disk. This managed disk type is discussed in “Managed Disk and Hosted Disk” on page 13. 
`VIXDISKLIB_DISK_VMFS_SPARSE – Employs a copy‐on‐write (COW) mechanism to save storage space.
`VIXDISKLIB_DISK_VMFS_THIN – Growable virtual disk that consumes only as much space as needed, 
`compatible with ESX 3 or later, supported by VDDK 1.1 or later, and highly recommended.
`VIXDISKLIB_DISK_STREAM_OPTIMIZED – Monolithic sparse format compressed for streaming. Stream 
`optimized format does not support random reads or writes.
`
`
`
`
`
`
`
`
`
`
`
`VMware, Inc.
`
`
`
`19
`
`

`

`Virtual Disk Programming Guide
`
`Persistence Disk Modes
`In persistent disk mode, changes are immediately and permanently written to the virtual disk, so that they 
`survive even through to the next power on. 
`In nonpersistent mode, changes to the virtual disk are discarded when the virtual machine powers off. The 
`VMDK files revert to their original state. 
`The virtual disk library does not encapsulate this distinction, which is a virtual machine setting.
`
`VMDK File Naming
`Table 3‐1 explains the different types of virtual disk. The first column corresponds to “Virtual Disk Types” on 
`page 19 but without the VIXDISKLIB_DISK prefix. The third column gives the possible names of VMDK files 
`as implemented on Workstation and ESXi hosts.
`NOTE   When you open a VMDK file with the virtual disk library, always open the one that points to the others, 
`not the split or flat sectors. The file to open is most likely the one with the shortest name. 
`For information about other virtual machine files, see section “Files that Make Up a Virtual Machine” in the 
`VMware Workstation User’s Manual. On ESXi hosts, VMDK files are type VMFS_FLAT or VMFS_THIN. 
`
`Table 3-1. VMDK Virtual Disk Files
`Disk Type in API
`Virtual Disk Creation on VMware Host
`
`MONOLITHIC_SPARSE
`
`MONOLITHIC_FLAT 
`or VMFS_FLAT
`or VMFS_THIN
`
`SPLIT_SPARSE
`
`SPLIT_FLAT
`
`MONOLITHIC_SPARSE 
`or SPLIT_SPARSE
`snapshot
`
`SE_SPARSE
`
`n/a
`
`In Select A Disk Type, accepting the defaults by not checking any 
`box produces one VMDK file that can grow larger if more space is 
`needed. The <vmname> represents the name of a virtual machine.
`On VMFS partitions, this is name of the disk descriptor file.
`If you select only the Allocate all disk space now check box, space 
`is pre‐allocated, so the virtual disk cannot grow. The first VMDK 
`file is small and points to a much larger one, whose filename says 
`flat without a sequence number.
`Similarly on VMFS partitions, this is the virtual disk file that 
`points to virtual disk data files, either thick or thin provisioned.
`If you select only the Split disk into 2GB files check box, virtual 
`disk can grow when more space is needed. The first VMDK file is 
`small and points to a sequence of other VMDK files, all of which 
`have an s before a sequence number, meaning sparse. The number 
`of VMDK files depends on the disk size requested. As data grows, 
`more VMDK files are added in sequence.
`If you select the Allocate all disk space now and Split disk into 
`2GB files check boxes, space is pre‐allocated, so the virtual disk 
`cannot grow. The first VMDK file is small and points to a sequence 
`of other files, all of which have an f before the sequence number, 
`meaning flat. The number of files depends on the requested size.
`A redo log (or child disk or delta link) is created when a snapshot 
`is taken of a virtual machine, or with the virtual disk library. 
`Snapshot file numbers are in sequence, without an s or f prefix. 
`The numbered VMDK file stores changes made to the virtual disk 
`<diskname> since the original parent disk, or previously 
`numbered redo log (in other words the previous snapshot). 
`Space‐efficient sparse (seSparse) format. In vSphere 5.1 and later, 
`used by VMware View to optimize linked clone templates. In the 
`vSphere API, see data object SeSparseVirtualDiskSpec. Use of 
`seSparse as a base disk is neither documented nor supported.
`Snapshot of a virtual machine, which includes pointers to all its 
`.vmdk virtual disk files.
`
`Filename on Host
`
`<vmname>.vmdk
`
`<vnname>-flat.vmdk
`
`<vmname>-s<###>.vmdk
`
`<vnname>-f<###>.vmdk
`
`<diskname>-<###>.vmdk
`
`<vnname>Snapshot.vmsn
`
`For lazy zeroed thick disk, all blocks are allocated, and data written to used blocks, however unused blocks 
`are left as‐is, so they may contain data from previous use. Many storage systems will zero‐out unused blocks 
`in the background. With eager zeroed thick disk, unused blocks are zeroed‐out at allocation time. 
`
`20
`
`
`
`VMware, Inc.
`
`

`

`Chapter 3 Virtual Disk Interfaces
`
`Thin Provisioned Disk
`With thin provisioned disk, the vSphere Client may report that provisioned size is greater than disk capacity.
`Provisioned size for a thin disk is the maximum size the disk will occupy when fully allocated. Actual size is 
`the current size of the thin disk. Overcommit means that if all thin disks were fully provisioned, there would 
`not be enough space to accommodate all of the thin disks. 
`
`Internationalization and Localization
`VDDK libraries are not localized, but backup partners can support any locale that uses UTF‐8 encoding. Other 
`than Unicode, VDDK does not support multibyte character encodings such as Extended Unix Code (EUC) for 
`Chinese, Japanese, and Korean (ISO‐2022).
`The path name to a virtual machine and its VMDK can be expressed with any character set supported by the 
`host file system. As of vSphere 4 and Workstation 7, VMware supports Unicode UTF‐8 path names, although 
`for portability to various locales, ASCII‐only path names are recommended. 
`Windows 2000 systems (and later) use UTF‐16 for localized path names. For example, in locale FR (Français) 
`the VDDK sample code might mount disk at C:\Windows\Temp\vmware‐Système, where è is encoded as 
`UTF‐16 so the VixMntapi library cannot recognize it. In this case, a workaround is to set the tmpDirectory 
`configuration key with an ASCII‐only path before program start‐up; see “Initialize the Library” on page 29.
`For programs opening arbitrary path names, Unicode offers a GNU library with C functions iconv_open() 
`to initialize codeset conversion, and iconv() to convert UTF‐8 to UTF‐16, or UTF‐16 to UTF‐8.
`
`Virtual Disk Internal Format
`The Virtual Disk Format 5.0 technical note provides possibly useful information about the VMDK format, and 
`is available at this URL: 
`http://www.vmware.com/support/developer/vddk/vmdk_50_technote.pdf 
`
`Grain Directories and Grain Tables
`SPARSE type virtual disks use a hierarchical representation to organize sectors. See Virtual Disk Format 5.0 
`referenced in “Virtual Disk Internal Format” on page 21. In this context, grain means granular unit of data, 
`larger than a sector. The hierarchy includes:
` Grain directory (and redundant grain directory) whose entries point to grai