Virtual Disk API Programming Guide

VMware Virtual Disk Development Kit 1.0

Virtual Disk API Programming Guide

Virtual Disk API Programming Guide Revision: 20080411 VDDK Virtual Disk Development Kit

You can find the most up-to-date technical documentation on our 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

2008 VMware, Inc. All rights reserved. Protected by one or more of U.S. Patent Nos. 6,397,242, 6,496,847, 6,704,925, 6,711,672, 6,725,289, 6,735,601, 6,785,886, 6,789,156, 6,795,966, 6,880,022, 6,944,699, 6,961,806, 6,961,941, 7,069,413, 7,082,598, 7,089,377, 7,111,086, 7,111,145, 7,117,481, 7,149,843, 7,155,558, 7,222,221, 7,260,815, 7,260,820, 7,269,683, 7,275,136, 7,277,998, 7,277,999, 7,278,030, 7,281,102, and 7,290,253; patents pending. VMware, the VMware boxes logo and design, Virtual SMP and VMotion are registered trademarks or trademarks 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

VMware, Inc.

Contents

AboutThisBook

1 IntroductiontotheVirtualDiskAPI 9
VirtualDiskManagement 9 WhatisManagedDisk? 9 VirtualDiskDevelopmentKit 10 VirtualDiskManagementUtilities 10 DiskMountUtility 10 VirtualDiskManagerUtility 10 VirtualDiskAPI 10 VMwareInfrastructureAPItoReadandWriteVMDK 10 VirtualDiskInternalFormat 11 SolutionsEnabledbytheVirtualDiskAPI 11 VirtualDiskLibraryFunctions 12

2 InstallingtheVirtualDiskDevelopmentKit 13
PackagingandComponents 13 SupportedPlatforms 13 ProgrammingEnvironments 13 VisualStudioonWindows 13 C++andConLinuxSystems 13 InstallingtheVirtualDiskDevelopmentKit 14 TargetSystemConnectivity 14 VMwareProducts 14 VMDKAccessandCredentials 14

3 VirtualDiskAPIFunctions 15
VirtualDiskandDataStructures 15 VMDKFileLocation 15 DiskTypes 15 PersistenceDiskModes 16 VMDKFileNaming 16 GrainDirectoriesandGrainTables 16 InternationalizationandLocalization 17 AdapterTypes 17 DataStructuresinVirtualDiskAPI 17 LibraryFunctions 18 StartUp 18 InitializetheLibrary 18 ConnecttoaWorkstationorServer 18 DiskOperations 18 CreateaNewHostedDisk 18 OpenaLocalorRemoteDisk 18 ReadSectorsFromaDisk 18 WriteSectorsToaDisk 19 CloseaLocalorRemoteDisk 19

VMware, Inc.

Virtual Disk API Programming Guide

GetInformationAboutaDisk 19 FreeMemoryfromGetInformation 19 ErrorHandling 19 ReturnErrorDescriptionText 19 FreeErrorDescriptionText 19 MetadataHandling 19 ReadMetadataKeyfromDisk 19 GetMetadataTablefromDisk 19 WriteMetadataTabletoDisk 20 CloningaVirtualDisk 20 ComputeSpaceNeededforClone 20 CloneaDiskbyCopyingData 20 AdvancedDiskOperations 20 RenameanExistingDisk 20 GrowanExistingLocalDisk 20 DefragmentanExistingDisk 20 ShrinkanExistingLocalDisk 20 UnlinkExtentstoRemoveDisk 21 DiskChainingandRedoLogs 21 CreateChildfromParentDisk 21 AttachChildtoParentDisk 22 ShutDown 22 DisconnectfromServer 22 CleanUpandExit 22 CapabilitiesofLibraryCalls 23 SupportforHostedDisk 23 SupportforManagedDisk 23

4 VirtualDiskAPISampleCode 25
CompilingtheSampleProgram 25 VisualC++onWindows 25 SLNandVCPROJFiles 25 C++onLinuxSystems 25 Makefile 26 LibraryFilesRequired 26 UsageMessage 26 WalkThroughofSampleProgram 26 IncludeFiles 26 DefinitionsandStructures 26 DynamicLoading 27 WrapperClasses 27 CommandFunctions 27 VMXSpecification 27 DoInfo() 28 DoCreate() 28 DoRedo() 28 WritebyDoFill() 28 DoReadMetadata() 28 DoWriteMetadata() 29 DoDumpMetadata() 29 DoDump() 29 DoTestMultiThread() 29 DoClone() 29

VMware, Inc.

Contents

5 PracticalProgrammingTasks 31
ScanVMDKforVirusSignatures 31 CreatingVirtualDisks 32 CreatingLocalDisk 32 CreatingRemoteDisk 33 SpecialConsiderationforESXServer 33 WorkingwithVirtualDiskData 33 ReadingandWritingLocalDisk 33 ReadingandWritingRemoteDisk 34 DeletingaDisk(Unlink) 34 EffectsofDeletingaVirtualDisk 34 RenamingaDisk 34 EffectsofRenamingaVirtualDisk 34 WorkingwithDiskMetadata 34 ManagingChildDisks 34 CreatingRedoLogs 34 VirtualDiskinSnapshots 35 Windows2000ReadOnlyFileSystem 35 InterfacingWiththeVIXAPI 35 VirusScanallHostedDisk 36 InterfacingWithVMwareInfrastructure 36 VirusScanAllManagedDisk 36

A VirtualDiskAPIErrors 37
FindingErrorCodeDocumentation 37 AssociationWithVIXAPIErrors 37

B OpenVirtualMachineFormat 39
OVFTool 39 OVFLibrary 39

Glossary Index 43

41

VMware, Inc.

Virtual Disk API Programming Guide

VMware, Inc.

About This Book

TheVirtualDiskAPIProgrammingGuideintroducestheVirtualDiskDevelopmentKitanddescribeshowto developsoftwareusingtheVMwarevirtualdisklibrary,whichprovidesasetofsystemcallstyleinterfaces formanagingvirtualdisks.

Revision History
Thisbookisrevisedwitheachreleaseoftheproductorwhennecessary.Arevisedversioncancontainminor ormajorchanges.Table 1summarizesthesignificantchangesineachversionofthisguide. Table 1. Revision History
Revision 20080411 20080131 Description SecondversionoftheVirtualDiskDevelopmentKitdocumentationfordeliverywithrelease1.0. FirstversionoftheVirtualDiskDevelopmentKitdocumentationforpartnerbetarelease.

Intended Audience
Thisguideisintendedfordeveloperswhoarecreatingapplicationsthatmanagevirtualstorage. VMwareoffersmanySDKproductsthattargetdifferentdevelopercommunities,programminglanguages, andplatforms.Tofindthem,andthemostcurrentversionofthisguide,goto http://www.vmware.com/support/pubs/sdk_pubs.html.

Technical Support and Education Resources

Thefollowingsectionsdescribethetechnicalsupportresourcesavailabletoyou.Youcanaccessthemost currentversionsofotherVMwaremanualsbygoingto: http://www.vmware.com/support/pubs

Online Support
YoucansubmitquestionsorpostcommentstotheDeveloperCommunitysSDKsandAPIsforum,whichis monitoredbyVMwaretechnicalsupportandproductteams.Youcanaccesstheforumat: http://communities.vmware.com/community/developer

Support Offerings
FindouthowVMwaresupportofferingscanhelpmeetyourbusinessneeds.Goto http://www.vmware.com/support/services.

VMware, Inc.

Virtual Disk API Programming Guide

VMware Education Services

VMwarecoursesofferextensivehandsonlabs,casestudyexamples,andcoursematerialsdesignedtobeused asonthejobreferencetools.FormoreinformationaboutVMwareEducationServices,goto http://mylearn1.vmware.com/mgrreg/index.cfm.

Document Feedback
VMwarewelcomesyoursuggestionsforimprovingourdocumentation.Ifyouhavecomments,sendyour feedbackto: docfeedback@vmware.com

VMware, Inc.

Introduction to the Virtual Disk API

ThischapterintroducesVMwarevirtualdiskmanagementandtheVirtualDiskDevelopmentKit.

Virtual Disk Management

TheVirtualDiskAPI,orVixDiskLib,isasetoffunctioncallstomanipulatevirtualdiskfilesinVMDKformat (virtualmachinedisk).FunctioncallsemanticsarepatternedafterCsystemcallsforfileI/O.ThisAPIenables partnersandsoftwarevendorstomanageVMDKdirectlyfromtheirapplications. TheselibraryfunctionscanmanipulatevirtualdiskonaVMwareWorkstationorsimilarproduct(hosteddisk) orvirtualdiskcontainedwithinaVMFSvolumeonanESXServer(manageddisk).Hosteddiskisanoriginal VMwareconceptmeaningadiskmanagedbytheWorkstationhostforaguestoperatingsystem.

What is Managed Disk?

VMDKformatdatesbacktotheearlydaysofVMwareWorkstation.Virtualmachinediskfilesrepresentthe storagevolumesofavirtualmachine,andarenamedwith.vmdksuffix.OnaVMwareWorkstationhost,file systemsofeachguestOSarekeptinVMDKfilesonthehostsphysicaldiskdrive. Withthevirtualmachinefilesystem(VMFS)forESXServer,VMDKfilesrepresentthediskvolumesofvirtual machinesonVMFS.Thisiscalledmanageddisk.ManageddiskisthesamethingasVMFS_FLATvirtualdisk, presentedinDiskTypesonpage 15.FunctionsintheVirtualDiskAPIsupportVMFS,withsomeexceptions asnotedformanageddisk. VMFSdiskcanresideonaSAN(storageareanetwork)attachedtotheESXServerbyFibreChanneloriSCSI. Itcanalsoresideonnetworkattachedstorage,andondirectlyattacheddisk.Inallcases,ESXServermanages physicaldisk.TheVirtualDiskAPIhasnofacilitytoaddressastoragepartitiondirectly.ForVMFSplanning, seethewhitepaperVMwareVirtualMachineFileSystem:TechnicalOverviewandBestPracticesintheResources sectionoftheVMwareWebsite.Followtheconfigurationadviceofyourstoragevendor. Figure 1-1. Managed Disk and Hosted Disk

ESX Server Workstation Guest OS Guest OS Guest OS

VMDK

VMDK

VMDK

VMware, Inc.

Virtual Disk API Programming Guide

Virtual Disk Development Kit

TheVirtualDiskDevelopmentKitincludesthefollowingcomponents: VirtualDiskAPIlibraryfunctions VMwarediskutilities:diskmountandvirtualdiskmanager Documentationfortheabovecomponents

Virtual Disk Management Utilities

TheVirtualDiskDevelopmentKitincludestwocommandlineutilitiesformanagingvirtualdisk:diskmount andvirtualdiskmanager.ThevirtualdiskmanagerisincludedwithWorkstation6.0.xandServerproducts. DiskmountisavailableintheVirtualDiskDevelopmentKitandinupcomingproducts.

Disk Mount Utility

VMwarediskmount(vmware-mount)isautilityforWindowsandLinuxhosts.Ifavirtualdiskisnotinuse, theutilitymountsitasanindependentdiskvolume,soitcanbeexaminedoutsideitsoriginalvirtualmachine. Youcanalsomountspecificvolumesofavirtualdiskifthevirtualdiskispartitioned. DiskmountisusefulbecausetheVirtualDiskAPIcontainsnofunctionformakingamountedpartition availabletootherprocesses.OpeningaVMDKislikemounting,butforthecallingprocessonly. SeetheVMwareDiskMountUsersGuide,whichisavailableontheWebandinthekit.

