Technical Note

Designing Backup Solutions for VMware vSphere

VMware vStorage APIs for Data Protection
Thisdocumentintroducescodedeveloperstotheconceptsandproceduresnecessarytocreatebackupand restoresoftwareforvirtualmachinesandVMwarevSphere(formerlyVMwareInfrastructure,orVI).You shouldbefamiliarwithprogrammingconcepts,practices,[Link] theseconcepts:virtualmachine,snapshot,andvSphere(ESXandvCenter).Thisdocumentdoesnotduplicate [Link],itreferstootherdocuments. YoushouldbefamiliarwithnavigatingtheWebbasedVMwarevSphereAPIReferenceDocumentation,andread partsoftheVMwarevSphereWebServicesSDKProgrammingGuide,[Link] areavailableat[Link] [Link]:

ConceptualOverviewonpage 1 HighLevelImplementationonpage 2 LowLevelProceduresonpage 8 ChangedBlockTrackingonVirtualDisksonpage 21 IncrementalRestoreofBackupDataonpage 24

Ifyouarelookingforahighleveloverviewofbackupandrestore,[Link] yourtoplevelprogramstructure,[Link] [Link].

Conceptual Overview
Thissectionsummarizesthebackupprocessandtherestoreprocess.

The Backup Process

Becausesnapshotsareaviewofavirtualmachinecorrespondingtoacertainpointintime,theyallowfora [Link]: 1 2 3 4 5 Contacttheservermachinecontainingthetargetvirtualmachine. Commandthatservertoproduceasnapshotofthetargetvirtualmachine. Usetheservertogainaccesstothevirtualdisk(s)andfilesinthesnapshot. Capturethevirtualdiskdataandvirtualmachineconfigurationinformation([Link]). Commandtheservertodestroythebackupsnapshot.

Asideeffectofsteponeisbeingabletodeterminethearrangementanddescriptionofvirtualmachinesonthe [Link].
Copyright 2009 VMware, Inc. All rights reserved. 1

Designing Backup Solutions for VMware vSphere

The Restore Process

Youcanchooseoneoftworestorescenarios: To bring an existing virtual machine to a particular state 1 2 3 Contacttheserverandcommandittohaltandpoweroffthetargetvirtualmachine. Usetheservertogainaccesstothevirtualdisk(s). Transfertheimage(s)ofthedisk(s)fromthebackupprogram.

To completely re-create a virtual machine 1 2 3 Contacttheserver. Commandtheservertocreateanewvirtualmachineanditsvirtualdisksusingtheconfiguration informationinstep4ofthebackupprocessabove. Transferthevirtualdiskdatatothenewlycreatedvirtualdisk(s).Thisincludesthevirtualdiskformatting information,soitisunnecessarytobuildanykindoffilesystemonthevirtualdisk(s).

Summary of Requirements
Abackupprogrammustbeableto:

ContactaVMwarehost,displayinformationaboutthevirtualmachinesthatitcontrols,andmanipulate thosevirtualmachines. Forbackup,instructeachvirtualmachinetocreateatemporarysnapshot,andtransfersnapshotdatato thebackupapplication. Forrestore,instructthehosttohaltorrecreateatargetvirtualmachine,andrestorethedataforthat virtualmachinefromthebackupapplication.

High Level Implementation

Thissectionintroduces,atahighlevel,theVMwaresoftwareabstractionsneededtoaccomplishthesteps [Link]:

Contactingtheserver Extractinginformationfromtheserver Causingtheservertoperformactions Givinginstancespecificcommandsandcontrol Transferringdata

Exceptforthelast,datatransfer,alltheabovecategoriesaresupportedbytheVMwarevSphereSDK,which containsawidevarietyofmanagementandcontrolinterfaces.

Communicating With the Server

InatypicalVMwarevSpheredeploymentthatconsistsofmultipleESXhosts,aninstanceofthevCenter [Link] ratherthanwiththeindividualESXhosts. [Link] virtualmachinesastheymove(throughVMotion)fromoneESXhosttoanother,anditdirectsvSphereSDK operationstotheappropriateESXhostthatcurrentlyhoststhevirtualmachine. ThehandlingofavCenteroranindividualESXhostisessentiallyequivalentwhenusingthevSphereSDK. ThuswhenvCenterispresent,[Link] documentusesthetermvSpheretoindicateeitheravCenteroranESXhost.

Copyright 2009 VMware, Inc. All rights reserved.

Designing Backup Solutions for VMware vSphere

UsingvCenterorthevSphereAPI,itisevenpossibletoidentifyanyVirtualApp(vApp)thatisinstalledand [Link]. ToreducetheresourcesusedbythevSphere,itisgenerallyrecommendedthatthenumberofconnections(or Sessions)[Link],itisinthebestinterestsofanyprogramthatcommunicateswiththe vSpheretocreateoneSessionandshareitwithallelementsoftheprogramthatneedtoexchangeinformation [Link],thenyourprogramneedsto multiplextheuseoftheconnectionobjectthroughtheuseofaccesscontrollocks(mutexandthelike). ItisalsoimportanttonotethatallvSphereSDKoperationsproceedfromaninstanceofaSessionobjectthat [Link] thevSphereSDKthatareSessionspecificandthereforewouldnotbeknowntoportionsofyourapplication thatareusingadifferentSession.

Information Containers as Managed Objects

VMwaredocumentationintroducesyoutotheconceptoftheManagedObjectanditshandle(calledaMoRef forManagedObjectReference).YoumightbetemptedtogetconfigurationandstatusinformationofManaged [Link] connectiontotheserver,[Link] [Link],discussedinPropertyCollectorUseonpage 4.

More About Managed Objects

WhenyoureadthedocumentationontheVMwarevSphereObjectModel,youareintroducedtoalarge [Link] [Link]:

Folder ComputeResource ResourcePool DataCenter VirtualMachine

ItisacharacteristicofallManagedObjectsthattheyhaveaMoReftotheManagedObjectthatservesasthe [Link] [Link]: RootFolder>DataCenter>ComputeResource>ResourcePool>VirtualMachine Therearevariationsonthistheme,dependingonwhetheryouconnecttovCenterordirectlytoanESXhost, [Link].

Managed Object References

AManagedObjectReference(moRef )[Link] absolutelycertainthataMoRefalwayscontainsauniquevalue,theuniquevalueisonlyrelativetotheinstance [Link],ifavCentermanagesaclusterofESXhosts,eachESX hostmaintainsitsownManagedObjectReferencenamespaceandthevCentermustmaintainaManaged [Link],whenanESXhostisrepresentedbyavCenter, [Link] bycreatinguniqueManagedObjectReferencenamesinsideitsownnamespace,whichdifferfromthenames thattheESXusesforthesameManagedObjects. AvSphereinstance(vCenterorESX)attemptstokeeptheManagedObjectReferenceforavirtualmachine consistentacrosssessions,[Link],unregisteringand reregisteringavirtualmachinecouldresultinachangetotheManagedObjectReferenceforthevirtual [Link],itisnotagoodideatostoreaMoRefvalueandexpectittoworkcorrectlyinafuturesession, oragainstadifferentvSphereinstance.

Copyright 2009 VMware, Inc. All rights reserved.

Designing Backup Solutions for VMware vSphere

Unique ID for a Virtual Machine

OnonevCenterServer,theManagedObjectReference(moRef )[Link] needtoinventoryandtrackvirtualmachinebackupsacrossmultiplevCenterServers,youcanusethe [Link]:
[Link]

FordirectconnectionstoESX/ESXi,[Link] thismoRefcouldbedifferentfromtheonethatvCenterServerreturns,hencethefallbacktoinstanceUuid. [Link],thefallbackisinsteadUuid.

Gathering Status and Configuration Information