Virtual Disk Manager Utility

VMwarevirtualdiskmanager(vmware-vdiskmanager)isacommandlineutilityforWindowsandLinux hosts.Itallowsyoutocreate,convert,expand,defragment,shrink,andrenamevirtualdiskfiles.Itdoesnot haveafacilitytocreateredologsorsnapshots. SeetheVMwareVirtualDiskManagerUsersGuide,whichisavailableontheWebandinthekit.

Virtual Disk API

VMwareprovidesgraphicaltoolsandcommandlineutilitiestohelpadministratorsmanagevirtualdisk. Customershaveaskedforprogrammaticinterfacesalso.TheVirtualDiskAPIpartlyduplicatesfunctionality ofthevirtualdiskmanagementutilitiesandhasadditionalcapabilities: Itpermitsrandomread/writeaccesstodataanywhereinaVMDKfile. Itcreatesandmanagesredologs(parentchilddiskchaining,ordeltalinks). Itcanreadandwritediskmetadata. ItisabledeleteVMDKfilesprogrammatically. Errorexplanationsareavailable. ManyoperationsareeasiertoautomatewithanAPIthanwithutilities. Thisisastandalonewrapperlibrarythathelpsyoudevelopsolutionsthatintegrateintovirtualdiskfacilities ofVMwareWorkstation,ESXServer,andVirtualCenter.

VMware Infrastructure API to Read and Write VMDK

Version2.5oftheVMwareInfrastructure(VI)APIcontainssomeexperimentalmethodstomanageVMDK files.SeethemanagedobjecttypeVirtualDiskManager,whichcontainsaboutadozenmethodssimilarto thoseintheVirtualDiskAPIdocumentedhere. Ifyouareinterested,navigatetotheVMwareInfrastructureSDKontheWebandclickVIAPIReferenceGuide forVIAPI2.5.FindVirtualDiskManagerunderAllTypes.

10

VMware, Inc.

Chapter 1 Introduction to the Virtual Disk API

Virtual Disk Internal Format

AdocumentdetailingtheVMwarevirtualdiskformatisavailableonrequest.NavigatetoVMwareInterfaces Webpage,clicktheRequestlink,andprovideyourname,organization,andemailaddress.Alinktotheonline PDFdocumentshouldarriveshortlyinyouremailinbox. http://www.vmware.com/interfaces/vmdk.html ThisVirtualDiskFormat1.0documentprovidesusefulinformationabouttheVMDKformat.Itusestheterm deltalinkforwhatthismanualcallsredologorchilddisk.

Solutions Enabled by the Virtual Disk API

Whenintegratedintoapplications,theVirtualDiskAPIallowsyoutomanipulatevirtualdiskimagesand providesupportforVMDKformat. SometaskscanbeaccomplishedeitherbythevirtualdiskmanagementutilityorbytheAPI: Createanewsetofnewvirtualdisksandpreparetoprovisionapplications. Createdisktemplatesforfreshsysteminstall,orpatchupdates,bytheITdepartment. Backupaparticularvolume,orallvolumes,associatedwithavirtualmachine. ClonetheVMDKofavirtualmachineandusetheclonedcopytoperformofflinemaintenance. Manipulatevirtualdiskstodefragment,expand,rename,orshrinktheunderlyingfilesystemimage. Convertavirtualdisktoanotherformat,forexamplefromhosteddisktomanageddisk. Convertaphysicaldisktoavirtualdisk(P2V),oravirtualdisktoaphysicaldisk(V2P). Migratevirtualdisksondemandtoenableuserworkforcemobility. SomesolutionscanbedevelopedmoreeasilywiththeVirtualDiskAPIthanwiththeutilities: ScanaVMDKforvirussignatures,eitherlive,orfirstcloningitforofflinescanning.Itisnotnecessary fortheantivirusscannertohaveknowledgeoftheunderlyingfilesystem. Searchfordatainvirtualdisksacrossmultiplevirtualmachines. Performdatarecoveryfromunresponsiveorcorruptvirtualmachines. VerifytheintegrityofaVMDKandpossiblyrepairthefilesystemimage. OptimizeVMDKimagesbycombiningandcompactingthem. Writedefragmentationtoolsthatoperateonthenativefilesystem,notonlyon2GBextents. CreateVMDKsavesbybackingupthechild,compactingtheimage,andcreatinganewchild. MakeapluginforaforensicanalysistoolsuchastheXWaysproduct. DevelopatoollikeVDK,anopensourcekernelmodedriverthatopens(mounts)aVMDKforreadwrite accessonaWindowsdriveletter. ExtendVMDKforadditionalOSsupport,forexamplemountcapabilityinBSD. Createdisksupporttoolstoassisthardwarevendors.

VMware, Inc.

11

Virtual Disk API Programming Guide

Virtual Disk Library Functions

Table 11alphabeticallylistsfunctioncallsintheVirtualDiskAPI. Table 1-1. Virtual Disk API Functions
Function VixDiskLib_Attach VixDiskLib_Clone VixDiskLib_Close VixDiskLib_Connect VixDiskLib_Create VixDiskLib_CreateChild VixDiskLib_Defragment VixDiskLib_Disconnect VixDiskLib_Exit VixDiskLib_FreeErrorText VixDiskLib_FreeInfo VixDiskLib_GetErrorText VixDiskLib_GetInfo VixDiskLib_GetMetadataKeys VixDiskLib_Grow VixDiskLib_Init VixDiskLib_Open VixDiskLib_Read VixDiskLib_ReadMetadata VixDiskLib_Rename VixDiskLib_Shrink VixDiskLib_SpaceNeededForClone VixDiskLib_Unlink VixDiskLib_Write VixDiskLib_WriteMetadata Description Attachesthechilddiskchaintotheparentdiskchain. Copiesvirtualdisktosomedestination,convertingformatsasappropriate. Closesanopenvirtualdisk. Connectstothevirtualdisklibrarytoobtainservices. Createsavirtualdiskaccordingtospecifiedparameters. Createsachilddisk(redologordeltalink)forahostedvirtualdisk. Defragmentsavirtualdisk. Disconnectsfromthevirtualdisklibrary. Releasesallresourcesheldbythelibrary. FreesthemessagebufferallocatedbyGetErrorText. FreesthememoryallocatedbyGetInfo. Returnsthetextdescriptionofalibraryerrorcode. Retrievesinformationaboutavirtualdisk. Retrievesallkeysinthemetadataofavirtualdisk. Growsanexistingvirtualdisk. Initializesthevirtualdisklibrary. Opensavirtualdisk. Readsarangeofsectorsfromanopenvirtualdisk. Retrievesthevalueofagivenkeyfromdiskmetadata. Renamesavirtualdisk. Reclaimsblocksofzeroesfromthevirtualdisk. Computesthespacerequiredtocloneavirtualdisk,inbytes. Deletesthespecifiedvirtualdisk. Writesarangeofsectorstoanopenvirtualdisk. Updatesvirtualdiskmetadatawiththegivenkey/valuepair.

12

VMware, Inc.

Installing the Virtual Disk Development Kit

ThischaptercoverstheprerequisitesforandinstallationoftheVirtualDiskDevelopmentKit.

Packaging and Components

TheVirtualDiskDevelopmentKitispackagedlikeotherVMwaresoftwareasacompressedarchiveforLinux, oranexecutableinstallerforWindows.Itincludesthefollowingcomponents: Utilitiesvmware-mountandvmware-vdiskmanagerinthebindirectory. HeaderfilesvixDiskLib.handvm_basic_types.hintheincludedirectory. FunctionlibraryvixDiskLib.lib(Windows)orlibvixDiskLib.so(Linux)inthelibdirectory. HTMLreferencedocumentationandsampleprograminthedocdirectory.

Supported Platforms
YoucaninstalltheVirtualDiskDevelopmentKitonthefollowingplatforms: Windows,both32bitx86and64bitx8664processors: WindowsXP(ServicePack2) Windows2003(ServerServicePack2) WindowsVista Linux,separatepackagesfor32bitx86and64bitx8664processors: RedHatEnterpriseLinux(RHEL)5 UbuntuDesktop7.10 SUSEEnterpriseServer10(ServicePack1) FedoraCore8

Programming Environments
Youcancompilethesampleprograminthefollowingenvironments:

Visual Studio on Windows

OnWindowssystems,programmerscanusetheCcompilersinVisualStudio2003orVisualStudio2005. VisualStudio2008mightworkbutcompatibilitycannotbeguaranteed.

C++ and C on Linux Systems

OnLinuxsystems,mostprogrammersusetheGNUCcompiler,version4andhigher.Thesampleprogram compileswiththeC++compilerg++,butthispackagealsosupportstheregularCcompilergcc.

VMware, Inc.

13

Virtual Disk API Programming Guide

Installing the Virtual Disk Development Kit

ThereisoneinstallpackageforWindows,onefor32bitLinux,andonefor64bitLinux. To install the package on Windows 1 2 3 OntheDownloadpage,choosethebinary.exeforWindowsanddownloadittoyourdesktop. Doubleclickthenewdesktopicon. ClickNext,readandacceptthelicenseterms,clickNexttwice,clickInstall,andFinish.

To Install the package on Linux 1 2 OntheDownloadpage,choosethebinarytar.gzforeither32bitLinuxor64bitLinux. Unpackthearchive:

tar xvzf VMware-vix-disklib.*.tar.gz

Thiscreatesthevmware-vix-disklib-distribsubdirectory. 3 Changetothatdirectoryandruntheinstallationscriptasroot:
cd vmware-vix-disklib-distrib sudo ./vmware-install.pl

Readthelicensetermsandtypeyestoacceptthem. Softwarecomponentsinstallin/usrunlessyouspecifyotherwise. YoumightneedtoedityourLD_LIBRARY_PATHenvironmenttoincludethelibraryinstallationpath, /usr/lib/vmware-vix-disklib/lib32(orlib64)forinstance.Alternatively,youcanaddthelibrary locationtothelistin/etc/ld.so.confandrunldconfigasroot.

Target System Connectivity

Thissectionlistssupportedproductsandcapabilities.

VMware Products
TheVirtualDiskDevelopmentKitsupportsthefollowingVMwareproducts: ESXServer3.0and3.5 ESXServer3iwithFoundationLicense(butnotwithBaseorCorelicense) VirtualCenterServer2.0and2.5 ESXServer2.5whenconnectingthroughVirtualCenter HostedproductsincludingWorkstation,ACE,Server,andPlayer

VMDK Access and Credentials

LocaloperationsaresupportedbylocalVMDK.AccesstoESXServerisauthenticatedbycredentials,sowith propercredentialsVixDiskLibcanreachanyVMDKontheESXhost.VirtualCentermanagesitsown authenticationcredentials,soVixDiskLibcanreachanyVMDKpermittedbylogincredentials.Onallthese platforms,VixDiskLibsupportsthefollowing: Bothreadonlyandread/writemodes Readonlyaccesstodiskassociatedwithanysnapshotofonlinevirtualmachines AccesstoVMDKfilesofofflinevirtualmachines(VirtualCenterrestrictedtoregisteredvirtualmachines) ReadingofMicrosoftVirtualHardDisk(VHD)format

14

VMware, Inc.

3Vi

Virtual Disk API Functions

ThischapterprovidesanoverviewoftheVirtualDiskAPIintwomajorsections: VirtualDiskandDataStructuresonpage 15 LibraryFunctionsonpage 18

Virtual Disk and Data Structures

VMwareoffersmanyoptionsforvirtualdisklayout,asencapsulatedinlibrarydatastructures.

VMDK File Location

VMDKfilesarestoredinthedirectorythatalsoholdsvirtualmachineconfigurationfiles.OnLinuxthis directorycouldbeanywhere,soitisusuallydocumentedas/path/to/disk.OnWindowsthisdirectoryis likelytobeinC:\MyDocuments\MyVirtualMachines,underitsvirtualmachinename. VMDKfilesstoredatarepresentingavirtualmachinesharddiskdrive.AlmosttheentireportionofaVMDK fileisthevirtualmachinesdata,withasmallportionallottedtooverhead.Ifavirtualmachineisconnected directlytophysicaldisk,theVMDKfilestoresinformationaboutwhichareasthevirtualmachinecanaccess.

Disk Types
Thefollowingdisktypesaredefinedinthevirtualdisklibrary: VIXDISKLIB_DISK_MONOLITHIC_SPARSEGrowablevirtualdiskcontainedinasinglevirtualdiskfile. Thisisthedefaulttypeforhosteddisk,andtheonlysettingintheChapter 4sampleprogram. VIXDISKLIB_DISK_MONOLITHIC_FLATPreallocatedvirtualdiskcontainedinasinglevirtualdiskfile. Thistakesawhiletocreateandoccupiesalotofspace,butmightperformthebest. VIXDISKLIB_DISK_SPLIT_SPARSEGrowablevirtualdisksplitinto2GBextents(ssequence).These filesstartsmallbutcangrowto2GB,whichisthemaximumonoldfilesystems.Thistypeiscomplicated butverymanageablebecausesplitVMDKcanbedefragmented. VIXDISKLIB_DISK_SPLIT_FLATPreallocatedvirtualdisksplitinto2GBextents(fsequence).These filesstartat2GB,sotheytakeawhiletocreateandoccupyalotofspace,butavailablespaceishuge. VIXDISKLIB_DISK_VMFS_FLATPreallocatedvirtualdiskcompatiblewithESXServer3.0.Thisisthe sameasmanageddiskintroducedinVirtualDiskManagementonpage 9. VIXDISKLIB_DISK_STREAM_OPTIMIZEDMonolithicsparseandcompressedforstreaming. VIXDISKLIB_DISK_UNKNOWNDisklayoutisunknown. NOTEVMFS_SPARSEexistsbutisnotsupportedinthisreleaseoftheVirtualDiskAPI. Sparsedisksemploythecopyonwrite(COW)mechanism,inwhichvirtualdiskcontainsnodatainplaces, untilcopiedtherebyawrite.Thisoptimizationsavesstoragespace.
VMware, Inc. 15

Virtual Disk API Programming Guide

Persistence Disk Modes

Inpersistentdiskmode,changesareimmediatelyandpermanentlywrittentothevirtualdisk,sothatthey surviveuntilthenextpoweron. Innonpersistentmode,changestothevirtualdiskarediscardedwhenthevirtualmachinepowersoff.The VMDKfilesreverttotheiroriginalstate. Thevirtualdisklibrarydoesnotencapsulatethisdistinction,whichisavirtualmachinesetting.

VMDK File Naming

Table 31furtherexplainsthedifferentvirtualdisktypes.ThefirstcolumncorrespondstoDiskTypeson page 15butwithoutVIXDISKLIB_DISKprefix.ThethirdcolumngivesthecurrentnamesofVMDKfileson Workstationhosts.Thisisanimplementationdetail;thesefilenamesarecurrentlyinuse. NOTEWhenyouopenaVMDKfilewiththevirtualdisklibrary,alwaysopentheonethatpointstotheothers, notthesplitorflatsectors.Thefiletoopenismostlikelytheonewiththeshortestname. Forinformationaboutothervirtualmachinefiles,seesectionFilesthatMakeUpaVirtualMachineinthe VMwareWorkstationUsersManual.OnESXServer,VMDKfilesaretypeVMFS_FLATorVMFS_SPARSE. Table 3-1. VMDK Virtual Disk Files
Disk Type in API MONOLITHIC_SPARSE Virtual Disk Creation on VMware Host InSelectADiskType,acceptingthedefaultsbynotcheckingany boxproducesoneVMDKfilethatcangrowlargerifmorespaceis needed.The<vmname>representsthenameofavirtualmachine. IfyouselectonlytheAllocatealldiskspacenowcheckbox,space ispreallocated,sothevirtualdiskcannotgrow.ThefirstVMDK fileissmallandpointstoamuchlargerone,whosefilenamesays flatwithoutasequencenumber. IfyouselectonlytheSplitdiskinto2GBfilescheckbox,virtual diskcangrowwhenmorespaceisneeded.ThefirstVMDKfileis smallandpointstoasequenceofotherVMDKfiles,allofwhich haveansbeforeasequencenumber,meaningsparse.Thenumber ofVMDKfilesdependsonthedisksizerequested.Asdatagrows, moreVMDKfilesareaddedinsequence. IfyouselecttheAllocatealldiskspacenowandSplitdiskinto 2GBfilescheckboxes,spaceispreallocated,sothevirtualdisk cannotgrow.ThefirstVMDKfileissmallandpointstoasequence ofotherfiles,allofwhichhaveanfbeforethesequencenumber, meaningflat.Thenumberoffilesdependsontherequestedsize. Aredolog(orchilddiskordeltalink)iscreatedwhenasnapshot istakenofavirtualmachine,orwiththevirtualdisklibrary. Snapshotfilenumbersareinsequence,withoutansorfprefix. ThenumberedVMDKfilestoreschangesmadetothevirtualdisk <diskname>sincetheoriginalparentdisk,orpreviously numberedredolog(inotherwordstheprevioussnapshot). Snapshotofavirtualmachine,whichincludespointerstoallits .vmdkvirtualdiskfiles. Filename on Host <vmname>.vmdk

MONOLITHIC_FLAT

<vnname>-flat.vmdk

SPLIT_SPARSE

<vmname>-s<###>.vmdk

SPLIT_FLAT

<vnname>-f<###>.vmdk

MONOLITHIC_SPARSE or SPLIT_SPARSE

<diskname>-<###>.vmdk

n/a

<vnname>Snapshot.vmsn

Grain Directories and Grain Tables

SPARSEtypevirtualdisksuseahierarchicalrepresentationtoorganizesectors.SeetheVirtualDiskFormat1.0 documentreferencedinVirtualDiskInternalFormatonpage 11.Inthiscontext,grainmeansgranularunit ofdata,largerthanasector.Thehierarchyincludes: Graindirectory(andredundantgraindirectory)whoseentriespointtograintables. Graintables(andredundantgraintables)whoseentriespointtograins. Eachgrainisablockofsectorscontainingvirtualdiskdata.Defaultsizeis128sectorsor64KB.

16

VMware, Inc.

Chapter 3 Virtual Disk API Functions

Internationalization and Localization

ThepathnametoavirtualmachineanditsVMDKcanbeexpressedwithanycharactersetsupportedbythe hostfilesystem,butforportabilitytootherlocales,ASCIIonlypathnamesarerecommended.Futurereleases areexpectedtosupportUnicodeUTF8pathnames,basedonsupportinVMwareproducts.

Adapter Types
Thelibrarycanselectthefollowingadapters: VIXDISKLIB_ADAPTER_IDEVirtualdiskactslikeATA,ATAPI,PATA,SATA,andsoon.Youmightselect thisadaptertypewhenitisspecificallyrequiredbylegacysoftware. VIXDISKLIB_ADAPTER_SCSI_BUSLOGICVirtualSCSIdiskwithBuslogicadapter.Thisisthedefaulton someplatformsandisusuallyrecommendedoverIDEduetohigherperformance. VIXDISKLIB_ADAPTER_SCSI_LSILOGICVirtualSCSIdiskwithLSILogicadapter.WindowsServer2003 andmostLinuxvirtualmachinesusethistypebydefault.PerformanceisaboutthesameasBuslogic.

Data Structures in Virtual Disk API

Hereareimportantdatastructureobjectswithbriefdescriptions: VixErrorErrorcodeoftypeuint64. VixDiskLibConnectParamsPublictypesdesignatethevirtualmachinecredentialsvmxSpec(possibly throughVirtualCenter),thenameofitshostorserver,andthecredentialtypeforauthentication.Formore aboutvmxSpec,seeVMXSpecificationonpage 27.
typedef char * vmxSpec typedef char * serverName typedef VixDiskLibCredType credType

VixDiskLibConnectParams::VixDiskLibCredsCredentialsforeitheruserIDorsessionID: VixDiskLibConnectParams::VixDiskLibCreds::VixDiskLibUidPasswdCredsString datafieldsrepresentusernameandpasswordforauthentication. VixDiskLibConnectParams::VixDiskLibCreds::VixDiskLibSessionIdCredsString datafieldsrepresentthesessioncookie,username,andencryptedsessionkey. VixDiskLibCreateParamsPublictypesrepresentthevirtualdisk(seeDiskTypesonpage 15),the diskadapter(seeAdapterTypesonpage 17),VMwareversion(suchasWorkstation5orESXServer), andcapacityofthedisksector.
typedef typedef typedef typedef VixDiskLibDiskType diskType VixDiskLibAdapterType adapterType uint hwVersion VixDiskLibSectorType capacity

VixDiskLibDiskInfoPublictypesrepresentthegeometryintheBIOSandphysicaldisk,thecapacity ofthedisksector,thediskadapter(seeAdapterTypesonpage 17),thenumberofchilddisklinks(redo logs),andastringtohelplocatetheparentdisk(statebeforeredologs).

VixDiskLibGeometry biosGeo VixDiskLibGeometry physGeo VixDiskLibSectorType capacity VixDiskLibAdapterType adapterType int numLinks char * parentFileNameHint

VixDiskLibGeometryPublictypesspecifydiskgeometry.Virtualdiskgeometrydoesnotnecessarily correspondwithphysicaldiskgeometry.
typedef uint32 cylinders typedef uint32 heads typedef uint32 sectors

VMware, Inc.

17

Virtual Disk API Programming Guide

Library Functions
YoucanfindtheVixDiskLibAPIReferencebyusingaWebbrowsertoopenthedoc/index.htmlfileinthe VDDKsoftwaredistribution.Inthissection,functionsareorderedbyhowtheymightbecalled,ratherthan alphabeticallyasintheAPIreference. WhentheAPIreferencesaysthatafunctionsupportsonlyhosteddisks,itmeansvirtualdiskimageshosted byVMwareWorkstationorsimilarproducts.VirtualdiskimagesstoredonVMFSpartitionsforESXServer aremanageddisk.WhenthelibraryaccessesvirtualdiskonVMFS,allI/OgoesthroughtheESXserver, whichmanagesphysicaldiskstorage.TheVirtualDiskAPIhasnodirectaccesstoSANstorage.

Start Up
TheVixDiskLib_Init()andVixDiskLib_Connect()functionsmustappearinallvirtualdiskprograms.

Initialize the Library