ThePropertyCollectoristhemostefficientmechanismtospecify,atthetoplevel,alloftheManagedObjects [Link] [Link]:

[Link] advantageofthismechanismisthatexceptforthepollrequest,itinvolvesnochatterexceptforreporting. [Link] [Link] isthatthereisnochatteratallonthecommunicationsthreadunlesssomethingmustbereported.

TheVMwarevSphereWebServicesSDKProgrammingGuidecontainsalotofinformationaboutthe [Link],[Link] featuresofthePropertyCollectorarecoveredinLowLevelProceduresonpage [Link] nextsectionhighlightssomecharacteristicsofthePropertyCollectorasanoverview.

PropertyCollector Use
ThisdocumentassumesthatyouwanttokeepupwithchangesintheconfigurationoftheVMwareserver, [Link] requirestwofairlycomplexarguments:thePropertySpecandtheObjectSpec. TheObjectSpeccontainsinstructionstothePropertyCollectordescribingwheretolookforthedesired [Link],the [Link] complex,nested,[Link],onceyouhavedeterminedthelocationofall thedesiredinformationis,theObjectSpecneededtodeterminethelayoutofavSphereobjecthierarchycan [Link] 9. [Link] informationcantakesomeefforttocompile,butoncedetermined,thiscanbeastaticobjectalso. [Link] [Link] identifiedwithoneofthefollowingkeys:enter(add),leave(delete),[Link], everydataitemisincluded,andeverydataitemismarkedenter. [Link] haveaparentproperty,youcanreconstructtheconfigurationhierarchybybuildingatreeinmemory,using [Link].

Useful Information
YoucanfindmostoftheinformationthatisusefultoabackupprogramintheVirtualMachineManaged [Link],butthefollowingisprobablymostuseful:

VirtualDisksNames,Types,andCapacities. MachineTypeandConfigurationWhateverwouldbeusefulin(re)[Link] mightincludesuchinformationasnumberofCPUsandmemorysize.

Copyright 2009 VMware, Inc. All rights reserved.

Designing Backup Solutions for VMware vSphere

[Link] shouldkeeptrackofthesenamesandcorrelatethemforconsistencybetweenyourproductandwhat VMwaredisplaysinitsproducts.

[Link] implementationisimportantfortworeasons:

[Link],you [Link],thistypeofvirtualdiskcannotbebacked upusingthesnapshotmethoddescribedinthisdocument. Onrestore,youshouldrecreatevirtualdiskwiththesamedisktypeastheoriginalvirtualmachineused.

Doing a Backup Operation

Afteryouobtaintheinformationaboutwhatisavailabletobackup,[Link] stepstothebackupprocessare:

CreatingaTemporarySnapshotontheTargetVirtualMachineonpage 5 ExtractingtheBackupDatafromtheTargetVirtualMachineonpage 5,saveconfigurationinformation DeletingtheTemporarySnapshotonpage 6

Creating a Temporary Snapshot on the Target Virtual Machine

ThelowlevelprocedureforcreatingasnapshotofavirtualmachineisdocumentedinthesectionCreating aSnapshotonpage [Link] systemisnotquiescent,[Link] [Link]. Thereisalsoasecondflagthatallowsyoutoincludeadumpofapoweredonvirtualmachinesinmemory [Link],soyoushouldthisflagtofalse. Asabestpractice,youshouldsearchfor,anddelete,anyexistingsnapshotswiththesamenamethatyou [Link] thevirtualmachine.

Extracting the Backup Data from the Target Virtual Machine

Associatedwiththesnapshotyoujustcreatedareversionsofthevirtualdisk(s).Inordertoidentifythese disks,[Link],youcanextractthedisk [Link] 13. Withinaspecificsnapshot,thenamesofvirtualdiskfiles([Link])canbemodifiedwitha [Link] whetherornotthecurrentvirtualmachinehadapreexistingsnapshot,thedisknameforasnapshotcould havethisformat:<diskname>-<NNNNNN>.[Link] destroyed,soanydataforasnapshotdiskshouldbestoredinthebackupprogramunderitsbasediskname. Toaccessthedatainavirtualdisk,[Link] fromthe(extremely)[Link] accesstodiskdataonsectorboundariesonly,andthetransfersizeissomemultipleofthedisksectorsize. WhenaccessingdisksonESXhosts,VixDiskLibrelease1.0transferredvirtualdiskdataoverthenetwork. VixDiskLibrelease1.1containsAPIenhancementssoyoucanrequestmoreefficientdatapaths,suchasdirect [Link] changestoyourapplication,forexamplecallingVixDiskLib_ConnectEx()insteadofplainconnect. Partoftheinformationinavirtualdiskisanumberofkey/valuepairsthatdescribetheconfigurationofthe [Link] VixDiskLib_GetMetadataKeys().Youshouldsavethismetadatainformationinordertobeabletorecreate thevirtualdiskshoulditbecomenecessary.

Copyright 2009 VMware, Inc. All rights reserved.

Designing Backup Solutions for VMware vSphere

[Link] VixMntapilibrarycanextractinformationaboutaguestoperatingsystemfromitsvirtualdisks,soyour [Link] volumestodevicenodes,sothatapplicationscanperformfileorientedbackupsofavirtualmachine.

Deleting the Temporary Snapshot

Asthelastpartofthebackupprocess,[Link],and [Link] intheVMwarevSphereWebServicesSDKProgrammingGuide.

Doing a Restore Operation

Therestoreprocesshastwomodesofoperation:

RestoringanExistingVirtualMachinetoaKnownStateonpage 6 CreatingaNewVirtualMachineonpage 6

Restoring an Existing Virtual Machine to a Known State

Thefollowingstepsrestoreavirtualmachinetoaknownstate: 1 Shutdownthevirtualmachine(ifitisnotalreadyshutdown). Forobvioussecurityreasons,youarenotgrantedwriteaccesstothedisksofarunningvirtualmachine. Beforeyoushutitdown,[Link] thatisavailablefromthePropertyCollector,andifyouhavebeenkeepingthisinformationuptodate, thenyourapplicationalreadyknowstherunstateofthevirtualmachine. TochangetherunstateofavirtualmachinerequiresthatyoudeterminetheMoRefofthevirtualmachine. YoucanthenusethisMoRefinaPowerOnVM_Taskcallthroughtheconnectionyoumaketotheserver. TheprocedureforaccomplishingvirtualmachineshutdownisoutlinedintheVMwarevSphereWeb ServicesSDKProgrammingGuideinthePerformingPowerOperationsonaVirtualMachinesection. 2 Restorethecontentsofthevirtualdisks. [Link] processissimilartotheonedescribedinExtractingtheBackupDatafromtheTargetVirtualMachine onpage 5,exceptinthiscaseyouobtainthisinformationdirectlyfromthevirtualmachineandnotfrom [Link](includinganysequence numberthatmayexist),becausethecurrentincarnationofthevirtualmachinemaybederivedfromone ormoresnapshots. [Link] [Link] [Link] toevensectorboundariesonly,andthetransferlengthmustbeanevenmultipleofasectorsize. Sincethevirtualdiskexists,itisnotnecessarytorestorethediskconfigurationinformationmentionedin ExtractingtheBackupDatafromtheTargetVirtualMachineonpage 5.

Creating a New Virtual Machine

Theprocessofbuildingavirtualmachinefrombackupdatainvolvesthefollowingsteps: 1 Createthevirtualmachine. TheprocessforcreatingavirtualmachineisdescribedintheVMwarevSphereWebServicesSDK [Link],youmust usetheinformationaboutvirtualmachineconfigurationthatyouderivedandsavedduringthebackup [Link] [Link] changethevirtualmachineslayout(forinstance,storingthevirtualdisksondifferentdatastores).