VixDiskLib_Init()initializestheVirtualDiskAPI.Thefirsttwoarguments,1and0,representmajorand minorAPIversionnumbers.Thethird,fourth,andfifthargumentsspecifylog,warning,andpanichandlers. DLLsandsharedobjectsarelocatedinlibDir.
VixError vixError = VixDiskLib_Init(1, 0, &logFunc, &warnFunc, &panicFunc, libDir);

AlwayscallVixDiskLib_Exit()attheendofyourprogramtodeinitialize.

Connect to a Workstation or Server

VixDiskLib_Connect()connectsthelibrarytoeitheralocalVMwarehostoraremoteserver.Forhosteddisk onthelocalsystem,providenullvaluesformostconnectionparameters.FormanageddiskonanESXServer, specifyvirtualmachinename,ESXServername,username,password,andport.
vixError = VixDiskLib_Connect(&cnxParams, &srcConnection)

AlwayscallVixDiskLib_Disconnect()beforetheendofyourprogram.

Disk Operations
Thesefunctionscreate,open,read,write,query,andclosevirtualdisk.

Create a New Hosted Disk

VixDiskLib_Create()locallycreatesanewvirtualdisk,afterbeingconnectedtothehost.IncreateParams, youmustspecifythedisktype,adapter,hardwareversion,andcapacityasanumberofsectors.Thisfunction supportshosteddiskonly.Tocreatemanagedvirtualdisk,useVixDiskLib_Clone().
vixError = VixDiskLib_Create(appGlobals.connection, appGlobals.diskPath, &createParams, NULL, NULL);

Open a Local or Remote Disk

Afterthelibraryconnectstoaworkstationorserver,VixDiskLib_Open()opensavirtualdisk.
vixError = VixDiskLib_Open(appGlobals.connection, appGlobals.diskPath, appGlobals.openFlags, &srcHandle);

Read Sectors From a Disk

VixDiskLib_Read()readsarangeofsectorsfromanopenvirtualdisk.Youspecifythebeginningsectorand thenumberofsectors.Sectorsizemightvarydependingontheoperatingsystem,butin<vixDiskLib.h>it isdefinedas512bytes.
vixError = VixDiskLib_Read(srcHandle, i, j, buf);

18

VMware, Inc.

Chapter 3 Virtual Disk API Functions

Write Sectors To a Disk

VixDiskLib_Write()writesoneormoresectorstoanopenvirtualdisk.Thisfunctionexpectsthefourth parameterbuftobeVIXDISKLIB_SECTOR_SIZEbyteslong.
vixError = VixDiskLib_Write(newDisk.Handle(), i, j, buf);

Close a Local or Remote Disk

VixDiskLib_Close()closesanopenvirtualdisk.
VixDiskLib_Close(srcHandle);

Get Information About a Disk

vixError = VixDiskLib_GetInfo(srcHandle, diskInfo);

VixDiskLib_GetInfo()getsdataaboutanopenvirtualdisk,allocatingafilledinVixDiskLibDiskInfo structure(page 17).Someofthisinformationoverlapswithmetadata(seeMetadataHandlingonpage 19).

Free Memory from Get Information

ThisfunctiondeallocatesmemoryallocatedbyVixDiskLib_GetInfo().Callittoavoidamemoryleak.
vixError = VixDiskLib_FreeInfo(diskInfo);

Error Handling
Thesefunctionsenhancetheusefulnessoferrormessages.

Return Error Description Text

VixDiskLib_GetErrorText()returnsthetextualdescriptionofanumericerrorcode.
char* msg = VixDiskLib_GetErrorText(errCode, NULL);

Free Error Description Text

VixDiskLib_FreeErrorText()deallocatesspaceassociatedwiththeerrordescriptiontext.
VixDiskLib_FreeErrorText(msg);

Metadata Handling
Read Metadata Key from Disk
vixError = VixDiskLib_ReadMetadata(disk.Handle(), appGlobals.metaKey, &val[0], requiredLen, NULL);

Retrievesthevalueofagivenkeyfromdiskmetadata.ThemetadataforahostedVMDKisnotasextensiveas formanageddiskonanESXServer.Heldinamappingfile,VMFSmetadatamightalsocontaininformation suchasdisklabel,LUNorpartitionlayout,numberoflinks,fileattributes,locks,andsoforth.Metadataalso describesencapsulationofrawdiskmapping(RDM)storage,ifapplicable.

Get Metadata Table from Disk

VixDiskLib_GetMetadataKeys()retrievesallexistingkeysfromthemetadataofavirtualdisk,butnotthe keyvalues.UsethisinconjunctionwithVixDiskLib_ReadMetadata().Below
vixError = VixDiskLib_GetMetadataKeys(disk.Handle(), &buf[0], requiredLen, NULL);

Hereisanexampleofasimplemetadatatable.Uuidistheuniversallyuniqueidentifierforthevirtualdisk.
adapterType = buslogic geometry.sectors = 32 geometry.heads = 64 geometry.cylinders = 100 uuid = 60 00 C2 93 7b a0 3a 03-9f 22 56 c5 29 93 b7 27

VMware, Inc.

19

Virtual Disk API Programming Guide

Write Metadata Table to Disk

VixDiskLib_WriteMetadata()updatesthemetadataofavirtualdiskwiththegivenkeyvaluepair.Ifnew, thelibraryaddsittotheexistingmetadatatable.Ifthekeyalreadyexists,thelibraryupdatesitsvalue.
vixError = VixDiskLib_WriteMetadata(disk.Handle(), appGlobals.metaKey, appGlobals.metaVal);

Cloning a Virtual Disk

Compute Space Needed for Clone
Thisfunctioncomputesthespacerequired(inbytes)tocloneavirtualdisk,afterpossibleformatconversion.
vixError = VixDiskLib_SpaceNeededForClone(child.Handle(), VIXDISKLIB_DISK_VMFS_FLAT, &spaceReq);

Clone a Disk by Copying Data

Thisfunctioncopiesdatafromonevirtualdisktoanother,converting(disktype,size,hardware)asspecified.
vixError = VixDiskLib_Clone(appGlobals.connection, appGlobals.diskPath, srcConnection, appGlobals.srcPath, &createParams, CloneProgressFunc, NULL, TRUE);

Advanced Disk Operations

Thesefunctionsrename,grow,defragment,shrink,andremovevirtualdisk.

Rename an Existing Disk

VixDiskLib_Rename()changesthenameofavirtualdisk.Usethisfunctiononlywhenthevirtualmachine ispoweredoff.
vixError = VixDiskLib_Rename(oldGlobals.diskpath, newGlobals.diskpath);

Grow an Existing Local Disk

VixDiskLib_Grow()extendsanexistingvirtualdiskbyaddingsectors.Supportshosted,notmanaged,disk.
vixError = VixDiskLib_Grow(appGlobals.connection, appGlobals.diskPath, size, TRUE, GrowProgressFunc, NULL);

Defragment an Existing Disk

VixDiskLib_Defragment()defragmentsanexistingvirtualdisk.DefragmentationiseffectivewithSPARSE typefiles,butmightnotdoanythingwithFLATtype.Ineithercase,thefunctionreturnsVIX_OK.Supports hosted,notmanaged,disk.
vixError = VixDiskLib_Defragment(disk.Handle(), DefragProgressFunc, NULL);

Defragmentconsolidatesdatainthe2GBextents,movingittolowernumberedextents.Thisisindependent ofdefragmentationtoolsintheguestOS,suchasDisk>Properties>Tools>DefragmentationinWindows, orthedefragcommandfortheLinuxExt2filesystem. VMwarerecommendsdefragmentationfromtheinsideout:firstwithinthevirtualmachine,thenusingthis functionoraVMwaredefragmentationtool,andfinallywithinthehostoperatingsystem.

Shrink an Existing Local Disk

VixDiskLib_Shrink()reclaimsunusedspaceinanexistingvirtualdisk,unusedspacebeingrecognizedas blocksofzeroes.Thisismoreeffective(gainsmorespace)withSPARSEtypefilesthanwithpreallocatedFLAT type,althoughFLATfilesmightshrinkbyasmallamount.Ineithercase,thefunctionreturnsVIX_OK.
vixError = VixDiskLib_Shrink(disk.Handle(), ShrinkProgressFunc, NULL);

InVMwaresystemutilities,preparezerosoutunusedblocksintheVMDKsoshrinkcanreclaimthem.In theAPI,useVixDiskLib_Write()tozerooutunusedblocks,andVixDiskLib_Shrink()toreclaimspace. Shrinkdoesnotchangethevirtualdiskcapacity,butitmakesmorespaceavailable.

20

VMware, Inc.

Chapter 3 Virtual Disk API Functions

Unlink Extents to Remove Disk

VixDiskLib_Unlink()deletesallextentsofthespecifiedvirtualdisk,whichunlinks(removes)thediskdata. Thisissimilartotheremoveorerasecommandinacommandtool.
vixError = VixDiskLib_Unlink(appGlobals.connection, appGlobals.diskPath);

Disk Chaining and Redo Logs

InVMDKterminology,allthefollowingaresynonyms:childdisk,redolog,anddeltalink.Fromtheoriginal parentdisk,eachchildconstitutesaredologpointingbackfromthepresentstateofthevirtualdisk,onestep atatime,totheoriginal.Thispseudoequationrepresentstherelativecomplexityofbackupsandsnapshots: backupimage<childdisk=redolog=deltalink<snapshot Abackupimage(suchasonmagnetictape)islessthanachilddiskbecausethebackupimageismerelyadata stream.Asnapshotismorethanachilddiskbecauseitalsocontainsthevirtualmachinestate,withpointers toassociatedfilesystemstatesonVMDK.

Create Child from Parent Disk

VixDiskLib_CreateChild()createsachilddisk(orredolog)forahostedvirtualdisk.Generally,youcreate thefirstchildfromtheparentandcreatesuccessivechildrenfromthelatestoneinthechain.ThechildVMDK tracks,inSPARSEtypeformat,anydisksectorschangedsinceinception,asillustratedinFigure 31.
vixError = VixDiskLib_CreateChild(parent.Handle(), appGlobals.diskPath, VIXDISKLIB_DISK_MONOLITHIC_SPARSE, NULL, NULL);

Figure 3-1. Child Disks Created from Parent Virtual Machine Writes Here

Child3

vm.vmdk

vm-001.vmdk

Changed Sectors Only Child2 vm.vmdk vm-002.vmdk

Child1

vm.vmdk

vm-001.vmdk

Parent

vm.vmdk

vm-flat.vmdk

Physical Disk Afteryoucreateachild,itisanerrortoopentheparent,orearlierchildreninthediskchain.InVMware products,thechildrensvm.vmdkfilespointtoredologs,ratherthantotheparentdisk,vm-flat.vmdkinthis example.Ifyoumustaccesstheoriginalparent,orearlierchildreninthechain,useVixDiskLib_Attach().

VMware, Inc.

21

Virtual Disk API Programming Guide

Attach Child to Parent Disk

VixDiskLib_Attach()attachesthechilddiskintoitsparentdiskchain.Afterwards,theparenthandleis invalidandthechildhandlerepresentsthecombineddiskchainofredologs.
vixError = VixDiskLib_Attach(parent.Handle(), child.Handle());

Forexample,supposeyouwanttoaccesstheolderdiskimagerecordedbyChild1.Attachthehandleofnew Child1atoChild1,whichprovidesChild1asparenthandle,asshowninFigure 32.Itisnowpermissibleto open,read,andwritetheChild1avirtualdisk. Theparentchilddiskchainisefficientintermsofstoragespace,becausethechildVMDKrecordsonlythe sectorsthatchangedsincethelastVixDiskLib_CreateChild().Theparentchilddiskchainalsoprovidesa redomechanism,permittingprogrammaticaccesstoanygenerationwithVixDiskLib_Attach(). Figure 3-2. Child Disks Created from Parent Virtual Machine Writes Here

Child3

vm.vmdk

vm-001.vmdk

Child2 Attach Child1

vm.vmdk

vm-002.vmdk

Child1a.vmdk

vm.vmdk

vm-001.vmdk

Parent

vm.vmdk

vm-flat.vmdk

Physical Disk

Shut Down
AllVirtualDiskAPIapplicationsshouldcallthesefunctionsatendofprogram.

Disconnect from Server

VixDiskLib_Disconnect()breaksanexistingconnection.
VixDiskLib_Disconnect(srcConnection);

Clean Up and Exit

VixDiskLib_Exit()cleansupthelibrarybeforeexit.
VixDiskLib_Exit();

22

VMware, Inc.

Chapter 3 Virtual Disk API Functions

Capabilities of Library Calls

Thissectiondescribeslimitations,ifany.

Support for Hosted Disk

Everythingissupported.

Support for Managed Disk

Someoperationsarenotsupported: ForVixDiskLib_Connect()toopenaconnectiontomanageddisk,youmustprovidevalidcredentials sotheESXServercanaccessthevirtualdisk. ForVixDiskLib_Create()tocreateamanageddiskontheESXServer,firstcreateahostedtypedisk, thenuseVixDiskLib_Clone()toconvertthehostedvirtualdisktomanagedvirtualdisk. VixDiskLib_Defragment()candefragmenthosteddisksonly. VixDiskLib_Grow()cangrowhosteddisksonly.

VMware, Inc.

23

Virtual Disk API Programming Guide

24

VMware, Inc.

4Vi

Virtual Disk API Sample Code

ThischapterdiscussestheVDDKsampleprogram,inthefollowingsections: CompilingtheSampleProgramonpage 25 UsageMessageonpage 26 WalkThroughofSampleProgramonpage 26

Compiling the Sample Program

ThesampleprogramiswritteninC++,althoughtheVirtualDiskAPIalsosupportsC.

Visual C++ on Windows

Beforecompiling,setyoursearchpathtofindtherequiredDLLfiles.ChooseMyComputer>Properties> Advanced>EnvironmentVariables,selectPathintheSystemVariableslowerlist,clickEdit,andtypethe followingattheend,ifitisnotalreadythere(assumingyouinstalledinthedefaultlocation):
;C:\Program Files\VMware\VMware Virtual Disk Development Kit\bin

IfyouinsertthatpathearlierinthePathsystemvariable,thesemicolongoesattheend. Tocompiletheprogram,findthesamplesourcevixDiskLibSample.cppatthislocation:
C:\Program Files\VMware\VMware Virtual Disk Development Kit\doc\sample\

Doubleclickthevcprojfile,possiblyconvertformattoanewerversion,andchooseBuild>BuildSolution. Toexecutethecompiledprogram,chooseDebug>StartWithoutDebugging,ortypethisinacommand promptafterchangingtothedoc\samplelocationgivenabove:

Debug\vixdisklibsample.exe

SLN and VCPROJ Files

TheVisualStudiosolutionfilevixDiskLibSample.slnandprojectfilevixDiskLibSample.vcprojare includedinthesampledirectory.

C++ on Linux Systems

Findthesamplesourceinthisdirectory:
/usr/share/doc/vmware-vix-disklib/sample

NOTEEdit/etc/ld.so.confandrunldconfigasroot,orchangeyourLD_LIBRARY_PATHenvironmentto includethelibraryinstallationpath,/usr/lib/vmware-fix-disklib/lib32(orlib64). YoumightneedtocopythesourcevixDiskLibSample.cppanditsMakefiletoadifferentdirectorywhere youhavewritepermission.

VMware, Inc.

25

Virtual Disk API Programming Guide

Typethemakecommandtocompile.Thenruntheapplication:
make ./vix-disklib-sample

Makefile
TheMakefilefetchesanypackagesthatarerequiredforcompilationbutarenotinstalled.

Library Files Required