Copyright 2009 VMware, Inc. All rights reserved.

Designing Backup Solutions for VMware vSphere

[Link] [Link] 8fordetails. 2 Restorethevirtualdiskdata. Thisprocessissimilartorestoringthecontentsofvirtualdiskswiththefollowingexception:youmust useaVixDiskLibfunctiontosetthediskconfigurationkey/valuedataintothevirtualdiskbeforewriting [Link],asdescribedabove. 3 Poweronthevirtualmachine.

Changed Block Tracking

Thisrelativelynewfeatureprovidesthefoundationforincrementalordifferentialbackupofvirtualdisks. YourapplicationcanbackuponlychangeddataasindicatedbytheQueryChangedDiskAreasmethod. Recentlycreatedvirtualmachinescansupportthiscapability,inwhichcasethevirtualmachinecontains [Link] BlockTrackingonVirtualDisksonpage 21formoredetails.

Accessing Files on Virtual Disks

[Link] toaccomplishthisintheVixMntapilibrary,[Link] orvolumescontainedwithinavirtualmachinetobemountedandexaminedinanywaynecessary. Theprocedureformountingavirtualdiskrequiresthefollowingsequenceofsteps: 1 2 3 4 5 6 7 Locatethepathnamesofallthevirtualdisksassociatedwithasnapshot. CallVixDiskLib_Open()[Link] handles,whichyoushouldstoreinanarray. CallVixMntapi_OpenDiskSet()tocreateaVixDiskSetHandle,passinginthearrayofVixDiskLib handlesthatyoucreatedinstep2. PassVixDiskSetHandleasaparametertoVixMntapi_GetVolumeHandles()toobtainanarrayof VixVolumeHandlepointerstoallvolumesinthediskset. CallVixMntapi_GetOsInfo()todeterminewhatkindofoperatingsystemisinvolved,andwhere importantpiecesofinformationaretobefound. Forimportantvolumes,callVixMntapi_MountVolume()thenVixMntapi_GetVolumeInfo(),which revealshowthevolumeissetup. Ifyouneedinformationabouthowtheguestoperatingsystemseesthedataonthisvolume,youcanlook inthedatastructureVixVolumeInforeturnedbyVixMntapi_GetVolumeInfo(). VixVolumeInfo::symbolicLink,obtainedusingVixMntapi_GetVolumeInfo(),isthepathonthe proxywhereyoucanaccessthefilesysteminthevirtualdiskusingordinaryopen,read,andwritecalls. Onceyouaredonewithaccessingfilesinavolume,thereareVixMntapiproceduresfortakingdownthe [Link]:

VixMntapi_DismountVolume() VixMntapi_FreeOsInfo() VixMntapi_FreeVolumeInfo() VixMntapi_CloseDiskSet()

ThisleavestheVixDiskLibhandlesthatyouobtainedinthebeginning;youmustdisposeofthoseproperly.

Copyright 2009 VMware, Inc. All rights reserved.

Designing Backup Solutions for VMware vSphere

Summary
Intheprecedingsectionsyouhaveseenatahighlevel:

Howtocontactaserver Howtoextractinformationfromthatserver Howtomanipulateitemsontheserver Howtobackupandrestoredatafromvirtualdisks Howtoaccessfiledataonvirtualdisks

Thefollowingsectionscoverthesameinformationatalowerlevel.

Low Level Procedures

Thissectiondescribesthelowleveldetailsthatshouldbehelpfulinactuallycodingyourbackupapplication. [Link],thisdocumentshouldserveasaguideline, [Link] lackappropriateerrorhandling,andtheyignoreotherdetailsthatmaybenecessarytomakeaprogramwork. Thecodesamplesaremainlymeanttodemonstrateapproachestoaccomplishthebackuptask.

Communicating with the Server

Connectionstotheservermachinerequirecredentials:username,password,andhostname(orIPaddress). Thefollowingcodeshowshowtocontacttheserverandextracttheinformationthatismostusefulfor [Link] VMwarevSphereWebServicesSDKProgrammingGuidesectionsaboutinstallationandconfigurationoftheSDK server. 1 Createtheserviceinstance:
ManagedObjectReference svcRef = new ManagedObjectReference(); [Link]("ServiceInstance"); [Link]("ServiceInstance");

Locatetheservice:
VimServiceLocator locator = new VimServiceLocator(); [Link](true); VimPortType serviceConnection = [Link]("[Link] ServiceInstanceContent serviceContent = [Link](svcRef); ManagedObjectReference sessionManager = [Link](); UserSession us = [Link](sessionManager, username, password, null);

The PropertyCollector
ThePropertyCollectorisdescribedinsomedetailintheVMwarevSphereWebServicesSDKProgramming [Link].

PropertyCollector Arguments
[Link] PropertyCollectorUseonpage 4,[Link] isalistoftheinformationdesired,andtheObjectSpecisalistofinstructionsindicatingwherethedesired [Link],[Link] [Link],gettingtheMoRefinthefirstplacecanbeachallengewhena [Link],youneedtounderstandthe structureoftheavailabledata,[Link] ObjectSpeccancontainrecursiveelements.

Copyright 2009 VMware, Inc. All rights reserved.

Designing Backup Solutions for VMware vSphere

Understanding an ObjectSpec [Link],andgivesa [Link] 3describesfive [Link](howoneManagedObjectleadstoanother).

FolderIfyoureadtheVMwarevSphereSDKReferenceGuidesectionaboutaFolderManagedObject,you seethatoneoftheitemscontainedintheFolderiscalledchildEntity,whichisalistofMoRefsthatcan containanyofthefollowingManagedObjecttypes:Folder,DataCenter,ComputeResource,orVirtual [Link]. [Link]:

hostFolderAMoReftoaFoldercontainingalistofComputeResourcescomprisingaDataCenter. [Link] itisyourobjectivetoduplicatethedisplayseeninaVirtualClientGUI,thenthisFolderisoflimited usebecauseitdoesnotdescribetheResourcePoolthatistheparentofthevirtualmachine.

[Link] [Link] [Link],aVirtualMachinesisalwaysachildofaResourcePool,whichisusedtocontrol [Link] containsanitemnamedresourcePool,whichisaMoReftoaResourcePool. VirtualAppAVirtualApp(vApp)isacollectionofVirtualMachinesthatmakeupasingleapplication. ThisisaspecialformofResourcePool(definedbelow).AVirtualAppmayhavethreetypesofchildren:

VirtualMachineAfoldernamedvmcontainsalistofMoRefstochildVirtualMachines. resourcePoolAfoldercontainingalistofMoRefspointingtochildResourcePoolsorVirtualApps.

VirtualAppAVirtualAppcanbecomposedofotherVirtualApps. ResourcePoolYoucansegmenttheresourcesofaVirtualAppusingaResourcePool.

ResourcePoolResourcePoolcontainstwochilditems:

resourcePoolAfoldercontainingalistofMoRefspointingtochildResourcePoolsorVirtualApps. vmAlistofMoRefstochildVirtualMachinesthatemploytheresourcesoftheparentResourcePool. AVirtualMachinealwayslistsaResourcePoolasitsparent.

VirtualMachineVirtualMachinecanbeconsideredtobeanendobjectandassuchyouneednot describeanytraversalforthisobject.

YoumustunderstandthattheObjectSpecdoesnothavetoleadyouanyfartherthantheMoRefofatarget [Link]. ThisisdescribedindetailinthesectionUnderstandingaPropertySpeconpage 10. InthedocumentVMwarevSphereWebServicesSDKProgrammingGuide,anObjectSpecelement(calleda TraversalSpec)isdescribedascontainingthefollowingelements:

TypeThetypeofobjectbeingreferenced. PathTheelementcontainedintheobjectthatisusedtosteertraversal. NameOptionalreferencenamethatyoucanusetoreferencethisTraversalSpecinanotherSelectSet. SelectSetAnarraycontainingeitherSelectionSpecorTraversalSpecelements.

SelectionSpecisadirecttargetfortraversal,asisTraversalSpec(aclassextendingSelectionSpec).Itis intheSelectSetthatrecursioncanoccur. Ifyouwishtotraversetheentireconfigurationtreeforaserver,thenyouneedonlytherootnodeMoRef, [Link] [Link]:

// Remember, TraversalSpec objects can use a symbolic name.

Copyright 2009 VMware, Inc. All rights reserved.

Designing Backup Solutions for VMware vSphere

// In this case we use the symbolic name "folderTSpec". // First we must define the TraversalSpec objects used to fill in the ObjectSpec. // // This TraversalSpec traverses Datacenter to vmFolder TraversalSpec dc2vmFolder = new TraversalSpec(); [Link]("Datacenter"); // Type of object for this spec [Link]("vmFolder"); // Property name defining the next object [Link](new SelectionSpec[] {"folderTSpec"}); // // This TraversalSpec traverses Datacenter to hostFolder TraversalSpec dc2hostFolder = new TraversalSpec(); [Link]("Datacenter"); [Link]("hostFolder"); [Link](new SelectionSpec[] {"folderTSpec"}); // // This TraversalSpec traverses ComputeResource to resourcePool TraversalSpec cr2resourcePool = new TraversalSpec(); [Link]("ComputeResource"); [Link]("resourcePool"); // // This TraversalSpec traverses ComputeResource to host TraversalSpec cr2host = new TraversalSpec(); [Link]("ComputeResource"); [Link]("host"); // // This TraversalSpec traverses ResourcePool to resourcePool TraversalSpec rp2rp = new TraversalSpec(); [Link]("ResourcePool"); [Link]("resourcePool"); // // Finally, we tie it all together with the Folder TraversalSpec TraversalSpec folderTS = new TraversalSpec(); [Link]{"folderTSpec"); // Used for symbolic reference [Link]("Folder"); [Link]("childEntity"); [Link](new SelectionSpec[]{ "folderTSpec", dc2vmFolder, dc2hostFolder, cr2resourcePool, rp2rp}); ObjectSpec ospec = new ObjectSpec(); [Link](startingPoint); // This is where you supply the starting MoRef (usually root folder) [Link]([Link]); [Link](folderTS); // Attach the TraversalSpec we designed above

Understanding a PropertySpec APropertySpecisalistofindividualpropertiesthatcanbefoundatplacesidentifiedbytheObjectSpec. OncethePropertyCollectorhasaMoRef,itcanthenreturnthepropertiesassociatedwiththatMoRef. [Link] [Link]. [Link] VMwarevSphereSDKReferenceGuideyouseethataVirtualMachinehasthepropertyidentifiedassummary, [Link],theVirtualMachineSummarycontains propertyconfig,[Link] apropertycalledname,[Link] [Link] information,[Link]. [Link]:

TypeThetypeofobjectthatidentifiestheenclosedlistofproperties. PathSetAnarrayofstringscontainingnamesofpropertiestobereturned,includingnestedproperties.

Copyright 2009 VMware, Inc. All rights reserved.

10

Designing Backup Solutions for VMware vSphere

[Link] acodesampleofaPropertySpec:
// This code demonstrates how to specify a PropertySpec for several types of target objects: PropertySpec folderSp = new PropertySpec(); [Link]("Folder"); [Link]([Link]); [Link](new String [] {"parent", "name"}); PropertySpec dcSp = new PropertySpec(); [Link]("Datacenter"); [Link]([Link]); [Link](new String [] {"parent","name"}); PropertySpec rpSp = new PropertySpec(); [Link]("ResourcePool"); [Link]([Link]); [Link](new String [] {"parent","name","vm"}); PropertySpec crSp = new PropertySpec(); [Link]("ComputeResource"); [Link]([Link]); [Link]:PathSet(new String [] {"parent","name"}); PropertySpec vmSp = new PropertySpec(); [Link]("VirtualMachine"); [Link]([Link]); [Link](new String [] {"parent", "name", "[Link]", "snapshot", "[Link]"}); // Tie it all together PropertySpec [] pspec = new PropertySpec [] {folderSp, dcSp, rpSp, crSp, vmSp};

Getting the Data from the PropertyCollector

NowthatwehavedefinedObjectSpecandPropertySpec(thewhereandwhat),weneedtoputtheminto [Link] (theminimumnumberofelementsisone).TwomechanismscanretrievedatafromPropertyCollector:

RetrievePropertiesAonetimerequestforallofthedesiredproperties. UpdatesPropertyCollectorupdaterequeststaketwoforms:pollingandwaiting,discussedbelow.

Checking for Updates TheRetrievePropertiesoperationisratherobvious,[Link] Waiting,[Link] accomplishthisusingtheCreateFilterfunction,whichsendsacopyofyourFilterSpectotheserver. UnliketheRetrievePropertiesfunction,FilterSpecisnotdiscardedaftertheCreateFilteroperation. ThefollowingcodeshowshowtosetyourFilterSpec:

// We already showed examples of creating pspec and ospec in the examples above. // Remember, the PropertyCollector wants an array of FilterSpec objects, so: PropertyFilterSpec fs = new PropertyFilterSpec(); [Link](pspec); [Link](ospec); PropertyFilterSpec [] fsa = new PropertyFilterSpec [] {fs}; ManagedObjectReference pcRef = [Link](); // This next statement sends the filter to the server for reference by the PropertyCollector ManagedObjectReference pFilter = [Link](pcRef, fsa, [Link]);

Copyright 2009 VMware, Inc. All rights reserved.

11

Designing Backup Solutions for VMware vSphere

Ifyouwishtobeginpolling,youmaythencallthefunctionCheckForUpdates,whichonthefirsttry(whenit mustcontainanemptystringfortheversionnumber)returnsacompletedumpofalltherequestedproperties, [Link] [Link] apartiallistcontainingonlythechangesfromthepreviousversion(includinganewversionnumber),ora [Link]:

String updateVersion = ""; // Start with no version UpdateSet changeData = [Link](pcRef, version); if (changeData != nil) { version = [Link](); // Extract the version of the data set } ... // Get changes since the last version was sent. UpdateSet latestData = [Link](pcRef, version);

Ifinsteadyouwishtowaitforupdatestooccur,youmustcreateataskthreadthatblocksonthecall [Link]. Extracting Information from the Change Data ThedatareturnedfromCheckForUpdates(orWaitForUpdates)isanarrayofPropertyFilterUpdate [Link],hereissomecodeshowinghowtoextract informationfromthePropertyFilterUpdate.
// Extract the PropertyFilterUpdate set from the changeData // PropertyFilterUpdate [] updateSet = [Link](); // // There is one entry in the updateSet for each filter you registered with the PropertyCollector. // Since we currently have only one filter, the array length should be one. // PropertyFilterUpdate myUpdate = updateSet[0]; ObjectUpdate [] changes = [Link](); for (a = 0; a < [Link]; ++a) { ObjectUpdate theObject = changes[a]; String objName = [Link]().getMoType().getName(); // Must decide how to handle the value based on the name returned. // The only names returned are names found in the PropertySpec lists. ... }

Getting Specific Data Fromtimetotime,[Link] [Link] propertiesyouwant,[Link] generalexaminationofthepropertiesoutlinedabove(whereyousearchforinformationfromtherootFolder).

Identifying Virtual Disks for Backup and Restore

Whenattemptingtobackupavirtualmachine,[Link] created,[Link] attemptingtorestorethevirtualdisksinthevirtualmachine,thenyouneedtofindandidentifythevirtual [Link],itisfirstnecessarytounderstand [Link] [Link],anda [Link] [Link]:[Link] wouldbesomenumberlike:000032.

Copyright 2009 VMware, Inc. All rights reserved.

12

Designing Backup Solutions for VMware vSphere

Inadditiontothenameofthedisk,thereshouldbeapathtothisdiskontheserver,whichisstoredasa datastorepath:[storagex]myvmname/[Link] correspondstothenameofthedatastorethatcontainsthisvirtualdiskwhiletheremainderofthepathstring [Link], [Link]?Whetherwearetalkingabouta snapshotorobtainingtheinformationfromthebasevirtualmachine,[Link] differenceisintheManagedObjectthatweusetoextracttheinformation. WhetheryouusethePropertyCollectortogetaVirtualMachineoraVirtualMachineSnapshot,youneed toselecttheproperty:[Link] [Link] [Link],examinethe [Link]:

VirtualDiskFlatVer1BackingInfo VirtualDiskFlatVer2BackingInfo VirtualDiskRawDiskMappingVer1BackingInfo VirtualDiskSparseVer1BackingInfo VirtualDiskSparseVer2BackingInfo

[Link] importanttoknowthatyoucannotsnapshotadiskoftypeVirtualDiskRawDiskMappingVer1BackingInfo, andthereforeyoucannotbackupthistypeofVirtualDisk. [Link],when changetrackingisinplace,youshouldalsosavethechangeID.

Creating a Snapshot
Inordertoperformabackupoperation,[Link] followingcodesampleshowshowtocreateasnapshotonaspecificvirtualmachine:
// At this point we assume the virtual machine is identified as ManagedObjectReference vmMoRef. String SnapshotName = "Backup"; String SnapshotDescription = "Temporary Snapshot for Backup"; boolean memory_files = false; boolean quiesce_filesystem = true; ManagedObjectReference taskRef = serviceConnection.CreateSnapshot_Task(vmMoRef, SnapshotName, SnapshotDescription, memory_files, quiesce_filesystem);

Backing Up a Virtual Disk

[Link] virtualdisk,[Link] [Link]. AtthepresenttimeVixDiskLibisimplementedonlyfortheClanguage,sothisisnotJavacode:
VixDiskLibConnectParams connectParams; VixDiskLibConnection srcConnection; [Link] = strdup("TargetServer"); [Link] = strdup("root"); [Link] = strdup("yourPasswd"); [Link] = 902; VixError vixError = VixDiskLib_Init(1, 0, &logFunc, &warnFunc, &panicFunc, libDir); vixError = VixDiskLib_Connect(&connectParams, &srcConnection);

Thisnextsectionofcodeshowshowtoopenandreadaspecificvirtualdisk:
VixDiskLibHandle diskHandle; vixError = VixDiskLib_Open(srcConnection, diskPath, flags, &diskHandle); uint8 mybuffer[some_multiple_of_512]; vixError = VixDiskLib_Read(diskHandle, startSector, numSectors, &mybuffer);

Copyright 2009 VMware, Inc. All rights reserved.

13

Designing Backup Solutions for VMware vSphere

// Also getting the disk metadata: size_t requiredLength = 1; char *buf = new char [1]; // This next operation fails, but updates "requiredLength" with the proper buffer size vixError = VixDiskLib_GetMetadataKeys(diskHandle, buf, requiredLength, &requiredLength); delete [] buf; buf = new char[requiredLength]; // Create a large enough buffer vixError = VixDiskLib_GetMetadataKeys(diskHandle, buf, requiredLength, NULL);

Andfinally,closethediskHandle:
vixError = VixDiskLib_Close(diskHandle); // And if you are completely done with the VixDiskLib VixDiskLib_Disconnect(srcConnection); VixDiskLib_Exit();

Deleting a Snapshot
Whenyouaredoneperformingabackup,[Link] [Link] Javacodedemonstrateshowtodeletethesnapshot:
ManagedObjectReference removeSnapshotTask; SnapshotManagedObject snapshot; removeSnapshotTask = serviceConnection.removeSnapshot_Task(snapshot, Boolean FALSE);

Restoring a Virtual Disk

ThissectiondescribeshowtorestorethedataintotheVirtualDisk. Nomatterhowyouattempttodoit,[Link] mustensurethatthediskisnotinusebyhaltingtheparentVirtualMachine,thenperformingthepoweroff [Link]:
// At this point we assume that you have a ManagedObjectReference to the VM - vmMoRef. // You also need a ManagedObjectReference to the host running the VM - hostMoRef. ManagedObjectReference taskRef = [Link](vmMoRef, hostMoRef);

ThisisthephasewhereitisnecessarytouseVixDiskLibtoreloadthecontentsoftheVirtualDisk,sothe followingcodeisC,notJava:
// At this point we assume that you already have a VixDiskLib connection to the server machine. uint8 mybuffer[some_multiple_of_512]; int mylocalfile = open("localfile", openflags); read(mylocalfile, mybuffer, sizeof mybuffer); vixError = VixDiskLib_Open(srcConnection, path, flags, &diskHandle); VixDiskLib_Write(diskHandle, startsector, (sizeof mybuffer) / 512, mybuffer);

Creating a Virtual Machine

[Link] [Link] [Link] [Link],whichisatablecontainingallofthedevice [Link],whichisa [Link],eachdevicehasacontrollerKey,whichisthekeyidentifierofthe [Link]/keyrelationships [Link] [Link] VirtualMachine([Link]).
// beginning of VirtualMachineConfigSpec // ends several pages later { dynamicType = <unset>, changeVersion = <unset>,

Copyright 2009 VMware, Inc. All rights reserved.

14

Designing Backup Solutions for VMware vSphere

//This is the display name of the VM name = My New VM, version = "vmx-04", uuid = <unset>, instanceUuid = <unset>, npivWorldWideNameType = <unset>, npivDesiredNodeWwns = <unset>, npivDesiredPortWwns = <unset>, npivTemporaryDisabled = <unset>, npivOnNonRdmDisks = <unset>, npivWorldWideNameOp = <unset>, locationId = <unset>, // // This is advisory, the disk determines the O/S guestId = "winNetStandardGuest", alternateGuestName = "Microsoft Windows Server 2003, Standard annotation = <unset>, files = ([Link]) { dynamicType = <unset>, vmPathName = "[plat004-local]", snapshotDirectory = "[plat004-local]", suspendDirectory = <unset>, logDirectory = <unset>, }, tools = ([Link]) { dynamicType = <unset>, toolsVersion = <unset>, afterPowerOn = true, afterResume = true, beforeGuestStandby = true, beforeGuestShutdown = true, beforeGuestReboot = true, toolsUpgradePolicy = <unset>, pendingCustomization = <unset>, syncTimeWithHost = <unset>, }, flags = ([Link]) { dynamicType = <unset>, disableAcceleration = <unset>, enableLogging = <unset>, useToe = <unset>, runWithDebugInfo = <unset>, monitorType = <unset>, htSharing = <unset>, snapshotDisabled = <unset>, snapshotLocked = <unset>, diskUuidEnabled = <unset>, virtualMmuUsage = <unset>, snapshotPowerOffBehavior = "powerOff", recordReplayEnabled = <unset>, }, consolePreferences = ([Link]) null, powerOpInfo = ([Link]) { dynamicType = <unset>, powerOffType = "preset", suspendType = "preset", resetType = "preset", defaultPowerOffType = <unset>, defaultSuspendType = <unset>, defaultResetType = <unset>, standbyAction = "powerOnSuspend", }, // the number of CPUs numCPUs = 1, // the number of memory megabytes memoryMB = 256, memoryHotAddEnabled = <unset>, cpuHotAddEnabled = <unset>,

Edition (32-bit)",

Copyright 2009 VMware, Inc. All rights reserved.

15

Designing Backup Solutions for VMware vSphere

//

//

//

//

//

//

//

cpuHotRemoveEnabled = <unset>, deviceChange = ([Link]) [ ([Link]) { dynamicType = <unset>, operation = "add", fileOperation = <unset>, CDROM device = ([Link]) { dynamicType = <unset>, key number of CDROM key = -42, deviceInfo = ([Link]) null, backing = ([Link]) { dynamicType = <unset>, deviceName = "", useAutoDetect = <unset>, exclusive = false, }, connectable = ([Link]) { dynamicType = <unset>, startConnected = false, allowGuestControl = true, connected = false, }, connects to this controller controllerKey = 200, unitNumber = 0, }, }, ([Link]) { dynamicType = <unset>, operation = "add", fileOperation = <unset>, SCSI controller device = ([Link]) { dynamicType = <unset>, key number of SCSI controller key = -44, deviceInfo = ([Link]) null, backing = ([Link]) null, connectable = ([Link]) null, controllerKey = <unset>, unitNumber = <unset>, busNumber = 0, hotAddRemove = <unset>, sharedBus = "noSharing", scsiCtlrUnitNumber = <unset>, }, }, ([Link]) { dynamicType = <unset>, operation = "add", fileOperation = <unset>, Network controller device = ([Link].VirtualPCNet32) { dynamicType = <unset>, key number of Network controller key = -48, deviceInfo = ([Link]) null, backing = ([Link]) { dynamicType = <unset>, deviceName = "Virtual Machine Network", useAutoDetect = <unset>, network = <unset>, inPassthroughMode = <unset>, }, connectable = ([Link]) { dynamicType = <unset>,

Copyright 2009 VMware, Inc. All rights reserved.

16

Designing Backup Solutions for VMware vSphere

startConnected = true, allowGuestControl = true, connected = true, }, controllerKey = <unset>, unitNumber = <unset>, addressType = "generated", macAddress = <unset>, wakeOnLanEnabled = true, }, }, ([Link]) { dynamicType = <unset>, operation = "add", fileOperation = "create", SCSI disk one device = ([Link]) { dynamicType = <unset>, key number for SCSI disk one key = -1000000, deviceInfo = ([Link]) null, backing = ([Link].FlatVer2BackingInfo) { dynamicType = <unset>, fileName = "", datastore = <unset>, diskMode = "persistent", split = false, writeThrough = false, thinProvisioned = <unset>, eagerlyScrub = <unset>, uuid = <unset>, contentId = <unset>, changeId = <unset>, parent = ([Link].FlatVer2BackingInfo) null, }, connectable = ([Link]) { dynamicType = <unset>, startConnected = true, allowGuestControl = false, connected = true, }, controller for SCSI disk one controllerKey = -44, unitNumber = 0, size in MB SCSI disk one capacityInKB = 524288, committedSpace = <unset>, shares = ([Link]) null, }, }, ([Link]) { dynamicType = <unset>, operation = "add", fileOperation = "create", SCSI disk two device = ([Link]) { dynamicType = <unset>, key number of SCSI disk two key = -100, deviceInfo = ([Link]) null, backing = ([Link].FlatVer2BackingInfo) { dynamicType = <unset>, fileName = "", datastore = <unset>, diskMode = "persistent", split = false, writeThrough = false, thinProvisioned = <unset>,

//

//

//

//

//

//

Copyright 2009 VMware, Inc. All rights reserved.

17

Designing Backup Solutions for VMware vSphere

eagerlyScrub = <unset>, uuid = <unset>, contentId = <unset>, changeId = <unset>, parent = ([Link].FlatVer2BackingInfo) null, }, connectable = ([Link]) { dynamicType = <unset>, startConnected = true, allowGuestControl = false, connected = true, }, // controller for SCSI disk two controllerKey = -44, unitNumber = 1, // size in MB SCSI disk two capacityInKB = 131072, committedSpace = <unset>, shares = ([Link]) null, }, } }, cpuAllocation = ([Link]) { dynamicType = <unset>, reservation = 0, expandableReservation = <unset>, limit = <unset>, shares = ([Link]) { dynamicType = <unset>, shares = 100, level = "normal", }, overheadLimit = <unset>, }, memoryAllocation = ([Link]) { dynamicType = <unset>, reservation = 0, expandableReservation = <unset>, limit = <unset>, shares = ([Link]) { dynamicType = <unset>, shares = 100, level = "normal", }, overheadLimit = <unset>, }, cpuAffinity = ([Link]) null, memoryAffinity = ([Link]) null, networkShaper = ([Link]) null, swapPlacement = <unset>, swapDirectory = <unset>, preserveSwapOnPowerOff = <unset>, bootOptions = ([Link]) null, appliance = ([Link]) null, ftInfo = ([Link]) null, applianceConfigRemoved = <unset>, vAssertsEnabled = <unset>, changeTrackingEnabled = <unset>, } // end of VirtualMachineConfigSpec

Theinformationaboveappearstobequitecomplex,butmuchoftheinputconsistsofdefaultedvaluestobe [Link] [Link] theVMwarevSphereWebServicesSDKProgrammingGuide,wegetthefollowingcodethatduplicates functionalityoftheconfigurationspecificationseenabove:

// Duplicate virtual machine configuration

Copyright 2009 VMware, Inc. All rights reserved.

18

Designing Backup Solutions for VMware vSphere

VirtualMachineConfigSpec configSpec = new VirtualMachineConfigSpec(); // Set the VM values [Link]("My New VM"); [Link]("vmx-04"); [Link]("winNetStandardGuest"); [Link](1); [Link](256); // Set up file storage info VirtualMachineFileInfo vmfi = new VirtualMachineFileInfo(); [Link]("[plat004-local]"); [Link](vmfi); [Link]("[plat004-local]"); // Set up tools config info ToolsConfigInfo tools = new ToolsConfigInfo(); [Link](tools); [Link](new Boolean(true)); [Link](new Boolean(true)); [Link](new Boolean(true)); [Link](new Boolean(true)); [Link](new Boolean(true)); // Set flags VirtualMachineFlagInfo flags = new VirtualMachineFlagInfo(); [Link](flags); [Link]("powerOff"); // Set power op info VirtualMachineDefaultPowerOpInfo powerInfo = new VirtualMachineDefaultPowerOpInfo(); [Link](powerInfo); [Link]("preset"); [Link]("preset"); [Link]("preset"); [Link]("powerOnSuspend"); // Now add in the devices VirtualDeviceConfigSpec[] deviceConfigSpec = new VirtualDeviceConfigSpec [5]; [Link](deviceConfigSpec); // Formulate the CDROM deviceConfigSpec[0].setOperation([Link]); VirtualCdrom cdrom = new VirtualCdrom(); VirtualCdromIsoBackingInfo cdDeviceBacking = new VirtualCdromRemotePassthroughBackingInfo(); [Link](datastoreRef); [Link](cdDeviceBacking); [Link](-42); [Link](new Integer(200)); [Link](new Integer(0)); deviceConfigSpec[0].setDevice(cdrom); // Formulate the SCSI controller deviceConfigSpec[1].setOperation([Link]); VirtualLsiLogicController scsiCtrl = new VirtualLsiLogicController(); [Link](0); deviceConfigSpec[1].setDevice(scsiCtrl); [Link](-44); [Link]([Link]); // Formulate SCIS disk one deviceConfigSpec[2].setFileOperation([Link]); deviceConfigSpec[2].setOperation([Link]); VirtualDisk disk = new VirtualDisk(); VirtualDiskFlatVer2BackingInfo diskfileBacking = new VirtualDiskFlatVer2BackingInfo(); [Link](datastoreRef); [Link](volumeName); [Link]("persistent"); [Link](new Boolean(false)); [Link](new Boolean(false)); [Link](-1000000); [Link](new Integer(-44)); [Link](new Integer(0)); [Link](diskfileBacking); [Link](524288); deviceConfigSpec[2].setDevice(disk); // Formulate SCSI disk two

Copyright 2009 VMware, Inc. All rights reserved.

19

Designing Backup Solutions for VMware vSphere

deviceConfigSpec[3].setFileOperation([Link]); deviceConfigSpec[3].setOperation([Link]); VirtualDisk disk2 = new VirtualDisk(); VirtualDiskFlatVer2BackingInfo diskfileBacking2 = new VirtualDiskFlatVer2BackingInfo(); [Link](datastoreRef); [Link](volumeName); [Link]("persistent"); [Link](new Boolean(false)); [Link](new Boolean(false)); [Link](-100); [Link](new Integer(-44)); [Link](new Integer(1)); [Link](diskfileBacking2); [Link](131072); deviceConfigSpec[3].setDevice(disk2); // Finally, formulate the NIC deviceConfigSpec[4].setOperation([Link]); [Link] nic = new VirtualPCNet32(); VirtualEthernetCardNetworkBackingInfo nicBacking = new VirtualEthernetCardNetworkBackingInfo(); [Link](networkRef); [Link](networkName); [Link]("generated"); [Link](nicBacking); [Link](-48); deviceConfigSpec[4].setDevice(nic); // Now that it is all put together, create the virtual machine // Note that folderMo, hostMo, and resourcePool are MoRefs to the Folder, Host, and ResourcePool // where the VM is to be created ManagedObjectReference taskMoRef = [Link]().createVM_Task( folderMo, configSpec, resourcePool, hostMo);

Using VirtualMachineConfigInfo to Create a Virtual Machine

[Link] preservealloftheinformationinaVirtualMachineConfigInfothatdescribesthevirtualmachine,youcan transfermuchofthisinformationintoaVirtualMachineConfigSpecinordertocreateavirtualmachine. However,someoftheinformationinVirtualMachineConfigInfoisnotneeded,andifusedintheSpec, [Link],aVirtualMachineConfigSpecthatcontainsinformation [Link]:
[Link] [Link].VirtualPS2Controller [Link] [Link] [Link] [Link] [Link]

However,othercontrollersanddevicesmustbeexplicitlyincludedintheVirtualMachineConfigSpec. [Link] [Link],whichisanarrayofdevicesthatreporttothe [Link](negative)devicekey numberssuppliedasaguide. Therelationshipbetweencontrolleranddevicemustbepreservedusingnegativekeynumbersinthesame relationshipasinthehardwarearrayoftheVirtualMachineConfigInfo. [Link] containsthefieldcpuFeatureMask,[Link] convertedtoArrayUpdateSpecentriesthatcontaintheVirtualMachineCpuIdInfoSpecalongwithafield calledoperationthatmustcontainthevalueArrayUpdateOperation::add. TheVirtualMachineCpuIdInfoSpecalsocontainsaHostCpuIdInfothatyoucancopyfromthe cpuFeatureMaskarrayinVirtualMachineConfigInfo. EverythingelsecanbecopiedintactfromtheVirtualMachineConfigInfodata.

Copyright 2009 VMware, Inc. All rights reserved.

20

Designing Backup Solutions for VMware vSphere

Restoring the Data

AsinthesectionRestoringaVirtualDiskonpage 14,VixDiskLibfunctionsprovideinterfacesforwriting thedatatovirtualdisk,eitherlocallyorremotely.

Changed Block Tracking on Virtual Disks

OnhostsrunningESX4.0andlater,[Link] [Link],which takesthefollowingparameters:

_thisManagedObjectReferencetothevirtualmachine. snapshotManagedObjectReferencetoaSnapshotofthevirtualmachine. deviceKeyVirtualdiskforwhichtocomputethechanges. [Link] sector(s)examinedisreturnedinDiskChangeInfo. [Link] [Link] youextract(usingQueryChangedDiskAreas)fromthesnapshotsvirtualdisk. Whenyoubackupasnapshot,[Link] savedChangeId,itidentifiesthelasttimeyouperformedabackup,andtellsthechangedblocktracking [Link] savedChangeId,thenyoumustsaveabaseline(full)[Link] getthisbaselinebackup:(1)istodirectlysaveallofthevirtualdiskscontents,and(2)istoprovidethe specialChangeId*(star).ThestarChangeIdindicatesthatonlyactiveportionsofthevirtualdisk [Link](sparse)virtualdisksandfor ordinaryvirtualdisks,thisrepresentsasubstantialreductionintheamountofdatatobesaved.

[Link]*toidentifyallallocatedareasofvirtualdisk,ignoring unallocatedareas(ofsparsedisk),oritcouldbeachangeIdstringsavedatthetimeofsnapshotbackup. ItonlymakessensetousethespecialChangeId=*[Link] ChangeIddoesexist,thenQueryChangedDiskAreasreturnsthedisksectorsthatchangedsincethenew [Link]:

New Change ID change0 change1 Old Change ID none change0 Used for Query * change0 Result Allinusesectorsofthedisk. Allsectorsalteredsincechange0.

Enabling Changed Block Tracking

Thisfeatureisdisabledbydefault,[Link] querythevirtualmachineconfiguration,[Link] [Link] fieldcontainstheflagchangeTrackingSupported,[Link] be7orhighertosupportthis.Ifthevirtualmachineversionislowerthan7,upgradethevirtualhardware. Ifsupported,youenableChangedBlockTrackingusinganabbreviatedformofVirtualMachineConfigSpec, thenusetheReconfigVM_TaskmethodtoreconfigurethevirtualmachinewithChangedBlockTracking:
VirtualMachineConfigSpec configSpec = new VirtualMachineConfigSpec; [Link](new Boolean(true)); ManagedObjectReference taskMoRef = [Link]().ReconfigureVm_Task(targetVM_MoRef, configSpec);

Poweredonvirtualmachinesmustgothroughastununstuncycle(poweron,resumeaftersuspend,migrate, orsnapshotcreate/delete/revert)beforethereconfigurationtakeseffect.

Copyright 2009 VMware, Inc. All rights reserved.

21

Designing Backup Solutions for VMware vSphere

To enable Changed Block Tracking with the VMware vSphere Client: 1 2 3 4 5 SelectthevirtualmachineandensurethatSummary>VMVersionsays7forvirtualhardwareversion. IntheSummarytab,clickEditSettings>Options>Advanced>General. Intherightsideofthedialogbox,clickConfigurationParameters... Inthenewdialogbox,locatetherowfornamectkEnabled,andchangeitsvaluefromfalsetotrue. Seeaboveconcerningthestununstuncycle.

To enable Changed Block Tracking and back up with the VMware vSphere API: 1 2 3 4 5 6 [Link],activateChangedBlockTracking. [Link]. StartingfromthesnapshotsConfigInfo,workyourwaytotheBackingInfoofallvirtualdisksinthe [Link]. HoldontothechangeIDsanddoafullbackupofthesnapshot,sincethisisthefirsttimeforbackup. Deletethesnapshotwhenyourbackuphascompleted. Nexttimeyoubackupthisvirtualmachine,createasnapshotanduseQueryChangedDiskAreaswiththe changeIDsfromyourpreviousbackuptotakeadvantageofChangedBlockTracking.

Gathering Changed Block Information

AssociatedwithChangedBlockTrackingischangeId,anidentifierforversionsofchangedblockdata. Wheneveravirtualmachinesnapshotiscreated,associatedwiththatsnapshotisachangeIdthatfunctions [Link] purposeofcreatinganinitialvirtualdiskbackup,thechangeIdassociatedwiththatsnapshotcanbeusedto retrievechangesthathaveoccurredsincesnapshotcreation. ToobtainthechangeIdassociatedwithanydiskinasnapshot,youexaminethehardwarearrayfromthe [Link] enclosesaclassdescribingthebackingstorage(obtainedusinggetBacking)thatimplementsvirtualdisk. Ifbackingstorageisoneofthefollowingtypes,youcanusethegetChangeIdmethodtoobtainthechangeId:
[Link].FlatVer2BackingInfo [Link].SparseVer2BackingInfo [Link].RawDiskVer2BackingInfo

[Link] dataobjectcontainingadescriptionoftheareaofthediskcovered(startoffsetandlength),andanarrayof [Link] variousdiskareasthathavechanged. Forbestresults,whenusingQueryChangedDiskAreastogatherinformationaboutsnapshots,enablechange [Link] [Link] additionalbenefitofsavingdiskspacebecauseitallowsforthebackupofonlyinformationthathaschanged. Ifchangetrackingisnotenabled,itisunknownwhathaschanged,sotheentirevirtualmachinemustbe backedupeachtime,ratherthanonlybackingupchangeddata. Beawarethatentiredisksareallocated,andthereforearereturnedwhenQueryChangedDiskAreasisusedin thefollowingscenarios:

Aclonedthickdiskiscreated. DisksareformattedusingtheLongFormatsetting. Disksarecreatedwithvmkfstoolsusingtheeagerzeroedthickformatoption. AVMDKisstoredonstoragethatdoesnotsupportVMFS,suchasNFSoriSCSIdevices.

Copyright 2009 VMware, Inc. All rights reserved.

22

Designing Backup Solutions for VMware vSphere

Tofindchangeinformation,youcanusetheManagedObjectBrowserat[Link] content>hafolderroot>hadatacenter>datastore>vm>snapshot>config>hardware>virtualDisk. Changedblocktrackingisassociatedwiththesnapshot,notwiththebasedisk. Thefollowingcodesampleassumesthat,inthepast,youobtainedacompletecopyofthevirtualdisk,andat thetimewhenthechangeIdassociatedwiththesnapshotwascollected,youstoreditforuseatalatertime, [Link],andtheappropriateMoRefisavailable:

String changeId; // Already initialized ManagedObjectReference theSnapshot; ManagedObjectReference theVM; int diskDeviceKey; [Link] changes; long position = 0; do { changes = [Link](theSnapshot, diskDeviceKey, position, changeId); for (int i = 0; i < [Link]; i++) { long length = [Link][i].length; long offset = [Link][i].startOffset; // // Go get and save disk data here } position = [Link] + [Link]; } while (position < diskCapacity);

Intheabovecode,QueryChangedDiskAreasiscalledrepeatedly,aspositionmovesthroughthevirtualdisk. ThisisbecausethenumberofentriesintheChangedDiskAreaarraycouldendupoccupyingalargeamount ofmemoryfordescribingmanychangestoalargevirtualdisk. ThechangeId(changedblockID)containsasequencenumberintheform<UUID>/<nnn>.Ifthe<UUID> changes,itindicatesthattrackinginformationhasbecomeinvalid,[Link] incrementalbackupscancontinueintheusualpattern.

Troubleshooting
IfyoureconfigureavirtualmachinetosetchangeTrackingEnabled,butthepropertyremainsfalse,check thatyouhavequeriedthevirtualmachinestatuswithVirtualMachine->config()afterreconfiguration withVirtualMachine->reconfigure().Yes,[Link] ishardwareversion7andhasundergoneastununstuncyclesincereconfiguration.

Checking for Namespace

YoucanavoidusingthequeryChangedDiskAreasAPIonESX3.5/3.5i(andearlier)storagebyparsingXML [Link],seetheseSDKcodesamples:
Axis/java/com/vmware/samples/version/displaynewpropertieshost/[Link] Axis/java/com/vmware/samples/version/getvirtualdiskfiles/[Link] DotNet/cs/DisplayNewProperties/[Link] DotNet/cs/GetVirtualDiskFiles/[Link]

Limitations on Changed Block Tracking

ChangedBlockTrackingdoesnotworkinanyofthefollowingcases:

Virtualhardwareversionis6orearlier. ThevirtualdiskisaphysicalcompatibilityRDM. ThevirtualdiskisattachedtoasharedvirtualSCSIbus.

ChangedBlockTrackingcanbeenabledonvirtualmachinesthathavediskslikethese,butwhenqueriedfor theirchangeID,[Link] O/SdiskandapassthroughRDMasadatadiskyoucantrackchangesontheO/Sdiskonly.

Copyright 2009 VMware, Inc. All rights reserved.

23

Designing Backup Solutions for VMware vSphere

Incremental Restore of Backup Data

Atsomepointyoumightneedtorestoreavirtualdiskfromthebackupdatathatyougatheredasdescribed insectionChangedBlockTrackingonVirtualDisksonpage [Link]: 1 2 Poweroffthevirtualmachine,ifpoweredon. UsingtheVirtualMachineConfigInfothatcorrespondstothelastknowngoodstateoftheguest operatingsystem,recreatethevirtualmachineasdescribedinsectionUsingVirtualMachineConfigInfo toCreateaVirtualMachineonpage 20. Completelyreloadthebasevirtualdiskusingthefullbackupthatstartedthemostrecentseriesof incrementalbackups. Createasnapshot,asachildofthebasevirtualdisk. [Link] workforwards,[Link],youmust keeptrackofwhichsectorswererestoredsoastoavoidrestoringthemagainfromolderdata. GetthechangeIDofthebackupthisisbeingrestored,andusethechangetrackingAPIstofindtheareas [Link],becauseonceyoustartrestoringa virtualdisk,thechangetrackingmechanismwillfail. [Link] [Link](sparse)disk, usethestar*changeIDtoavoidwritingzeroestotheunallocatedblocks. RepeatStep 6andStep 7asnecessarybyapplyingincrementalbackupdatasetsinorder. Optionally,reverttothebasevirtualdisk,thuseliminatingthesnapshot.

3 4 5

8 9

Working with Microsoft Shadow Copy

MicrosoftShadowCopy,alsocalledVolumeSnapshotService(VSS),isaWindowsServerdatabackupfeature forcreatingconsistentpointintimecopiesofdata(calledshadowcopies). WhenVMwareToolsperformVSSquiescingwhilecreatingasnapshotinaWindowsguest,theygeneratea [Link](BCD)[Link] [Link] [Link]. YoucanaccessthisHTTPprotocoleitherthroughtheCopyDatastoreFile_TaskmethodinthevSphereAPI, orusingthevifscommandinthevCLI(inESX/ESXi4),formerlycalledtheRCLI. [Link] [Link] HTTPaccesswilldemandausernameandpassword,unlessthesessionwasrecentlyauthenticated. ForinformationaboutVSS,seetheMicrosoftTechNetarticle,[Link] informationaboutSecuritySupportProviderInterface(SSPI),seetheMSDNWebsite.

If you have comments about this documentation, submit your feedback to: docfeedback@[Link] VMware, Inc. 3401 Hillview Ave., Palo Alto, CA 94304 [Link] Copyright 2009 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 [Link] 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. Item: EN-000165-01 | Revised: 11/16/09

24

Designing Backup Solutions for VMware vSphere

Conclusion
ThistechnicalnoteintroducedtheVMwarevStorageAPIsforDataProtection,givinganoverviewofbackup [Link] underlyingconceptsandstepstotakeforimplementingapplicationstoprotectvirtualmachinedata.

Copyright 2009 VMware, Inc. All rights reserved.

25