Thevirtualdisklibrarycomeswithdynamiclibraries,orsharedobjectsonLinux,becauseitismorereliable todistributesoftwarethatway,comparedtousingstaticlibraries. Windowsrequiresthelib/vixDiskLib.libfileforlinking,andthebin/*.dllfilesatruntime. Linuxuses.sofilesforbothlinkingandrunning.OnWindowsandLinux,dynamiclinkingistheonlyoption.

Usage Message
Runningthesampleapplicationwithoutargumentsproducesthefollowingusagemessage:
Usage: vixdisklibsample command [options] diskPath commands: -create : creates a sparse virtual disk with capacity specified by -cap -redo parentPath : creates a redo log 'diskPath' for base disk 'parentPath' -info : displays information for specified virtual disk -dump : dumps the contents of specified range of sectors in hexadecimal -fill : fills specified range of sectors with byte value specified by -val -wmeta key value : writes (key,value) entry into disk's metadata table -rmeta key : displays the value of the specified metada entry -meta : dumps all entries of the disk's metadata -clone sourcePath : clone source vmdk possibly to a remote site options: ...

Walk-Through of Sample Program

ThesampleprogramisthesameforWindowsasforLinux,with#ifdefblocksforWin32.

Include Files
Windowsdynamiclinklibrary(DLL)declarationsareinprocess.h,whileLinuxsharedobject(.so) declarationsareindlfcn.h.Windowsoffersthetchar.hextensionforUnicodegenerictextmappings,not readilyavailableinLinux.

Definitions and Structures

Thesampleprogramusestenbitwiseshiftoperations(1<<9)totrackitsnineavailablecommandsandthe multithreadoption.TheVirtualDiskAPIhas24functioncalls,someforinitializationandcleanup. Thefollowinglibraryfunctionsarenotdemonstratedinthesampleprogram: VixDiskLib_Rename() VixDiskLib_Defragment() VixDiskLib_Grow() VixDiskLib_Shrink() VixDiskLib_Unlink() VixDiskLib_Attach() ThesampleprogramtransmitsstateintheappGlobalsstructure.

26

VMware, Inc.

Chapter 4 Virtual Disk API Sample Code

Dynamic Loading
The#ifdefDYNAMIC_LOADINGblockislong,startingonline97andendingatline339. Thisblockcontainsfunctiondefinitionsfordynamicloading.ItalsocontainstheLoadOneFunc()procedure toobtainanyrequestedfunctionfromthedynamiclibraryandtheDynLoadDiskLib()proceduretobindit. Thisdemonstrationfeaturecouldalsobecalledruntimeloadingtodistinguishitfromdynamiclinking. TotrytheprogramwithruntimeloadingenabledonLinux,add-DDYNAMIC_LOADINGafterg++inthe Makefileandrecompile.OnWindows,defineDYNAMIC_LOADINGintheproject.

Wrapper Classes
Belowthedynamicloadingblockaretwowrapperclasses,oneforerrorcodesanddescriptivetext,andthe otherfortheconnectionhandletodisk. Theerrorwrapperappearsincatchandthrowstatementstosimplifyerrorhandlingacrossfunctions. WrapperclassVixDiskisacleanwaytoopenandcloseconnectionstodisk.Theonlytimethatlibrary functionsVixDiskLib_Open()andVixDiskLib_Close()appearelsewhere,asidefromdynamicloading,is intheCopyThread()functionneartheendofthesampleprogram.

Command Functions
Theprintusagemessageappearsnext,withoutputpartiallyshowninUsageMessageonpage 26. Nextcomesthemain()function,whichsetsdefaultsandparsescommandlineargumentstodeterminethe operationandpossiblysetoptionstochangedefaults.Dynamicloadingoccurs,ifdefined.Noticetheallzero initializationoftheVixDiskLibConnectParamsdeclaredstructure:
VixDiskLibConnectParams cnxParams = {0};

ForconnectionstoESXServer,credentialsincludingusernameandpasswordmustbecorrectlysuppliedin the-userand-passwordcommandlinearguments.Boththe-hostnameoftheESXServerandits-vm inventorypath(vmxSpec)mustbesupplied.Whenset,thesevaluespopulatethecnxParamsstructure. Initializeallconnectionparameters,especiallyvmxSpec,ortheconnectionmightbehaveunexpectedly. AcalltoVixDiskLib_Init()initializesthelibrary.Inaproductionapplication,youcansupplyappropriate log,warn,andpanicfunctionsasparameters,inplaceofNULL. AcalltoVixDiskLib_Connect()createsalibraryconnectiontodisk.IfhostcnxParams.serverNameisnull, asitiswithout-hostcommandlineargument,aconnectionismadetohosteddiskonthelocalhost.Ifserver nameisset,aconnectionismadetomanageddiskontheremoteserver. Next,anappropriatefunctioniscalledfortherequestedoperation,followedbyerrorinformationifapplicable. Finally,themain()functionclosesthelibraryconnectiontodiskandexits.

VMX Specification
OnESXserver,theVirtualMachineeXecutable(VMX)istheuserspacecomponentofvirtualinfrastructure. OnWorkstationandhostedproducts,the.vmxfilespecifiesvirtualmachineconfiguration.Inthevirtualdisk library,vmxSpeccanbeeitheraVMXfilelocator,oraninventorypathtothevirtualmachine: <vmxPathName>?dcPath=<datacenter>&dsName=<dstore> vmPath=<datacenter>/<path/to/vm> <vmxPathName>isthefullpathnameoftheVMXfile. <datacenter>istheinventorypathofthedatacenter. <dstore>isthedatastorename. HerearetwovmxSpecexamplesusingVirtualCenter;vixDiskLib.hdocumentsonlythefirst.
WinXP/WinXP.vmx?dcPath=Datacenter&dsName=Storage1 vmPath=Datacenter/vm/WinXP

VMware, Inc.

27

Virtual Disk API Programming Guide

DoInfo()
ThisprocedurecallsVixDiskLib_GetInfo()forinformationaboutthevirtualdisk,displaysresults,andcalls VixDiskLib_FreeInfo()toreclaimmemory.Theparameterdisk.Handle()comesfromtheVixDisk wrapperclassdiscussedinWrapperClassesonpage 27. Inthisexample,thesampleprogramconnectstotheESXServernamedesx3anddisplaysvirtualdisk informationforaRedHatEnterpriseLinuxclient.ForanESXServer,pathtodiskis[storage1]followedby thevirtualmachinenameandtheVMDKfilename.
vix-diskLib-sample -info -host esx3 -user admin -password secret "[storage1]RHEL5/RHEL5.vmdk" capacity = 8388608 sectors number of links = 1 adapter type = LsiLogic SCSI BIOS geometry = 0/0/0 physical geometry = 522/255/63

Ifyoumultiplyphysicalgeometrynumbers(522cylinders*255headspercylinder*63sectorsperhead)the resultisacapacityof8385930sectors,althoughthefirstlinesays8388608.Asmalldiscrepancyispossible.In general,yougetatleastthecapacitythatyourequested. Thenumberoflinksspecifiestheseparationofachildfromitsoriginalparentinthediskchain(redologs), startingatone.Theparenthasonelink,itschildhastwolinks,thegrandchildhasthreelinks,andsoforth.

DoCreate()
ThisprocedurecallsVixDiskLib_Create()toallocatevirtualdisk.AdaptertypeisSCSIunlessspecifiedas IDEonthecommandline.Sizeis100MB,unlesssetby-caponthecommandline.Becausethesectorsizeis 512bytes,thecodemultipliesappGlobals.mbsizeby2048insteadof1024.Typeisalwaysmonolithicsparse andWorkstation5.Inaproductionapplication,progressFuncandcallbackdatacanbedefinedratherthan NULL.TypethesecommandstocreateasampleVMDKfile(thefirstlineisforLinuxonly):
export LD_LIBRARY_PATH=/usr/lib/vmware-vix-disklib/lib32 vix-disklib-sample -create sample.vmdk

AsaVMDKfile,monolithicsparse(growableinasinglefile)virtualdiskisinitially65536bytes(2^16)insize, includingoverhead.Thefirsttimeyouwritetothistypeofvirtualdisk,aswithDoFill()below,theVMDK expandsto131075bytes(2^17),whereitremainsuntilmorespaceisneeded.Youcanverifyfilecontentswith the-dumpoption.

DoRedo()
ThisprocedurecallsVixDiskLib_CreateChild()toestablisharedolog.Achilddiskrecordsdisksectors thatchangedsincetheparentdiskorpreviouschild.Childrencanbechainedasasetofredologs. ThesampleprogramdoesnotdemonstrateuseofVixDiskLib_Attach(),whichyoucanusetoaccessalink inthediskchain.VixDiskLib_CreateChild()establishesaredolog,withthechildreplacingtheparentfor read/writeaccess.Givenapreexistingdiskchain,VixDiskLib_Attach()createsarelatedchild,oracousin youmightsay,thatislinkedintosomegenerationofthediskchain. Foradiagramoftheattachoperation,seeFigure 32,ChildDisksCreatedfromParent,onpage 22.

Write by DoFill()
ThisprocedurecallsVixDiskLib_Write()tofilladisksectorwithones(bytevalueFF)unlessotherwise specifiedby-valonthecommandline.Thedefaultistofillonlythefirstsector,butthiscanbechangedwith options-startand-countonthecommandline.

DoReadMetadata()
ThisprocedurecallsVixDiskLib_ReadMetadata()toservethe-rmetacommandlineoption.Forexample, typethiscommandtoobtaintheuniversallyuniqueidentifier:
vix-disklib-sample -rmeta uuid sample.vmdk

28

VMware, Inc.

Chapter 4 Virtual Disk API Sample Code

DoWriteMetadata()
ThisprocedurecallsVixDiskLib_WriteMetadata()toservethe-wmetacommandlineoption.Forexample, youcanchangethetoolsversionfrom1to2asfollows:
vix-disklib-sample -wmeta toolsVersion 2 sample.vmdk

DoDumpMetadata()
ThisprocedurecallsVixDiskLib_GetMetadataKeys()thenVixDiskLib_ReadMetadata()toservethe -metacommandlineoption.Tworeadmetadatacallsareneededforeachkey:onetodeterminelengthofthe valuestringandanothertofillinthevalue.SeeGetMetadataTablefromDiskonpage 19. Inthefollowingexample,thesampleprogramconnectstotheESXServernamedesx3anddisplaysthe metadataoftheRedHatEnterpriseLinuxclientsvirtualdisk.ForanESXServer,pathtodiskis[storage1] followedbythevirtualmachinenameandtheVMDKfilename.
vix-diskLib-sample -meta -host esx3 -user admin -password secret "[storage1]RHEL5/RHEL5.vmdk" geometry.sectors = 63 geometry.heads = 255 geometry.cylinders = 522 adapterType = buslogic toolsVersion = 1

Toolsversionandvirtualhardwareversionappearinthemetadata,butnotinthediskinformationretrieved byDoInfo()onpage 28.Geometryinformationandadaptertypearerepeated,butinadifferentformat. Othermetadataitemsnotlistedabovemightexist.

DoDump()
ThisprocedurecallsVixDiskLib_Read()toretrievesectorsanddisplayssectorcontentsontheoutputin hexadecimal.Thedefaultistodumponlythefirstsectornumberedzero,butyoucanchangethiswiththe -startand-countoptions.Hereisasequenceofcommandstodemonstrate:
vix-disklib-sample vix-disklib-sample vix-disklib-sample vix-disklib-sample od -c sample.vmdk -create sample.vmdk -fill -val 1 sample.vmdk -fill -val 2 -start 1 -count 1 sample.vmdk -dump -start 0 -count 2 sample.vmdk

OnLinux(orCygwin)youcanruntheodcommandtoshowoverheadandmetadataatthebeginningoffile, andtherepeatedonesandtwosinthefirsttwosectors.The-dumpoptionofthesampleprogramshowsonly data,notoverhead.

DoTestMultiThread()
ThisprocedureemploystheWindowsthreadlibrarytomakemultiplecopiesofavirtualdiskfile.Specifythe numberofcopieswiththe-multithreadcommandlineoption.Foreachcopy,thesampleprogramcallsthe CopyThread()procedure,whichinturncallsasequenceofsixVirtualDiskAPIroutines. OnLinuxthemultithreadoptionisunimplemented.

DoClone()
ThisprocedurecallsVixDiskLib_Clone()tomakeacopyofthedataonvirtualdisk.Acallbackfunction, suppliedasthesixthparameter,displaysthepercentofcloningcompleted.Forlocalhosteddisk,theadapter typeisSCSIunlessspecifiedasIDEonthecommandline,sizeis200MB,unlesssetby-capoption,andtype ismonolithicsparse,forWorkstation5.ForanESXServer,adaptertypeistakenfrommanageddiskitself, usingtheconnectionparametersestablishedbyVixDiskLib_Connect(). ThefinalparameterTRUEmeanstooverwriteifthedestinationVMDKexists. Thecloneoptionisanexcellentbackupmethod.Oftentheclonedvirtualdiskissmaller,becauseitcanbe organizedmoreefficiently.Moreover,afullyallocatedflatfilecanbeconvertedtoasparserepresentation.

VMware, Inc.

29

Virtual Disk API Programming Guide

30

VMware, Inc.

5Vi

Practical Programming Tasks

Thischapterpresentssomepracticalprogrammingchallengesnotcoveredinthesampleprogram,including: ScanVMDKforVirusSignaturesonpage 31 CreatingVirtualDisksonpage 32 WorkingwithVirtualDiskDataonpage 33 ManagingChildDisksonpage 34 InterfacingWiththeVIXAPIonpage 35 InterfacingWithVMwareInfrastructureonpage 36

Scan VMDK for Virus Signatures

OneofthetaskslistedinSolutionsEnabledbytheVirtualDiskAPIonpage 11istoscanaVMDKforvirus signatures.Usingtheframeworkofoursampleprogram,afunctioncanimplementthe-viruscommandline option.ThefunctioninExample 51reliesonapreexistinglibraryroutinecalledSecureVirusScan(),which typicallyissuppliedbyavendorofantivirussoftware.Asitdoesforemailmessages,thelibraryroutinescans abufferofanysizeagainstthevendorslatestpatternlibrary,andreturnsTRUEifitidentifiesavirus. Example 5-1. Function to Scan VMDK for Viruses
extern int SecureVirusScan(const uint8 *buf, size_t n); /* * DoVirusScan -* Scan the content of a virtual disk for virus signatures. */ static void DoVirusScan(void) { VixDisk disk(appGlobals.connection, appGlobals.diskPath, appGlobals.openFlags); VixDiskLibDiskInfo info; uint8 buf[VIXDISKLIB_SECTOR_SIZE]; VixDiskLibSectorType sector; VixError vixError = VixDiskLib_GetInfo(disk.Handle(), &info); CHECK_AND_THROW(vixError); cout << "capacity = " << info.capacity << " sectors" << endl; // read all sectors even if not yet populated for (sector = 0; sector < info.capacity; sector++) { vixError = VixDiskLib_Read(disk.Handle(), sector, 1, buf); CHECK_AND_THROW(vixError); if (SecureVirusScan(buf, sizeof buf)) { printf("Virus detected in sector %d\n", sector); } } cout << info.capacity << " sectors scanned" << endl; }

VMware, Inc.

31

Virtual Disk API Programming Guide

ThisfunctioncallsVixDiskLib_GetInfo()todeterminethenumberofsectorsallocatedinthevirtualdisk. ThenumberofsectorsisavailableintheVixDiskLibDiskInfostructure,butnormallynotinthemetadata. WithSPARSEtypelayout,datacanoccurinanysector,sothisfunctionreadsallsectors,whetherfilledornot. VixDiskLib_Read()continueswithouterrorwhenitencountersanemptysectorfullofzeroes. Thefollowingdifferencelistshowstheremainingcodechangesnecessaryforaddingthe-virusoptiontothe vixDiskLibSample.cppsampleprogram:

43a44 > #define COMMAND_VIRUS_SCAN (1 << 10) 72a74 > static void DoVirusScan(void); 425a429 > printf(" -virus: scan source vmdk for virus signature \n"); 519a524,525 > } else if (appGlobals.command & COMMAND_VIRUS_SCAN) { > DoVirusScan(); 564a571,572 > } else if (!strcmp(argv[i], "-virus")) { > appGlobals.command |= COMMAND_VIRUS_SCAN;

Creating Virtual Disks

ThissectiondiscussesthetypesoflocalVMDKfilesandhowtocreatevirtualdiskforaremoteESXServer.

Creating Local Disk

ThesampleprogrampresentedinChapter 4createsvirtualdiskoftypeMONOLITHIC_SPARSE,inotherwords onebigfile,notpreallocated.ThisisthedefaultforVMwareWorkstation,andisidealformodernfilesystems, allofwhichsupportfileslargerthan2GB,andcanholdmorethan2GBoftotaldata.Thisisnottrueoflegacy filesystems,suchasFAT16onMSDOSuntilWindows95,ortheISO9660filesystemcommonlyusedtowrite filesonCD.Botharelimitedto2GBpervolume,althoughFATwasextendedwithFAT32beforeNTFS. However,aSPLITvirtualdiskmightbesaferthantheMONOLITHICvariety,becauseifsomethinggoeswrong withtheunderlyinghostfilesystem,somedatamightberecoverablefromuncorrupted2GBextents.VMware productsdotheirbesttorepairadamagedVMDK,buthavingasplitVMDKincreasesthechanceofsalvaging filesduringrepair.Onthedownside,SPLITvirtualdiskinvolveshigheroverhead(morefiledescriptors)and increasesadministrativecomplexity. WhenrequiredforaFAT16filesystem,hereishowtocreateSPLIT_SPARSEvirtualdisk.Thechangeissimple: thelinehighlightedinboldface.Thesampleprogramcouldbeextendedtohaveanoptionforthis.
static void DoCreate(void) { VixDiskLibAdapterType adapter = strcmp(appGlobals.adapterType, "scsi") == 0 ? VIXDISKLIB_ADAPTER_SCSI_BUSLOGIC : VIXDISKLIB_ADAPTER_IDE; VixDiskLibCreateParams createParams; VixError vixError; createParams.adapterType = adapter; createParams.capacity = appGlobals.mbSize * 2048; createParams.diskType = VIXDISKLIB_DISK_SPLIT_SPARSE; vixError = VixDiskLib_Create(appGlobals.connection, appGlobals.diskPath, &createParams, NULL, NULL); CHECK_AND_THROW(vixError); }

NOTEYoucansplitVMDKfilesintosmallerthan2GBextents,butcreatedfilenamesstillfollowthepatterns showninTable 31,VMDKVirtualDiskFiles,onpage 16. ThisonelinechangetoDoCreate()causescreationof200MBsplitVMDKfiles(200MBbeingthecapacityset onthepreviousline)unlessthe-capcommandlineargumentspecifiesotherwise.

32

VMware, Inc.

Chapter 5 Practical Programming Tasks

Creating Remote Disk

AsstatedinSupportforManagedDiskonpage 23,VixDiskLib_Create()doesnotsupportmanageddisk. TocreateamanageddiskontheremoteESXServer,firstcreateahosteddiskonthelocalWorkstation,then convertthehosteddiskintomanageddiskwithVixDiskLib_Clone()overthenetwork. Tocreateremotemanageddiskusingthesampleprogram,typethefollowingcommands:
./vix-disklib-sample -create -cap 1000000 virtdisk.vmdk ./vix-disklib-sample -clone virtdisk.vmdk -host esx3i -user root -password secret vmfsdisk.vmdk

Itmightbeusefultowriteavirtualmachineprovisioningapplicationusingthevirtualdisklibrarytoperform thefollowingsteps: 1 2 3 CreateahosteddiskVMDKwith2GBcapacity,usingVixDiskLib_Create(). WriteimageoftheguestOSandapplicationsoftwareintotheVMDK,usingVixDiskLib_Write(). ClonethehosteddiskVMDKontotheVMFSfilesystemoftheESXServer.

vixError = VixDiskLib_Clone(appGlobals.connection, appGlobals.diskPath, srcConnection, appGlobals.srcPath, &createParams, CloneProgressFunc, NULL, TRUE);

Inthiscall,appGlobals.connectionandappGolbals.diskpathrepresenttheremoteVMDKonthe ESXServer,whilesrcConnectionandappGlobals.srcPathrepresentthelocalhostedVMDK. 4 PoweronthenewguestOStogetanewvirtualmachine. OnWorkstation,theVixVMPowerOn()functionintheVIXAPIdoesthis.ForESXServer,youmustuse thePowerOnVM_Taskmethod.AseasywaytousethismethodisintheVIPerlToolkit,whichhasthe PowerOnVM_Task()call(nonblocking),andthePowerOnVM()call(synchronous). 5 ProvisionanddeploythenewvirtualmachineontheESXServer.

Special Consideration for ESX Server

NomatterwhatvirtualfiletypeyoucreateinStep1,itbecomestypeVIXDISKLIB_DISK_VMFS_FLATinStep3.

Working with Virtual Disk Data

Thevirtualdisklibraryreadsandwritessectorsofdata.IthasnointerfaceforcharacterorbyteorientedI/O.

Reading and Writing Local Disk

DemonstratingrandomI/O,thisfunctionreadsasectoratatimebackwardsthroughaVMDK.Ifitseesthe stringVmWareitsubstitutesthestringVMwareinitsplaceandwritesthesectorbacktoVMDK.
#include <string> static void DoEdit(void)/ { VixDisk disk(appGlobals.connection, appGlobals.diskPath, appGlobals.openFlags); uint8 buf[VIXDISKLIB_SECTOR_SIZE]; VixDiskLibSectorType i; string str; for (i = appGlobals.numSectors; i >= 0; i--) { VixError vixError; vixError = VixDiskLib_Read(disk.Handle(), appGlobals.startSector + i, 1, buf); CHECK_AND_THROW(vixError); str = buf; if (pos = str.find(VmWare, 0)) { str.replace(pos, 5, VMware); buf = str; vixError = VixDiskLib_Write(disk.Handle(), appGlobals.startSector + i, 1, buf); CHECK_AND_THROW(vixError); } } }
VMware, Inc. 33

Virtual Disk API Programming Guide

Reading and Writing Remote Disk

ThefunctionissimilarforremotediskonESXServer,butcallsVixDiskLib_Connect()withauthentication credentialsinsteadofpassingNULLparameters.
if (appGlobals.isRemote) { cnxParams.vmxSpec = NULL; cnxParams.serverName = appGlobals.host; cnxParams.credType = VIXDISKLIB_CRED_UID; cnxParams.creds.uid.userName = appGlobals.userName; cnxParams.creds.uid.password = appGlobals.password; cnxParams.port = appGlobals.port; } VixError vixError = VixDiskLib_Init(1, 0, NULL, NULL, NULL, NULL); CHECK_AND_THROW(vixError); vixError = VixDiskLib_Connect(&cnxParams, &appGlobals.connection);

Deleting a Disk (Unlink)

ThefunctiontodeletevirtualdiskfilesisVixDiskLib_Unlink().Ittakestwoarguments:aconnectionanda VMDKfilename.
vixError = VixDiskLib_Unlink(appGlobals.connection, appGlobals.diskPath);

Effects of Deleting a Virtual Disk

WhenyoudeleteaVMDK,youlosealltheinformationitcontained.Inmostcases,thehostoperatingsystem preventsyoufromdoingthiswhenavirtualmachineisrunning.However,ifyoudeleteaVMDKwithits virtualmachinepoweredoff,thatguestOSbecomesunbootable.

Renaming a Disk
ThefunctiontorenamevirtualdiskfilesisVixDiskLib_Rename().Ittakestwoarguments:theoldandthe newVMDKfilenames.
vixError = VixDiskLib_Rename(oldGlobals.diskpath, newGlobals.diskpath);

Effects of Renaming a Virtual Disk

TheserverexpectsVMDKfilesofitsguestOSvirtualmachinestobeinapredictablelocation.Anyfileaccesses thatoccurduringrenamingmightcauseI/OfailureandpossiblycauseaguestOStofail.

Working with Disk Metadata

WithVMFSonESXServer,diskmetadatabecomesimportantbecauseitstoresinformationabouttherawdisk mapping(RDM)andinteractionswiththecontainingfilesystem.

Managing Child Disks

IntheVirtualDiskAPI,redologsaremanagedasaparentchilddiskchain,eachchildbeingtheredologof diskchangesmadesinceitsinception.Tryingtowriteontheparentaftercreatingachildresultsinanerror. Thelibraryexpectsyoutowriteonthechildinstead.SeeFigure 32,ChildDisksCreatedfromParent,on page 22foradiagram.

Creating Redo Logs

Ordinarilyaredologiscreatedbyasnapshotofthevirtualmachine,allowingrestorationofbothdiskdata andthevirtualmachinestate. Forexample,youcouldwriteanapplicationtocreatenewredologs,independentofsnapshots,at3:00AM nightly.Thisallowsyoutorecreatedataforanygivenday.Whenyoucreatearedologwhilethevirtual machineisrunning,theVMwarehostrearrangesfilepointerssotheprimaryVMDK,<vmname>.vmdkfor example,keepstrackofredologsinthediskchain.

34

VMware, Inc.

Chapter 5 Practical Programming Tasks

To re-create data for any given day 1 Locatethe<vmname>-<NNN>.vmdkredologforthedayinquestion. <NNN>isasequencenumber.Youcanidentifythisredologbyitstimestamp. 2 3 Initializethevirtualdisklibraryandopentheredologtoobtainitsparenthandle. CreateachilddiskwiththeVixDiskLib_Create()function,andattachittotheparent:
vixError = VixDiskLib_Attach(parent.Handle(), child.Handle());

Readandwritethevirtualdiskoftheattachedchild.

Virtual Disk in Snapshots

TheVirtualDiskAPIprovidesthefollowingfeaturestodealwiththediskcomponentofsnapshots: Attachinganarbitrarychildinadiskchain Openingreadonlyvirtualdisks AbilitytoopensnapshotdiskonESXServerthroughVirtualCenter

Windows 2000 Read-Only File System

AnotheruseofparentchilddiskchainingistocreatereadonlyaccessforWindows2000,whichhasnooption formountingareadonlyfilesystem.InFigure 51,thegraycirclerepresentsavirtualdiskthatmustremain readonlybecauseithaschildren.Inthisexample,youwanttheWindows2000virtualmachinetousethat virtualdisk,ratherthantheneweronesC1andC2.CreatenewchilddiskC2,attachtothegrayvirtualdiskas parent,andmountC3asthevirtualdiskoftheWindows2000guestOS. Figure 5-1. Attaching Virtual Read/Write Disk for Windows 2000

Windows 2000

C1

C2

C3

Interfacing With the VIX API

TheVIXAPIisapopular,easytousedeveloperinterfaceforVMwareWorkstationandotherhostedproducts. SeetheSupportsectionoftheVMwareWebsiteforinformationabouttheVIXAPI: http://www.vmware.com/support/developer/vixapi TheVIXAPIReferenceGuideincludesfunctionreferencepagesforC++,Perl,andCOM,acomponentobject modelforMicrosoftC#,VBScript,andVisualBasic.Mostofthefunctionreferencepagesincludehelpfulcode examples.Additionally,theaboveWebpageincludesexamplesforpoweronandoff,suspendingavirtual machine,takingasnapshot,asynchronoususe,andapollingeventpump.

VMware, Inc.

35

Virtual Disk API Programming Guide

Virus Scan all Hosted Disk

SupposeyouwanttoruntheantivirussoftwarepresentedinScanVMDKforVirusSignaturesonpage 31 forallvirtualmachineshostedonaVMwareWorkstation.HereisthehighlevelalgorithmforanVIXbased applicationthatwouldscanhosteddiskonallvirtualmachines: 1 2 3 4 WriteanapplicationincludingboththeVirtualDiskAPIandtheVIXAPI. InitializethevirtualdisklibrarywithVixDiskLib_Init(). ConnectVIXtotheWorkstationhostwithVixHost_Connect(). CallVixHost_FindItems()withitemtype(secondargument)VIX_FIND_RUNNING_VMS. Thisprovidestoacallbackroutine(fifthargument)thenameofeachvirtualmachine,oneatatime.To derivethenameofeachvirtualmachinesdisk,append.vmdktothevirtualmachinename. 5 WriteacallbackfunctiontoopenthevirtualmachinesVMDK. YourcallbackfunctionmustbesimilartotheVixDiscoveryProc()callbackfunctionshownasan exampleontheVixHost_FindItems()pageintheVIXAPIReferenceGuide. 6 7 InsteadofprintingFoundvirtualmachineinthecallbackfunction,calltheDoVirusScan()function showninScanVMDKforVirusSignaturesonpage 31. Decontaminateanyinfectedsectorsthatthevirusscannerlocated.

Interfacing With VMware Infrastructure

TheVMwareInfrastructure(VI)APIisadeveloperinterfaceforESXServerandVirtualCenter.SeetheSupport sectionoftheVMwareWebsiteforinformationabouttheVMwareInfrastructureSDK: http://www.vmware.com/support/developer/vcsdk TheDevelopersSetupGuidefortheVMwareInfrastructureSDK2.5hasachapterdescribinghowtosetupyour programmingenvironmentforMicrosoftC#.SomeoftheinformationappliestoC++also. TheProgrammingGuidefortheVMwareInfrastructureSDK2.5containssampleapplicationswritteninJava, butnoexamplesinC++.YoumightfindtheJavaexampleshelpful. ESXServerandtheVIAPIuseaprogrammingmodelbasedonWebservices,inwhichclientsgenerate(Web servicesdescriptionlanguage(WSDL)requeststhatpassoverthenetworkasXMLmessagesencapsulatedin simpleobjectaccessprotocol(SOAP).OnESXServerorVirtualCenter,theVIlayeranswersclientrequests, possiblypassingbackSOAPresponses.Thisisaverydifferentprogrammingmodelthantheobjectoriented functioncallinterfaceofC++andtheVIXAPI.

Virus Scan All Managed Disk

SupposeyouwanttoruntheantivirussoftwarepresentedinScanVMDKforVirusSignaturesonpage 31 forallvirtualmachineshostedonanESXServer.HereisthehighlevelalgorithmforanVisualInfrastructure solutionthatwouldscanmanageddiskonallvirtualmachines: 1 2 3 UsingtheVIPerlToolkit,writeaPerlscriptthatconnectstoagivenESXServer. CallVim::find_entity_views()tofindtheinventoryofeveryVirtualMachine. CallVim::get_inventory_path()togetthevirtualdisknameinitsappropriateresource. TheVMDKfilenameisavailableasdiskPathintheGuestDiskInfodataobject. 4 UsingPerlssystem(@cmd)call,runtheextendedvixDiskLibSample.exeprogramwith-virusoption. ForESXServeryoumustspecify-host,-user,and-passwordoptions. 5 Decontaminateanyinfectedsectorsthatthevirusscannerlocated.

36

VMware, Inc.

Virtual Disk API Errors

Finding Error Code Documentation

ForalistofVirtualDiskAPIerrorcodes,seetheonlinereferenceguideIntroductiontotheVixDiskLibAPI: WindowsC:\ProgramFiles\VMware\VMwareVirtualDiskDevelopmentKit\doc\intro.html Linux/usr/share/doc/vmware-vix-disklib/intro.html InaWebbrowser,clicktheErrorCodeslinkintheupperleftframe,andclickanylinkinthelowerleftframe. Therighthandframedisplaysanalphabetizedlistoferrorcodes,withexplanations.

Association With VIX API Errors

MosterrorcodesintheVirtualDiskAPIaresharedwiththeVMwareVIXAPI,whichexplainstheVIXprefix. ForinformationabouttheVIXAPI,includingitsonlinereferenceguidetofunctionsanderrorcodes,seethe SupportsectionoftheVMwareWebsite. ThefollowingerrorswereintroducedwiththeVirtualDiskAPI,orwithnewversionsoftheVIXAPI,sothey arenotfoundintheonlinedocumentation.Someoftheseinvolvevirtualdiskoperations,whileothersinvolve connectingtoaremoteVMwareServer.
VIX_E_BUFFER_TOOSMALL VIX_E_CANNOT_CONNECT_TO_HOST VIX_E_DISK_CANTSHRINK VIX_E_DISK_CID_MISMATCH VIX_E_DISK_INVAL VIX_E_DISK_INVALIDCHAIN VIX_E_DISK_INVALIDPARTITIONTABLE VIX_E_DISK_INVALID_CONNECTION VIX_E_DISK_KEY_NOTFOUND VIX_E_DISK_NEEDKEY VIX_E_DISK_NEEDSREPAIR VIX_E_DISK_NEEDVMFS VIX_E_DISK_NOINIT VIX_E_DISK_NOIO VIX_E_DISK_NOKEY VIX_E_DISK_NOKEYOVERRIDE VIX_E_DISK_NOTENCDESC VIX_E_DISK_NOTENCRYPTED VIX_E_DISK_NOTNORMAL VIX_E_DISK_NOTSUPPORTED VIX_E_DISK_OPENPARENT VIX_E_DISK_OUTOFRANGE VIX_E_DISK_PARTIALCHAIN VIX_E_DISK_PARTMISMATCH VIX_E_DISK_RAWTOOBIG VIX_E_DISK_RAWTOOSMALL VIX_E_DISK_SUBSYSTEM_INIT_FAIL VIX_E_DISK_TOOMANYOPENFILES VIX_E_DISK_TOOMANYREDO

VMware, Inc.

37

Virtual Disk API Programming Guide

VIX_E_DISK_UNSUPPORTEDDISKVERSION VIX_E_HOST_DISK_INVALID_VALUE VIX_E_HOST_DISK_SECTORSIZE VIX_E_HOST_FILE_ERROR_EOF VIX_E_HOST_NBD_HASHFILE_INIT VIX_E_HOST_NBD_HASHFILE_VOLUME VIX_E_HOST_NETBLKDEV_HANDSHAKE VIX_E_HOST_NETWORK_CONN_REFUSED VIX_E_HOST_SERVER_NOT_FOUND VIX_E_HOST_SOCKET_CREATION_ERROR VIX_E_HOST_TCP_CONN_LOST VIX_E_HOST_TCP_SOCKET_ERROR VIX_E_NOT_ALLOWED_DURING_VM_RECORDING VIX_E_NOT_ALLOWED_DURING_VM_REPLAY VIX_E_NOT_FOR_REMOTE_HOST

38

VMware, Inc.

BVi

Open Virtual Machine Format

OpenVirtualMachineFormat(OVF)isarelativelynewindustrystandardfordescribingvirtualmachinesin XMLformat.CompaniesthatcontributedtothestandardincludeDell,HP,IBM,Microsoft,VMware,and XenSource.AsVMwareincreasesitssupportforthisstandard,partnersareencouragedtodevelopsolutions thatincorporateOVF. TheOVFspecificationdescribesasecure,portable,efficient,andflexiblemethodtopackageanddistribute virtualmachinesandcomponents.ItoriginatedfromtheDistributedManagementTaskForce(DMTF)after vendorinitiative.SeetheVirtualAppliancessectionoftheVMwareWebsiteforanintroduction: http://www.vmware.com/appliances/learn/ovf.html OVFincludesamechanismfordescribingvirtualdisks.

OVF Tool
VMwarecurrentlyprovidestheOVFTool,agraphicaluserinterfacethatallowsthirdpartiestocreateOVF images.SeetheCommunitiessectionoftheVMwareWebsitefortheusersguide: http://www.vmware.com/resources/techresources/1013 AsimilarOVFpackagingmethodisincludedwithnewversionsofESXServer.

OVF Library
Atsomepoint,anOVFlibrarywillbepackagedforusewiththeVMwareVirtualDiskDevelopmentKitand otherVMwaredevelopmentplatforms.

VMware, Inc.

39

Virtual Disk API Programming Guide

40

VMware, Inc.

Glossary

extent InthecontextofVMDK,asplitportionofvirtualdisk,usually2GB. flat SpaceinaVMDKisfullyallocatedatcreationtime(preallocated).Contrastwithsparse.

hosteddisk Avirtualdiskmanagedbyahostedproduct,suchasWorkstation,foritsguestoperatingsystem. manageddisk AvirtualdiskmanagedbyanESXServerorVirtualCenter,containedwithinaVMFSvolume. monolithic ThevirtualdiskisasingleVMDKfile,ratherthanacollectionof2GBextents.Contrastwithsplit.

sparse SpaceinaVMDKisallocatedonlywhenneededtostoredata.Contrastwithflat. split ThevirtualdiskisacollectionofVMDKfilescontaining2GBextents.Contrastwithmonolithic.

VMware, Inc.

41

Virtual Disk API Programming Guide

42

VMware, Inc.

Index

A
access and credentials 14

O
OVF (open virtual-machine format) 39

C
code sample walk-through 26 CopyThread 27, 29 credentials and access 14

P
packaging of Virtual Disk API 13 persistent disk mode 16 platforms supported for development 13 products from VMware that are supported 14

D
datacenter path (dcpath) 27 datastore name (dsname) 27 development platforms 13 disk manager See virtual disk manager disk mount (vmware-mount) 10

R
redo logs and snapshots 10, 14, 16, 21, 34

S
sample program walk-through 26 SAN and the Virtual Disk API 9, 18 snapshot management 35 snapshots and redo logs 10, 14, 16, 21, 34 sparse VMDK 15, 16, 20, 21, 26, 28, 29, 32, 41 split VMDK 15, 16, 32, 41 SPLIT_FLAT 15, 16 SPLIT_SPARSE 15, 16 STREAM_OPTIMIZED 15 supported platforms for development 13 supported VMware products 14

E
error codes, finding explanations for 37 ESX Server 9 ESX Server and VirtualCenter 14 extent 11, 15, 20, 32, 41

F
flat VMDK 15, 16, 20, 41

G
gcc (GNU C compiler) 13

T
technical support resources 7

H
hosted disk 9, 11, 15, 18, 23, 27, 29, 33, 36, 41

U
Unicode UTF-8 support 17

I
installation on Linux 14 installation on Windows 14 internationalization (i18n) 17

V
VHD from Microsoft 14 Vim::find_entity_views 36 Vim::get_inventory_path 36 virtual disk manager (vmware-vdiskmanager) 10 VirtualCenter and ESX Server 14 Visual Studio 13 VixDiscoveryProc 36 VIXDISKLIB_ADAPTER_IDE 17, 32 VIXDISKLIB_ADAPTER_SCSI_BUSLOGIC 17, 32 VIXDISKLIB_ADAPTER_SCSI_LSILOGIC 17 VixDiskLib_Attach 12, 22, 28, 35 VixDiskLib_Clone 12, 20, 23, 29, 33 VixDiskLib_Close 12, 19, 27 VixDiskLib_Connect 12, 18, 23, 27, 29, 34 VixDiskLib_Create 12, 18, 23, 28, 32, 33, 35
43

L
Linux installation 14 localization (l10n) 17

M
managed disk 9, 11, 15, 18, 23, 29, 33, 41 monolithic VMDK 15, 16, 21, 28, 29, 32, 41 MONOLITHIC_FLAT 15, 16 MONOLITHIC_SPARSE 15, 16

N
nonpersistent disk mode 16

VMware, Inc.

Title

VixDiskLib_CreateChild 12, 21, 22, 28 VIXDISKLIB_CRED_UID 34 VixDiskLib_Defragment 12, 20, 23 VixDiskLib_Disconnect 12, 22 VIXDISKLIB_DISK_SPLIT_SPARSE 32 VixDiskLib_Exit 12, 22 VixDiskLib_FreeErrorText 12, 19 VixDiskLib_FreeInfo 12, 19, 28 VixDiskLib_GetErrorText 12, 19 VixDiskLib_GetInfo 12, 19, 28, 31, 32 VixDiskLib_GetMetadataKeys 12, 19, 29 VixDiskLib_Grow 12, 20, 23 VixDiskLib_Init 12, 18, 27, 34, 36 VixDiskLib_Open 12, 18, 27 VixDiskLib_Read 12, 18, 29, 31, 32, 33 VixDiskLib_ReadMetadata 12, 19, 28, 29 VixDiskLib_Rename 12, 20, 34 VIXDISKLIB_SECTOR_SIZE 19, 31, 33 VixDiskLib_Shrink 12, 20 VixDiskLib_SpaceNeededForClone 12, 20 VixDiskLib_Unlink 12, 21, 34 VixDiskLib_Write 12, 19, 20, 28, 33 VixDiskLib_WriteMetadata 12, 20, 29 VixHost_Connect 36 VixHost_FindItems 36 VMDK (virtual machine disk) file 9, 10, 11, 14, 15, 19, 28, 29, 31, 32, 33, 34, 36 VMFS_FLAT 15, 33 VMFS_SPARSE 15 VMX specification (vmxSpec) 27

W
walk-through of sample program 26 Windows installation 14

44

VMware, Inc.