S DK 40 Programming Guide

vSphere Web Services SDK Programming Guide
vSphere Web Services SDK 4.0
EN-000145-00
You can find the most up-to-date technical documentation on the VMware Web site at: http://www.vmware.com/support/ The VMware Web site also provides the latest product updates. If you have comments about this documentation, submit your feedback to: docfeedback@vmware.com
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 http://www.vmware.com/go/patents. 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 IntroductiontotheVirtualDatacenter 11
VirtualizationandVMwarevSphereComponents 11 SummaryofNewFeaturesforDevelopersUsingtheSDK 12 NewManagedEntities 13 SupportforPreviousAPIsinvSphere4.0 13 InteroperabilityofSDK2.5ClientsandvSphere4.0Servers 13 ClientLibrariesandExistingSDK2.5ClientApplications 14 ModifyingVISDK2.5basedClientApplicationstousevSphereAPI4.0Features 14
2 vSphereObjectModel 15
UsingtheVMwarevSphereClienttoExploretheObjectModel 15 UsingtheManagedObjectBrowsertoExploretheObjectModel 16 AccessingtheMOB 17 NavigatingtheObjectModelintheMOB 17 UnderstandingtheServiceContentDataObject 18 UnderstandingtheObjectModelasDataStructures 21 UnderstandingtheUnifiedModelingLanguageUsedinthisGuide 21 TheManagedObjectTypeasDataStructureandServiceInterface 22 ServiceInstanceManagedObjectasStartingPointtoOtherServiceInterfaces 23 ReferencestoManagedObjects 24
3 UnderstandingtheInventory 25
OverviewofManagedEntities 25 UnderstandingContainerObjectsandtheInventory 26 FolderasContainer 27 InventoryObjectsandPrivileges 28 FolderasFactory 30 vCenterServerandUnmanagedESX/ESXiHostInventories 30
4 OverviewofUserModelsandServerAccessControlConcepts 33
IntroductiontoAuthenticationandAuthorization 33 UnderstandingSystemPrivileges 34 PrivilegesDefinedinthevSphereAPIReference 34 HTTPBasedFileAccessandPrivileges 34 OverviewofESX/ESXiUserModel 35 UsingHostLocalAccountManagerManagedObject 35 OverviewofvCenterServerUserModel 36 EnablingSingleSignonSupportandIntegrationwithMicrosoftActiveDirectory 37 ObtainingInformationaboutUsersandGroupsfromUserDirectory 37 AuthenticatingUsersthroughSessionManager 39 OverviewoftheAuthorizationManager 39 UsingRolestoConsolidateSetsofPrivileges 40 ModifyingSampleRolestoCreateNewRoles 42
VMware, Inc.
GrantingPrivilegesthroughPermissions 42 ObtainingInformationaboutPermissions 43 Setting,Changing,orDeletingPermissions 43 ImpactofGroupMembershiponPermissions 44
5 vSphereAPIProgrammingModel 45
APIasaWebService 45 APIDefinedinWSDLFile 45 ClientApplicationCharacteristics 46 AsynchronousClientServerApplicationStyle 46 DistributedObjectOrientedApplicationStyle 46 ObtainingManagedObjectReferences 49 DoNotStoreManagedObjectReferenceValues 49 WorkingwithDataStructuresinClientApplicationCode 49 AccessingPropertyValues 49 AccessingtheAPIontheWebService 50 UsingthevSphereAPIReference 51 IdentifyingDeprecatedItemsinthevSphereAPIReference 51 IdentifyingVersionInformationinthevSphereAPIReference 51 MappingtheWSDLtotheClientsideProxyCode 51 ObtainingValuesfromNestedProperties 52 MappingXMLDatatypestoJavaandC#Datatypes 53 EscapeCharacterUsedinNameandPathProperties 53 InvokingOperationsthroughtheMOB 53 PassingPrimitiveDatatypestoOperationsthroughtheMOB 54 PassingArraysofPrimitivestoOperationsthroughtheMOB 54 PassingComplexStructurestoOperationsthroughtheMOB 54
6 ClientApplicationPattern 59
MinimalClientApplicationPattern 59 ConnectingtotheWebService 59 ObtainingaSessionTokenandCreatingaConnectionObject 59 LoggingIntotheServer 60 ClosetheServerConnection 60 OverviewofaJavaSampleApplication 61 SavingandReusingaWebServerSessionTokenorCookie 63 SupportingMultipleAPIVersions 63 IdentifyingtheAPIVersionSupportedbytheServer 64 HelperClassesforSampleApplications 64 JavaHelperClasses 65 C#HelperClasses 65
7 AutomatingClientApplicationLogin 67
IntroductiontotheCredentialStore 67 OverviewoftheCredentialStoreBackingFile 68 CredentialStoreBackingFileStructure 68 UsingSamplestoUnderstandtheCredentialStore 69 SecurityBestPracticesandtheCredentialStore 69 UsingthePrincipleofLeastPrivilegewiththeCredentialStore 69 UsingtheCredentialStoreAdminTool 70 UsingAuthorizationManagertoLimitAccess 70 CreatingNewUserAccounts 70 ApplyingPermissiontoanEntity 71
VMware, Inc.
Contents
8 ObtainingReferencestoObjectsandPropertyValuesfromtheServer 73
SampleCodeReference 73 IntroductiontothePropertyCollector 74 PropertyCollectorOperations 74 UnderstandingthePropertyFilterSpec 75 TraversalSpecDataObjectandRecursion 76 RetrievePropertiesOperation 76 CreateFilterandUpdateOperations 77 KeepingClientDatainSynchwithServerObjects 78 PropertyCollectorPerformance 79 ImprovingCollectionPerformancebyUsingtheViewManagerandView Objects 79 UsingtheSearchIndextoObtainManagedObjectReferences 80
9 OverviewoftheTaskInfrastructure 83
SampleCodeReference 83 UnderstandingTaskManagerandTaskManagedObjects 84 UnderstandingtheTaskInfoDataObject 85 MonitoringTaskInfoProperties 88 CancellingaTask 88 UsingtheTaskManagertoObtainInformationaboutTasks 88 ObtainingInformationaboutRecentTasksUsingaPropertyCollector 89 OperationsThatReturnTaskManagedObjects 90 IntroductiontotheEventDataObject 92
10 WorkingwithVirtualMachines 93
SampleCodeReference 93 CreatingVirtualMachines 93 OverviewofVirtualMachineOperations 94 OverviewofSnapshots 97 CreatingSnapshots 97 RevertingtoSnapshots 97
11 ManagingStorage 99
SampleCodeReference 99 OverviewofPhysicalandVirtualStorageConcepts 99 RequirementsforStorage 100 OverviewofInternetSCSIStorage 101 IntroductiontoManagedObjectsthatSupportStorage 101 IntroductiontotheHostStorageSystemManagedObject 102 IntroductiontotheHostDatastoreSystemManagedObject 106 ObtainingInformationaboutConfiguredStorage 107 CreatingNewDatastores 108 ModifyingDatastoreConfiguration 110
12 MonitoringPerformance 111
SampleCodeReference 111 IntroductiontoPerformanceManager 112 OverviewofCounterGroupsandthePerfCounterInfoDataObject SamplingPeriodsandIntervals 114 ObtainingStatistics 115 112
VMware, Inc.
vCenterServerandPerformanceManager 117 HistoricalIntervals 117 ModifyingHistoricalIntervals 117 OptimizingQueryResponseTime 118
13 UsingvCenterServerforVirtualMachineOperations 119
SampleCodeReference 120 OverviewoftheVirtualMachineManagedObjectType 120 UsingTemplatestoDeployStandardVirtualMachines 124 CreatingTemplates 124 RevertingaTemplatetoItsActiveVirtualMachineStatus 125 MigratingVirtualMachinesUsingVMotion 125 CheckingtheValidityofaMigrationInAdvance 126 UsingtheMigrateVM_TaskOperation 126 MovingStorageDynamicallyUsingStorageVMotion 127
14 EventandTaskManagementUsingvCenterServer 129
SampleCodeReference 129 UnderstandingEventManagerandtheEventDataObject 129 EventManagerManagedObject 130 EventDataObjects 130 FormattingEventMessageContent 131 CreatingCustomEvents 132 ObtainingInformationaboutEventsUsingaHistoryCollector 133 OverviewofHistoryCollectorManagedObjects 133 NewObjectsAppendedtoaHistoryCollector 135 DeletingaHistoryCollector 135
15 UsingtheAlarmInfrastructure 137
SampleCodeReference 137 OverviewofAlarmManagerandAlarmManagedObjects 137 ObtainingaListofAlarms 138 DefininganAlarm 138 OverviewoftheAlarmSpecDataObject 139 OverviewoftheAlarmExpressionDataObject 139 OverviewoftheAlarmActionDataObject 141 DeletingorDisablinganAlarm 142
16 SchedulingvCenterServerOperations 143
SampleCodeReference 143 ScheduledTaskManagerManagedObject 143 RetrievingScheduledTasksforaSpecificManagedEntity 144 CreatingaScheduledTaskObject 144 DefiningtheScheduleforthevCenterServerOperation 145 DefiningtheActions 146 SchedulingRecurringOperations 146 DeletingaScheduledTask 148
A ManagedObjectPrivilegesReference 149
PrivilegesRequiredtoInvokeOperations 149 PrivilegesRequiredtoReadProperties 156 PrivilegesDefinedfortheAdministratorRole 158
VMware, Inc.
Contents
B DiagnosticsandTroubleshooting 161
BestPracticesforTroubleshooting 161 OverviewofConfigurationFilesandLogFiles 162 ESXLogFile 163 VirtualMachineLogFiles 163 vCenterServerLogFiles 164 ModifyingtheLogLeveltoObtainDetailedInformation 164 LogLevelSettings 165 SettingtheLogLevelonESXSystems 165 GeneratingLogs 166 SettingtheLogLevelonvCenterServerSystem 167 UnderstandingandUsingtheDiagnosticManager 167 UsingtheMOBtoExploretheDiagnosticManager 169 GeneratingDiagnosticBundles 171
C DeployingClientApplications 173
UnderstandingtheClientApplicationDeploymentModel 173 CredentialStoreAdministrationToolforNonInteractiveClients 173 GuidelinesforUsingtheCredentialStoreAdminTool 173 CredentialStoreAdminToolandtheBackingFile 174
Index 177
VMware, Inc.
VMware, Inc.
About This Book
ThevSphereWebServicesSDKProgrammingGuide,providesinformationaboutdevelopingapplicationsusing theVMwarevSphereWebServicesSDK4.0. VMwareprovidesseveraldifferentAPIsandSDKsforvariousapplicationsandgoals.Thisbookprovides informationaboutusingthevSphereWebServicesSDKfordevelopersthatareinterestedincreatingclient applicationsformanagingVMwarevSpherecomponentsavailableonVMwareESX,VMwareESXi,and VMwarevCenterServersystems. ToviewthecurrentversionofthisbookaswellasallVMwareAPIandSDKdocumentation,goto http://www.vmware.com/support/pubs/sdk_pubs.html.
Revision History
Thisguideisrevisedwitheachreleaseoftheproductorwhennecessary.Arevisedversioncancontainminor ormajorchanges.Table 1summarizesthesignificantchangesineachversionofthisguide. Table 1. Revision History
Revision 20090507 Description FirstversionofthevSphereWebServicesSDK4.0ProgrammingGuide.
Intended Audience
ThisbookisintendedforanyonewhoneedstodevelopapplicationsusingtheVMwarevSphereWebServices SDK.vSphereWebServicesSDKdeveloperstypicallyincludesoftwaredeveloperscreatingclientapplications usingJavaorC#(intheMicrosoft.NETenvironment)targetingVMwarevSphere.
Document Feedback
VMwarewelcomesyoursuggestionsforimprovingourdocumentation.Sendyourfeedbackto docfeedback@vmware.com.
Technical Support and Education Resources

Thefollowingsectionsdescribethetechnicalsupportresourcesavailabletoyou.Toaccessthecurrentversions ofotherVMwarebooks,gotohttp://www.vmware.com/support/pubs.
Online and Telephone Support

Touseonlinesupporttosubmittechnicalsupportrequests,viewyourproductandcontractinformation,and registeryourproducts,gotohttp://www.vmware.com/support.
VMware, Inc.
Support Offerings
TofindouthowVMwaresupportofferingscanhelpmeetyourbusinessneeds,goto http://www.vmware.com/support/services.
VMware Professional Services

VMwareEducationServicescoursesofferextensivehandsonlabs,casestudyexamples,andcoursematerials designedtobeusedasonthejobreferencetools.Coursesareavailableonsite,intheclassroom,andlive online.Foronsitepilotprograms andimplementationbestpractices,VMwareConsultingServicesprovides offeringsto helpyouassess,plan,build,andmanageyourvirtualenvironment.Toaccessinformationabout educationclasses,certificationprograms,andconsultingservices,gotohttp://www.vmware.com/services.
10
VMware, Inc.
Introduction to the Virtual Datacenter
TheVMwarevSphereWebServicesSDKgivesWebservicesdevelopersprogrammaticaccesstothevirtual datacentercomponents.VMwarevSphereprovidesacompleteplatformtosupportrobust,faulttolerant virtualizedapplications,networking,storage,andallotherdatacenterresources. VirtualizationandVMwarevSphereComponentsonpage 11 SummaryofNewFeaturesforDevelopersUsingtheSDKonpage 12 SupportforPreviousAPIsinvSphere4.0onpage 13
Virtualization and VMware vSphere Components

VMwaresoftwareproductsvirtualizecomputingresources,includingCPU,memory,storage,andnetworks, forexample,sothatphysicalresourcescandeliveroptimalvalue.Figure 11showssomeofthekeyVMware vSphereinthecontextofphysicalcomponents,suchasenterpriseservers,networks,andstorage. Figure 1-1. VMware vSphere Components
Virtualizationprovidesanabstractionlayerbetweencomputingresources,physicalstorage,andnetworking hardware,andtheapplicationsthatusealloftheseresources.Forexample,virtualmemoryenablessoftware tousemorememorythanisphysicallyinstalledinacomputerbyswappingdatafromphysicalmemoryto physicaldisk.
VMware, Inc.
11
WithitsVMwarevSphereproductsuite,VMwarevirtualizesalllayersofanITinfrastructure,fromnetworks, storage,laptopanddesktopcomputers,toserverhardware,operatingsystems,andapplications. VMwarevSphereincludesESX/ESXi,vCenterServer,andseveraladditionalserverproductsfordistributed resourcemanagement(DRS),disasterrecovery,andhighavailability(HA)(Figure 11). ESX/ESXiprovidesthefoundationhypervisorcapableofsupportingmultiplevirtualmachinesandother virtualcomponents,suchasstorageandnetworks. vCenterServerisadatabasebackedWindowsservicethatprovidescentralmanagementformultiple ESX/ESXisystems. IfyouarenewtoVMwarevSphereornewtotheVMwarevSphereWebServicesSDK,seeoneoftheseguides formorebackgroundinformationaboutvSphere: IntroductiontoVMwarevSphere vSphereBasicSystemAdministration ESXConfigurationGuideandESXiConfigurationGuide vSphereResourceManagementGuide FormoreinformationaboutESX/ESXiandvCenterServer,seetheVMwarevSpheredocumentationpageon theVMwarewebsite.
Summary of New Features for Developers Using the SDK

ThissectionlistsjustsomeofthehighlightsofthevSphere4.0,withafocusonchangestotheAPIandthe objectmodel.Forallnewmanagedobject,dataobject,andothertypes,seethevSphereAPIReference. Rapid, Compliant Host Provisioning Using Profiles Configurehostsquicklyusingprofilesthatcomplywithspecificconfigurationpolicies.Severalnewmanaged objectsandassociateddataobjectssupportprovisioningnewhostsusingprofiles.Forexample,youcanusea newserviceinterface,theHostProfileManager,todefineconfigurationsandpolicies.Withprofiles,you configuresettingsfortheenvironmentonceandusetheprofiletoprovisionnewhosts.Useprofilesto configurenetworking,storagesettings,security,andothersettingsacrossanynumberofhosts. Distributed Virtual Switch VMwareDistributedVirtualSwitch(DVS)providesnextgenerationvirtualnetworkingmanagementthat spanstheentirevirtualinfrastructure.Italsoenablesyoutoquicklyincreasenetworkingcapacityandreduce ongoingnetworkmaintenancetasks,bysimplifyingmonitoringandtroubleshootingactivities. Inaddition,DVSsupportsthelatestinVMotiontechnology,soyoucanbuildcompleteVMotionaware networkingapplicationsontopofvSphere.NetworkVMotiontracksthenetworkingstateofavirtualmachine asitmigratesthroughoutthevirtualinfrastructure. SeethevSphereAPIReferenceforcompletedetailsaboutthenewmanagedobjecttypesthatsupportDVS, startingwiththeDistributedVirtualSwitchandDistributedVirtualSwitchManager. More Granular Permissions Model for Delegated Administration vCenterServernowsupportsamorediscretepermissionsmodelfordatastoresandnetworks.Theseentities canbegrantedpermissionsdistinctfromthedatacenter. Accesstoadatastoreornetworkcanbegrantedtoordeniedforaspecificsetofusersorgroups.Thisfeature issupportedintheobjectmodelbyelevatingtheDatastoreandNetworkmanagedobjectsinthehierarchy. TheseobjectsarenowdirectdescendentsoftheManagedEntitybaseclassandcansupportpermissions independentlyofDatacenter(Figure 12).
12
VMware, Inc.
Chapter 1 Introduction to the Virtual Datacenter
New Managed Entities

Manynewfeaturesareimplementedasoneormorenewmanagedobjects.Thoseavailablethroughthe inventoryasmanagedentitiesareshowninFigure 12. Figure 1-2. ManagedEntity and Its Descendents
TheVirtualApp,DistributedVirtualSwitch,andDistributedVirtualPortgrouparenewmanaged entitieswithmanyassociateddataobjects,faulttypes,andenumerationstosupportthem.SeethevSphereAPI Referencefordetails. Virtualized Application Services AVirtualizedApplicationService(VirtualApp)isacontainerforoneormorevirtualmachines.AVirtualApp allowsanapplicationtobemanagedasaunit,includingpoweroperations,cloneanddeployoperations, resourceallocation,andmonitoring.vCenterServersupportscreating,running,importing,andexporting virtualizedapplicationsasfilesusingtheindustrystandardOpenVirtualizationFormat(OVF)1.0.
Support for Previous APIs in vSphere 4.0

YoucanusetheVMwarevSphereWebServicesSDK4.0withallvSphereserverproducts,includingESX4, ESXi4,vCenterServer4,ESX3,ESXi3,ESXServer3.0.x,VirtualCenterServer2.5,VirtualCenterServer2.0.x. BothESX/ESXiandvCenterServerprovideanewversionoftheWebservicesbasedAPI,vSphereAPI4.0, whichisasupersetofallAPIsreleasedsinceVIAPI2.5. UnlikepriorreleasesoftheAPI,thevSphereAPI4.0hasnodependencyontheWSDLnamespaceattribute forversioninformation.TargetingmultipleversionsoftheAPIinpriorreleasesrequiredtheclientapplication toexaminetheWSDLfileontheserverandobtainthevalueofthenamespaceannotation. WithvSphereAPI4.0,allSOAPmessagesfromtheclienttotheserverincludetheversioninformationusing apreviouslyunusedattributeintheSOAPheader.Thesedetailsaretransparenttodevelopers. BecausetheversioningmodelhaschangedandnolongerdependsontheWSDLnamespaceattributeto identifytheversionoftheAPI,thenamespaceforvSphere4.0APIremainsurn:vim25.InthevSphereWeb ServicesSDK4.0,thetwosubdirectoriesfortheWSDLfilesareasfollows: vim25,whichistheWSDLforVIAPI2.5,andsubsequentreleases,includingvSphereAPI4.0 vim,whichistheWSDLforVIAPI2.0andpriorreleases
Interoperability of SDK 2.5 Clients and vSphere 4.0 Servers

AsVMwareevolvestheAPItosupportnewcapabilities,newparametersforexistingoperationsandnew propertiesforexistingdataobjectsarealwaysdefinedasoptionalsothatclientsthatweredevelopedwithone versionoftheAPIcancontinuetoworkwithnewreleasesofthevSphereInfrastructureserverproducts.The resultofthisapproachisthatclientapplicationsdevelopedusingtheVISDK2.5canworkunchangedwith ESX4.0,ESXi4.0,orvCenterServer4.0servers.However,modifyinganexistingVISDK2.5basedclienthas someimplications,detailedinModifyingVISDK2.5basedClientApplicationstousevSphereAPI4.0 Features.
VMware, Inc. 13
Client Libraries and Existing SDK 2.5 Client Applications

ClientapplicationsthatweredevelopedusingtheVISDK2.5canworkwithvSphere4.0serversaslongthe applicationscontinuetousetheclientlibrariesfromtheVISDK2.5package.DonotusethevSphere4.0client librarieswithclientapplicationsthatwerecreatedusingVISDK2.5. UsethelibrariesfromthevSphereSDK4.0withVISDK2.5basedapplicationsonlyifyouaremodifyingsuch anapplicationtousenewfeaturesinthevSphereAPI4.0.Inaddition,youmightneedtomodifysomeofyour existingcode,asdetailedinthenextsection.
Modifying VI SDK 2.5-based Client Applications to use vSphere API 4.0 Features
TomodifyanSDK2.5clientapplicationtoincorporatenewAPI4.0functionality,youmustusetheclient libraries(vim25.jar)fromtheVMwareWebServicesSDK4.0package. Inaddition,youmustcheckyourexistingcodeforoperationsanddataobjectsthatmightcontainnew parametersandpropertiesinvSphereAPI4.0.Manyofthedataobjectsavailableinpreviousversionsofthe APIhavenewpropertiesinvSphereAPI4.0.Forexample,theEventdataobjecthasseveralnewpropertiesto supportmanagedobjectreferencestonewmanagedentitiesassociatedwithanEvent,suchasthe DistributedVirtualSwitch. Inaddition,manyoperationshavenewparametersinthisrelease.Forexample,theoperationslistedin Table 11wereavailableinVIAPI2.5andhavenewparametersinvSphereAPI4.0. Table 1-1. Operations with New Parameters in vSphere API 4.0
Operation addHost_Task addStandaloneHost_Task createTask extendVirtualDisk_Task findByUuid Operation queryVmfsDatastoreExtendOptions relocateVM_Task revertToCurrentSnapshot_Task revertToSnapshot_Task updateInternetScsiAuthenticationProperties
IfyourexistingVISDK2.5basedclientapplicationusesanyoftheoperationslistedinthetable,youmust modifythecodetopassnullforthe4.0specificparameter,asshowninthecodesnippetinTable 12. Table 1-2. Example of Modified Code for New Parameter
Original Code ...revertToSnapshot_Task(snapmor,null) Modified Code ...revertToSnapshot_Task(snapmor,null,null)
SeethevSphereAPIReferenceforcompleteinformationabouttheseoperations.
14
VMware, Inc.
vSphere Object Model
AswithphysicalITinfrastructurecomponents,virtualinfrastructurecomponentsmustbeprovisioned, deployed,monitored,andmanaged.TheVMwarevSphereobjectmodelisacomprehensivesetofrobust serversidecompositeobjectsthatprovidesthecompletemanagementcapabilities. Theobjectmodelincludesserviceinterfacesformanaging,monitoring,configuring,obtaininginformation, andcontrollinglifecycleoperationsassociatedwithvirtualinfrastructure,andobjecttypesthatinstantiatethe virtualcomponentsontheserveratruntime. Externalclientapplicationsaccessthismanagementframework,theVMwarevSphereobjectmodel,through thevSphereAPI,whichisavailablethroughtheWebserviceonESX,ESXi,andvCenterServersystems.Client applications,boththirdpartyandVMwareclientapplicationssuchasVMwarevSphereClient,usethe vSphereAPItoperformalllifecycle,management,andmonitoringoperations. UnderstandingthevSpheremanagementobjectmodeliskeytousingtheVMwarevSphereAPIforsuccessful clientapplicationdevelopmentandintegration.Thechapterincludesthesetopics: UsingtheVMwarevSphereClienttoExploretheObjectModelonpage 15 UsingtheManagedObjectBrowsertoExploretheObjectModelonpage 16 UnderstandingtheObjectModelasDataStructuresonpage 21
Using the VMware vSphere Client to Explore the Object Model

TheVMwarevSphereClientisagraphicaluserinterfacetoolthatconnectstovCenterServerandESX/ESXi systemsforadministeringandmanagingvirtualinfrastructurecomponents.DeveloperscanusethevSphere Clientasatoolforexploringtheobjectmodel. ThevSphereClientrendersvirtualcomponentsasahierarchicaltreeintheleftpaneofthedisplay(Figure 22). WhenconnectedtoavCenterServer,thevSphereClientdisplaysalltheoptionsavailabletotheVMware vSphereenvironment,basedontheconfiguredlicensingandthepermissionsoftheuser.Whenconnectedto anESX/ESXihost,thevSphereClientdisplaysoptionsappropriateforsinglehostmanagement. ThevSphereClientlayoutisasinglewindowwithamenubar,anavigationbar,atoolbar,astatusbar,anda panelsection.Theleftpaneshowstheinventoryofobjectsontheserver(vCenterServer,ESX,orESXi). SeeManagingthevSphereClientInventoryUnderstandingvSphereClientObjectsintheVMwarevSphereonline libraryformoreinformationabouthowthevSphereClientgraphicallydepictsserversideobjects. TheVMwarevSpheremanagementframeworkusestheconceptofaninventorytokeeptrackofvirtual infrastructureassets,includingdatacenters,hosts,virtualmachines,storage,networkswitches,andsoon. A VMwarevSphereserverinventoryincludesbothcontainerobjects,suchasfolders,andnoncontainer objects,suchasvirtualmachines.SeeUnderstandingtheInventoryonpage 25formoreinformation. TherootFolderobjectandthedefaultDatacenterobjectarenotdisplayedinthevSphereClient(Figure 21), butthesedoexist.YoucanseethemintheManagedObjectBrowser,forexample.EveryServiceInstance hasarootFolderpropertyconsistingoftherootFolderobject,whichhasareferencetothedefault Datacenter.
VMware, Inc. 15
Figure 2-1. vSphere Client Connected to an ESX/ESXi System
Figure 21andFigure 22highlightsomeofthedifferencesbetweenvCenterServerandESX/ESXi.Figure 21 showshowtheinventoryofanESX/ESXisystemdisplays,intheleftpane. Intermsofmanagementservices,vCenterServerprovidesadditionalservicecapabilitiesandadministrative functions.Forexample,vCenterServersupportsScheduledTasks,Events,andMaps(notetheseiconsinthe menubarofFigure 22),whileESXorESXidoesnot(seethemenubaroftheESXinstanceshownin Figure 22). Figure 2-2. vSphere Client Connected to a vCenter Server System
TheinventoryasdisplayedinthevSphereClientisrenderedfromthecontentoftheserversideobjectsatany givenpointintime.TheinventoryshowninFigure 22andFigure 21consistsofasingledatacenterwiththree differentvirtualmachines.Thesesameobjectsandservicescanbeseen,renderedasHTMLpages,inthe ManagedObjectBrowser.TheManagedObjectBrowserprovidesalowerlevelviewoftheactualserverside objectsthatmakeupthecomponentsthatdisplayinthevSphereClient.
Using the Managed Object Browser to Explore the Object Model

TheManagedObjectBrowser,orMOB,isawebbasedserverapplicationavailableonallESX/ESXiand vCenterServersystems.UsetheMOBtolookattheobjectsthatexistontheserverandnavigatethroughthe hierarchyofinstantiatedobjectsbyclickingonhyperlinksthatarepopulatedwithactualruntimeinformation. Youcanviewthenamesofproperties,forexample. CAUTIONDespitethewordbrowserinitsname,theMOBisnotareadonlymechanism.TheMOBisa powerfultoolthatcanbeusedtomakechangestotheserver,byclickingtheInvokeMethodlinkassociated withmethodsavailableonanymanagedobjectpage.WheneveryouexploreaVMwarevSphereserverusing theMOB,beawareofitscapabilitiessothatyoudontmakeunintendedchangestotheserver.
16
VMware, Inc.
Chapter 2 vSphere Object Model
Accessing the MOB

TheMOBrunsinawebbrowserandisaccessedbyusingthefullyqualifieddomainnameorIPaddressfor theESX/ESXiorvCenterServer. To access the managed object browser (MOB) 1 2 LaunchaWebbrowser,suchasFirefoxorInternetExplorer. Enterthefullyqualifieddomainname(ortheIPaddress)fortheESX/ESXihostorvCenterServersystem:
https://<hostname.yourcompany.com>/mob
Youllbenotifiedthattheobjectbrowserrequiresausernameandpassword,withapromptrequiringa usernameandpassword. 3 Entertheuseraccountandpasswordfortheserversystem.Typically,thisisroot/<password>forthe ESX/ESXisystem,andAdministrator/<password>forvCenterServersystem. SomepreliminarywarningmessagesregardingtheauthorityoftheSSLcertificate,suchasWebsite Certified by an Unknown Authoritymightdisplayassumingthatthedefaultservercertificate providedbyVMwarehasnotbeenreplaced.Thespecificmessagetextvariesbywebbrowser. DisregardsuchwarningsandcontinuetologintotheMOB,aslongasVMwareisthecertificateauthority. IMPORTANTIftheESX/ESXiorvCenterServersystemhasbeenconfiguredtosupportregularHTTP (nonSSL)connections,apromptforusernameandpassworddoesnotdisplay,nordoany SSLcertificaterelatedwarnings. UnlikewiththevSphereClient,theMOBrevealstheunderlyingstructuresoftheVMwarevSphere managementobjectmodel,whichcanbeveryusefultodeveloperstryingtounderstandtheobjectmodel. UsedinconjunctionwiththevSphereAPIReference,theMOBcanhelpyougainafairlycomplete understandingofthemodel.
Navigating the Object Model in the MOB

UponsuccessfulconnectiontotheMOB,thebrowserdisplaysthemanagedobjectreferencefortheservice instance(Figure 23).Clientapplicationsdonotusemanagedobjectsdirectly.Rather,clientapplications interactwithserversidemanagedobjectsbyreference,usinginstancesoftheManagedObjectReferencedata object,thedatastructurecreatedforthispurpose.Invokingoperationsontheservertypicallyrequiresoneor morereferencestoamanagedobject. Forexample,thetitleofthepageshowninFigure 23identifiestheobjectasamanagedobjectreferencetothe ServiceInstance.ThepagealsoliststhepropertiesandmethodsavailablethroughServiceInstance. Figure 2-3. Managed Object Browser Connected to a vCenter Server System
VMware, Inc.
17
AlthoughServiceInstancehasonlyafewmethodsandproperties(Table 21),theseultimatelyprovide accesstotheentiresetofservicesandinventoryobjectsavailableontheserver. ClientapplicationsmustalwaysobtainareferencetotheserversServiceInstanceobjectfromthe appropriateVMwarevSphere(ESX,ESXi,orvCenterServer)target. Table 2-1. ServiceInstance Properties

Property capability Datatype Capabilitydataobject Description AninstanceofaCapabilitydataobject.ACapabilitydataobject consistsofseveralflagsthatindicatesupportorlackofsupportfor featuresontheserverinstance.Forexample,multiHostSupported capabilityistrueforvCenterServerbutfalseforESX.A provisioningSupportedflagthatreturnstrueenablesactions,such ascloningavirtualmachine.Somecapabilitiesareversionspecific. AninstanceofaServiceContentdataobject.AServiceContentdata objectcontainsreferences(managedobjectreferences)toalltheservice interfacesavailabletothespecificServiceInstance,suchasthe sessionmanager(sessionManagerproperty)andtherootfolderofthe inventory(rootFolderproperty). Serverdateandtime.
content
ServiceContentdataobject
serverClock
xsd:dateTime
YoucanusetheMOBtodirectlyexaminetherelationshipsamongobjectsbylookingatthepropertiesandtheir valuesandthenclickingthelink,ifoneisavailable,inthevaluecolumnofthepage.Forexample,tofindout moreaboutServiceContent,clickonthecontentlinktodisplaytheServiceContentdataobjectinstance (Figure 24). FromtheServiceContentpage,youcanclickonthelinksintheValuecolumntodisplaythecontentsofthe associatedobjects.Forexample,clickontheaboutlinktodisplaythecurrentvalueoftheaboutproperty, whichdisplaysthecontentoftheAboutInfodataobjectforthisserver.However,mostobjectscontainmany otherobjectsandnestedobjects. AccesstotheinventorybeginsfromtherootFolderpropertyofServiceContent.(Theinventoryiscovered inmoredetailinChapter 3,UnderstandingtheInventory,onpage 25.)
Understanding the ServiceContent Data Object

Insimpleterms,ServiceContentisalargegrainedserverobjectthatprovidesaccesstotheserviceinterfaces andtheinventorysupportedbytheserver.ServiceContentisadataobjectwhosepropertiesincludemany managedobjectreferences(instancesofManagedObjectReference)thatpointtospecificinstancesof managedobjects(Figure 24). Forexample,therootFolderpropertyisaManagedObjectReferencetoaninstanceofaFoldermanaged object.TheperfManagerisaManagedObjectReferencetoaspecificinstanceofaPerformanceManager managedobject,andsoon.
18
VMware, Inc.
Figure 24showsapartialServiceContentdataobjectdisplayedintheMOBofavCenterServer4.0system. Figure 2-4. ServiceContent Data Object Contains References to Instances of Managed Objects
Table 22summarizestheServiceContentpropertynamesandvaluesforanexampleESXandvCenter Serversystem,sidebyside,asdisplayedintheMOB.TheexamplevalueslistedinTable 22aretheinstance namesfortheobjects.ThepropertiesthatdisplayanUnsetvalueindicatethatthemanagedobjecttypeisnot availableontheserver. Forexample,thepropertyforaccountManagerwhichhasareferencetoasingleton HostLocalAccountManagerobjectonESXsystemshasnovalueonvCenterServersystems,becausevCenter ServerusesWindowsuseraccountmanagementfacilities(suchasActiveDirectory). Conversely,thepropertyforalarmManageronESXisunset,becausealarmsarenotsupportedonan unmanagedhost.TheAlarminfrastructureismanagedbyvCenterServer.Manyothermanagedobjecttypes requirevCenterServer,includingthese: ClusterProfileManager DistributedVirtualSwitchManager ExtensionManager HostProfileManager HostSnmpSystem IpPoolManager LocalizationManager OvfManager ProfileComplianceManager ScheduledTaskManager VirtualMachineCompatibilityChecker VirtualMachineProvisioningChecker
VMware, Inc.
19
Table 2-2. ServiceContent Property Names, Return Types, and Values

Example values Property name about accountManager alarmManager authorizationManager clusterProfileManager complianceManager customFieldsManager customizationSpecManager diagnosticManager dvSwitchManager Type AboutInfo ManagedObjectReference: HostLocalAccountManager ManagedObjectReference: AlarmManager ManagedObjectReference: AuthorizationManager ManagedObjectReference: ClusterProfileManager ManagedObjectReference: ProfileComplianceManager ManagedObjectReference: CustomFieldsManager ManagedObjectReference: CustomizationSpecManager ManagedObjectReference: DiagnosticManager ManagedObjectReference: DistributedVirtualSwitchMa nager ManagedObjectReference: EventManager ManagedObjectReference: ExtensionManager ManagedObjectReference: FileManager ManagedObjectReference: HostProfileManager ManagedObjectReference: IpPoolManager ManagedObjectReference: LicenseManager ManagedObjectReference: LocalizationManager ManagedObjectReference: OvfManager ManagedObjectReference: PerformanceManager ManagedObjectReference: PropertyCollector ManagedObjectReference: Folder ManagedObjectReference: ScheduledTaskManager ManagedObjectReference: SearchIndex ManagedObjectReference: SessionManager ESX about halocalacctmgr Unset haauthmgr Unset Unset Unset Unset hadiagnosticmgr Unset vCenter Server about Unset AlarmManager AuthorizationManager ClusterProfileManager MoComplianceManager CustomFieldsManager CustomizationSpecManager DiagMgr DVSManager
eventManager extensionManager fileManager hostProfileManager ipPoolManager licenseManager localizationManager ovfManager perfManager propertyCollector rootFolder scheduledTaskManager searchIndex sessionManager
haeventmgr Unset hanfcfilemanager Unset Unset halicensemanager Unset Unset haperfmgr hapropertycollector hafolderroot Unset hasearchindex hasessionmgr
EventManager ExtensionManager FileManager HostProfileManager IpPoolManager LicenseManager LocalizationManager OvfManager PerfMgr propertyCollector groupd1 ScheduledTaskManager SearchIndex SessionManager
20
VMware, Inc.
Table 2-2. ServiceContent Property Names, Return Types, and Values (Continued)
Example values Property name setting snmpSystem taskManager userDirectory viewManager virtualDiskManager vmCompatibilityChecker Type ManagedObjectReference: OptionManager ManagedObjectReference: HostSnmpSystem ManagedObjectReference: TaskManager ManagedObjectReference: UserDirectory ManagedObjectReference: ViewManager ManagedObjectReference: VirtualDiskManager ManagedObjectReference: VirtualMachineCompatibilit yChecker ManagedObjectReference: VirtualMachineProvisioning Checker ESX HostAgentSettings Unset hataskmgr hauserdirectory ViewManager havdiskmanager Unset vCenter Server VpxSettings SnmpSystem TaskManager UserDirectory ViewManager VirtualDiskManager CompatChecker
vmProvisioningChecker
Unset
ProvChecker
Understanding the Object Model as Data Structures

ThevSphereobjectmodelcanalsobeviewedfromadatastructuresperspective.TheVMwarevSphere managementobjectmodelcomprisestwobroadcategoriesofdatastructures: Managedobjecttypes.Amanagedobjecttypeisadatastructurethatcontainsbothpropertiesand operations.Theoperationssupportspecific,expectedbehaviorsthatadheretoacontract.Forexample,a VirtualMachinemanagedobjecttypesupportsvirtualmachinepoweroffandpoweron,recordingall virtualmachineoperations,andmanyoperationsthatcontroltheguestoperatingsystemrunningona virtualmachine,suchasrebootingtheguest.Thesearejustsomeexamples:theVirtualMachine managedobjecttypeprovidescloseto50operations.SeeChapter 10,WorkingwithVirtualMachines, onpage 93andChapter 13,UsingvCenterServerforVirtualMachineOperations,onpage 119. Dataobjecttypes.Adataobjectisadatastructurethatcontainspropertiesonly.Instancesofdataobjects donotprovideanyoperations.Dataobjectsareanalogoustostructures(struct)inC,C++,andseveral otherprogramminglanguages,orabstractdatatypes(classdefinition)inJava.Javadoesnotusethe conceptofastruct,butratherusesclassdeclarationstodefineabstractdatatypes. Thepropertiesofthemanagedobjecttypesaredefinedasprimitivedatatypes,suchasstringorint,oras specifictypesofdataobjects.Likewise,propertiesofdataobjectsaredefinedasprimitivevaluesorasspecific instancesofotherdataobjects. NOTEAlthoughmanymanagedobjecttypeshavewordslikesystemormanagerintheirnames,somedata objecttypesdoaswell.Forexample,theHostConfigManagerisadataobjecttype.AlwayscheckthevSphere APIReferencefordetailsaboutdataobjectandmanagedobjecttypes.
Understanding the Unified Modeling Language Used in this Guide

Figure 25showstheunifiedmodelinglanguage(UML)notationusedtodepictthetwoprimarytypesofdata structuresrepresentedinthisguide:managedobjecttypes,anddataobjecttypes.Thediagramsuseatildeto denoteabsenceofanypropertiesormethods(operations).Ellipsesareusedtodenoteadditionalcontent deliberatelynotshown.
VMware, Inc.
21
Figure 2-5. Legend for UML Class Diagrams
NOTEThefiguresshowninthisguidehighlightvariouscharacteristicsoftheobjectmodelusingUML diagrams.Forthesakeofsimplicity,thesediagramsdonotincludecompletedetails.Forexample,alldata objecttypesextendtheDynamicDatadataobject.However,thebasepropertiesofDynamicDataarerarely relevantforthetopic,sothatobjectrelationshipistypicallynotshown. Inadditiontoclassdiagrams,thisguidealsoincludesseveralinstancediagrams,especiallyinthosesections thatdiscussnavigatingtheinventory,whichisbestexplainedinthecontextofactualobjectinstances.Many detailsareleftoutoftheinstancediagramsaswell. Thisguideusesthesetermsandabbreviationsinfiguresandtext. MOR.Managedobjectreference.Anopaquedataobjectthatisusedasaremotereferencetomanaged objects.Managedobjectreferencesarealsocalledreferencesintext,andmo_reforMoRefincodesamples. MOR>ManagedObjectType.Amanagedobjectreferenceidentifiesaspecificinstanceofaspecifictypeof managedobject,onaVMwarevSphereserver.TheabbreviationMOR>ManagedObjectspecifiesthetype ofmanagedobjectinstancetowhichagivenMORrefers.Thisnotationisusedthroughoutthisguideto replacethewordstoa,asinMORtoaVirtualMachine,orMORtoaHostDatastoreSystem.
The Managed Object Type as Data Structure and Service Interface

Amanagedobjecttypeisacoredatastructureoftheserversideobjectmodel.Itisanyoneofabout60 serversidedatastructureshavingpropertiesandoperationsavailableontheserver.Differentmanaged objectsofferdifferentoperations.AnoperationisWebservicesterminologyforwhatmightbecalledamethod inanotherprogramminglanguage,suchasJava.Thewordsmethodandoperationareusedinterchangeably inthedocumentation. Instancesofmanagedobjecttypesareoftenreferredtogenericallyasmanagedobjectsthroughoutthis guide.However,managedobjectsincludethefollowingbroadcategories: ManagedobjectsthatextendtheManagedEntitymanagedobjecttype.Thesemanagedobjecttypesare referredtogenericallyasmanagedentities.Managedentitiesmakeuptheinventoryofvirtual components.Forexample,instancesofhostsystems(HostSystem),virtualmachines(VirtualMachine), anddatastores(Datastore)areinventoriedobjectsandextendthemanagedentity(ManagedEntity) type.InventoriedobjectsdisplayintheleftpaneofthevSphereClient. ManagedobjectsthatcomprisetheinterfacetoavSpheremanagementservice.Forexample, PerformanceManagerprovidestheinterfaceformonitoringsystemperformance. DistributedVirtualSwitchManagerprovidestheinterfaceformanaging DistributedVirtualSwitchmanagedobjects.AlarmManageristheserviceinterfaceforsettingalarms torespondtovariouseventsorstatechangesonspecificmanagedentities. Managedobjectswhoselifecycledependsuponorexistssolelyinthecontextofanothermanagedobject typeorserviceinterface.Forexample,instancesofTaskmanagedobjectsarereturnedbymethod invocationsonmostallmanagedobjectsinthesystem.PropertyFilterisamanagedobjecttype associatedwithaninstanceofPropertyCollector.HostNetworkSystemmanagedobjectsare associatedwithspecificinstancesofHostSystemmanagedobjects.Thesearejustafewexamples.
22
VMware, Inc.
ServiceInstance Managed Object as Starting Point to Other Service Interfaces

ThechiefmanagedobjectintheserviceinterfacecategoryisServiceInstance,whichistheentrypointfor allotherserviceinterfacesandinventoryobjects.Allinteractionwiththeserverbeginsthrough ServiceInstance.AServiceInstancehasonlyafewpropertiesandmethods.Thecontentpropertyis definedasaninstanceofServiceContent,whichisadataobjectcontainingreferencestoallavailableservice interfacesontheserverinstance. Figure 26highlightstherelationshipbetweenServiceInstanceandServiceContent,andtherelationship betweenServiceContentandsomeofthemanagedobjectreferences(MOR)tomanagementservices.Some services,suchasAlarmManager,aresupportedonvCenterServeronly,notonunmanagedhosts.Other services,suchasHostLocalAccountManager,aresupportedonESXorESXisystemsonly,notonvCenter Server.Figure 26isnottheentiresetofservicesavailable.VMwarevSphereAPI4.0providesaccesstoalmost 60managementservices. Figure 2-6. Simplified UML of ServiceInstance Managed Object and ServiceContent Data Object
Figure 27showsamoredetailedUMLdiagramofServiceInstanceandServiceContent. ServiceContent,Capability,andAboutInfoarealldataobjects,denotedbythetildeinsectionoftheclass definitionwhereoperations(methods)aredepictedformanagedobjects.
VMware, Inc.
23
Figure 2-7. The ServiceInstance Managed Object Type and Some of Its Properties
References to Managed Objects

Theclientapplicationdevelopmentmodelinvolvesworkingdirectlywithdataobjectsonly.Managedobjects areneverpassedbetweenserverandclient.Clientapplicationsusereferencestothemanagedobject,orwith thedataobjectsthatcomprisethevariouspropertiesofthemanagedobject.Somereferencescanbeobtained throughthepropertiesoftheServiceContentdataobject. Thereferenceisaninstanceofaspecificdataobjecttype,theManagedObjectReference.Instancesofthis dataobjecttypefacilitateremoteinvocationofoperationsonthemanagedobjectslocatedontheserver. InstancesofManagedObjectReferencedataobjectsaresentbetweenclientandserver. Tocreateaninstanceofaspecificmanagedentity,youmustpopulateoneormoredataobjectsandpassthe dataobjectstotheserverwiththeappropriatereference(ManagedObjectReference)toinvoketheoperation ontheserver. NOTEThroughoutthisguide,managedobjectreferencesarereferredtoasreferences.Codesamplesmight useMoRef,mo_ref,orMORasavariablenameforspecificinstancesoftheManagedObjectReferencedata object.Intext,amanagedobjectreferenceorreferencemeansaspecificinstanceofthe ManagedObjectReferencedataobjecttype.
24
VMware, Inc.
Understanding the Inventory
ThevSphereinventorycontainsvirtualassets,includingdatacenters,hosts,virtualmachines,virtual applications,storage,networks,andsoon.AdministratorscanviewtheinventoryusingthevSphereClient. ThevSphereClientobtainsinformationaboutalltheobjectsintheinventoryofaserverandrendersthe informationintheGUI. Developerswhowanttocreateclientapplicationsmustunderstandthecomponentsthatmakeupthe inventory.Youmustunderstandtherelationshipofoneobjecttoanotherintheinventory,withrespecttothe theparentchildrelationshipsamonginventoryobjectsandthepermissionsmodel,amongotherdetails. This chaptercoversthebasics.Itincludesthesetopics: OverviewofManagedEntitiesonpage 25 UnderstandingContainerObjectsandtheInventoryonpage 26 InventoryObjectsandPrivilegesonpage 28 vCenterServerandUnmanagedESX/ESXiHostInventoriesonpage 30
Overview of Managed Entities

IntermsofthevSphereobjectmodel,thecomponentsthatmakeupaninventorybelongtotheclassofobjects generallycalledmanagedentities.Amanagedentityisanyofthedozenmanagedobjecttypesthatextend directlyorindirectlyfromtheManagedEntitymanagedobjecttype.Managedentitiesinclude VirtualMachine,Datacenter,Datastore,Network,ResourcePool,ComputeResource,HostSystem, VirtualAppandtheothermanagedobjecttypesshowninFigure 31. Figure 3-1. ManagedEntity and ManagedEntity Subtypes
TheManagedEntitymanagedobjecttypeisanabstracttype.Itincludesseveralpropertiesandoperationsthat areinheritedbyeachsubtype.
VMware, Inc.
25
Forexample,thename,effectiveRole,permission,andparentaresomeofthepropertiesdefinedinthe ManagedEntitybasetypethatareinheritedbyeachsubtype.Lifecycleoperationsfortheobject,suchas destroyinganobjectinstance,arealsopartoftheManagedEntitybasetype. Figure 3-2. Datacenter and Folder Managed Object Types Extend ManagedEntity
InadditiontothepropertiesandoperationsinheritedfromManagedEntity,eachsubtypehasitsown propertiesandspecialpurposeoperationsthatmodelitsexpectedbehavior.Forexample,aHostSystem managedobjecthasanEnterMaintenanceMode_Taskoperation.Theothermanagedentitiesdonot. Instancesofspecificmanagedentitiesarecreatedbyadministratorsusingvarioustools,includingvSphere Client.Somemanagedentitiesarecreatedwhentheserversoftwareisfirstinstalled.Forexample,a HostSystemmanagedentityexistsintheinventoryofanewlyinstalledESX/ESXisystem.Itisnotexplicitly created.TheHostSystemmanagedentitycontainsthephysicalcharacteristicsofanESX/ESXihostsystem. ThedataobjectsthatmakeupthepropertiesofaHostSystemmanagedentitycontainthespecificproperties oftheunderlyinghardwareanditscapabilities.Forexample,thevaluesofthecapabilitypropertyof HostSystemaresetduringinstallation,basedonthespecificsofthehardwareonwhichESX/ESXiisinstalled. AllotherentitiesinaninventoryareexplicitlycreatedusingthevSphereClientorotherclienttools,orby usingtheAPI.Theentitiesthatcancompriseanyspecificinventoryareconstrainedbythephysicalresources ofthehardwareandtherulesofcontainment,ownership,andotherpropertiesofthemanagedentitytypes andsubtypes.
Understanding Container Objects and the Inventory

ThevSphereobjectmodelincludesseveralobjectsthatservespecificpurposes,includinginventory organization,applicationpackaging,delegatedadministration,andresourceallocation.Someobjectsareused toorganizetheinventoryandestablishassociationsamongtheentitiesintheinventory.Forexample,Folder, Datacenter,andVirtualApparegenerallycalledcontainerobjecttypes. VirtualAppisanewmanagedentitytypeinvSphereAPI4.0designedforapplicationpackaging. VirtualAppextendstheResourcePooltypewithadditionalpropertiesandoperationstosupportproduct andvendornaming,licensing,powercyclingtheapplication,andimportexportcapabilities.VirtualApp instancesareexportedandimportedtheindustrystandardOVF(openvirtualformat)files.AVirtualApp consistsofthevirtualmachinesandotherVirtualAppcontainersthatoperateasaunit.UnmanagedESX/ESXi hostsystemsdonotsupportVirtualApp. SeethevSphereAPIReferenceformoreinformationaboutVirtualApp.
26
VMware, Inc.
Chapter 3 Understanding the Inventory
Folder as Container
TheFoldermanagedobjecttypeisthechiefcontainerobjectinaninventory.Containmentisconceptual,not literal,andreliesontheparentchildrelationshipamongtheobjectsasdefinedincertainpropertiesofactual instances.Specifically,everymanagedentityhasaparentpropertythatcanbeusedtoidentifyitsrelative positionintheinventoryhierarchy.Inaddition,theFoldermanagedobjecttypehasachildEntityproperty thatidentifiesobjectscontainedbythespecificfolderinstance. Figure 33showsaninstancediagramhighlightingthechildEntityandfolderpropertiesthatdefinethe defaultobjectsintheinventoryofanunmanagedESX/ESXisystem.Theinventorybeginsfromthe rootFolderpropertyoftheServiceContentdataobject.TherootFolderistherootnodeoftheinventory. IthasachildEntitythatconsistsofamanagedobjectreferencetoaDatacentermanagedobject. Figure 3-3. Instance Diagram of Root Folders in an Inventory
ChildentitiesareidentifiedthroughtheirchildEntityproperty,throughaparentproperty,orthrougha specificfolderreferenceinthecontainingobject. Figure 3-4. Parent-Child Associations Among Inventory Objects
VMware, Inc.
27
Forexample,everyDatacenterobjectinaninventoryisguaranteedtohavefourspecificFolderobjects associatedwithit,oneeachfordatastores,networks,hosts,andvirtualmachines.ThefoldersforDatastore objectsandNetworkobjectsarenewasofvSphereAPI4.0.Thesefoldersareassociatedwiththe datastoreFolderandthenetworkFolderpropertiesofaDatacentermanagedobject(seealsoFigure 32 onpage 26). TheinventoryhierarchyshowninFigure 34,ParentChildAssociationsAmongInventoryObjects,on page 27includestherootfolderobject,aFolderobjectnamedha-root-folderhasachildEntitythatisa referencetoaDatacenter.TheVirtualMachineinstancewhoseIDis32isthechildEntityoftheFolder identifiedasha-folder-vm. Variousothernodesinthehierarchyarecalledrootnodesfortheirtypeofobject.Forexample,the ha-folder-datastore,ha-folder-host,ha-folder-network,andha-folder-vmareconsideredtheroot foldersforthetypeofentitiesthateachcontains.
Inventory Objects and Privileges

WhetherthroughthevSphereClientorbyusingtheAPI,navigatingtheentitiesintheinventoryrequiresa useraccountthatcanconnecttotheserverandobtainavalidsession.Theuseridentityassociatedwiththe sessioniscalledaprincipal.Whenaclientapplicationattemptstoaccessobjectsinaninventory,itdoesso usingtheprivilegesgrantedtoaspecificrolethatisassociatedwiththeprincipal.Theserverchecksthe permissionobjectorobjectsassociatedwiththeentitybeforeallowingaprincipaltovieworoperateonan entity. SeeChapter 4,OverviewofUserModelsandServerAccessControlConcepts,onpage 33formore informationaboutauthentication,authorization,roles,anduseridentity. Forinventorynavigation,itisimportanttounderstandtheaffectofparentchildrelationshipsamong inventoryentitiesandhowprivilegerequirementsmightapplytotheobject. Toviewcertainpropertiesortoinvokecertainoperationsonmanagedobjects,aprincipalmusthavethe appropriateprivileges.AprivilegeisasystemdefinedrequirementassociatedwithaVMwarevSphere managementobject.PrivilegesaredefinedbyVMware.Privilegesarestatic,anddonotchangeforasingle versionofaproduct.Table 31showstheformatinwhichprivilegesarespecifiedforVMwarevSphere components. Table 3-1. Privilege Definition Format and Examples
Format Datacenter.Create <group>[.<group>].privilege Datacenter.Delete Datacenter.Move Examples Host.Config.Connection Host.Config.Memory Host.Config.Snmp
SomeprivilegesarespecifictoobjectsonvCenterServerorESX/ESXionly.Forexample,theAlarm.Create privilegeisassociatedwithAlarmManager,whichistheserviceinterfaceforcreatingandmanagingalarms thatisavailablethroughvCenterServersystemsonly. Completeinformationaboutrequiredprivilegesfortheoperationsofamanagedentityisavailableinthe vSphereAPIReference. ToviewanypropertyofamanagedentitytypicallyrequirestheSystem.Viewprivilegeontherootfolderof theinventoryandtheSystem.Read privilegeonthespecificFolderandVirtualMachineobjects. Forexample,creatingavirtualmachinerequiresthattheprincipalassociatedwiththesessionhavethe followingprivileges: TheVirtualMachine.Inventory.Createprivilegeonthefolderinwhichtocreatethevirtualmachine TheResource.AssignVMToPoolprivilegeontheresourcepoolfromwhichthevirtualmachineobtains itsallocationofCPUandmemoryresources.
28
VMware, Inc.
ToreadtheperfCounterpropertyofthePerformanceManagermanagedobject,ausermusthavethe System.View privilegeontherootfolder. Achildentitytypicallyinheritsthepermissionsofitsparent.Ifyousetthepermissiononaparentobjectand setitspropagatepropertytotrue,thechildentitiesaccruethesamepermissionsettingastheparent.However, youcansetapermissiondirectlyonachildentitythatisdifferentthanitsparent. TheAuthorizationManagerserviceinterfaceprovidesoperationsforqueryingandsettingpermissions.See Chapter 4,OverviewofUserModelsandServerAccessControlConcepts,onpage 33formoreinformation aboutAuthorizationManager. Figure 3-5. A ManagedEntity Has One or More Permission Objects
ThePermissiondataobjectappliestothechildEntityassociatedwiththemanagedentitywhenthe propagatepropertyofPermissionissettotrue. Soforexample,inFigure 36thehafolderrootobjecthastwopermissionobjectsinthearraythatmakesup itspermissionproperty.Bothpermissionobjectshavetheirpropagateflagsettotrue.ThechildEntityof ha-folder-rootisha-datacenter,soha-datacenterinheritsthepermissionsofha-folder-root. AssigningpermissionstotheDatacenternodeandsettingthePermissionobjectspropagateflagsettotrue effectivelygrantspermissionattheDatacenterlevelandallchildentitiesthathaveaspecificDatacenter objectastheirparent. Figure 3-6. Inventory and Permissions
VMware, Inc.
29
Figure 36showsthatusersrootandvpxuserbothhavepermissionsontherootFolderoftheinventory. The vpxuseristheaccountcreatedonthehostbythevCenterServersystemwhenthehostisaddedtothe vCenterServer.ThevCenterServerneedsaccesstotheinventoryobjectsofthehostsystemsthatitmanages, sothevpxuseraccountisgrantedprivilegestotherootFolderofeachhost. Forexample,toinvoketheDestroy_Taskoperationonaspecificdatacenterinstancerequirestheusertohave theDatacenter.DeleteprivilegeonthedatacenterandontheparentFoldercontainingtheDatacenter.
Folder as Factory
TheFoldermanagedentityisafactoryobject.Itprovidesoperationsforcreatinginstancesofothermanaged entities,includingthefollowingtypes: Datacenters Distributedvirtualswitches Virtualmachines Clusters Folders ForanunmanagedESX/ESXisystem,theFoldermanagedentitydoesnotsupportcreatingadditionalFolder objectsorDatacenterobjects.
vCenter Server and Unmanaged ESX/ESXi Host Inventories

TheinventoryofavCenterServersystemsupportsmultipleESX/ESXihosts.ThehostsareaddedtoavCenter ServerusingthevSphereClient,orprogrammaticallybyusingtheAPI.AddingahosttoavCenterServer systemaddsthehosttotheinventoryofthevCenterServer,afterwhichitbecomesamanagedhost.Youcan configuretwoormoreofhostsinavCenterServersystemintoclusters. Theinventoryofanunmanagedhostcansupportmultiplevirtualmachinesandmultipleresourcepools,but itcontainsasingledefaultdatacenterandasinglerootfolder.Thedefaultdatacenterandrootfolderarenot visibleinthevSphereClient,buttheyexistintheinventoryofanunmanagedhostandtheyarevisibleinthe MOB.TherootFolderisapropertyavailableintheServiceContentdataobject,andthedefaultdatacenter isactuallythechildEntityassociatedwiththerootfolder,asshowninFigure 33,InstanceDiagramofRoot FoldersinanInventory,onpage 27. Youmustaccountfortheseobjectswhenyounavigatetheinventoryprogrammatically,suchaswhenyouuse aPropertyCollectorinyourcode.Table 32summarizesthedifferencesbetweenthenumberofobjectsthat aninventorycancontain. Table 3-2. Comparison of Unmanaged ESX/ESXi and vCenter Server Inventories
ManagedEntity Subtype ClusterComputeResource ComputeResource Description AbstractsmultipleHostSystemobjects intoaunifiedcomputeresource. Abstractsthephysicalresourcesofahost systemandenablesthemtobe associatedwiththevirtualmachinesthat runonthehost. Containerobjectforestablishing associationsamongmanagedentities, includingfolders,virtualmachines,host systems. Logicalstoragevolumesonwhichto storevirtualmachinefiles. InterfaceforDistributedVirtualSwitch (vNetworkDistributedSwitch). ESX/ESXi Inventory None. Exactlyoneonly. vCenter Server Inventory Multipleinstances supported. Multipleinstances supported.
Datacenter
Exactlyoneonly. Cannotbe destroyed. Transparent. Multipleinstances supported. Multipleinstances supported.
Multipleinstances supported.
Datastore DistributedVirtualSwitch
Multipleinstances supported. Multipleinstances supported.
30
VMware, Inc.
Table 3-2. Comparison of Unmanaged ESX/ESXi and vCenter Server Inventories (Continued)
ManagedEntity Subtype Folder Description Containerobjectusedtoorganizevirtual machinesandhostsinaninventory. ESX/ESXi Inventory Exactlyoneonly. Cannotbe destroyed. Transparent. Exactlyoneonly. Multipleinstances supported. Multipleinstances supported. None. vCenter Server Inventory Multipleinstances supported.
HostSystem Network ResourcePool
Abstractionforasinglephysical machine. Abstractionforaphysicaloravirtual network(VLAN). Abstractionforphysicalresourcesthat canpartitionedintosmallerunitsforuse byvirtualmachines. Containerobjectforoneormorevirtual machinesandassociatedobjects packagedusingopenvirtualformat (OVF)1.0. Abstractionforavirtualmachine.
Multipleinstances supported. Multipleinstances supported. Multipleinstances supported. Multipleinstances supported.
VirtualApp
VirtualMachine
VMware, Inc.
31
32
VMware, Inc.
Overview of User Models and Server Access Control Concepts
VMwarevSphereimplementsmechanismstoensurethatonlyvaliduserscanaccessvirtualinfrastructure components.TheusermodelforESX/ESXisystemsisdifferentthantheusermodelforvCenterServer systems.Thischapterdiscussestheseusermodelsandthemanagedobjects(serviceinterfaces)thatprovide variousmechanismstosecurethesystem.Itincludesthesetopics: IntroductiontoAuthenticationandAuthorizationonpage 33 OverviewofESX/ESXiUserModelonpage 35 OverviewofvCenterServerUserModelonpage 36 ObtainingInformationaboutUsersandGroupsfromUserDirectoryonpage 37 AuthenticatingUsersthroughSessionManageronpage 39 OverviewoftheAuthorizationManageronpage 39 GrantingPrivilegesthroughPermissionsonpage 42
Introduction to Authentication and Authorization

Severalserversidemechanismsinteractivelyauthenticateahumanuserwhenaclientapplication,suchasthe vSphereClientoracustomapplicationdevelopedusingthevSphereWebServicesSDK,connectstotheserver. TheVMwarevSphereinterfacesforauthenticatingusersandprotectingvirtualinfrastructurefrom unauthorizedaccessinclude: HostLocalAccountManagerisusedtocreateandmanageuseraccountsandgroupsonESX/ESXi systems.Dependingonthepermissionsassociatedwiththerolesassignedtotheuseraccountsorgroups, authenticateduserscanviewobjectsorinvokeoperationsontheserver.SeeOverviewofESX/ESXiUser Modelonpage 35formoreinformationabouttheHostLocalAccountManager. SessionManagerprovidesaninterfacetotheserverauthenticationinfrastructureonthetargetserver system. ForvCenterServersystems,SessionManagersupportsintegrationwithMicrosoftSSPI(Security ServiceProviderInterface),whichenablessinglesignonusingMicrosoftWindowslocalaccountsor ActiveDirectory. ForESX/ESXisystems,SessionManagersupportsauthenticatinguseraccountsasdefinedonthe hostsystem,suchasaccountscreatedusingvSphereClientorthosecreatedprogrammatically throughtheHostLocalAccountManagerAPI.
VMware, Inc.
33
AuthorizationManagerprotectsVMwarevSpherecomponentsfromunauthorizedaccess.Accessto componentsisrolebased:Usersandgroupsareassignedrolesthatencompasstheprivilegesneededto performoperationsonsomemanagedentities,ortoviewobjects.AuthorizationManagerhas operationsforcreatingnewroles,modifyinguserroles,settingpermissionsonentities,andhandlingall otheraspectsoftherelationshipmanagedobjectsandthepermissionsgrantedtoprincipals(users, groups)toaccessthem. UserDirectoryprovidesalookupmechanismthatreturnsuseraccountinformationto AuthorizationManagerortoanotherrequestor,suchasaclientapplication.SeeOverviewofESX/ESXi UserModelonpage 35formoreinformationabouttheUserDirectory. TheseservicesworktogethertoensurethatonlyauthenticateduserscanconnecttoESX/ESXiorvCenter Serversystems,andthattheycanaccessonlythoseobjectsfolders,virtualmachines,datacenters,virtual services,andsoonforwhichtheyhavetherequiredprivilegesandareauthorizedtouseortoview. Accessinganobjectmightmeanreadingapropertyvalue,orinvokinganoperation.Inmanycases,the privilegesrequiredtoreadapropertyvaluearelessrestrictivethantheprivilegesrequiredtoperform operations.Forexample,ausermightbeabletoseeavirtualmachineintheinventory,butmightnotbe allowedtocreateanewvirtualmachine.
Understanding System Privileges

AprivilegeisasystemdefinedrequirementassociatedwithaVMwarevSphereobject.Privilegesaredefined byVMware.Privilegesarestatic,anddonotchangeforasingleversionofaproduct.Eachmanagedobjecthas oneormoreprivilegesrequiredonthepartofaprincipal(user,groupmember)toinvokeanoperationorto viewaproperty.Forexample,managedentitiessuchasFolderandVirtualMachinerequiretheprincipalto havetheSystem.Readprivilegeontheentitytoviewthevaluesofitsproperties.
Privileges Defined in the vSphere API Reference

ThevSphereAPIReferenceincludesinformationaboutprivilegesrequiredtoinvokeoperationsandtoview properties.Inthedocumentationpageofthespecificmanagedobject,lookfortheRequiredPrivilegeslabel tofindoutaboutspecificprivileges,ifany,requiredtoviewthepropertyorinvoketheoperation.Table 41 showstheformatusedtospecifyprivileges. Table 4-1. Privilege Specification Format and Examples
Format Datacenter.Create <group>[.<group>].privilege Datacenter.Delete Datacenter.Move Examples Host.Config.Connection Host.Config.Memory Host.Config.Snmp
AprivilegemightbespecifictovCenterServerortoESX/ESXisystems.Forexample,theAlarm.Create privilegeisdefinedonvCenterServer.SettingalarmsrequiresvCenterServer,whichhasanAlarmManager serviceinterfacethatintegrateswithmanyoftheothermanagementobjectsontheserver. Usersaregrantedprivilegestoobjectsthroughroles.SeeUsingRolestoConsolidateSetsofPrivilegeson page 40formoreinformation.SeeTable A3,PrivilegesGrantedtotheAdministratorRole,onpage 158for acompletelistofprivilegesencompassedbytheAdministratorroleasdefinedonavCenterServer4.0system.
HTTP-Based File Access and Privileges

Privilegerequirementsapplytosystemobjectsregardlessofhowagivenclientapplicationattemptstoaccess servercontent.Forexample,supportforHTTP/HTTPSaccesstothefilescomprisingDatastoreobjectswas addedinESX/ESXi3.5.Filescomprisingtheobjectsthatmakeupvirtualmachinedatastorescanbeaccessed byspecifyingaURLinthisformat:
https://<hostname>/folder[/<path>]/?dcPath=<datacenter_path>[&dsName=<datastore_name>]
34
VMware, Inc.
Chapter 4 Overview of User Models and Server Access Control Concepts
Becausetheobjectsbeingaccessedaredatastoreobjectsintheinventoryandtheseobjectsareassociatedwith aspecificfolderstructure,theprivilegesrequiredtoaccessthesefilesarethesameprivilegesrequiredtoobtain thesefilesusinganyothermechanism,suchasthevSphereClient. Table 4-2. Privileges Required for Datastore Objects Apply Regardless of Access Mechanism
Object associated with file Rootfolder Datacenter Portion of URL /folder ?dcPath Required privileges System.View Datastore.Browse Datastore.FileManagement Datastore &dsName Datastore.Browse Datastore.FileManagement Host /host /tmp/ Host.Config.AdvancedConfig Host.Config.SystemManagement
Overview of ESX/ESXi User Model

Whenusersentertheiruseraccountandcredentialfromaclientapplication,theserverconsultsthe appropriateuseraccountstoreandvalidatestheauthenticityoftheuseraccountandtheassociatedcredential. Currently,thecredentialconsistsofapassword,buttheVMwarevSpherealsosupportscertificates,suchas X.509certificates.Authenticateduserscanthenaccessobjectstheyvebeenauthorizedtouse.Auseridentity mustexistonthetargetsystemorinasupporteddirectoryservice,asauseraccount,tobeauthenticated. ESX/ESXileveragesstandardLinuxinfrastructure,includingtheLinuxpluggableauthenticationmodule(PAM) mechanismforuseraccountcreationandmanagement.TheVMwareauthenticationdaemon(vmwareauthd) isimplementedasaPAMmodule.YoucancreateuseraccountsonanESX/ESXisystemusinganyofthe VMwareclienttools,orusingtheHostLocalAccountManager.
Using HostLocalAccountManager Managed Object

TheHostLocalAccountManagermanagedobjectprovidesoperationsforcreatingusers,creatinggroups, assigninguserstogroups,andotheruserandgroupadministrationtasks.TheHostLocalAccountManager serviceinterfaceisavailablethroughtheWebserviceonESX/ESXionly.vCenterServerusestheWindowsuser managementfacilities.SeeOverviewofvCenterServerUserModelonpage 36fordetails. Figure 4-1. HostLocalAccountManager Managed Object
YoumustdefinetheHostAccountSpecdataobjectusingthecharacteristicsrequiredforthetargetsystem,as configuredbythesystemadministrator.Thesecharacteristicsincludepasswordlengthrequirements,restrict useofdictionarywords,andsoon. Inadditiontocreatinguseraccountsandgroups,HostLocalAccountManagerprovidesseveralother operations: AssignUserToGroup,whichassignsaspecifieduseraccounttoagroup. UnAssignUserFromGroup,whichremovesauserfromagroup.UseRetrieveUserGroupsfirstif necessary,toobtaingroupinformationfortheuseraccount. UpdateUser,whichallowsyoutomodifyinformation,includingpasswordanddescription,foran existinguseraccount.
VMware, Inc.
35
Table 43summarizestheAPIreferencedocumentationfortheseoperations.Forcompleteinformationabout HostLocalAccountManager,seethevSphereAPIReference. Table 4-3. HostLocalAccountManager Operations for User and Group Management
Operation AssignUserToGroup Parameter _this Type MOR > HostLocalAccountManager string Description Referencetothe HostLocalAccountManagerused tomakethecall. UserID(thegeneratednumber fromtheuserstoreofthehost system). Grouptowhichtheuseraccount (userID)isbeingadded. Referencetothe HostLocalAccountManagerused tomakethecall. Nameofuserbeingremovedfrom agroup. Groupfromwhichtoremoveuser. Referencetothe HostLocalAccountManagerused tomakethecall. Dataobjectthatcontains description,useraccountID,anda passwordfortheprincipalbeing updated.
user
group UnAssignUserFromGroup _this
string MOR > HostLocalAccountManager string string MOR > HostLocalAccountManager HostAccountSpecdataobject
user group UpdateUser _this
user
Afteruseraccountsandgroupsonthehostsystem(ESX/ESXi),youcangranttheseusersaccesstovirtual componentsbyusingtheAuthorizationManageroperations.SeeOverviewoftheAuthorizationManager onpage 39formoreinformation.
Overview of vCenter Server User Model

vCenterServerisaWindowsbasedservicethatusesnativeWindowsfacilitiesandusermodelfor identificationandauthentication.TheserviceisassociatedwiththeWindowsuseraccountthatwaslogged ontothemachineforthevCenterServerinstallationprocess.ThisvCenterServeradministratoraccountmust beamemberofthelocalWindowsAdministratorgrouponthemachine.OthervCenterServeruserswho connecttotheWebservicemustalsohaveaWindowsaccountonthelocalAdministratorgroup.Ifyouuse WindowsdomainloginaccountsforvCenterServer,theaccountmustbeamemberofthelocalhostsystem Administratorgroup.VMwarerecommendscreatingaWindowsuseraccountspecificallyforinstallingand managingthevCenterServer. Bydefault,vCenterServerandVirtualCenter2.5canobtainuseraccountinformationfromMicrosoftActive Directory,theuseraccountrepositoryforMicrosoftWindowsdomaincontroller. To create an Administrator account for vCenter Server 1 2 3 4 5 6 LogintotheWindowsserveraslocalAdministrator. CreateauseraccountforvCenterServer. AddtheuseraccounttotheAdministratorgroupofthemachine. LogoutasAdministrator. LogintotheWindowsserveragain,usingthenewaccount. InstallvCenterServer.
Fordetails,seetheBasicSystemAdministrationguideintheVMwarevSpheredocumentationset.
36
VMware, Inc.
Enabling Single Sign-on Support and Integration with Microsoft Active Directory
OrganizationsthatareusingMicrosoftActiveDirectorycanleveragetheuseridentitiescontainedina Windows2003ServerdomaincontrollerorActiveDirectoryserviceacrosstheirvirtualinfrastructure,for clientsthatrunvSphereWebServicesSDKclientapplicationsfromWindowsbasedsystems. VMwarevSphereWebServicesSDKclientapplicationscanuseSSPItoauthenticatetothelocalmachineand thenestablisharemoteconnection.SeethevSphereAPIReferenceformoreinformation.
Obtaining Information about Users and Groups from UserDirectory

TheUserDirectorymanagedobjectenablesaclientapplicationtoobtaininformationaboutusersandgroups onaVMwarevSphereserver.Propertiesandresultsvary,dependingonwhethertheserverisavCenterServer oranESX/ESXisystem. Table 4-4. Server Source Data for UserManager
vCenter Server Domaincontroller,ActiveDirectory,orlocalWindows accountrepository ESX, ESXi /etc/passwd
Forexample,vCenterServeruseraccountscanbemanagedinaWindowsActiveDirectoryserverordomain controllerfromwhichthedomainListpropertyofUserDirectoryisderived.ForESX/ESXisystems,the domainListpropertyisempty. Figure 4-2. UserDirectory Managed Object
UserDirectoryprovidestwooperationsforobtaininginformationaboutusersandgroups: RetrieveCertificatePrincipals,whichreturnsanarrayofCertificatePrincipaldataobjects (principalsthatuseX.509certificatesforauthenticationtotheserver,ratherthanapassword). RetrieveUserGroups,whichcanobtainalistofalluseraccountsfromthehost,andcansearchfor specificusersorgroupsbasedonspecificcriteriatofiltertheresults: Byusername Bygroupname Foranexactmatch Forforapartialstring(substring) ForvCenterServer,searchislimitedtothespecifiedWindowsdomain.Ifthedomainisomitted,thesearchis performedonlocalusersandgroups. ForESXsystems,searchreturnsallusersandgroupsfromthepasswdfile.IfthisfilecontainsNetwork InformationSystem(NIS)orNIS+usersandgroups,RetrieveUserGroupsreturnstheseaccountsaswell. IMPORTANTDonotconfigureanESXorESXisystemtouseNISorNIS+,unlessitisacceptabletohaveNIS (orNIS+)userandgroupinformationavailablethroughtheRetrieveUserGroupsAPI.
VMware, Inc.
37
Figure 43showsthesetwodifferentusermanagementmechanismsassociatedwiththeVMwarevSphere server. Figure 4-3. Managed Objects for Handling Local User Accounts
BothRetrieveCertificatePrincipalsandRetrieveUserGroupsrequireamanagedobjectreferenceto theUserDirectory.BothoperationsreturnanarrayofUserResearchResultdataobjectsbasedonthestring orsubstringusedforthefilter. Table 4-5. UserManager Operations

Operation RetrieveCertificate Principals Parameter _this searchStr Type MOR > UserDirectory string Description ReferencetotheUserDirectory. Caseinsensitivestringthatfiltersresults.Matchesthe subjectNameofCertificatePrincipaldataobjects.Leave blanktoreturnallCertificatePrincipaldataobjects. ReferencetotheUserDirectory. Optional.Domainthatshouldbesearchedforuseraccount orgroupinformation.Leaveunsettosearchlocalmachine. Required.Caseinsensitivestringusedtofilterresults. Matchesonloginandfullnameforusers.Matchesname anddescriptionforgroups. Optional.ESXonly.Returnsusersorgroupsthatexplicitly containthespecifiedgroup.Indirectmembers(usersor groupsthataremembersofacontainedgroup)arenot returned. Optional.Returnsgroupsthatexplicitlycontaintheuser. Indirectusers(usersthataremembersofacontained group)arenotreturned. Required.Settofalsetorestrictresultstoprecisematchof userorgroupname. Required.Settotruetoincludeusersintheresult. Required.Settotruetoincludegroupinformationinthe result.
RetrieveUser Groups
_this domain searchStr
MOR > UserManager string string
belongsToGroup
string
belongsToUser
string
exactMatch findUsers findGroups
boolean boolean boolean
38
VMware, Inc.
Authenticating Users through SessionManager

TheSessionManagerprovidesseveraloperationsforloggingintotheserver,obtainingasession,andlogging out.TheSessionManagerdefinesthelifetimeandvisibilityofmanyobjects.Sessionspecificobjectsarenot visibleoutsidethesessioninwhichtheyarecreated. Figure 4-4. SessionManager Managed Object
Uponsuccessfulauthenticationoftheuseraccount,theSessionManagerreturnsaUserSessiondataobject totheclientapplication.Thesessionisassociatedwiththatspecificuseraccountforthedurationofthesession. Theclientapplicationcansavethesessionlocally,toasecurefile,andreusethesessionlatertoreconnectto theserver.YoucanalsoconfigureanESX/ESXiorvCenterServersystemtosupportlocalsessions,which enableuserswithcredentialsonthehosttologinbasedonthoseprivileges. TheSessionManagerprovidesthesecapabilities: Loginandlogout.BasicoperationstologintoESXorvCenterServer,obtainasession,andlogout.When asessionterminates,allsessionspecificobjectsaredestroyed. Impersonation.Oneusersessionadoptstheauthorizationlevelofanotherusersession.Impersonationis commoninWebbasedscenariosinwhichamiddletierapplicationfunctionsasacentralaccountthat interactswithotherbackendserversorprocesses.Windowsservicesimpersonateaclientwhenaccessing resourcesonbehalfoftheclient.SesssionManagersupportsimpersonationthroughits ImpersonateUseroperation. Delegation.AclientapplicationexecutingonbehalfofalocalusercaninvoketheAcquireLocalTicket operationofSessionManagertoobtainaonetimeusernameandpasswordforloggingonwithout enteringasubsequentpassword.Delegationisusefulforhostbasedutilitiesthatruninthelocalconsole. Iftheuseraccountassociatedwiththesessiondoesnothaveappropriatepermissionstoperformanaction, theAuthorizationManagerreturnsaNoPermissionfaulttotheclientapplication.
Overview of the AuthorizationManager

TheAuthorizationManageristheserviceinterfaceforhandlingpermissionsandroles.Itincludesclosetoa dozenoperationsforcreating,modifying,andmanagingrolesandpermissions,andforobtaininginformation abouttherolesandpermissionsdefinedinthesystem.TheAuthorizationManagerenablesaccessand preventsaccesstospecificserverobjectsbasedonthepermissionsassociatedwiththeobject. OperationsformanagingrolesincludeAddAuthorizationRole,RemoveAuthorizationRole,and UpdateAuthorizationRole.SeeTable 47,AuthorizationManagerOperationsforCreating,Updating,and DeletingRoles,onpage 41foremoreinformationabouttheseoperations. OperationsformanagingpermissionsincludeMergePermissions,RemoveEntityPermission, ResetEntityPermissions,RetrieveAllPermissions,RetrieveEntityPermissions, RetrieveRolePermissions,andSetEntityPermissions.
VMware, Inc.
39
Figure 45showstheseoperationsinthecontextofaUMLdiagramforAuthorizationManagerandsomeof itsassociateddataobjects. Figure 4-5. AuthorizationManager Managed Object
AuthorizationManageralsoprovidespropertiesthatcanbeusedtoobtaininformationfast.Forexample: TheprivilegeListpropertyreturnsthelistofallprivilegesdefinedonthesystem,asanarrayof AuthorizationPrivilegedataobjects.PrivilegesaredefinedbyVMware,onthevariousobjectsand propertiescontainedinthesystem.Theseprivilegesarefixedandcannotbechangedbyclient applications.SeeAppendix A,ManagedObjectPrivilegesReference,onpage 149forlistsofprivileges. TheroleListpropertyreturnslistofallcurrentlydefinedroles,includingthesystemdefinedroles,as anarrayofAuthorizationRoledataobjects. Youcanseethesepropertyvaluesforyourself,onyourESXorvCenterServersystem,bynavigatingtoyour theAuthorizationManagerusingtheMOBonyoursystem.SeeUsingtheManagedObjectBrowserto ExploretheObjectModelonpage 16formoreinformation.
Using Roles to Consolidate Sets of Privileges

Aroleisanamedsetofoneormoreprivileges,groupedforconvenience.Assigningarolethatencompasses allthenecessaryprivilegestoperformanactioniseasierandfasterthangrantingeachindividualprivilege separately.ESXdefinestwotypesofroles: Systemroles,whichcannotbemodifiedordeleted. Userroles,whichapplytodifferentusercommunitiesorthatrestrictaccessforaddontools.Several predefineduserrolesareincludedwithvCenterServerandwithESX/ESXisystems.Youcancreatenew rolesusingthesepredefineduserrolesasastartingpoint.
40
VMware, Inc.
Table 46describesthesetwotypesofrolesinmoredetail. Table 4-6. System and Pre-Defined User Roles

Type Systemroles Role name Administrator Role ID 1 Description Superuseraccess.Encompassesthesetofalldefinedprivileges. SeeTable A3,PrivilegesGrantedtotheAdministratorRole, onpage 158foranexamplelistfromavCenterServersystem. Thisrolecannotbedeleted.Bydefault,theAdministratorroleis grantedtotheuserorgroupthatownstherootnode. Cannotbegranted.Defaultaccessroleassociatedwithanyuser accountthathasloggedin. Noaccess.Explicitlydeniesaccesstotheuserorgroupwiththis role.Assigningthisroletoauseraccountpreventstheuserfrom seeinganyobjects.UsetheNoAccessroletomasksubobjects underahigherlevelobjectthathaspropagatedpermissions defined. Readonlyaccess.Encompassesthesetofallnonmutable privileges.(System.Anonymous,System.Read,and System.View).Equivalenttoauserrolewithnopermissions. Userswiththisrolecanreaddataorpropertiesandinvoke querymethods,butcannotmakeanychangestothesystem. VisibilityaccessconsistingofSystem.Anonymousand System.Viewprivileges.Cannotbegranted. Setofprivilegesnecessarytomanagevirtualmachinesand hostswithinthesystem. Setofprivilegesnecessarytomanageresourcesbutnotinteract withvirtualmachines. Setofprivilegesnecessarytoprovisionresources. Setofprivilegesforavirtualmachineuserthatcanalsomake configurationchangesandcreatenewvirtualmachines. Setofprivilegesnecessarytousevirtualmachinesonly.Cannot reconfigurevirtualmachines. AvailableonvCenterServersystemsonly. AvailableonvCenterServersystemsonly.Setofprivileges necessarytoruntheConsolidatedBackupUtility.
Anonymous NoAccess
4 5
ReadOnly
View Userroles (predefined samples) VirtualMachine Administrator Datacenter Administrator VirtualMachine Provider VirtualMachinePower User VirtualMachineUser ResourcePool Administrator VMwareConsolidated BackupUtility
3 1 2 3 4 5 6 7
Table 47listsseveralAuthorizationManageroperationsavailableformanagingroles. Table 4-7. AuthorizationManager Operations for Creating, Updating, and Deleting Roles
Operation AddAuthorizationRole Parameter _this Type MOR > AuthorizationManager Description Managedobjectreferencetothe serversAuthorizationManager obtainedthrough ServiceInstance. Nameforthenewrole. Listofprivilegestoassigntotherole intheformat: <group>[.<group>].privilege
name privIds
string string[]
VMware, Inc.
41
Table 4-7. AuthorizationManager Operations for Creating, Updating, and Deleting Roles (Continued)
Operation UpdateAuthorizationRole Parameter _this Type MOR > AuthorizationManager Description Managedobjectreferencetothe serversAuthorizationManager obtainedthrough ServiceInstance. Integerthatidentifiestheroletobe modified. Newnamefortherole. Stringarrayofprivilegestoassignto therole. Managedobjectreferencetothe AuthorizationManagerobtained fromtheServiceInstanceofthe server. Integerthatidentifiestherole.The roleIdisgeneratedby AddAuthorizationRolewhena newroleisdefined. Settotruetoensuretherolecannot beremovedifitisbeingused.
roleId newName privIds RemoveAuthorizationRole _this
int string string[] MOR > AuthorizationManager
roleId
int
failIfUsed
boolean
Modifying Sample Roles to Create New Roles

ThesystemroleslistedinTable 46cannotbemodifiedordeleted.However,youcancreatecompletelynew roles,ormodifythesampleuserrolestosuityourneeds. SeetheBasicSystemAdministrationguideorthevSphereClientonlinehelpforinformationaboutcreating newrolesormodifyingthesamplerolesusingthevSphereClient. SeethevSphereCommandLineInterfaceInstallationandReferenceGuideforinformationaboutusingthe vicfg-uservSphereCLIcommandtocreatenewrolesormodifythesampleroles. To create new roles using the API 1 2 Obtainareference(specificinstanceofManagedObjectReference)totheAuthorizationManagerfor theserver,fromtheServiceContentobjectfortheServiceInstance. InvoketheAddAuthorizationRolemethod,passingthereferenceintheinvocationalongwithaname fortherole(asastring)andanarrayofprivileges(arrayofstrings)thathasthelistofprivilegesthat shouldbeassignedtotherole. AddAuthorizationRolereturnsaninteger(xsd:int)valuefortheroleIdthatthesystemassignstothe newlydefinedrole. 3 UsetheroleIDinsubsequentcode,toassigntheroletospecificusersorgroups.
Granting Privileges through Permissions

APermissiondataobjectassociatesaprincipalwithasetofprivileges.Apermissionidentifies: Theuserorgroup(principal)towhichthepermissionapplies. Therolecontainingtheprivilegesthatshouldbegrantedtotheuserorgroup. Themanagedobjectreferencetotheentitytowhichthepermissionapplies EverymanagedentityhasatleastonePermissionobjectassociatedwithit.Amanagedentitycanhavemore thanonePermissionassignedtoit,effectivelygrantingdifferentprivilegestodifferentusersorgroups. Permissionsaredefinedformanagedentitieseitherexplicitlyorthroughinheritance.
42
VMware, Inc.
Obtaining Information about Permissions

UserswiththeAdministratorrolecanobtaininformationaboutPermissionobjectsatdifferentgranularities ofdetail,including: ForallusersdefinedinthesystembyinvokingtheRetrieveAllPermissionsoperation,whichreturns anarrayofPermissiondataobjects. Forspecificinventoryobjects,suchmanagedentities,suchasfolders,datacenters,orvirtualservicesby invokingtheRetrieveEntityPermissionsoperation. ForaroledefinedinthesystembyinvokingtheRetrieveRolePermissionsoperation. SeethevSphereAPIReferenceformoreinformation.However,youcaninvokeanyoftheseoperationsfromthe MOBtoobtaininformationaboutyoursystem,asyoudevelopyourcode.
Setting, Changing, or Deleting Permissions

ThePermissiondataobjectassociatestheprivilegesrequiredtoperformanactionwiththeprincipals(user, group)thathavebeengrantedthoseprivilegesbyvirtueoftheroleassignedtotheprincipals. TheAuthorizationManagerprovidesseveraloperationsformanagingPermissionobjects,includingthose listedinTable 48. Tosetorupdatepermissionsonanentity,usetheSetEntityPermissionsoperation.Settingorchanging permissionsonentitiesrequirestheAuthorization.ModifyPermissionsprivilegeonthetargetmanaged entity. To set permissions on an entity 1 ObtainareferencetotheAuthorizationManagerfortheserver,fromtheServiceInstances ServiceContentobject.Forexample:
ManagedObjectReference hostAuthorizationManager = cb.getConnection().getServiceContent().getAuthorizationManager();
CreateaPermissiondataobjectthatidentifiestheuser(orgroup)name,therole,theentitytowhichthe permissionshouldapply,andwhetherthepermissionshouldbeappliedtotheentityschildren. Forexample,tocreateapermissionontherootfolderoftheinventorygrantingauserAdministratorrole totherootfolderandallitschildren:

Permission per = new Permission(); per.setGroup(false); per.setPrincipal(new_user_name); per.setRoleId(-1); per.setPropagate(true); per.setEntity(rootFolder);
Tocompletelyreplaceexistingpermissionswithanewsetofpermissions,usetheResetEntityPermissions operation. Table 4-8. AuthorizationManager Operations for Setting, Changing, and Removing permissions
Operation SetEntityPermissions, ResetEntityPermissions Parameter _this Type MOR > AuthorizationManager Description Managedobjectreferencetothe servers(ServiceInstance) AuthorizationManager. Managedentityforwhichyouwant tograntordenyaccess. ArrayofPermissionobjectsthat defineaccessrulesfortheentity. Passinganemptyarrayremovesall permissionsfromtheentity.
entity
MOR > ManagedEntity [HostSystem,Folder, ComputeResource...] Permission[]
permission
VMware, Inc.
43
Table 4-8. AuthorizationManager Operations for Setting, Changing, and Removing permissions (Continued)
Operation RemoveEntityPermission Parameter _this entity Type MOR > AuthorizationManager MOR > ManagedEntity [HostSystem, Folder, ComputeResource...] Description Deletethepermissionfromanentity forspecifiedprincipal(user,group). Managedobjectreferencethat identifiesthemanagedentityfrom whichtodisassociateaPermission. UsetherootFoldermanagedobject referenceifthePermissionis associatedwithamanagedobjectthat isnotamanagedentity. Usethespecificmanagedentity subclasstype(Folder,Datacenter, andsoon)forPermissionbeing removedisassociatedwitha managedentity. user isGroup string boolean Principal(user,group)forwhichthe permissionsweredefined. Specifiesthattheuservalueisagroup (true)orasingleuser(false).
Permissionscannotbesetdirectlyonchildreninacomplexentity.Forcomplexentities,setpermissionsonthe parententityandsetthepropagateflagtotruetoapplypermissionstoitschildentities.
Impact of Group Membership on Permissions

Userscanbemembersofmultiplegroups.Ifauseraccountwithmembershipinmultiplegroupshasnoother explicitlydefinedpermissions,thentheaccountisgrantedthecombinedset(union)ofallgroupassigned permissions. Usersalsoobtaintheunionofpermissionsassociatedwiththecontainingresourcepoolandfolderforvirtual machinesforwhichtheyhavebeengivenpermission.However,userspecificpermissionsalwaystake precedenceoveranygrouppermissions.Table 49summarizesthesedetails. Table 4-9. User and Group Permissions Summary
User-level permissions Alwaystakeprecedenceoveranygrouplevel permissions. Group-level permissions Membershipinmultiplegroupswithpermissionson thesameobjectresultsinunionofpermissions. Absentexplicituserpermissions,grouplevel permissionsapplyasifgrantedtouserdirectly.
Permissionsareappliedtotheassociatedobjectsthatmakeuptheinventoryitem,fromthecontainingobject toeachofitschildentities.
44
VMware, Inc.
vSphere API Programming Model
TheVMwarevSpheremanagementobjectmodelprovidesaserversideframeworkforprovisioning, instrumenting,managing,andmonitoringVMwarevSpherecomponents,suchasvirtualmachines,host systems,andvirtualizedapplications.ProgrammaticaccesstotheVMwarevSphereobjectmodeland managementframeworkfromaclientapplicationisthroughthevSphereAPI.Thischapterincludesthese topics: APIasaWebServiceonpage 45 ClientApplicationCharacteristicsonpage 46 AccessingtheAPIontheWebServiceonpage 50 UsingthevSphereAPIReferenceonpage 51 MappingtheWSDLtotheClientsideProxyCodeonpage 51 InvokingOperationsthroughtheMOBonpage 53
API as a Web Service

ThevSphereAPIislanguageneutral.ItisimplementedasindustrystandardWebservicesthatarehostedon ESX/ESXiandvCenterServersystems.ThevSphereAPIcomplieswiththeWebServicesInteroperability Organization(WSI)BasicProfile1.0.TheWSIBasicProfile1.0includessupportfor: XMLSchema1.0 SOAP1.1 WSDL1.1 ForinformationabouttheWSIBasicProfile1.0,visittheWebServicesInteroperabilityOrganization(WSI) Websiteathttp://www.wsi.org. Webservicestechnologyprovidesoperations,whichisthesamebasicconceptasmethodsinother programminglanguages.TheWebserviceprovidesaccesstoalloperationsnecessaryformonitoringand managingthevirtualinfrastructurecomponents,suchascomputeresources,virtualmachines,networks, storage,andsoon.
API Defined in WSDL File

TheWebservicesAPIisdefinedinaWSDL(WebServicesDescriptionLanguage)file.TheWSDLfileisused byWebservicesclientapplicationdevelopmenttools(SOAPtoolkits,suchasAxisorMicrosoft.NET)to createclientsideproxycode(stubs)thatfacilitateremotemethodinvocation,marshallingandmarshalling objectdata,andotherlowleveldetailsofdistributedobjectorientedapplicationsprogramming. ClientapplicationsinvokeoperationsbysendingSOAP(SimpleObjectAccessProtocol)formattedmessages. SOAPisanXMLformatandisprogramminglanguageneutral.OneofthejobsoftheclientsideWebservices toolsisformattingtheSOAPmessagesfromtheprogramminglanguagethatyouuse.
VMware, Inc.
45
CommunicationsbetweenclientandserveroccuroverHTTPS(HTTPoveranencryptedSecureSockets Layer (SSL)connection).ThedefaultisHTTPS.However,theservercanbeconfiguredtosupportHTTP. See theDevelopersSetupGuidefordetails.
Client Application Characteristics

TheVMwarevSphereapplicationmodelisasynchronous,distributed,andreliesoninstancesofthe ManagedObjectReferencedataobjectforremotemethodinvocation.
Asynchronous Client-Server Application Style

TheVMwarevSphereapplicationmodelusesanasynchronousclientservercommunicationschemeby default.Thatis,mostmethodinvocationsarenonblocking,returningareferencetoaTaskmanagedobject. SeeChapter 9,OverviewoftheTaskInfrastructure,onpage 83foracompleteoverview.
Distributed Object-Oriented Application Style

VMwarevSphereclientapplicationsinvokeoperationsontheserverremotely,overanetwork.Onlydata objectsaresentbackandforthbetweenserverandclient.Managedobjectsareaccessedbyreference.Youuse instancesoftheManagedObjectReferencedataobjecttypetoinvokeoperationsontheserverobjectsfrom yourclientapplication.Eachmanagedobjectreferenceidentifiesaspecificmanagedobjectontheserverwith itstypeandavalue(Figure 51). Figure 5-1. ManagedObjectReference Data Object Diagram
Table 51listsallpossiblevalidstringsforthevaluepropertyofManagedObjectReference. Table 5-1. Valid Values for ManagedObjectReference Type Property
Type Property Alarm AlarmManager AuthorizationManager ClusterComputeResource ClusterProfile Refers to Alarmmanagedobject AlarmManagermanagedobject AuthorizationManagermanagedobject ClusterComputeResourcemanagedobject ClusterProfilemanagedobject
46
VMware, Inc.
Chapter 5 vSphere API Programming Model
Table 5-1. Valid Values for ManagedObjectReference Type Property (Continued)

Type Property ClusterProfileManager ComputeResource ContainerView CustomFieldsManager CustomizationSpecManager Datacenter Datastore DiagnosticManager DistributedVirtualPortgroup DistributedVirtualSwitch DistributedVirtualSwitchManager EnvironmentBrowser EventHistoryCollector EventManager ExtensibleManagedObject ExtensionManager FileManager Folder HistoryCollector HostAutoStartManager HostBootDeviceSystem HostCpuSchedulerSystem HostDatastoreBrowser HostDatastoreSystem HostDateTimeSystem HostDiagnosticSystem HostFirewallSystem HostFirmwareSystem HostHealthStatusSystem HostKernelModuleSystem HostLocalAccountManager HostMemorySystem HostNetworkSystem HostPatchManager HostPciPassthruSystem HostProfile HostProfileManager HostServiceSystem HostSnmpSystem HostStorageSystem HostSystem
VMware, Inc.
Refers to ClusterProfileManagermanagedobject ComputeResourcemanagedobject ContainerViewmanagedobject CustomFieldsManagermanagedobject CustomizationSpecManagermanagedobject Datacentermanagedobject Datastoremanagedobject DiagnosticManagermanagedobject DistributedVirtualPortgroupmanagedobject DistributedVirtualSwitchmanagedobject DistributedVirtualSwitchManagermanagedobject EnvironmentBrowsermanagedobject EventHistoryCollectormanagedobject EventManagermanagedobject ExtensibleManagedObjectmanagedobject ExtensionManagermanagedobject FileManagermanagedobject Foldermanagedobject HistoryCollectormanagedobject HostAutoStartManagermanagedobject HostBootDeviceSystemmanagedobject HostCpuSchedulerSystemmanagedobject HostDatastoreBrowsermanagedobject HostDatastoreSystemmanagedobject HostDateTimeSystemmanagedobject HostDiagnosticSystemmanagedobject HostFirewallSystemmanagedobject HostFirmwareSystemmanagedobject HostHealthStatusSystemmanagedobject HostKernelModuleSystemmanagedobject HostLocalAccountManagermanagedobject HostMemorySystemmanagedobject HostNetworkSystemmanagedobject HostPatchManagermanagedobject HostPciPassthruSystemmanagedobject HostProfilemanagedobject HostProfileManagermanagedobject HostServiceSystemmanagedobject HostSnmpSystemmanagedobject HostStorageSystemmanagedobject HostSystemmanagedobject
47
Table 5-1. Valid Values for ManagedObjectReference Type Property (Continued)

Type Property HostVirtualNicManager HostVMotionSystem HttpNfcLease InventoryView IpPoolManager LicenseAssignmentManager LicenseManager ListView LocalizationManager ManagedEntity ManagedObjectView Network OptionManager OvfManager PerformanceManager Profile ProfileComplianceManager ProfileManager PropertyCollector PropertyFilter ResourcePlanningManager ResourcePool ScheduledTask ScheduledTaskManager SearchIndex ServiceInstance SessionManager Task TaskHistoryCollector TaskManager UserDirectory View ViewManager VirtualApp VirtualDiskManager VirtualizationManager VirtualMachine VirtualMachineCompatibilityChecker VirtualMachineProvisioningChecker VirtualMachineSnapshot VmwareDistributedVirtualSwitch
48
Refers to HostVirtualNicManagermanagedobject HostVMotionSystemmanagedobject HttpNfcLeasemanagedobject InventoryViewmanagedobject IpPoolManagermanagedobject LicenseAssignmentManagermanagedobject LicenseManagermanagedobject ListViewmanagedobject LocalizationManagermanagedobject ManagedEntitymanagedobject ManagedObjectViewmanagedobject Networkmanagedobject OptionManagermanagedobject OvfManagermanagedobject PerformanceManagermanagedobject Profilemanagedobject ProfileComplianceManagermanagedobject ProfileManagermanagedobject PropertyCollectormanagedobject PropertyFiltermanagedobject ResourcePlanningManagermanagedobject ResourcePoolmanagedobject ScheduledTaskmanagedobject ScheduledTaskManagermanagedobject SearchIndexmanagedobject ServiceInstancemanagedobject SessionManagermanagedobject Taskmanagedobject TaskHistoryCollectormanagedobject TaskManagermanagedobject UserDirectorymanagedobject Viewmanagedobject ViewManagermanagedobject VirtualAppmanagedobject VirtualDiskManagermanagedobject VirtualizationManagermanagedobject VirtualMachinemanagedobject VirtualMachineCompatibilityCheckermanagedobject VirtualMachineProvisioningCheckermanagedobject VirtualMachineSnapshotmanagedobject VmwareDistributedVirtualSwitchmanagedobject
VMware, Inc.
Obtaining Managed Object References

Withareferencetoamanagedobject,youcanobtaininformationaboutthestateoftheserversideinventory objectsandpopulateclientsideobjectsbasedonthevalues.Generally,thesearethedifferentwaysof obtaininginformationaboutobjectsfromtheserver: Useanaccessormethodifyourtargethasone.Theclientstubsprovideaccessormethodsforeach propertyofadataobject.Youcanuseanyoftheseaccessormethodstoobtainthevaluesoftheobject. UseaPropertyCollectortonavigatetoaselectedpointontheserverandobtainvaluesfromspecific properties.SeeObtainingReferencestoObjectsandPropertyValuesfromtheServeronpage 73for moreinformationaboutPropertyCollector. UsingtheSearchIndexmanagedobjecttoobtainamanagedobjectreferencetothemanagedentityof interest.TheSearchIndexcanreturnmanagedobjectreferencestospecificmanaged entitiesComputeResource,Datacenter,Folder,HostSystem,ResourcePool, VirtualMachinegivenaninventorypath,IPaddress,orDNSname.
Do Not Store Managed Object Reference Values

Managedobjectreferencesmustbeunique.Toensurethattheyare,VMwarevSphereserverseachhavetheir ownnamespaceformanagedobjectreferencevaluesthatensuresgloballyuniquevaluesthroughoutthe serverinstance.ManagedobjectreferencestoanobjectinanESX/ESXinamespaceisdifferentthanthe managedobjectreferencetothesameobjectinthevCenterServernamespace(assumingtheESX/ESXiinstance isbeingmanagedbythevCenterServerinstance).vCenterServermustensurethatmanagedobjectreferences acrossallthesystemsitmanagesareunique.Forthesereasons,youmustnotstoreamanagedobjectreference fromavCenterServerduringonesessionandexpecttouseitinasubsequentsession.
Working with Data Structures in Client Application Code

Propertiescontaininformationabouttheserversideobjectsatagivenpointintime.Eachpropertyisdefined asaspecificdatatype.Datatypesinclude: Simpledatatypes,suchasastring,boolean,orinteger(orothernumeric)datatype.Forexample,the ManagedEntitymanagedobjecthasanamepropertythattakesastringvalue. Arraysofsimpledatatypesordataobjects.Forexample,aHostSystemmanagedobjectcontainsanarray ofmanagedobjectreferences(atypeofdataobject)tovirtualmachineshostedbythatphysicalmachine. Asanotherexample,theSessionManagermanagedobjecthasasessionListpropertythatisanarray ofUserSessiondataobjects. Enumeratedtypes(enumeration,enum)ofpredefinedvalues.Thevaluescanbeacollectionofsimple datatypesordataobjects.Forexample,avirtualmachinespowerstatecanbeoneofthreepossiblestring valuespoweredOn,poweredOff,orsuspended. Complexdatatypes.DataobjectssuchasAboutInfo,Action,andServiceContent,thathavebeen specificallydefinedfortheVMwarevSphereobjectmodel.
Accessing Property Values

Workingwithcompositedatastructuresrequiressomeunderstandingofnestedpropertiesandhowtoaccess thedatatheycontain. Nested Properties and Property Paths TheVMwarevSphereobjectmodelismadeupofcompositedatastructures.Objecttypescanincludedata members(properties)definedasprimitivedatatypes,suchasanxsd:intorxsd:string,orascomplexdata types,suchasdataobjects.Propertiescannesttoseverallevels. Forexample,Figure 52showsaUMLclassdiagramoftheVirtualMachinemanagedobjecttype,whichhas aproperty(runtime)thatisdefinedasanxsd:dateTimedatatype.VirtualMachinealsohasaproperty namedsummarythatismodeledasaVirtualMachineSummarydataobject.TheVirtualMachineSummary dataobjectcontainsaproperty(config)thatismodeledasaVirtualMachineConfigSummarydataobject.
VMware, Inc.
49
Figure 5-2. VirtualMachine Managed Object Type and Nested Properties
Torefertoanestedpropertyatanydepthinyourcode,usedotnotationbetweenthevariousobjectnamesto definethepathtotheproperty,beingawaretohandlethereturntypecorrectly.Thereturntypeobtained dependsonthedatatypeattheendofthepath. Forexample,thepropertydefinedatthepathsummary.config.guestIdisastringvalue,whiletheproperty definedaspathsummary.configreturnsacompleteVirtualMachineSummarydataobject. Table 52showsseveralexamplesofhowtoaccesssomeofthenestedpropertiesoftheVirtualMachine managedobjecttypeshowninFigure 52. Table 5-2. Nested Properties and Return Datatypes
Example summary summary.config summary.config.guestID Returns VirtualMachineSummarydataobject VirtualMachineConfigSummarydataobject string
Properties Defined as Key-Based Arrays and Indexed Arrays Nestedpropertiescanalsorefertopropertiesthatarekeybasedarrays.Forexample,a.b.c["xyz"]refersto thepropertycthathasthekeyvalueofxyz.Anarraypropertyisanypropertywhosetypeisanarray.The VMwarevSpheredatastructuresincludebothindexedarraysandkeybasedarrays. Indexedarraysareaccessedbyusinganindexinteger.Indexedarraysareusedforarraysofdatatypes whosepositioninthearraydoesnotchange.Forexample,theroleListpropertyofthe AuthorizationManagermanagedobjectisanarrayofauthorizationroles.Addinganewroletothe arraydoesnotchangethepositionofexistingelementsinthearray. Keybasedarraysareusedforinformationwhosepositionissubjecttochange.Akeybasedarray(same basicconceptasaPerlhash)usesaunique,unchangingvalueasakeytoaccessanelementsvalue. Typically,thekeyisspecifiedasastring,butintegerscanalsobeused.Forexample,Eventarraysuse integersaskeys. Nestedpropertiescanalsorefertopropertiesthatarekeybasedarrays.Forexample, a.b.c["xyz"]refers tothepropertycthathasthekeyvalueofxyz. TheVMwarevSpheremanagementobjectmodeluseskeybasedarraystokeeptrackofmanagedobject references.Thecontentsofakeybasedarraypropertyareaccessedbythevalueofeitherthekeypropertyor, inthecaseofamanagedobjectreference,itsvalueproperty.Thevalueofthesefieldsisuniqueacrossallthe componentsofanarray.
Accessing the API on the Web Service

ThevSphereAPIisavailableonESX/ESXiandvCenterServersystems,asasecureWebservice,availableover HTTPSatport443.AsistypicalofotherWebservicesclientapplicationdevelopmentprojects,developing clientapplicationsusingthevSphereWebServicesSDKrequiresaccesstotheWebServicesDescription Language(WSDL)filedescribingtheoperationsanddatatypesavailableontheWebservice.
50
VMware, Inc.
ThevSphereWebServicesSDKincludestheWSDLthatdefinestheAPI. IMPORTANTThevSphereWebServicesSDKshipswithJavaclientsideproxycodethathasbeengenerated usingtheAxistoolkit.IftheversionsofJavaandAxisonyourdevelopmentplatformarethesameasthose usedtogeneratethestubsshippedintheSDK,youdonothavetogenerateclientsideproxycodefromthe WSDL.SeetheDevelopersSetupGuideforinformationaboutconfiguringadevelopmentenvironmentforthe vSphereWebServicesSDK. TheVMwareclientlibrariesmustbeimportedintoclientapplications(Table 53). Table 5-3. Import Statements for Including the vSphere API Client Library
Java import com.vmware.vim25.*; C# usingVimApi;
TheAPIisdocumentedinthevSphereAPIReference,whichisincludedintheVMwarevSphereWebServices SDKpackage.
Using the vSphere API Reference

ThevSphereAPIReferenceistheHTMLreferencedocumentationgeneratedfromtheVMwarevSphereobject modelinterfacedefinitions.Thisdocumentationsetisalanguageneutralreferencethatprovidescomplete informationaboutalldatastructuresthatmakeuptheVMwarevSpheremanagementframeworkmanaged objecttypes,dataobjecttypes,faulttypes,enumerations,andassociatedpropertiesandoperationsavailable throughtheWebservice. TheAPIreferencedocumentationisavailableinthe\SDK\doc\ReferenceGuidesubdirectoryofthevSphere WebServicesSDKpackage. ThevSphereAPIidentifiesdeprecatedtypesandmethodsandprovidescrossreferencestothenewproperty, operation,ortype.
Identifying Deprecated Items in the vSphere API Reference

Thedeprecatedlabelonatype,operation,orpropertydocumentedinthevSphereAPIReferencemeansthata new,betterwaytomeetaspecificrequirementisavailable.Forexample,VIAPI2.5deprecatedthe HostSystemmanagedobjecttypesQueryMemoryOverheadoperation,infavorofanewoperation, QueryMemoryOverheadEx.Althoughclientapplicationsusingdeprecatedfeaturescontinuetowork,VMware recommendsthatyouusethenewtype,operation,orproperty(ratherthanthedeprecation)fornewclient applicationdevelopment.
Identifying Version Information in the vSphere API Reference

VersioninformationinthevSphereAPIReferenceisavailablestartingwithAPI2.5andsubsequentreleases. If thevSphereAPIReferencedocumentationdoesnotincludetheversionlabel,youcanassumeitissupported onAPI2.0andpriorreleases.NewfeaturesinthisreleaseareidentifiedasSincevSphereAPI4.0,for example.Theversioninformationisusefulespeciallyforclientapplicationsthatmusttargetmultipleversions ofVMwarevSphereservers,someofwhichmaysupportfeaturesprovidedinoneversion,butnotinanother.
Mapping the WSDL to the Client-side Proxy Code

ClientapplicationdevelopersuseSOAPtoolssuchasAxisWSDL2Java,orMicrosoft.NETwsdl.exeto generateclientsideproxycodefromtheWSDL.Thegeneratedproxycodehandlestheremotemethod invocation,datatypemappingfromservertoclient,andothersuchdetails. Thegeneratedclientsideproxycodeincludesaccessor(getter)andmutator(setter)methodsforeachproperty definedinserversidedataobjecttypes.
VMware, Inc.
51
Table 54showsanexampleofthemethodsignaturesasdefinedintheJavaandC#clientproxycodeforthe AfterStartupTaskSchedulerdataobjectsminuteproperty. Table 5-4. Example of Generated Accessor and Mutator Methods in Client Proxy Code
Data Object AfterStartup TaskScheduler Property minute Type xsd:int Java public int getMinute() { return minute; } public void setMinute(int minute) { this.minute = minute; } C# public int minute { set; get; }
YoucanextrapolatefromthedocumentationintheVMwarevSphereAPIReferencetoidentifygetterandsetter methodsthatareavailabletoyourclientapplication,withoutexaminingthe*.java,*.cs,orothergenerated clientsidestubstofindtheactualmethods. Forexample,giventhattheManagedObjectReferencedataobjecttypehasatypeproperty,youcansafely assumethatyoucanassignavaluetoamanagedobjectreferencebyusingsetType,passingoneofthevalid stringvaluesasaparameter.YoucanobtainthestringvaluebyusinggetType. Table 55showssomevalidstringvaluesamanagedobjectreferencedataobjectcanacceptorreturn. Table 5-5. ManagedObjectReference Data Object Default Methods and Valid String Values
Property (Datatype) type (string) Default Getter Method getType Default Setter Method setType Valid values Alarm,"AlarmManager","AuthorizationManager", "ClusterComputeResource","ComputeResource", "ContainerView","CustomFieldsManager",andsoon. See completelistofsupportedvaluesinTable 51.
Asanotherexample,theServiceContentdataobjecthasanaboutpropertythatisdefinedasaninstanceof theAboutInfodataobjecttype.ByexaminingtheAPIReference,youseethattheAboutInfodataobjecthas severalotherproperties,includingapiVersionandapiType,bothofwhicharedefinedasxsd:stringdata types.Thesedetailsprovidethefollowinginformation: Theclientstubscontaingetterandsettermethodsfortheproperties(getApiVersion,setApiVersion, getApiType,setApiType). Thedatatypethatcanbeacceptedasinputtoandreturnedbythesemethodsisastring. ThemethodscanbeinvokedoninstancesoftheServiceContentobject. SeeChapter 6,ClientApplicationPattern,onpage 59formoreinformation.
Obtaining Values from Nested Properties

Accessingnestedpropertiesrequiresdotnotationfromthetoplevelobjecttotheembeddedobject(see NestedPropertiesandPropertyPathsonpage 49).Thedatatypeoftheresultdependsonthedatatypeat theendoftheseries.Forexample,toobtainthevalueofaspecificvirtualmachinespowerState:
VirtualMachineRuntimeInfo().powerState()
Inaddition,yourcodemustbesetuptohandlethespecificdatatypereturnedbyanymethodinvocationor byobtainingthepropertyvalue.Forexample,intheseriesa.b.c,ifcisaninteger,yourcodemustbe preparedtohandleaninteger.Ifcisadataobjecttype,thenyouobtainaninstanceofthattype.Ifcisa ManagedObjectReference,yougetaninstanceofaManagedObjectReference.

... private ServiceContent =_sic; private String myServerVersion; ... myServerVersion = _sic.getAbout().getApiVersion(); ...
52
VMware, Inc.
Mapping XML Datatypes to Java and C# Datatypes

Tosimplifythepresentation,theUMLclassandobjectdiagramsinthisguideusetheprimitivedatatype namessuchasstringandinteger,withouttheXMLSchemadefinitionnamespaceprefix(xsd:).ThevSphere APIReferencecontainsthecompletedatatypename,suchasxsd:string.Thedatatypesmaptotheprimitive datatypesoftheprogramminglanguageusedfortheclientapplication. Table 56listssomeofthemorecommonXMLprimitivedatatypemappings. Table 5-6. Standard XML Schema Primitives to Java and .NET Data Type Mappings
XML Schema xsd:base64binary xsd:boolean xsd:byte xsd:dateTime xsd:decimal xsd:double xsd:float xsd:int xsd:string Java byte[] boolean byte java.util.Calendar java.math.BigDecimal double float int java.lang.String .NET Data Type Byte[] Boolean SByte DateTime Decimal Double Single Int32 String
De
Escape Character Used in Name and Path Properties

Thepercentsign(%)isusedasanescapecharactertoembedspecialcharactersinstrings.Forexample,%2f (or%2F)isinterpretedastheslash(/)character.Toincludeapercentsignasaliteralinastring,use%%.The pathtotheinventorystartsfromtherootfolder(rootFolderpropertyofServiceContent),denotedbythe /(slash)character. Table 5-7. Special Characters
Character % / \ . Description Percentsign Slash Backslash Dash Dot Doublequotationmark Representation in URL %25 %2F,%2f %5C,%5c %2D,%2d %2E,%2e %2B,%2b
Invoking Operations through the MOB

ThissectiondiscusseshowtopassvaluestotheserverusingtheMOB.YoucanusetheMOBtonavigatethe objectsontheserverandinvokeoperations.AnychangesyoumakethroughtheMOBtakeeffectontheserver. TheexamplesinthissectioninvokevariousqueryoperationsofthePerformanceManagerAPItodemonstrate howtopassprimitivedatatypes,arrays,andcomplexdatatypes(dataobjects,includingmanagedobject references)usingtheMOB. CAUTIONTheMOBisnotareadonlymechanism.ByclickingtheInvokeMethodlinkintheMOB,youmight changetheserverstate(dependingontheoperation).Ontheotherhand,manyoperationsarequeryonly operationsthatonlyreturnobjectsfromtheserver. InputfieldsfortheMOBarepresentedassingleentrytextfieldsorasscrollabletextareas.Atextfieldaccepts primitivedatatypes.Thescrollabletextareasareforenteringarraysandcomplextypes.Theremainderofthis sectiondiscusseshowtoentervaluesusingtheMOB.
VMware, Inc.
53
Passing Primitive Datatypes to Operations through the MOB

ThedatatypesaredefinedintheWSDLusingXMLSchemamarkup.Theprimitivedatatypesarespecified usingthexsdnamespace.Forexample,astringvalueforapropertyisdefinedasdatatypexsd:string. The APIReferencedocumentationprovidesthisdetail.ToenteraprimitivevalueintheMOB,enterthevalue asplaintext,withoutanyquotationmarksorothermarkup.Forexample,toenteranintegervalueof10,type 10inthefield. Figure 53showsanexample.Toobtaininformationabouttheavailableperformancecountersatlevel4onthe server,entera4inthelevelfieldoftheQueryPerfCounterByLeveloperation.(Thisoperationisavailable onlyonthevCenterServerPerformanceManagerAPI,notfromanESX/ESXisystem.) Figure 5-3. Using the MOB to Pass Primitive Datatypes to an Operation, as a Parameter
Figure 54showstheresultsofsubmittingthequery.ThearrayofPerfCounterInfodataobjectsandnested objects,withpopulatedvaluesfromtheserver,displaysintheWebbrowser. Figure 5-4. Example of Returned Object Displayed in the MOB
Passing Arrays of Primitives to Operations through the MOB

Foranarray,usethenameoftheparameterasthenameofthepropertyasifitwereanXMLelement,byusing openingandclosingtagsmadeupoftheparametername.Forexample,theQueryPerfCounteroperationof PerformanceManagerrequiresanarrayofintegersforthecounterIdparameter.Heresanexample:
<counterId>58</counterId><counterId>65603</counterId><counterId>65604</counterId>
Evenifyouwanttosubmitasinglevalueforasinglearrayelement,youmustwraptheparametername aroundthevalueinthisway.
Passing Complex Structures to Operations through the MOB

Forcomplexdatatypes,enterthevalueasdefinedbytheXMLSchemaintheWSDL.YoucanobtaintheWSDL definitionfromthevSphereAPIReferenceusingtheShowWSDLtypedefinitionlinks.Eachdataobjecttype hasanassociatedlink.
54
VMware, Inc.
Simple Content ThedataobjecttypeManagedObjectReferenceisoneofthemostcommonlyrequiredparameterstobe passedtotheserver.Forexample,theMOBfortheQueryPerfProviderSummaryoperationin PerformanceManagershowsthattheoperationrequiresasingleparameter,themanagedobjectreference(an instanceofManagedObjectReference)oftheentityforwhichyouwanttoobtainthePerfProviderSummary object. UsingthevSphereAPIReferenceforManagedObjectReferencetype,youcanobtaintheschemainformation fromtheShowWSDLtypedefinitionlinkatthebottomofthedocumentationpagefor ManagedObjectReference. Example 5-1. XML Schema Definition of ManagedObjectReference Data Object
<complexType xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ManagedObjectReference"> <simpleContent> <extension base="xsd:string"> <attribute name="type" type="xsd:string"/> </extension> </simpleContent> </complexType>
Example 51showsthatamanagedobjectreferenceisdefinedasa<SimpleContent> elementthatconsists ofastringthatshouldspecifytheattributetypewithitsassociatedvalue,alsoasstring.Usethisinformation toconstructtheappropriatestructurebyreplacingtypewiththeparameternamefromtheMOB,settingthe valueasneeded,andsubmittingintheentryfieldoftheMOB.(ThevaluefortheDatacenterisdisplayedin theMOB.)

<entity type=Datacenter>datacenter-21</entity>
Figure 55showstheresultofusingthedefinitionlistedinExample 51tospecifythemanagedobject referenceforatargetdatacentertotheQueryPerfProviderSummaryoperation. Figure 5-5. Using the MOB to Pass Complex Types to an Operation as a Parameter
Asanotherexample,oneoftheparametersrequiredbytheCloneVM_Taskoperation(oftheVirtualMachine managedobject)isafolder.Inthiscase,theparameterisdefinedasamanagedobjectreferencetoaspecific Folderobject.UsingthesamedefinitionshowninExample 51,theresultisasfollows:

<folder type=Folder>folder-87</folder>
AlthoughbothexamplessubmitaManagedObjectReferencetotheMOB,eachisspecifictotheparameter namerequiredbytheoperation(entitytypeforQueryPerfProviderSummaryoperationin PerformanceManager,foldertypefortheCloneVM_TaskoperationinVirtualMachine). Complex Content Unlikethe<simpleContent>showninExample 51,manyofthedataobjectsrequiredfortheMOBconsist ofXMLSchemaelementsdefinedas<complexContent>thatmayencompassmanyotherelements. Forexample,theCreateFilteroperationinPropertyCollectorhasaspecparameterthatmustbedefined priortoinvokingtheoperation.ThespecparameterisdefinedasaninstanceofaPropertyFilterSpec.
VMware, Inc.
55
Figure 56showstherelationshipsamongseveraldataobjectsthatPropertyFilterSpecconsistsof. Figure 5-6. PropertyFilterSpec and Associated Data Objects
TosubmitcomplexdatastructuressuchasthistotheMOB,startbynavigatingthevSphereAPIReference.Find thePropertyFilterSpecdataobject.FindtheShowWSDLtypedefinitionlink,andclickittodisplaythe XMLSchemadefinition(seeExample 52). Example 52showsthatthePropertyFilterSpecdataobjectisa<complexContent>elementthatextends theDynamicDataclasswithasequenceoftwoadditionalproperties(propSet,objectSet),eachofwhichhas itsowntypedefined(PropertySpecandObjectSpec,respectively). Example 5-2. XML Schema Definition of PropertyFilterSpec Data Object Type
<complexType xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="PropertyFilterSpec"> <complexContent> <extension base="vim25:DynamicData"> <sequence> <element name="propSet" type="vim25:PropertySpec" maxOccurs="unbounded"/> <element name="objectSet" type="vim25:ObjectSpec" maxOccurs="unbounded"/> </sequence> </extension> </complexContent> </complexType>
Becausebothelementsaredefinedasasequence,theymustexistintheorderlisted.Toobtainthedefinitions ofpropSetandobjectSet,youmustnavigatefurtherintothevSphereAPIReference.Example 53showsonly therelevantpartsoftheXMLSchemadefinitionforPropertySpec.TheminOccurs=0attributemeansthat theelementdoesnothavetoexist.ThemaxOccurs=unboundedattributedenotesthattheelementcanbe populatedasanarrayofanysize.(WhenminOccursisnotsetbutmaxOccursisset,thedefaultforminOccurs defaultsto1,meaningoneinstanceisrequired.) Example 5-3. XML Schema Extract for PropertySpec
<sequence> <element name="type" type="xsd:string"/> <element name="all" type="xsd:boolean" minOccurs="0"/> <element name="pathSet" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/> </sequence>
56
VMware, Inc.
NavigatethroughthevSphereAPIReferencetotheObjectSpecdefinition.Example 54showstheexcerpt. Example 5-4. ObjectSpec Definition as XML Schema

... <sequence> <element name="obj" type="vim25:ManagedObjectReference"/> <element name="skip" type="xsd:boolean" minOccurs="0"/> <element name="selectSet" type="vim25:SelectionSpec" minOccurs="0" maxOccurs="unbounded"/> </sequence> ...
ExtrapolatingfromtheWSDLdefinitionsshowninExample 52,Example 53,andExample 54might produceresultssimilartothoseshowninExample 55. Example 5-5. CreateFilter Spec Property Entry
<spec> <propSet> <type>VirtualMachine</type> <all>false</all> <pathSet>config.guestFullName</pathSet> </propSet> <objectSet> <obj type=Folder>group-v4</obj> <skip>true</skip> </objectSet> </spec>
Inthisexample,the<spec> elementidentifiesthespecparameteroftheCreateFilteroperation.Theorder oftheelementtagsisasdefinedintheXMLSchemafortheproperty(Example 52).ThepathSetproperty definesthefullpathtothenesteddataobjectofinterest.InExample 55,thepathSetpropertydefinesthepath totheguestFullNamepropertyofthetargetvirtualmachine.Figure 57showstheUMLofthesenesteddata objects. Figure 5-7. Nested Data Objects
VMware, Inc.
57
AllthesedetailsarepresentedinthevSphereAPIReference.ByexaminingtheWSDLdefinition,youcan constructthestringsneededtosubmitparametersthroughtheMOB.Table 58providesabriefsummaryof thestepsinvolvedwhenyouusetheMOBandthevSphereAPIReferencetogether. Table 5-8. Comparison of Datatypes for MOB Usage
Datatype Primitive Array Complex How to Input Values for Operations Enterthevalueasplaintextregardlessofitsdatatype(int,string,boolean).Donotusequotation marksorothermarkup. Usingthenameoftheparameterasthenameoftheelement,wrapthevaluesinaseriesofopeningand closingtagsforeacharrayelement. ObtainXMLSchemaformatinformationfromthevSphereAPIReferenceforthetype(fromtheShow WSDLtypedefinitionlink). Usetheschemadefinitiontoconstructthesequenceoftagsaroundthevalue(orvalues)youwanttopass totheMOB.
58
VMware, Inc.
Client Application Pattern
AnyclientapplicationthatyoucreateusingthevSphereWebServicesSDKmustconnecttotheserver,pass theappropriateuseraccountcredentialstoauthenticatetotheserver,andobtainingasessionfromtheserver. Thisgeneralpatternisdescribedinthischapter.Thechapterincludesthesetopics: MinimalClientApplicationPatternonpage 59 OverviewofaJavaSampleApplicationonpage 61 SavingandReusingaWebServerSessionTokenorCookieonpage 63 SupportingMultipleAPIVersionsonpage 63 HelperClassesforSampleApplicationsonpage 64
Minimal Client Application Pattern

Regardlessoftheprogramminglanguageusedfordevelopment,clientapplicationsthattargetthevSphere APItypicallyfollowthisbasicpattern: 1 2 3 4 5 ObtainasessiontokenandcreateaconnectiontotheWebService. InstantiatelocalproxyobjectforreferencetoServiceInstance. Logintotheserverusingappropriatecredentials. Processtheobjects. Closetheconnection.
Example 61providesashortclientapplicationthatfollowsthisbasicpattern.
Connecting to the Web Service

ToestablishaconnectionwiththeWebservice,youmustfirstpassintheuniformresourcelocator(URL)of theWebservice,useraccount,andpassword,intheconnectionstring. CAUTIONAlwaysgothroughavCenterServersystemtoperformoperationsonmanagedESX/ESXihosts. Invokingoperationsonmanagedhostsdirectly(ratherthanthroughvCenterServer)cancauseproblems.
Obtaining a Session Token and Creating a Connection Object

AswithotherWebservices,thevSphereWebservicemaintainssessionstateforeachclientconnectionby usingatokenintheHTTPheadertoidentifythesession.Thissessiontokenisreturnedtotheclientfromthe Webserviceandisthenusedtransparentlyinthemessagessentbetweenclientandserver.
VMware, Inc.
59
Table 61showstwoexamplesofsessiontokensreturnedfromconnectionstoVirtualCenterServer2.5and ESX/ESXi3.5. Table 6-1. Session Tokens as Strings

vCenterServer ESX/ESXi vmware_soap_session="63869259-F0FF-4DB5-9B3B-6493212AB9CD" vmware_soap_session="52b1910a-31ad-df35-95d1-210f86c55efb"
Witheveryconnection,theidentifierispassedintheHTTPheaderfromtheclienttotheserver.Sessiontokens canbepassedacrossmultipleconnectionstotheWebservice.Bydefault,sessionsexpireafter30minutesof inactivity,butthevaluecanbechanged.Forexample,tosetthetimeoutvalueto45minutes(2700seconds)of inactivity:

... _locator = new VimServiceLocator(); _locator.setMaintainSession(true); _service = _locator.getVimPort(new URL(url)); ((org.apache.axis.client.Stub)_service).setTimeout(2700); ...
TheWebservicessessiontokencanbesavedtoafileforlateruse.Forexample,ifyourclientapplicationis multithreaded,savethesessionanduseitforeachthreadintheapplication.SeeIntroductiontothe CredentialStore,inChapter 7,AutomatingClientApplicationLogin,onpage 67formoreinformation.
Logging In to the Server

AfterobtainingtheWebserversessiontoken,logintotheserverbypassingitavaliduseraccountand password,andsettingthelocale.Youcanpassanullvalueforthelocale.Theresultoftheloginprocessisa connectionobject. NOTESeeIntroductiontotheCredentialStoreonpage 67forinformationaboutthevSphereWebServices SDKcredentialstore,whichcanbeusedtostreamlinetheauthenticationprocessandmitigatetheriskthat administratorsorotherusersofyourclientapplicationsmightstorepasswordsinscriptsorotherfiles,such ascronorWindowsTaskdefinitions. Setting the Locale TheLoginoperationofSessionManagerhasanoptionalstringparameterforlocale.Example 61,Simple JavaClientApplication,onpage 61leavesthevalueforthelocaleunset:
_service.login(_sic.getSessionManager(), userName, password, null);
Whenthisoptionalparameterisnotprovided,theoperationusestheserverdefaultlocale. Tosetaspecificlocale,passtheappropriatestringvaluethatidentifiesthetwocharacterISO639languageID (forexample,en).YoucanalsoincludeanoptionaltwocharacterISO3166countryID.Forexample,en_US, de,fr_CA,zh,zh_CN,orzh_TW.

_service.login(_sic.getSessionManager(), userName, password, "en");
Alternatively,youcanuseSetLocaleoperationoftheSessionManagertosetthelocaleinaseparatestep.
Close the Server Connection

Forsecurityreasons,alwayscloseyourconnectionstotheserverwhentheapplicationcompletesitswork:
_service.logout(_sic.getSessionManager()); _service = null; _sic = null;
60
VMware, Inc.
Chapter 6 Client Application Pattern
Overview of a Java Sample Application

Example 61isacompleteclientapplicationthatdemonstratesthisminimalclientpattern.Thesampledoes notusethehelperclassesdiscussedinHelperClassesforSampleApplications,nordoesitfollowbest practices.Itdoesnothandleexceptions,forexample,anditusestheSunFakeTrustSocketFactoryclassto facilitatethesecuresocketslayer(SSL)handshakewithoutusingalocalJavaSSLcertificate.Thistechniqueis recommendedfordevelopmentenvironmentsonly.Donotusethistechniqueforproductionapplications. Example 61demonstratesthefollowingcommonclientapplicationtasks: Connectingtotheserver CreatingalocalmanagedobjectreferencetoServiceInstance ObtainingsomebasicinformationabouttheserveravailablefromtheServiceContentdataobject, withoutusingaPropertyCollector. Example 6-1. Simple Java Client Application
import com.vmware.vim25.*; import java.net.URL; public class MyClient { private ManagedObjectReference _svcRef; private VimServiceLocator _locator; private VimPortType _service; private ServiceContent _sic; private String fileName; private void createServiceRef() throws Exception { _svcRef = new ManagedObjectReference(); _svcRef.setType("ServiceInstance"); _svcRef.set_value("ServiceInstance"); } private void connectAndLogin(String hostName, String userName, String password) throws Exception { System.setProperty("axis.socketSecureFactory", "org.apache.axis.components.net.SunFakeTrustSocketFactory"); String url = "https://"+hostName+"/sdk/vimService"; createServiceRef(); _locator = new VimServiceLocator(); _locator.setMaintainSession(true); _service = _locator.getVimPort(new URL(url)); _sic = _service.retrieveServiceContent(_svcRef); if (_sic.getSessionManager() != null) { _service.login(_sic.getSessionManager(), userName, password, null); } System.out.println(_sic.getAbout().getFullName()); System.out.println("API type is " + _sic.getAbout().getApiType()); System.out.println("API version is " + _sic.getAbout().getApiVersion()); } public static void main(String [] args) throws Exception { MyClient obj = new MyClient(); String serverName = args[0]; String userName = args[1]; String password = args[2]; obj.connectAndLogin(serverName, userName, password); } }
VMware, Inc.
61
Connectingtoaserverandobtainingamanagedobjectreferencerequiresthatanapplicationperforma numberoftasks,illustratedinExample 61. To connect to a server and obtain a managed object reference to the ServiceInstance 1 DefinealocalproxyobjectforthevimServiceport(vimServiceLocator,VimPortType).InJava,the variabledefinitionsmightlooklikethis:
private VimServiceLocator _locator; private VimPortType _service; ... _locator = new VimServiceLocator(); _locator.setMaintainSession(true); ...
2 3
Connecttotheserver,passingtheURL,useraccount,andpassword. CreateamanagedobjectreferencetoServiceInstance.ThecreateServiceRef()methodin Example 61createsthemanagedobjectreferencetoServiceInstanceandassignsitto_svcRef:

_svcRef = new ManagedObjectReference(); _svcRef.setType("ServiceInstance"); _svcRef.set_value("ServiceInstance");
ToobtaintheServiceContentobject,the_svcRefmanagedobjectreferenceisusedintheinvocationon thelocalserviceproxyobject(_service):
_sic = _service.retrieveServiceContent(_svcRef);
AftercheckingthataninstanceofSessionManagerexistsforthecurrentServiceContentobject,the examplecodeinvokestheloginmethodonthelocalproxyobject(_service).The _sic.getSessionManager()effectivelypassesthemanagedobjectreferenceofthecurrent SessionManagerinstancetotheloginmethod,alongwiththeusernameandpassword:

if (_sic.getSessionManager() != null) { _service.login(_sic.getSessionManager(), userName, password, null);
ThenullvalueintheargumentlistisfortheLoginoperationslocaleparameter. 6 Obtaintherootfolderoftheinventory,obtainareferencetooneormoreofthemanagers (PerformanceManager,forexample),andperformothertasksdefinedbyyourapplication.In Example 61,theonlyrealtaskperformedbytheapplicationisobtainingtheaboutpropertyfromthe ServiceContentdataobjectandprintingoutsomeofthevaluesfromtheAboutInfodataobject instance:

System.out.println(_sic.getAbout().getFullName()); System.out.println("API type is " + _sic.getAbout().getApiType()); System.out.println("API version is " + _sic.getAbout().getApiVersion());
Thecompiledclassisexecutedasfollows:
C:\>java MyClient pubslab01.vmware.com tooluser password
Table 62showstheoutputfromrunsofExample 61targetingESX/ESXiandvCenterServersystems. Table 6-2. Sample Runs of Simple Client Application
ESX VMware ESX 4.0.0 build-139526 API type is HostAgent API version is 4.0 vCenter Server VMware vCenter Server 4.0.0 build-139524 API type is VirtualCenter API version is 4.0
62
VMware, Inc.
Saving and Reusing a Web Server Session Token or Cookie

InExample 61,thesessiontokenisnotexplicitlyhandledbytheclientapplication.However,afteryourclient applicationobtainsasessiontoken,youcansaveittoalocalfile,forreuselater.Example 62showsan exampleofusingJavaandAxisclientlibrariestoobtainthesessiontokenfromthecurrentSOAPmessage context,andcastingittoaString.WiththesessiontokeninStringform,youcansaveitlocallytoafileon theclientforsubsequentreuse.Inyourconnectionsetupcode,youcancheckforanexistingsessionfileand usethatsessionfilewhenitsappropriatetodoso. Example 6-2. Obtaining Session Token from the Web Services Context
org.apache.axis.client.Stub clientStub = (org.apache.axis.client.Stub)_service; org.apache.axis.client.Call callObj = clientStub._getCall(); org.apache.axis.MessageContext msgContext = callObj.getMessageContext(); String sessionString = (String)msgContext.getProperty( org.apache.axis.transport.http.HTTPConstants.HEADER_COOKIE);
ThesampleapplicationsincludedwiththevSphereWebServicesSDKincludebothC#andJavahelperclasses thathandlethedetailsofcreatingsessions,obtainingsessiontokens,savingthesessionasastringtoafile,and reusingthesession.TheMicrosoft.NETWebservicesimplementationusestheCookieclasstohandlethe sessioninformationfromtheserver.
Supporting Multiple API Versions

WhenaclientapplicationconnectstoaWebservicerunningonanvSphereserver(ESX/ESXiorvCenterServer system),theserverdetectstheversionoftheAPIthatwasusedtodeveloptheclientandmakesavailableonly thoseoperationssupportedbytheclient. ClientapplicationsconveyinformationabouttheAPIversionusedintheSOAPmessagestheysendtoa vSphereserver.TheseSOAPmessagesincludeaversionIDinthesoapActionattribute.Thedetailsare handledtransparentlybytheSOAPtoolkitandtheclientproxycode.Theserveradjustsitsbehaviorasneeded basedontheclientsversioninformation,exposingtotheclienttheAPIversionsupportedbytheclient. StartingwithvSphere4.0,informationaboutthesupportedAPIversionsiscontainedinanXMLfile, vimServiceVersions.xml,locatedontheserver(Example 63). Example 6-3. Service-Versions File (vimServiceVersions.xml)
<?xml version="1.0" encoding="UTF-8" ?> - <!-Copyright 2008 VMware, Inc. All rights reserved. --> - <namespaces version="1.0"> - <namespace> <name>urn:vim25</name> <version>4.0</version> - <priorVersions> <version>2.5u2</version> <version>2.5</version> </priorVersions> </namespace> - <namespace> <name>urn:vim2</name> <version>2.0</version> </namespace> </namespaces>
Ifyouaredevelopingaclientapplicationthatmustsupportmultipleserverversionsatthesametime (ESX/ESXi4andESX/ESXi3.5,forexample),youmustobtaininformationabouttheAPIversionsthatare supportedontheserverandprovidelogicinyourcodetouseornotusefeatures,basedupontheversion information.
VMware, Inc.
63
ThevSphereWebServicesSDKpackageincludesseveralsampleapplicationsdemonstratinghowtowork withmultipleserverversions(Table 63). Table 6-3. Sample Applications that Demonstrate Working with Multiple API Version
Java SDK\samples\Axis\java\com\vmware\samples\version displaynewproperties displaynewpropertieshost displaynewpropertiesvm getvirtualdiskfiles hostpowerops installhostpatch querymemoryoverhead recordsession apputils\version C# SDK\samples\DotNet\cs\ DisplayNewProperties DisplayNewPropertiesHost DisplayNewPropertiesVM GetVirtualDiskFiles HostPowerOps ~ QueryMemoryOverhead RecordSession AppUtil\VersionUtil.cs
Identifying the API Version Supported by the Server

OneapproachtotargetingmultipleversionsoftheAPIfromthesameclientapplicationcodeistocheckfor theexistenceoftheserverversionsfileontheserver.IfyoudonotfindavimServiceVersions.xmlfileonthe server,youcanassumethattheserverisnotESX/ESXi4.0orvCenterServer4.0. Example 64isanexcerptfromtheVersionUtil.javasamplethatdemonstratesthisgeneralapproach. See thegetTargetNameSpaceAndVersion()methodofVersionUtil.javalocatedinthevSphereWeb ServicesSDKpackageformoreinformation. Example 6-4. Determining the URL from Which to Obtain the API Version Information
try { String wsdlUrlString = ""; String vimServiceXmlUrlString = ""; if((urlString.indexOf("https://") !=-1) || (urlString.indexOf("http://") !=-1)){ wsdlUrlString = urlString.substring(0,urlString.indexOf("/sdk")+4) + "/vimService?wsdl"; vimServiceXmlUrlString = urlString.substring(0,urlString.indexOf("/sdk")+4) + "/vimServiceVersions.xml"; } else{ wsdlUrlString = "https://"+ urlString + "/sdk/vimService?wsdl"; vimServiceXmlUrlString = "https://"+ urlString + "/sdk/vimServiceVersions.xml"; }
Helper Classes for Sample Applications

ThevSphereWebServicesSDKincludesmanysampleapplications,writteninC#andinJava,that demonstratefeaturesofthevSphereAPIandobjectmodel.Thesamplesrelyonseveralutilityclasses(or helperclasses).Thehelperclassesformthebasisofconsolestyle,commandlineapplications.Theseclasses (listedinTable 64andTable 65)handlecommandlineinputsuchascommonparameters,servername,and otherdetails.ThesehelperclassesarelocatedintheunpackedSDKdownload,intheselocations: Java Helper Classes %SDKHOME%\samples\Axis\java\apputils C# Helper Classes %SDKHOME%\samples\DotNet\cs\AppUtil
64
VMware, Inc.
Java Helper Classes

Table 64summarizestheJavaversionsoftheclienthelperclasses. Table 6-4. Helper Classes for Java Sample Applications
Package com.vmware.apputils Java Class ClientUtil.java Functional Description Providesconveniencemethodsforhandlinguser inputfromcommandline.Catcheserrors(faults). Logsoutputtoconsole. ProvideswrappermethodsforthevimService methods(thelocalproxycodemethods). CreatesinstancesofServiceConnectionand AppUtil,handlesconnectiontotheserviceand Supportsobtaininginitialmanagedobjectreferences forrootfolderandallitsdescendents. com.vmware.apputils.vim ServiceConnection.java Createsaninstanceoflocalproxyforconnectingto theserver,andobtainsmanagedobjectreferencesto severalmanagedobjects(ServiceInstance, ServiceContent,rootFolder)thatserveas startingpointsforobtainingobjects. Includesmethodsforsavingsessionsforreuseand loadingsavedsessions. IncludesignoreCertmethodforcircumventingthe localSSLcertificatehandling. com.vmware.apputils com.vmware.apputils.version AppUtil.java VersionUtil.java Setsuplogging,instantiateslocalClientUtil.Uses thecredentialstore. IdentifiestheversionoftheWSDLontheserver. ExtractspriorAPIversioninformationfromthe vimServiceVersions.xmlfileontheserver(ifit exists). ExtendstheAppUtilclasswithadditional functionalityforhandlingmultipleAPIversions. Conveniencemethodsforworkingwithvirtual machineobjects.Provisioning,lifecycle management.
com.vmware.apputils.vim
ServiceUtil.java
com.vmware.apputils.version com.vmware.apputils.vim
ExtendedAppUtil.java VMUtils.java
C# Helper Classes
Table 65liststhehelperclassesavailableforC#. Table 6-5. Helper Classes for C# Sample Applications
AppUtils AppUtil.cs ClientUtil.cs OptionSpec.cs ServiceUtil.cs ServiceUtilV25.cs TrustAllCertificatePolicy.cs Functional Description Conveniencemethodsforhandlinguserinputfromcommandline.Catcheserrors (faults).Logsoutputtoconsole. Conveniencemethodsforhandlinguserinputfromcommandline.Catcheserrors (faults).Logsoutputtoconsole. Helperclassforhandlingdefaultandcustomcommandlinearguments. WrappermethodsforthevimServicemethods(thelocalproxycodemethods)for API2.0andpriorreleases. WrappermethodsforthevimServicemethods(thelocalproxycodemethods)for API4.0,API3.5U2,API3.5U1,API3.5,andotherrecentreleases. Createsaninstanceoflocalproxyforconnectingtotheserver,andobtains managedobjectreferencestoseveralneededmanaged objectsServiceInstance,ServiceContent,rootFolder. HelperclassforidentifyingAPIversion.
VersionUtil.cs
VMware, Inc.
65
66
VMware, Inc.
Automating Client Application Login
Clientapplicationsthatlaunchautomaticallyforunattendedoperation,suchasasoftwareagentorcronjob, requirespecialtreatmenttofacilitatethelogonprocess.Noninteractiveclientapplicationslendthemselvesto poorsecuritypractices.Forexample,administratorsmaystorepasswordsinscriptorbatchfiles,tologin automatically. Tofacilitateautomatedloginforunattendedapplications,thevSphereWebServicesSDKincludesclientside credentialstorelibrariesandtoolsforautomatingtheloginprocessinamoresecuremanner.Theclient librariesobviatetheneedforsystemadministratorstokeeppasswordsinlocalscripts.Thischaptercontains informationaboutusingcredentialstorelibraries,andaboutcreatinguseraccountstousethesetools. The chapterincludesthesetopics: IntroductiontotheCredentialStoreonpage 67 OverviewoftheCredentialStoreBackingFileonpage 68 SecurityBestPracticesandtheCredentialStoreonpage 69 UsingtheCredentialStoreAdminToolonpage 70 UsingAuthorizationManagertoLimitAccessonpage 70
Introduction to the Credential Store

ThecredentialstoreincludedinthevSphereWebServicesSDKenablesmoreadvancedclientapplication capabilities,suchasautomatedlogintoservers.TheSDKincludesbothC#andJavaclientlibraries(Table 71) thatyoucanuseinyourownapplicationstosimplifytheloginandauthenticationprocess.Thecredentialstore includes: Apersistencefile(credentialstorebackingfile)thatstoresauthenticationcredentials.Currently,only passwordsaresupported.ThepersistencefilemapsaremoteuseraccountfromanESX/ESXihosttothe passwordforthatuserontheserver. C#,Java,andPerllibrariesformanagingthecredentialstoreprogrammatically.SeeTable 72foravailable methods. JavaandMicrosoftPowerShellbasedcommandlineutilitiesformanagingthecredentialstore. Table 7-1. Credential Store Client API Libraries
Namespace VMware.Security.CredentialStore(C#) CredentialStoreFactory.cs ICredentialStore.cs Package com.vmware.security.credstore (Java) CredentialStore.java CredentialStoreFactory.java
VMware, Inc.
67
Severalofthehelperclassesprovidedwiththesampleapplicationsusethecredentialstoremechanism. Table 7-2. Credential Store Client API Methods

Java addPassword(hostname, username, password) C# AddPassword(hostname, username, password) Description Storesthepasswordforthespecifiedhost anduser.Overwritesanyexisting passwordfortheuserifonealreadyexists inthecredentialstore.Createsthedefault credentialstorebackingfileinthedefault location(ifitdoesnotexist). Deletesthepasswordforthespecified userfromthecredentialstore. Deletesallpasswordsfromthecredential store. Returnsthepasswordforthespecified hostanduserfromthecredentialstore. Returnsthesetofhostscontainedinthe credentialstore. Returnsthecollectionofallusernames thathavepasswordsstoredforthe specifiedhostname. Closesthecredentialstore,preventing furthermethodinvocations.Releases associatedresources.
removePassword(hostname, username) clearPasswords() getPassword(hostname, username) getHosts() getUsernames(hostname)
RemovePassword(hostname, username) ClearPasswords() GetPassword(hostname, username) GetHosts() GetUsernames(hostname)
close()
Close()
ThecredentialstoreclientAPIsuseaplatformdependentdefaultfilelocationwhenthefilelocationisnot specifiedexplicitly.
Overview of the Credential Store Backing File

ThecredentialstorebackingfileisatextbasedfileformattedasXMLthatissavedlocallyontheclientmachine foraccessatruntime.Unlessotherwisespecified,thebackingfileislocatedinthedefaultlocationshownin Table 73.Thecredentialstorepersistslocallyonaperuserbasiseachuserhashisorherowncredentialstore backingfilethatshouldbeprotectedbyappropriatefileaccesspermissions. CAUTIONThecredentialstorebackingfileusesfilesystemlevelpermissionstoensurethatpasswordsremain confidential.Administratorsoruserswhoshareworkstationsshouldsettheappropriatefilepermissionson theirrespectivecredentialstorebackingfiletoensurethattheyalonecanaccessthefileanditscontents.
Credential Store Backing File Structure

Example 71showsthevalidXMLelementsthatarereadandwrittentothefile. Example 7-1. Credential Store File Format
<?xml version="1.0" encoding="UTF-8"?> <viCredentials> <version>1.0</version> <passwordEntry> <host>mi6.vmware.com</host> <username>agent007</username> <password>IhWS1saIhtsw2FbIh0w2F2...</password> </passwordEntry> <passwordEntry> ... </passwordEntry> ... </viCredentials>
68
VMware, Inc.
Chapter 7 Automating Client Application Login
Using Samples to Understand the Credential Store

ThevSphereWebServicesSDKCreateUserandSimpleAgentsampleapplicationsdemonstratethe functionalityavailablethroughthecredentialstoreclientlibraries(Table 71). TheCreateUserapplicationcreatesauseraccountandpasswordbasedonrandomnumbergeneration schemefortheserver,andpopulatesthelocalcredentialstorebackingfilewiththisinformation.Ifthebacking filedoesnotexist,itiscreatedinthedefaultlocation(Table 73). ToruntheCreateUserapplication,youmustenterthenameoftheserverwithanESX/ESXiadministrator accountandpassword.Agenerateduseraccountnameandgeneratedpasswordarecreatedontheserver.
java com.vmware.samples.simpleagent.CreateUser --server <servername> --url https://<servername>/sdk --username <adminuser> --password <pwd> --ignorecert ignorecert
TheCreateUsersampleprintsoutasfollowsuponsuccessfulexecution:
Started Successfully created user and populated the credential store Ended CreateUser
TheSimpleAgentsampleapplicationdemonstrateshowthecredentialstorelibrariescanbeusedtoextract theuseraccountandpasswordatruntimetoauthenticateauseraccount,noninteractively.Torunthe SimpleAgentsample:

java com.vmware.samples.simpleagent.SimpleAgent <servername>
Theconsoleshoulddisplayamessagesimilartothefollowing:
Connected Successfully VMware ESX Server 3.5.0 build-78591
CAUTIONTheCreateUsersampleapplicationCreateUserisfordemonstrationpurposesonlyandshould notbeusedasamodelforproductioncode.CreateUserbreaksoneofthecardinalrulesofsecuritybest practices:Nevergiveuseraccountsmoreprivilegesthanneededdothetasksrequiredofthem.
Security Best Practices and the Credential Store

Theprincipleofleastprivilegeshouldbeappliedtoanyagentlikesoftwareorautomatedapplicationthat takesadvantageofthecredentialstore.Thiscommonsecuritytenetdictatesthatuseraccountsbegiventhe minimalnumberofprivilegesonthesystemthattheyrequiretodotheirjobs.
Using the Principle of Least Privilege with the Credential Store

Tofollowthiscommonsensebestpractice,VMwarerecommendsthatthecredentialstorebeusedonlyas describedhereinaproductionenvironment.Indevelopmentandtestenvironments,securitymightnotbeas muchofaconcern. To follow security best practices while using the credential store 1 2 Nevergrantadministratorprivilegestoauseraccountassociatedwithanautomatedscriptorsoftware agent,especiallyonethatusesthecredentialstore. CreatespecificrolessolelyforpurposesofusinganySDKbasedapplicationthatusesthecredentialstore. Or,selectapredefinedsampleuserroleifoneexiststhatmeetsyourneeds. Forexample,ifyouaredevelopinganagentlikeapplicationtoautomaticallylaunchtheVMware ConsolidatedBackuputility,youmightusetheVMwareConsolidatedBackupUtilityrole(roleID7). Ifapredefineduserrolethatmeetstheneedsofyourapplicationdoesnotexist,createarolewithonly thoseprivilegesneededfortheapplication.SeeTable 46,SystemandPreDefinedUserRoles,on page 41formoreinformationaboutroles. 3 Createauseraccountexpresslyforusewiththeagentorapplication.
VMware, Inc.
69
4 5
Applythespecificrolecreatedinstep2totheuseraccountcreatedinstep3. Storethespecialuseraccountandpasswordinthecredentialstore,usingthe CredentialStoreAdministrationtoolasdetailedinCredentialStoreAdministrationToolfor NonInteractiveClientsonpage 173.
CAUTIONTheCreateUsersamplebreakstheprincipleofleastprivilege,bygrantingtheuseraccountthe Administratorrole(1).Neverdothisinaproductionenvironment.
Using the CredentialStoreAdmin Tool

InadditiontothefileslistedinTable 71,thevSphereWebServicesSDKalsoincludesanadministrationtool forcreatingandmanagingthecredentialstore.YoucanusetheCredentialStoreAdmintooltoexaminethe contentsofthecredentialstore.Forexample,youcanusetheCredentialStoreAdmintooltoseethe generateduseraccountsandpasswordscontainedinthefile. Table 7-3. Default Credential Store Locations
Client Linux WindowsVista WindowsXP Windows2000 Default Location $HOME/.vmware/credstore/vicredentials.xml C:\Users\[User Name]\AppData\Roaming\VMware\credstore\vicredentials.xml C:\Documents and Settings\[User Name]\Application Data\VMware\credstore\vicredentials.xml
Ifyouusetheclientlibrariesforthecredentialstoreinanapplicationthatyoucreate,youmustalsomanage thecredentialstoreontheclientmachinesthatmightrunyourapplication.SeeCredentialStore AdministrationToolforNonInteractiveClients,inAppendix C,DeployingClientApplications,on page 173formoreinformation.
Using AuthorizationManager to Limit Access

AuthorizationManagerprovidesoperationsforaddingrolesandassociatingpermissionswithmanaged entitiesinavSphereinventory.YoumightwanttocreatenewrolesiftheexistingrolesdefinedforESX/ESXi orvCenterServerdonotmeetyourneeds. Forexample,agentstyleclientapplicationsthatlogonandauthenticateautomaticallyusingthecredential store,shouldbeassignedrolesthatencompassonlytheprivilegesneeded.Ifapredefinedroledoesnotmeet thisneed,youshoulddefineanewonethatcontainsonlytheminimumsetofrequiredprivileges. Itisalsobestpracticetocreatespecificuseraccountsforsuchagentstyleclientapplicationsandmanyother clientapplicationsthatperformadministrativetasks.Ratherthanusetherootorotheraccountfromthe administratorsgroup,createanewuseraccountwithonlythenecessaryprivilegesontheserver.
Creating New User Accounts

NewuseraccountsforvSphereservers(ESX/ESXi)canbecreatedthroughtheAPIbyusingthe HostLocalAccountManagerserviceinterface. To create a user account on ESX/ESXi through the API 1 2 ObtainamanagedobjectreferencetotheHostLocalAccountManagerofthetargetsystem. CreateaHostAccountSpecdataobjectthatdefinesthepropertiesoftheuseraccount,including descriptionandpassword. DefineaccountnamesandpasswordsaccordingtotheconfigurationrequiredbyyourESX/ESXisystem foruseraccountnamingconventionsandpasswordrequirements,suchasminimumlength,characterset, andotherrequirements.
70
VMware, Inc.
Chapter 7 Automating Client Application Login
InvoketheCreateUserAccountoperation,passingthemanagedobjectreference(fromstep1)andthe HostAccountSpecdataobject(step2)intheinvocation. Atthispoint,youcancreateagroup(ifitdoesnotyetexist).
4 5
CreateaHostAccountSpecdataobjectthatdefinesthepropertiesofthegroup(description,id).No passwordisneeded. InvoketheCreateGroupoperation,passingthemanagedobjectreference(fromstep1)andthe HostAccountSpecdataobject(fromstep4)intheinvocation. Nowthattheuserandgroupbothexist,youcanaddtheusertothegroup.
InvoketheAssignUserToGroupoperation,passingthemanagedobjectreferencetothe HostLocalAccountManager,theuserid,andthegroupidintheinvocation.
Applying Permission to an Entity

Example 72showssomeofthecoderequiredtocreateanewuseraccountandapplyapermissiontoanentity thatgrantsaccesstotheuseraccountbasedonarole.Therole(4)assignedinthisexampleisdefinedasa VirtualMachinePowerUser.ThesampleusesAuthorizationManagertograntpermissionstotheuserand toassociatethepermissionwiththemanagedentityintheinventoryinthisexample,therootFolder. Example 7-2. Creating a User Account
... anagedObjectReference _authManRef = _sic.getAuthorizationManager(); public class CreateUser { private static AppUtil appUtil= null; private void createUser() throws Exception { ManagedObjectReference hostLocalAccountManager = appUtil.getConnection().getServiceContent().getAccountManager(); ManagedObjectReference hostAuthorizationManager = appUtil.getConnection().getServiceContent().getAuthorizationManager(); // Create a user HostAccountSpec hostAccountSpec = new HostAccountSpec(); hostAccountSpec.setId(userName); hostAccountSpec.setPassword(password); hostAccountSpec.setDescription("my delegated admin auto-agent software"); appUtil.getConnection().getService().createUser(hostLocalAccountManager, hostAccountSpec); ManagedObjectReference rootFolder = appUtil.getConnection().getServiceContent().getRootFolder(); Permission permission = new Permission(); permission.setGroup(false); permission.setPrincipal(userName); // Assign the Virtual Machine Power User role permission.setRoleId(4); permission.setPropagate(true); permission.setEntity(rootFolder); appUtil.getConnection().getService().setEntityPermissions(hostAuthorizationManager, rootFolder, new Permission [] {permission}); ...
VMware, Inc.
71
72
VMware, Inc.
Obtaining References to Objects and Property Values from the Server
ForanyclientapplicationyoudevelopusingthevSphereAPI,youmustobtainoneormoremanagedobject referencestotheserviceinterfacesthatyouwanttouse,andtospecificobjectsintheinventorythatyouwant tomanageoruseinyourapplication.ThePropertyCollectortheserviceinterfacethatyouusetoobtain referencestomanagedobjects,toobtainvaluesofthepropertiesfrommanagedobjects,andtomonitor changesandupdateyourclientsidewithnewvaluesforserversideobjectsasneededintheapplication. This chapterincludesthesetopics: SampleCodeReferenceonpage 73 IntroductiontothePropertyCollectoronpage 74 UnderstandingthePropertyFilterSpeconpage 75 RetrievePropertiesOperationonpage 76 CreateFilterandUpdateOperationsonpage 77 PropertyCollectorPerformanceonpage 79 UsingtheSearchIndextoObtainManagedObjectReferencesonpage 80
Sample Code Reference

Table 81liststhesampleapplicationsincludedwiththevSphereWebServicesSDKthatdemonstratesomeof thetopicsdiscussedinthischapter. Table 8-1. Sample Applications that Demonstrate PropertyCollector and SearchIndex Operations
Java SDK\samples\Axis\java\com\vmware\samples\general GetUpdates.java PropertyCollector.java SearchIndex.java SimpleClient.java TaskList.java C# SDK\samples\DotNet\cs\ GetUpdates PropertyCollector SearchIndex SimpleClient TaskList WatchVM
ThesampleslistedinTable 81dependonseveralhelperclassesthatusethePropertyCollectorextensively tonavigatethroughtheinventory,toobtainreferencesandvaluesofproperties,andtokeeptheclientside objectstatesynchronizedwiththestateofserverobjects.SeetheclasseslocatedintheAppUtilsubdirectory oftheJavaandC#samples,respectively,foradditionalexamplesofusingPropertyCollector.
VMware, Inc.
73
Introduction to the PropertyCollector

BeyondthebasicclientapplicationpatternintroducedinChapter 6,ClientApplicationPattern,onpage 59, anyclientapplicationtypicallyperformsmanydifferentoperationstoobtaininformationabouttheserver objectsatanygiventime.ThePropertyCollectorisaserviceinterfacethatsupportsthesekindsoftasks fromaclientapplication: Navigatetheinventoryandobtaininformationaboutspecificmanagedobjectsfromtheinventory,such aswhetheravirtualmachineispoweredonornot,whetherahostinaclusterisofflineoron,andsoon. Keepdataaboutserverstateintheclientapplicationsynchronizedwiththestateofserverobjectsasmuch asrequiredbytheapplication. UsingaPropertyCollectorrequiressomeknowledgeoftherelationshipsamongmanagedobjects. You mustunderstandthegeneralhierarchicalarrangementofentitiesintheinventorybeforeyoucancreatea filterthatstartscollectingobjectsorpropertiesatanypointintheinventoryhierarchy. Forexample,aninventoryalwaysstartsfromarootFolderwhoseparentpropertyvalueisalwaysUnset. ObjectsintheinventorydescendfromthisrootFolderintheorderdeterminedbytherelationshipofparent propertiesandchildEntityproperties,followingtheconstraintsimposedbytheunderlyingmanagedentity types.StepthroughsomeofthesampleslistedintheSampleCodeReferenceonpage 73,includingthe helperclasses,forexamplesofusingPropertyCollectortonavigateallobjectsavailableinthehierarchy. SeeChapter 3,UnderstandingtheInventory,onpage 25formoreinformationaboutinventoryentitiesand theirrelationships.
PropertyCollector Operations
TheServiceInstanceofavSphereserverprovideseachclientsessionwithitsowninstanceofthe PropertyCollector.APropertyCollectorhasasingleproperty,filter,thatisdefinedasanarrayof referencestoPropertyFiltermanagedobjects. Figure 8-1. PropertyCollector and PropertyFilter Managed Object Types
Thefilterpropertyissessionspecific.Itdoesnotexistbeyondthesession,norcanitbesharedwithanother session.Whenasessionends,theserverdestroysanyfiltersassociatedwiththesession. ThePropertyCollectorprovidesoperationsforcreatingfilterstoobtainspecificpropertiesandobjects, checkforupdatesonspecifiedobjects,andmonitorchangestopropertiesontheserver.Table 82provides summaryinformationaboutalltheoperationsavailableinaPropertyCollector. Table 8-2. PropertyCollector Operations
Operation CancelWaitForUpdates Parameter _this Type MOR >PropertyCollector Description Cancelsaninprogress WaitForUpdatesoperation.Upon successfulcancellation,thisoperation throwsaCancelledfault. ReturnsanUpdateSetdataobjectthat containsallrequestedpropertiesforthe specifiedversion. Returnsareferencetoa PropertyFiltermanagedobjectthat meetsthespecificationsdefinedinthe specparameter.
CheckForUpdates
_this version
MOR > PropertyCollector string MOR > PropertyCollector PropertyFilterSpec boolean
CreateFilter
_this spec partialUpdates
74
VMware, Inc.
Chapter 8 Obtaining References to Objects and Property Values from the Server
Table 8-2. PropertyCollector Operations (Continued)

Operation RetrieveProperties Parameter _this specSet WaitForUpdates _this version Type MOR > PropertyCollector PropertyFilterSpec[] MOR > PropertyCollector string Description ReturnsanarrayofObjectContent dataobjectscontainingmanagedobject referencesandpropertiesformanaged objects. ReturnsanUpdateSetdataobject containingthechangesbetweenthe previousversionandthecurrentvalues oftheproperties.
ThroughtheoperationslistedinTable 82, PropertyCollectorsupportstwogeneralapproachesto obtainingobjectsandpropertiesfromtheserver: Ifyoudonotneedyourclientapplicationtokeepclientstatesynchronizedwithserverstate,youusethe RetrievePropertiesoperation.Theserverinstantiatesafilter,collectsyourspecifiedobjectsand propertiesasaObjectContentdataobjectandreturnsittotheclientapplication.SeeRetrieveProperties Operationonpage 76formoreinformation. Ifyourapplicationmustkeepclientstatesynchronizedwiththeserverstate,youusetheCreateFilter operationinconjunctionwithCheckForUpdatesorWaitForUpdatesoperations.SeeKeepingClient DatainSynchwithServerObjectsonpage 78formoreinformation. BothapproachesrequireyoutocreateacomplexdatastructurecalledaPropertyFilterSpecthatdefines thepropertiesandobjectsyouwanttoretrievefromtheserver.
Understanding the PropertyFilterSpec

AsshowninFigure 82,PropertyFilterSpecdataobjecthastwoproperties,objectSetandpropSet, definedasinstancesofanarrayofObjectSpecdataobjectsandanarrayofPropertySpecdataobjects, respectively. Figure 8-2. PropertyFilterSpec and Associated Data Objects
PropertyFilterSpecrequiresatleastoneinstanceofanObjectSpec,butthearrayofPropertySpecobjects canbeempty.YouusetheObjectSpectospecifythestartingpointintheinventorythatyouwantthefilterto useforthecollection.TheobjpropertyofObjectSpecspecifiesthetypeofobject(themanagedobjecttype name,asastring)tocollectfromtheserver. Fortheobjproperty,youuseanyofthevalidstringsdefinedforthetypepropertyofthe ManagedObjectReferencedataobject.Validstringsarethenearly60managedobjecttypes,fromAlarm throughVmwareDistributedVirtualSwitch.SeeTable 51,ValidValuesforManagedObjectReference TypeProperty,onpage 46forthelistofvalidtypestrings.
VMware, Inc.
75
TheobjpropertyofObjectSpecisdefinedasaninstanceoftheManagedObjectReferenceforwhichyou wanttostartthecollection.UsingObjectSpecwithoutaPropertySpecreturnsthecompleteobjectfromthe specifiedlocation.Toreturnspecificpropertiesfromtheobject,youmustuseObjectSpecinconjunctionwith oneormorePropertySpecobjectsthatidentifiestheproperties. SeethevSphereAPIReferenceforcompleteinformation.
TraversalSpec Data Object and Recursion

TheTraversalSpecdataobjecttypeextendstheSelectionSpecdataobjectwithseveralpropertiesthat enableyourapplicationtoretrievepropertiesandobjectsrecursively.Youcancreateextensivenavigational specificationsusingtheTraversalSpecinconjunctionwithSelectionSpecdataobjects. Figure 8-3. Nested TraversalSpec
InaseriesofmultipleTraversalSpecdataobjectsassociatedwithaSelectionSpec,thenameofthelast TraversalSpecdataobjectintheseriesmustmatchthenameoftheSelectionSpec(Figure 83).
RetrieveProperties Operation
TheRetrievePropertiesoperationisdesignedforonetimeoradhocuse.Itcollectsalltheobjectsand propertiesyouspecifyinoneormorePropertyFilterSpecobjects.Thefilterisnotaddedtothearraythat makesupthefilterpropertyofPropertyCollector,butisinsteadusedimmediatelybytheserverto collecttheobjectsandpropertiesspecifiedinyourPropertyFilterSpecobjects,andthendestroyedafterthe serverreturnstheresultstoyourclient. TheRetrievePropertiesoperationacceptsanarrayofPropertyFilterSpecobjectsforitsspecSet parameter.TheoperationreturnsanObjectContentdataobject(Figure 84). Figure 8-4. ObjectContent Data Object Returned by RetrieveProperties Operation
Inyourclientcode,youobtainthevaluesfromthiscompositedatastructureandprocessfurtherinyourclient applicationasneeded.
76
VMware, Inc.
Example 81showsanexcerptfromtheServiceUtil.javahelperclasscontainedinthevSphereWeb ServicesSDKsamplespackage. Example 8-1. Loop that Obtains References from an ObjectContent Data Object
... ObjectContent oc = null; ManagedObjectReference mor = null; DynamicProperty[] propary = null; String propval = null; boolean found = false; for (int oci = 0; oci < ocary.length && !found; oci++) { oc = ocary[oci]; mor = oc.getObj(); propary = oc.getPropSet(); propval = null; if (type == null || typeIsA(type, mor.getType())) { if (propary.length > 0) { propval = (String)propary[0].getVal(); } found = propval != null && name.equals(propval); } } if (!found) { mor = null; } return mor; } // close for loop ...
CreateFilter and Update Operations

Tokeepclientsideobjectssynchronizedwiththeserverobjects,youstartbyusingCreateFiltertodefine thefilter.YouobtainservercontentusingCheckForUpdatesorWaitForUpdates,afteryourfiltersexistin yourPropertyCollector. TheCreateFilteroperationhasonlythreeparameters.However,thespecproperty,definedasaninstance ofaPropertyFilterSpec,consistsofseveralotherdataobjects,mostnotably,anObjectSpecanda PropertySpec.SeeUnderstandingthePropertyFilterSpeconpage 75foradditionalbackground informationaboutthesedataobjects.Figure 85showsthegeneralrelationshipoftheseobjectsasinputto PropertyCollectorCreateFilteroperation. Figure 8-5. Using the PropertyCollector
VMware, Inc.
77
To define the data objects needed to create a filter 1 IdentifythestartingobjectforthecollectionbycreatinganObjectSpecthatspecifiesthetypeofobjectin intheobjpropertyofObjectSpec.Ifyouwantthecollectiontoincludethestartingobject,settheskip propertyofObjectSpectofalse. DefinethespecificationforthePropertySpec,orpassnullfortheselectSetparametertoretrieve completeobjects. InstantiatethePropertyFilterSpecusingthearraysofObjectSpecandPropertySpecobjectsthat specifythedetailsyouwanttogatherinthecollection. UsetheCreateFilteroperationofPropertyCollector,passingthePropertyFilterSpecwiththe referencetothePropertyCollector.WhenyouinvokeCreateFilter,youalsopassavalueforthe partialUpdateproperty: SetpartialUpdatetofalsetoobtaincompletepropertyvalues. SetpartialUpdatetotruetoobtainnestedpropertyvaluesonly. 5 ThePropertyCollectorinstantiatesthePropertyFilterandaddsittothearrayoffiltersthatmake upthefilterpropertyonthatPropertyCollectorinstance.Theoperationreturnsthemanagedobject referencetothefiltertoyourclientapplication.
2 3 4
Keeping Client Data in Synch with Server Objects

WhenyouusetheCreateFilteroperationtospecifytheobjectsorpropertiesthatyouwanttoworkwithin yourapplication,theservercreatesfilterobjectsthatmeetyourspecification,populatingthefilterpropertyof thePropertyCollectorwiththearrayofreferencestoPropertyFilterobjects.CreateFilterdoesnot returnanyobjectsorpropertyvaluestotheclient. Toobtaindataontheclientside,youmustuseCheckForUpdatesorWaitForUpdatestoobtainUpdateSet objectsfromtheserver,usingthefilterorfiltersdefinedduringthesessionwiththeCreateFilteroperation. Table 83listssomeoftheadvantagesanddisadvantagesofthesetwooperations. Table 8-3. PropertyCollector Operations Compared
Operation CheckForUpdates Advantages Pollingmechanismthatreturnsonlyproperties thathavechangedsincetheversionspecified. Returnschangeddataonly,sobetternetwork utilizationthanRetrieveProperties. Notificationmechanismthatblocksuntilan updateoccurs.Efficientuseofnetwork resources.Theonlyoperationofthethreethat youcancancel. Disadvantages Returnsanemptysetevenwhennothinghas changedontheserver.Dependingonyour clientapplication,thismightbeinefficient. Blocksprocessingthreaduntilupdatesoccur. However,thiscallcanbecancelledsoyoucan monitorthetimetheoperationistakingand cancelifnecessary.
WaitForUpdates
BothoperationsreturnUpdateSetdataobjects,thecompositedatastructureshowninFigure 86.Both CheckForUpdatesandWaitForUpdatesapplythecompletearrayoffiltersdefinedforthe PropertyCollectortotheserverandreturnanUpdateSetobject.
78
VMware, Inc.
Figure 8-6. UpdateSet Data Object Returned by CheckForUpdates and WaitForUpdates Operations
BothCheckForUpdatesandWaitForUpdatesreturnonlychangedobjectsandpropertiesbasedontheunion ofallfiltersassociatedwiththePropertyCollectorforthesession. Thefirsttimeyouinvokeeitheroftheseoperationsaftercreatingyourfilter,useanemptystring()forthe versionparameter,toobtainacompletesetofresults.Theresultreturnedcontainsanewversionnumber thatyouuseinthenextcall. SeetheGetUpdates.java,GetUpdates.cs,ServiceUtil.java,andServiceUtil.cssamplesinthe vSphereWebServicesSDKpackageforsomeexamplesofusingtheseoperations.
PropertyCollector Performance
ThesefactorscanaffecttheperformanceofaPropertyCollectorforanygivensession: Numberofobjects Numberofproperties Densityofpropertydata(composite,nesteddataobjects) Frequencyofchangestotheobjectsandpropertiesontheserver Depthoftraversal(numberofpropertiestraversed) Inaddition,avSphereserverisaffectedbythenumberofPropertyCollectorinstancesandthenumberof filterseachissupportingacrossallsessionsontheserver. ForVirtualCenterServer2.5,foraninventoryof2,000virtualmachinessupportingabout25clientapplications simultaneously,performanceisacceptableuptoabout12moderatelycomplexfiltersmonitoringupdateson all2,000virtualmachines.Ifthefiltersincludecomplextraversalobjects,performancemightdegrade appreciablyunlessyoureducethenumberoffiltersacrossthesystem. ConsiderusingtheViewManagerandViewobjectsinconjunctionwithPropertyCollectortominimizeboth theoverheadonPropertyCollectorandtheamountofnetworktrafficforyourclientapplication. See ImprovingCollectionPerformancebyUsingtheViewManagerandView Objectsonpage 79.
Improving Collection Performance by Using the ViewManager and View Objects

TheViewManagerserviceinterfacesupportsclientaccesstoservermanagedobjectcontent.Youusethe ViewManagertocreatecustomizedobjectsthatrepresentsubsets,orviews,ofspecificinstancesofselect managedobjecttypesontheserver.
VMware, Inc.
79
TheViewManagerprovidesoperationsforcreatingseveraldifferentkindsofviews.Theseviewsextendfrom theViewandManagedObjectViewbasetypes(seeFigure 87). Figure 8-7. ViewManager and View Managed Object Types and View Subtypes
YouusetheappropriatecreateoperationofViewManagertocreateaview.AsshowninFigure 87,viewtypes includeContainerView,InventoryView,andListView. Forexample,youusetheCreateContainerViewtocreateaContainerView.TheContainerViewenables youtomonitorobjectsassociatedwithanyofthecontainerobjectssupportedontheserver,includingFolder, Datacenter,ComputeResource,HostSystem,ResourcePool,andVirtualAppobjects.Youusethe CreateInventoryViewtocreateanInventoryView. TheInventoryViewprovidesoperationsforopeningandclosingfoldersonaninventory.Itsviewproperty containsanarrayofthemanagedobjectreferencestotheobjectsthatmakeuptheinventory.Aswith PropertyCollector,thelifetimeofanyViewobjectisthedurationofthesession,oruntiltheobjectis explicitlydestroyed,byinvokingitsDestroyViewoperation. AfteryoucreatetheappropriateViewobjectsforyourapplication,insteadofusingaPropertyCollector withtheentireserverstructure,youusePropertyCollectorwiththeviews.Theappropriateviewsofserver objectsenableyoutocreatemuchsimplerPropertyFilterSpecobjectstodefineyourfilters,andtheback andforthcommunicationbetweentheclientandserverismoreefficient. SeethevSphereAPIReferenceformoreinformationaboutViewManager,aboutViewmanagedobjecttypesand subtypes,andabouthowtousetheseobjectsinconjunctionwithPropertyCollector.
Using the SearchIndex to Obtain Managed Object References

TheSearchIndexmanagedobjectistheserviceinterfaceforretrievingmanagedentitiesbyusingspecific propertyvalues,suchasinventorypath,datastorepath,DNSname,andvariousothermanagedentity propertyvalues. Forexample,ifyouknowtheIPaddressofavirtualmachine,youcanobtainitsmanagedobjectreferenceby usingtheFindByIpoperationofSearchIndex.YoucanusethePropertyCollectortofirstobtainthevalue ofaspecificproperty,andthenusethatvalueasinputtoSearchIndex.Seethesampleapplications SearchIndex.javaandSearchIndex.csformoreinformationaboutusingSearchIndex.
80
VMware, Inc.
Figure 8-8. PropertyCollector and SearchIndex Managed Objects
Table 84listsallSearchIndexoperations.WiththeexceptionoftheFindChildandFindByInventoryPath operations,SearchIndexoperationsacceptanoptionaldatacenter,tolimitthesearchtoaspecific Datacenterintheinventory.UnmanagedESX/ESXisystemshaveasingledatacenter,ha-datacenter. Table 8-4. SearchIndex Operations

Operation FindAllByDnsName Parameter _this datacenter dnsName vmSearch FindAllByIp _this datacenter ip vmSearch FindAllByUuid _this datacenter uuid vmSearch instanceUuid FindByDatastorePath _this datacenter path FindByDnsName _this datacenter dnsName vmSearch FindByInventoryPath _this inventoryPath Type MOR>SearchIndex MOR>Datacenter string boolean MOR>SearchIndex MOR>Datacenter string boolean MOR>SearchIndex MOR>Datacenter string boolean string MOR>SearchIndex MOR>Datacenter string MOR>SearchIndex MOR>Datacenter string boolean MOR>SearchIndex string Returnsanarrayofreferencestomanaged entitiesthatmatchtheBIOSUUIDspecified. Set vmSearchtotruetoincludevirtual machinesinthesearchresults.IfvmSearchisset totrue,youcanalsosetinstanceUuidtotrueto usevirtualmachineinstanceUUIDinthesearch results. Returnsareferencetoavirtualmachineatthe specifieddatastorelocation.Thepathisthe locationofthe.vmxfilethatcomprisesthevirtual machine. Returnsareferencetothemanagedentitythat matchesthefullyqualifieddomainnameofthe hostorvirtualmachine,asconfiguredusing VMwareTools.SetvmSearchtotruetosearch forvirtualmachines.Otherwise,thisoperation returnshosts. Returnsareferencetothemanagedentityatthe specifiedlocationintheinventory.Inventory pathsmustincludethecontainingfolders. For example,theinventorypathtoavirtual machineonanunmanagedESX/ESXihostmust includethecontainingdefaultdatacenterfolder andthedefaultvmFolder,asinthisexample: ha-datacenter/vm/pubslab-linux FindByIp _this datacenter ip vmSearch MOR>SearchIndex MOR>Datacenter string boolean Returnsareferencetothemanagedentitythat matchestheIPaddressofthehostorvirtual machine,asconfiguredusingVMwareTools. Set vmSearchtotruetoincludevirtual machinesinthesearch.Otherwise,search includeshostsonly. Description Returnsanarrayofreferencestomanaged entitiesthatmatchthefullyqualifieddomain nameofthehostorvirtualmachine,as configuredusingVMwareTools.Ifnoentities matchthednsNamesubmitted,returnsanempty array. Returnsanarrayofreferencestomanaged entitiesthatmatchtheIPaddressofthehostor virtualmachine,asconfiguredusingVMware Tools.IfnoentitiesmatchtheIPaddress,returns anemptyarray.
VMware, Inc.
81
Table 8-4. SearchIndex Operations (Continued)

Operation FindByUuid Parameter _this datacenter uuid vmSearch instanceUuid FindChild _this entity name Type MOR>SearchIndex MOR>Datacenter string boolean boolean MOR>SearchIndex MOR>ManagedEntity string Returnsareferencetothemanagedentitythat matchesthenameofthechildobject.Thesearch includesonlytheimmediatechildren,suchasthe datastoreFolder,hostFolder, networkFolder,andvmFolderofaDatacenter. Description Returnsareferencetothemanagedentitythat matchtheBIOSUUIDspecified.SetvmSearchto truetoincludevirtualmachinesinthesearch results.IfvmSearchissettotrue,youcanalso setinstanceUuidtotruetousevirtualmachine instanceUUIDinthesearchresults.
SeethevSphereAPIReferenceformoreinformationabouttheseoperations.
82
VMware, Inc.
Overview of the Task Infrastructure
AsdiscussedinAsynchronousClientServerApplicationStyleonpage 46,manyoftheoperationsavailable throughthevSphereAPIareasynchronous.Ratherthanblockingothercallerswhileexecutingtocompletion, asynchronousoperationsreturnareferencetoaTaskmanagedobject.Operationsassociatedwithan ESX/ESXihostanditsvirtualmachinesalsogenerateoneormoreEventdataobjectsthatprovidestatus, source,andotherinformationabouttheoperation.ThischapterprovidesanoverviewoftheTaskand TaskManagermanagedobjectsasfundamentalbackgroundfortheprogrammingmodel,andanintroduction toEventdataobjects.Thechapterincludesthesetopics: SampleCodeReferenceonpage 83 UnderstandingTaskManagerandTaskManagedObjectsonpage 84 UnderstandingtheTaskInfoDataObjectonpage 85 OperationsThatReturnTaskManagedObjectsonpage 90 IntroductiontotheEventDataObjectonpage 92 NOTEInadditiontotheTaskManagerandTaskmanagedobjectsdiscussedinthischapter,vCenterServer providesaScheduledTaskManagerthatsupportsschedulingoperationsinadvance.SeeChapter 16, SchedulingvCenterServerOperations,onpage 143forinformationaboutschedulingserveroperations usingtheScheduledTaskManager.

Table 91liststhesampleapplicationsincludedwiththevSphereWebServicesSDKthatdemonstratesomeof thetopicsdiscussedinthischapter. Table 9-1. Sample Applications
Java SDK\samples\Axis\java\com\vmware\samples general\TaskList.java events\EventFormat.java events\EventHistoryCollectorMonitor.java events\VMEventHistoryCollectorMonitor.java C# SDK\samples\DotNet\cs\ TaskList EventFormat EventHistoryCollectorMonitor VMEventHistoryCollectorMonitor
InadditiontothesampleslistedinTable 91,thehelperclassesassociatedwiththesampleapplicationsuse Taskobjectsextensively.
VMware, Inc.
83
Understanding TaskManager and Task Managed Objects

TheTaskManagerisusedextensivelybyvSphereserverstosupportasynchronousoperations.Atruntime, varioussubsystemsuseTaskManagertoinstantiateTaskobjectsinresponsetooperationinvocationsfrom clientapplications. NOTETaskandEventobjectsinthecontextofanunmanagedESX/ESXisystemarenonpersistent. See Chapter 14,EventandTaskManagementUsingvCenterServer,onpage 129forinformationabouttasks andeventsfrommultipleESX/ESXisystemsthatarestoredandmanagedbyavCenterServersystem. AlthoughmanyoperationsavailablethroughtheAPIareasynchronousandreturnareferencetoaTask object,someoperationsaresynchronousanddonot.Forexample,operationsavailablethroughthe PerformanceManagerandseveralotherserviceinterfacesdonotreturnTaskobjects.Onlythoseoperations thatincludethesuffix_TaskintheirnamesreturnTaskreferences.SeeTable 95,OperationsthatReturna ReferencetoaTaskManagedObject,onpage 90foralistofallvSphereAPI4.0operationsthatreturn referencestoTaskobjects. ATaskobjectprovidesinformationaboutthestatusoftheinvokedoperationthroughitsTaskInfodata object.AninstanceofTaskInfopopulatestheinfopropertyoftheTaskmanagedobjectatruntime.By monitoringvariouspropertiesoftheTaskInfoobject,aclientapplicationcantakeappropriateactionwhen theTaskcompletes,orcanhandleerrorsiftheTaskdoesnotcompletesuccessfully. ATaskanditsassociatedobjectsaresessionspecific.Theuseraccountassociatedwiththesessionislimited toobtaininginformationabouttheTaskobjectsthatitisauthorizedtoview. TheTaskManagerencompassesthepropertieslistedinTable 92. Table 9-2. TaskManager Properties
Property description Type TaskDescription Description TaskDescriptionincludesamethodInfopropertythatcontainsa keybasedarrayusedbyTaskManagertopopulatethevalueofa TaskInfodataobjectsdescriptionIdpropertywiththenameofthe operation.Examplesoftwoelementsfromthiskeybasedarrayinclude methodInfo["Folder.createVm"]and methodInfo["Folder.createClusterEx"]. IdentifiesthenumberofTaskHistoryCollectorobjectsperclient sessionthattheservercancreate.Thispropertyissetbytheserver. ForESX/ESXi,maxCollectorissetto0.A TaskHistoryCollectorcannotbecreatedonanunmanaged ESX/ESXisystem. ForvCenterServer,maxCollectorissetto32,whichspecifiesthe numberofTaskHistoryCollectorobjectsperclientsession supportedbytheserver.SeeObtainingInformationaboutEvents UsingaHistoryCollectoronpage 133. recentTask MOR[ ]>Task [ ] ContainsanarrayofmanagedobjectreferencesTaskobjectsthatmeet anyofthefollowingconditions: TheTaskisqueuedtorun. TheTaskisrunning. TheTaskcompletedwithinthepast10minutes.
maxCollector
int
84
VMware, Inc.
Chapter 9 Overview of the Task Infrastructure
Figure 91showsaUMLclassdiagramforTaskManageranditsassociatedobjects. Figure 9-1. TaskManager and Task Managed Object Types
InadditiontothepropertieslistedinTable 92,TaskManagerhasthefollowingoperations: CreateCollectorForTasksoperation.YoucanusetheCreateCollectorForTasksoperationtocreate anobjectthatcontainsallTasksfromthevCenterServerdatabasethatmeetspecificcriteria.See ObtainingInformationaboutEventsUsingaHistoryCollectoronpage 133. CreateTaskoperation. TheCreateTaskoperationisusedbyallotheroperationsavailablethroughthe API,tocreateamanagedobjectreferencetoaTaskobject.Developerscreatingextensionscanalsousethe TaskManagertocreateTaskobjectsfortheoperationssupportedbytheirextension.
Understanding the TaskInfo Data Object

TheTaskInfodataobjectmakesuptheinfopropertyofaspecificTaskobject.Aninstanceofaspecific TaskInfoobjectcontainsinformationabouttheTaskreturnedbytheservertoyourclientapplication. Table 93liststhepropertiesofTaskInfodataobject. Table 9-3. TaskInfo Data Object Properties
T
Property cancelable cancelled changeTag completeTime descriptionId
Data Type boolean boolean string dateTime string
Description IndicateswhethertheTaskcanbecancelled(true)ornot(false). Indicatesthattheclienthasattemptedtocancel(true)theTask. Userenteredtagthatidentifiesoperationsandtheirsideeffects. TimestampthatidentifiesthedateandtimethattheTaskcompleted. Indicatesneithersuccessnorfailure. Identifiestheoperation,includingpubliclyvisibleinternaltasks. ReturnsvaluesfromtheTaskDescriptiondataobjectmethodInfo property. Managedentitytowhichtheoperationapplies. Localespecificmanagedentitynameretainedforthe HistoryCollectordatabase. Whenstatepropertyissettofault,identifiesthefault.Otherwise, notset. EventchainIDthatleadstotheassociatedTaskobjects. UniquekeyfortheTask. Whenthestatepropertyisrunning,thispropertyidentifiesthelist ofmanagedentities(ifany)lockedbytheoperation(usingashared lock).Otherwise,notset.
entity entityName error eventChainId key locked
MOR>ManagedEntity string LocalizedMethodFault int string MOR[ ]>ManagedEntity[]
VMware, Inc.
85
Table 9-3. TaskInfo Data Object Properties (Continued)

Property name parentTaskKey progress queueTime reason result rootTaskKey startTime state Data Type string string int dateTime TaskReason anyType string dateTime TaskInfoState Description NameoftheoperationthatcreatedtheTask.Notsetforinternaltasks. TaskscanbecreatedbyanotherTask.IdentifiesthekeyoftheTaskthat spawnedthisTask.IdentifiescausalitybetweenTaskobjects. Whenstatepropertyissettorunning,identifiespercentageofTask completed,from0to100.Otherwise,notset. TimestampthatidentifiesdateandtimetheTaskwascreated. SourceresponsibleforcreatingtheTask.Thesourcecanbeanalarm, schedule,system,oruser. Whenstatepropertyissettosuccess,containsthereturnvalueof thecompletedoperation.Otherwise,notset. ATaskcancreatenewtasks,tomultiplelevels.TherootTaskKey identifiesthekeyoftheTaskthatstartedthechainoftasks. TimestampthatindicatesdateandtimetheTaskstartedrunning. RuntimestatusoftheTaskspecifiedasonethefollowing: error queued running success task MOR>Task ManagedobjectreferencetoTask.
TheresultpropertyoftheTaskInfodataobject(listedinTable 93andshowninFigure 92)isdefinedas anyType.WhentheTaskisinstantiatedbytheserver,thevalueoftheresultpropertyisinitializedasUnset. Onlyuponsuccessfulcompletionofanoperationistheresultpropertypopulatedwiththeactualreturntype specifictotheoperation.BecausetheresultpropertyisdefinedasanyType,theresultmightbeadata object,areferencetoamanagedobject,oranyotherdatastructureasdefinedbytheoperation. Forexample,theAddHost_Task(oftheClusterComputeResourcemanagedobject)returnsaTaskobject whoseinfopropertycontainsaTaskInfodataobject.Atthestartoftheoperation,theresultpropertyis Unset.Uponsuccessfulcompletionoftheoperation,theresultpropertyofTaskInfocontainsthemanaged objectreferenceofthenewlyaddedHostSystem.IntheexampleoftheCreateVM_TaskshowninTable 94, theresultisamanagedobjectreferencetoaVirtualMachinewhosemanagedobjectidis64. SeethevSphereAPIReferencefordetailsaboutthereturntypeinstantiateduponcompletionofthespecific Taskassociatedwiththeinvokingoperation.
86
VMware, Inc.
Figure 9-2. The Result Property of a TaskInfo Data Object Can Contain Any Type
Table 94liststhevaluesobtainedfromaTaskInfodataobjectatthebeginningandtheendoftheTask instantiatedbytheCreateVM_Taskoperationforcreatinganewvirtualmachine. Table 9-4. Sample TaskInfo Values from an ESX/ESXi 4.0 System During Creation of a VirtualMachine
Sample Values Property cancelable cancelled changeTag completeTime description descriptionId dynamicProperty dynamicType entity entityName error eventChainId key locked name parentTaskKey progress queueTime reason result rootTaskKey startTime Datatype boolean boolean string dateTime LocalizableMessage string DynamicProperty[] string ManagedObjectRefere nce:Folder string MethodFault int string MOR>ManagedEntity[] string string int dateTime TaskReason anyType string dateTime Start of Task false false Unset Unset Unset "Folder.createVm" Unset Unset ha-folder-vm "vm" Unset 159740 "haTask-ha-folder-vm-vim.Folder .createVm-159740" Unset "vim.Folder.createVm" Unset 36 "2009-02-19T22:50:39.111604Z" reason Unset Unset "2009-02-19T22:50:39.111604Z" End of Task false false Unset "2009-02-19T22:53:35.015338Z" Unset "Folder.createVm" Unset Unset ha-folder-vm "vm" Unset 159740 "haTask-ha-folder-vm-vim.Folder .createVm-159740" Unset "vim.Folder.createVm" Unset 100 "2009-02-19T22:50:39.111604Z" reason 64 Unset "2009-02-19T22:50:39.111604Z"
VMware, Inc.
87
Table 9-4. Sample TaskInfo Values from an ESX/ESXi 4.0 System During Creation of a VirtualMachine (Continued)
Sample Values Property state task Datatype TaskInfoState MOR>Task Start of Task "running" haTask-ha-folder-vm-vim.Folder. createVm-159740 End of Task "success" haTask-ha-folder-vm-vim.Folder. createVm-159740
Monitoring TaskInfo Properties

ThevaluesofTaskInfopropertieschangeovertimeastheTaskrunstocompletion.Dependingonthe requirementsofyourapplication,youmightmonitoroneormoreofthepropertiesofTaskInfo. Forexample,youcancheckthevaluesofstartTime,queueTime,completeTime,progress,result,and stateastheoperationprogressesuntilcompletion.Monitorthesepropertiesinyourcodeinaseparatethread untiltheTaskcompletes,whilethemainlineofyourcodecontinueswithotheractivities. YourcodemusthandlethedatatypereturnedwhentheTaskcompletes(managedobjectreference,data object,andsoon).Youmustalsohandlepossibleexceptions.Forexample,inadditiontosuccess,queued, andrunning,anoperationcanenteranerrorstateforanynumberofreasons.Inyourcode,youmusthandle errorsandexceptions. TomonitorthestateoftheTask,usetheCheckForUpdatesoperationofthePropertyCollector.See KeepingClientDatainSynchwithServerObjectsonpage 78.ATaskobjecthasalifecyclethatis independentoftheTaskManagerthatcreatesitandindependentoftheentitywithwhichitisassociated.It existstoconveystatusaboutanoperation,soyoucandiscardthereferencetoityourapplicationnolonger needstheinformation.
Cancelling a Task
TocancelaTaskthatisstillrunning,invoketheCancelTaskoperation,passingthemanagedobjectreference totheTaskyouwanttocancelasshowninthisexample:
my_conn.cancelTask(taskMoRef);
However,onlyaTaskthathasitscancelablepropertysettotrueanditsstatepropertysettorunningcan becancelled.TheoperationthatinitiatestheTasksetsthevalueofcancelablewhenitcreatestheTask. For example,theCreateVM_Taskcannotbecancelled.AsshowninTable 94,thevalueofthecancelable booleanisfalse.BeforeattemptingtocancelarunningTask,youcancheckthevaluesofthecancelable propertyandthestatepropertyoftheTaskInfodataobjectassociatedwiththeTask.
Using the TaskManager to Obtain Information about Tasks

FromthemomentaTaskisqueuedtorununtil10minutesafteritcompletes,areferencetotheTaskisheld intherecentTaskarrayofTaskManager.YoucanusethispropertytoobtaininformationabouttheTask objectsrunningonthesystem. ThevSphereClientapplicationusestherecentTaskarrayinthisway,forexample.Whenconnectedtoan ESX/ESXisystem,thevSphereClientdisplaysqueued,running,andcompletedtasksintheRecentTaskspane. ElementsfromthisarrayalsodisplayintheMOB.YoucanalsoviewrecenttasksintheMOB,bynavigating totheTaskManager(onanESX/ESXisystem)usingtheServiceInstance>ServiceContent>hataskmgrlink. Figure 93showsanexampleoftheTaskManagerdisplayedintheMOBofanESX4.0systemduringthe CreateVM_Taskoperation.Thearraycontainsonlyoneelement,thereferencetotheTaskforcreatingavirtual machine.ClickinganyoftherecentTasklinksintheMOBdisplaysthereferencetotheTaskmanagedobject whoseinfopropertycontainsalinktotheTaskInfodataobjectpopulatedwiththedetailsabouttheTask operation,suchasthoselistedinTable 94.
88
VMware, Inc.
Figure 9-3. TaskManager as Displayed in an ESX System MOB
AllcompletedTaskobjectsageoutoftherecentTasksarrayafter10minutes.However,thevCenterServer collectsinformationaboutTaskobjectsforallthehoststhatitmanages.Youcanobtaininformationabout TaskobjectsfromvCenterServerusingaTaskHistoryCollector.SeeObtainingInformationaboutEvents UsingaHistoryCollectoronpage 133.
Obtaining Information about Recent Tasks Using a PropertyCollector

Toobtainthelistofrecenttasksprogrammatically,useaPropertyCollectortoobtainreferencestothe TaskManagerandtoallTaskobjectsfromtherecentTaskpropertyoftheTaskManager.Example 91shows anexcerptfromtheTaskList.javasamplethatcreatestheObjectSpec,PropertySpec,anda TraversalSpectoobtainreferencestoallTaskobjectsontheserverfromtheTaskList. Example 9-1. PropertyFilterSpec Definition to Obtain recentTask Property Values
private PropertyFilterSpec[] createPFSForRecentTasks(ManagedObjectReference taskManagerRef) { PropertySpec pSpec = new PropertySpec(); pSpec.setAll(Boolean.FALSE); pSpec.setType("Task"); pSpec.setPathSet(new String[] {"info.entity", "info.entityName", "info.name", "info.state", "info.cancelled", "info.error"}); ObjectSpec oSpec = new ObjectSpec(); oSpec.setObj(taskManagerRef); oSpec.setSkip(Boolean.FALSE); TraversalSpec tSpec = new TraversalSpec(); tSpec.setType("TaskManager"); tSpec.setPath("recentTask"); tSpec.setSkip(Boolean.FALSE); oSpec.setSelectSet(new SelectionSpec[]{tSpec}); PropertyFilterSpec pfSpec = new PropertyFilterSpec(); pfSpec.setPropSet(new PropertySpec[]{pSpec}); pfSpec.setObjectSet(new ObjectSpec[]{oSpec}); return new PropertyFilterSpec[]{pfSpec}; }
VMware, Inc.
89
Example 92showsanexcerptofsomeofthecodethatobtainsvaluesfortheinfopropertyfromeachTask objectinthearray. Example 9-2. Displaying TaskInfoState Values for Each Task in the recentTask Array
... private void displayTasks(ObjectContent[] oContents) { for(int oci=0; oci<oContents.length; ++oci) { System.out.println("Task"); DynamicProperty[] dps = oContents[oci].getPropSet(); if(dps!=null) { String op="", name="", type="", state="", error=""; for(int dpi=0; dpi<dps.length; ++dpi) { DynamicProperty dp = dps[dpi]; if("info.entity".equals(dp.getName())) { type = ((ManagedObjectReference)dp.getVal()).getType(); } else if ("info.entityName".equals(dp.getName())) { name = ((String)dp.getVal()); } else if ("info.name".equals(dp.getName())) { op = ((String)dp.getVal()); } else if ("info.state".equals(dp.getName())) { TaskInfoState tis = (TaskInfoState)dp.getVal(); if(TaskInfoState.error.equals(tis)) { state = "-Error"; } else if(TaskInfoState.queued.equals(tis)) { state = "-Queued"; } else if(TaskInfoState.running.equals(tis)) { state = "-Running"; } else if(TaskInfoState.success.equals(tis)) { state = "-Success"; } } else if ("info.cancelled".equals(dp.getName())) { Boolean b = (Boolean)dp.getVal(); if(b != null && b.booleanValue()) { state += "-Cancelled"; } }...
Example 93showsoutputfromarunoftheprogram.SeethesourcecodelistingforTaskList.javaorfor TaskList.csinthevSphereWebServicesSDKpackagefordetails. Example 9-3. Sample Run of the TaskList Java Application
java com.vmware.samples.general.TaskList --url https://srv/sdk --username root --password ******* Started Task Operation AcquireCimServicesTicket Name srv Type HostSystem State -Success Error ====================== Ended TaskList
Operations That Return Task Managed Objects

Table 95liststheoperationsavailableinvSphereAPI4.0thatreturnareferencetoaTaskmanagedobject.See thevSphereAPIReferenceformoreinformationabouteachoftheseoperations. Table 9-5. Operations that Return a Reference to a Task Managed Object
AddHost_Task AddStandaloneHost_Task CheckCompatibility_Task PowerDownHostToStandBy_Task PowerOffVApp_Task PowerOffVM_Task
90
VMware, Inc.
Table 9-5. Operations that Return a Reference to a Task Managed Object (Continued)
CheckHostPatch_Task CheckMigrate_Task CheckRelocate_Task CloneVApp_Task CloneVM_Task ComplianceManagerCheckCompliance_Task CopyDatastoreFile_Task CopyVirtualDisk_Task CreateChildVM_Task CreateDVS_Task CreateScreenshot_Task CreateSecondaryVM_Task CreateSnapshot_Task CreateVirtualDisk_Task CreateVM_Task CustomizeVM_Task DefragmentVirtualDisk_Task DeleteDatastoreFile_Task DeleteVirtualDisk_Task Destroy_Task DisableSecondaryVM_Task DisconnectHost_Task DVPortgroupReconfigure_Task DVSAddPortgroups_Task DVSMerge_Task DVSMovePort_Task DVSPerformProductSpecOperation_Task DVSReconfigure_Task DVSRectifyHost_Task EagerZeroVirtualDisk_Task EnableSecondaryVM_Task EnterMaintenanceMode_Task ExitMaintenanceMode_Task ExtendVirtualDisk_Task GenerateLogBundles_Task HostProfileApply_Task InflateVirtualDisk_Task InstallHostPatch_Task InstallHostPatchV2_Task MakePrimaryVM_Task MigrateVM_Task MoveDatastoreFile_Task PowerOnMultiVM_Task PowerOnVApp_Task PowerOnVM_Task PowerUpHostFromStandBy_Task ProfileCheckCompliance_Task PromoteDisks_Task QueryHostPatch_Task QueryVMotionCompatibilityEx_Task RebootHost_Task ReconfigureCluster_Task ReconfigureComputeResource_Task ReconfigureHostForDAS_Task ReconfigurePort_Task ReconfigVM_Task ReconnectHost_Task RegisterChildVM_Task RegisterVM_Task RelocateVM_Task RemoveAllSnapshots_Task RemoveSnapshot_Task Rename_Task ResetVM_Task ResignatureUnresolvedVmfsVolume_Task RevertToCurrentSnapshot_Task RevertToSnapshot_Task ScanHostPatch_Task ScanHostPatchV2_Task SearchDatastore_Task SearchDatastoreSubFolders_Task ShrinkVirtualDisk_Task ShutdownHost_Task StageHostPatch_Task StartRecording_Task StartReplaying_Task StopRecording_Task StopReplaying_Task SuspendVM_Task TerminateFaultTolerantVM_Task TurnOffFaultToleranceForVM_Task UninstallHostPatch_Task UnregisterAndDestroy_Task unregisterVApp_Task
VMware, Inc.
91
Table 9-5. Operations that Return a Reference to a Task Managed Object (Continued)
MoveHostInto_Task MoveInto_Task MoveIntoFolder_Task MoveVirtualDisk_Task UpgradeTools_Task UpgradeVM_Task ZeroFillVirtualDisk_Task ~
Introduction to the Event Data Object

InadditiontocreatingTaskreferences,manyoperationsonhostsandvirtualmachinesalsogenerateoneor moreEventdataobjectsastheoperationexecutesontheserver.AnEventisadataobjectthatconveys informationaboutchangesinthestateofmanagedentities. ForunmanagedESX/ESXisystems,Eventobjectsarenonpersistent.Eventsareretainedonlyforaslongas thehostsystemslocalmemorycancontainthem.RebootinganunmanagedESX/ESXihostorpoweringoffa virtualmachineremovesEventobjectsfromlocalmemory. AnunmanagedESX/ESXisystemmightretainabout15minutesworthofEventdataaboutthehostand virtualmachineoperations,butthiscanvary,dependingontheprocessingloadofthehost,thenumberof virtualmachines,andotherfactorsthataffectmemory. Figure 9-4. Events Exported from an Unmanaged ESX/ESXi System
FormanagedESX/ESXisystems,Eventobjectsarepersistent.ManagedESX/ESXisystemssendEventdatato thevCenterServersystemthatmanagesthem,andthevCenterServerstorestheinformationitsdatabase. ThesampleapplicationsincludedintheSDKpackageforhandlingeventscanbeusedwitheitherunmanaged ESX/ESXiorvCenterServersystems. UsingaHistoryCollector,youcanobtaininformationabouttheseobjectsastheyarebeingcollectedona specificESX/ESXisystem,orfromaspecifichistoricalperiodfromthedatabase.SeeObtainingInformation aboutEventsUsingaHistoryCollectoronpage 133. SeeUnderstandingEventManagerandtheEventDataObjectonpage 129formoreinformation.
92
VMware, Inc.
10
Working with Virtual Machines
10
AVirtualMachineisassociatedwithbothitscontainingFolderandtheResourcePoolfromwhichit obtainsresourcesatruntime,soitacquirespermissionsfromboththeseobjects. ManycapabilitiesofvirtualmachinesrequirethatVMwareToolsisinstalledontheguestoperatingsystemof thevirtualmachine.Forexample,VMwareToolsprovidesthememorymanagementdriverthatsupports ballooning,andthenetworkingdriverthatprovidesaDNSnameforthevirtualmachine.Inaddition,some oftheAPIavailabletovirtualmachinesrequireVMwareTools.Forexample,thequiesceparameteroftheis supportedonlyifVMwareToolsisinstalledonthevirtualmachine. TheVirtualMachineAPIsupportsprogrammaticallyupgradingtheVMwareToolssoftwareonthevirtual machineguestOS. Thischapterincludesthesetopics: SampleCodeReferenceonpage 93 CreatingVirtualMachinesonpage 93 OverviewofVirtualMachineOperationsonpage 94 OverviewofSnapshotsonpage 97

Table 101liststhesampleapplicationsincludedwiththevSphereWebServicesSDKthatdemonstratesome ofthetopicsdiscussedinthischapter. Table 10-1. Sample Applications that Demonstrate VirtualMachine Operations
Java SDK\samples\Axis\java\com\vmware\samples VMCreate.java VMPowerOps.java VMReconfig.java VMSnapshot.java C# SDK\samples\DotNet\cs VMCreate VMPowerOps VMReconfig VMSnapshot
Creating Virtual Machines

ForunmanagedESX/ESXisystems,youcreatevirtualmachinesusingtheFolderfactoryobjectinconjunction withinstancesofthevariousdataobjectsthatdefineallaspectsofthevirtualmachine,andreferencesforthe Folder,ResourcePool,andHostSystemmanagedobjectinstancesthatyouwanttousetosupportthe VirtualMachine.
VMware, Inc.
93
ThedataobjectsyoupasstotheCreateVM_TaskoftheFoldermanagedobjectincludeaninstanceofthe VirtualMachineConfigSpec.AVirtualMachineConfigSpecisacomplexdataobjectconsistingofalmost 50differentpropertiesthatmakeuptheconfigurationofthevirtualmachineyouwanttocreate.However,to createavirtualmachineonanunmanagedhostsystemyoumustprovideonlyafewpropertyvaluesfora minimalnumberofproperties,suchasthoseshowninExample 101. Example 10-1. Creating a VirtualMachineConfigSpec Data Object
ManagedObjectReference resourcePool = cb.getServiceUtil().getMoRefProp(crmor, "resourcePool"); ManagedObjectReference vmFolderMor = cb.getServiceUtil().getMoRefProp(dcmor, "vmFolder"); VirtualMachineConfigSpec vmConfigSpec = vmUtils.createVmConfigSpec(cb.get_option("vmname"), cb.get_option("datastorename"), Integer.parseInt(cb.get_option("disksize")), crmor, hostmor); vmConfigSpec.setName(cb.get_option("vmname")); vmConfigSpec.setAnnotation("VirtualMachine Annotation"); vmConfigSpec.setMemoryMB(new Long(Integer.parseInt(cb.get_option("memorysize")))); vmConfigSpec.setNumCPUs(Integer.parseInt(cb.get_option("cpucount"))); vmConfigSpec.setGuestId(cb.get_option("guestosid")); ManagedObjectReference taskmor = cb.getConnection().getService().createVM_Task( vmFolderMor, vmConfigSpec, resourcePool, hostmor);
Table 102listssomeofthepropertiesoftheResourceAllocationInfodataobjectthatareusedtoallocate CPUandmemoryresources. Table 10-2. ResourceAllocationInfo Data Object Properties

Unit of Measure Property reservation CPU MHz Memory MB Description Minimumamountoftheresourceguaranteedtobeavailableifitis needed.Anyunusedamountofareservationcanbeconsumedby othervirtualmachinesorresourcepoolsthatneedit. Maximumamountofresourcethatcanbeutilized,regardlessof availableresourcesonothervirtualmachinesorresourcepools. Usethelimitsettingtoensureconsistentperformanceofvirtual machinesandresourcepools,regardlessofavailableresources. Setto1toremoveallrestrictionsontheresourceutilization.The resourceislimitedtoavailableresourcesandshares. shares Relativeamountofresource(ascomparedtolevelsofothervirtual machines)thatcanbeutilized,specifiedusingtheSharesLevel enumeration(high,normal,low,orcustom).Forcustomshares, defineusingthesharespropertyand Whensettotrue,specifiesthatachildresourcepoolcangrow beyonditsreservationamountifitsparentresourcepoolhas unreservedresourcesavailable.
limit
MHz
MB
expandableReservation
Overview of Virtual Machine Operations

Table 103listsVirtualMachineoperationsavailabletovirtualmachinesrunningonunmanagedESX/ESXi systems.ForanyhostmanagedbyvCenterServer,usetheAPIavailableonthevCenterServerWebservice whencreatingormanagingvirtualmachines.SeeChapter 13,UsingvCenterServerforVirtualMachine Operations,onpage 119.
94
VMware, Inc.
Chapter 10 Working with Virtual Machines
Table 10-3. Basic VirtualMachine Operations Summary

Operation AcquireMksTicket Description Createsandreturnsaonetimecredentialforestablishingaremote mousekeyboardscreenconnectiontothisvirtualmachine.thismethoddepends onbeingabletoretrieveTCPbindinginformationabouttheserverendofthe clientconnectionthatisrequestingtheticket.Ifsuchinformationisnotavailable, theNotSupportedfaultisthrown.ThismethodisappropriateforSOAPand authenticatedconnections,whicharebothTCPbasedconnections. Respondstoaquestionthatisblockingthisvirtualmachine. Checksthecustomizationspecificationagainstthevirtualmachineconfiguration. Forexample,thisisusedonasourcevirtualmachinebeforeacloneoperationto catchcustomizationfailurebeforethediskcopy.Thischecksthespecifications internalconsistencyandforcompatibilitywiththisvirtualmachinesconfiguration. Createascreenshotofavirtualmachine. Createsanewsnapshotofthisvirtualmachine.Asasideeffect,thisupdatesthe currentsnapshot.Any%(percent)characterusedinthisnameparametermustbe escaped,unlessitisusedtostartanescapesequence.Clientsmayalsoescapeany othercharactersinthisnameparameter. Customizesavirtualmachinesguestoperatingsystem. Defragmentallvirtualdisksattachedtothisvirtualmachine. MountstheVMwareToolsCDinstallerasaCDROMfortheguestoperating system.YoucancheckthestatusoftheVMwareToolsinstallationbycheckingthe guest.toolsStatusproperty. Powersoffthisvirtualmachine.Ifthisvirtualmachineisafaulttolerantprimary virtualmachine,thiswillresultinthesecondaryvirtualmachine(s)getting poweredoffaswell. Powersonthisvirtualmachine.Ifthevirtualmachineissuspended,thismethod resumesexecutionfromthesuspendpoint.Whenpoweringonavirtualmachine inacluster,thesystemmightimplicitlyorduetothehostargument,doanimplicit relocationofthevirtualmachinetoanotherhost.Hence,errorsrelatedtothis relocationcanbethrown.IftheclusterisaDRScluster,DRSisinvokedifthe virtualmachinecanbeautomaticallyplacedbyDRS.Becausethismethoddoes notreturnaDRSClusterRecommendation,neitherVMotionnorhostpower operationsaredoneaspartofaDRSfacilitatedpoweron.IfyouwantDRSto considersuchoperations,usePowerOnMultiVM_Task.Ifthisvirtualmachineisa faulttolerantprimaryvirtualmachine,itssecondaryvirtualmachinesisstartedon systemselectedhosts.IfthevirtualmachinesareinaVMwareDRSenabled cluster,DRSisinvokedtoobtainplacementsforthesecondaries.However,neither VMotionnorhostpoweroperationsareconsideredforthesepowerons. ForallfilesthatbelongtotheVM,checkthatthefileownerissettothecurrent datastoreprincipaluser,assetby HostDatastoreSystem.ConfigureDatastorePrincipal. Issuesacommandtotheguestoperatingsystemaskingittoperformareboot. Returnsimmediatelyanddoesnotwaitfortheguestoperatingsystemtocomplete theoperation. Reconfiguresthisvirtualmachine.Allthechangesinthegivenconfigurationare appliedtothevirtualmachineasanatomicoperation. Explicitlyrefreshesthestorageinformationofthisvirtualmachine,updating propertieslayoutExandstorage. Removeallthesnapshotsassociatedwiththisvirtualmachine.Ifthevirtual machinedoesnothaveanysnapshots,thisoperationreturnssuccess. Clearscachedguestinformation.Guestinformationcanbeclearedonlyifthe virtualmachineispoweredoff.Thismethodcanbeusefulifstaleinformationis cached,preventinganIPaddressorMACaddressfrombeingreused.
AnswerVM CheckCustomizationSpec
CreateScreenshot_Task CreateSnapshot_Task
CustomizeVM_Task DefragmentAllDisks MountToolsInstaller
PowerOffVM_Task
PowerOnVM_Task
QueryUnownedFiles
RebootGuest
ReconfigVM_Task RefreshStorageInfo RemoveAllSnapshots_Task ResetGuestInformation
VMware, Inc.
95
Table 10-3. Basic VirtualMachine Operations Summary (Continued)

Operation ResetVM_Task Description Resetspoweronthisvirtualmachine.IfthecurrentstateispoweredOn,thenthis methodfirstperformspowerOff(hard).OncethepowerstateispoweredOff, thenthismethodperformspowerOn(option).Althoughthismethodfunctionsas apowerOfffollowedbyapowerOn,thetwooperationsareatomicwithrespectto otherclients,meaningthatotherpoweroperationscannotbeperformeduntilthe resetmethodcompletes. Revertsthevirtualmachinetothecurrentsnapshot.Thisisequivalenttorunning snapshot.currentSnapshot.revert.Ifnosnapshotexists,thentheoperation doesnothing,andthevirtualmachinestateremainsunchanged. Setstheconsolewindowsdisplaytopologyasspecified. Setstheconsolewindowsresolutionasspecified. Issuesacommandtotheguestoperatingsystemaskingittoperformaclean shutdownofallservices.Returnsimmediatelyanddoesnotwaitfortheguest operatingsystemtocompletetheoperation. Issuesacommandtotheguestoperatingsystemaskingittoprepareforasuspend operation.Returnsimmediatelyanddoesnotwaitfortheguestoperatingsystem tocompletetheoperation. Initiatesarecordingsessiononthisvirtualmachine.Asasideeffect,thisoperation createsasnapshotonthevirtualmachine,whichinturnbecomesthecurrent snapshot. Startsareplaysessiononthisvirtualmachine.Asasideeffect,thisoperation updatesthecurrentsnapshotofthevirtualmachine. Stopsacurrentlyactiverecordingsessiononthisvirtualmachine. Stopsareplaysessiononthisvirtualmachine. Suspendsexecutioninthisvirtualmachine. UnmountsVMwareToolsinstallerCD. UsetheFolder.RegisterVMmethodtorecreateaVirtualMachineobjectfrom thesetofvirtualmachinefilesbypassinginthepathtotheconfigurationfile. However,theVirtualMachinemanagedobjectthatresultstypicallyhasdifferent objectsIDandmayinheritadifferentsetofpermissions. Beginsthetoolsupgradeprocess.Monitorthestatusoftheinstallationusingthe guest.toolsStatusproperty. Upgradesthisvirtualmachinesvirtualhardwaretothelatestrevisionthatis supportedbythevirtualmachinescurrenthost.
RevertToCurrentSnapshot_Task
SetDisplayTopology SetScreenResolution ShutdownGuest
StandbyGuest
StartRecording_Task
StartReplaying_Task StopRecording_Task StopReplaying_Task SuspendVM_Task UnmountToolsInstaller UnregisterVM
UpgradeTools_Task UpgradeVM_Task
Workingwithanyvirtualmachinesfromaclientapplicationrequiresthevirtualmachinetobeconfigured properlyfornetworking.Specifically,theappropriateversionofVMwareToolsmustbeinstalledand configuredontheguestoperatingsystem(guestOS). ForeachguestOS,suchasWindows2003Server,RedHatEnterpriseServerLinux,orUbuntuLinux,VMware providesaspecificbinarycompatibleversionofVMwareTools.TheVMwareToolssoftwareprovidesmany benefits,suchasenhancingthedisplayinteractionforendusers.Italsoprovidesthevmxnetdriverneededfor thevirtualnetworkinterfacecontroller(vNIC)andvirtualmachinenetworkconfiguration.WithVMware ToolsinstalledontheguestOS,thevirtualmachineobtainsitsDNS(domainnameserver)nameandanIP addressandisthereforereachableoverthenetwork. IMPORTANTSelectingInstallVMwareTools fromthevSphereClientmenuonlydownloadstheappropriate installationpackagetothevirtualmachine.Youmustunpackthefile,runtheinstallationscriptorlaunchthe executable,andconfigureVMwareToolsontheguestoperatingsystemofthevirtualmachinetoenable networking,memorymanagement,andothercapabilitiesonthevirtualmachine.
96
VMware, Inc.
Chapter 10 Working with Virtual Machines
Overview of Snapshots
Asnapshotpreservesthestateanddataofavirtualmachineataspecificpointintime. Stateincludesthevirtualmachinespowerstate(poweredon,poweredoff,suspended,forexample). Dataincludesallthefilesthatmakeupthevirtualmachine,includingdisks,memory,andotherdevices, suchasvirtualnetworkinterfacecards. AVirtualMachineobjectprovidesseveraloperationsforcreatingandmanagingsnapshots.Theseoperations letyoucreatesnapshots,reverttoanysnapshotinthetree,andremovesnapshots.Youcancreateextensive snapshottreesthatyoucanusetosavevirtualmachinestateatanypointintime,andrestoreitlater,if necessary.
Creating Snapshots
Creatingasnapshotofavirtualmachinestartswithareference(instanceofManagedObjectReference)tothe targetvirtualmachine.PassthereferencetotheCreateSnapshot_Taskoperation,providinganameand description(bothstrings)forthesnapshot. TheCreateSnapshot_Taskoperationalsohastwobooleanproperties: memory,whichcanbesettotruetoincludethevirtualmachinesmemorydumpinthesnapshot. Includingmemoryinthesnapshotwilltakelonger(tocompletethesnapshotoperation)andcreatea largersnapshotfile. quiesce,whichcan(andshould)besettotruesothatthesnapshotwillincludethevirtualmachines diskdatainaconsistentstate:thispropertyquiescesthevirtualmachinesfilesystempriortoinitiating theoperation. SeethevSphereAPIReferenceformoreinformation.
Reverting to Snapshots
Afterasnapshotexistsonthesysteminatreeofsnapshots,youcanreinstatethesnapshotbyusingthe RevertToSnapshot_Taskoperation.SeethevSphereAPIReferencefordetails.
VMware, Inc.
97
98
VMware, Inc.
11
Managing Storage
11
vSphereserversrequirededicatedstoragespacefortheoperatingsystemfilesandforthecomponentsthat makeuptheinventory.Storageincludesphysical,logical,andvirtualconstructs.Thischapterincludesthese topics: SampleCodeReferenceonpage 99 OverviewofPhysicalandVirtualStorageConceptsonpage 99 IntroductiontotheHostStorageSystemManagedObjectonpage 102 IntroductiontotheHostDatastoreSystemManagedObjectonpage 106 ObtainingInformationaboutConfiguredStorageonpage 107 CreatingNewDatastoresonpage 108 ModifyingDatastoreConfigurationonpage 110

Table 111liststhesampleapplicationsincludedwiththevSphereWebServicesSDKthatdemonstratesome ofthetopicsdiscussedinthischapter. Table 11-1. Sample Applications that Demonstrate Storage and Datastore Operations
Java SDK\samples\Axis\java\com\vmware\samples\scsilun SCSILunName C# SDK\samples\DotNet\cs\GetVirtualDiskFiles GetVirtualDiskFiles.cs
Overview of Physical and Virtual Storage Concepts

Avirtualmachineismadeupoffilesthatcanbecopiedandmoved,justasanyothercomputerbasedfile. Thesefilesarestoredonthephysicalmediathatbacksthelogicalrepresentationofthestorage(thedevice isthelogicalrepresentation,inthiscontext). Thehostsystemcandiscoverstoragedevicesthatithasaccesstoandcanformatthesestoragedevices (or portionsofthem)asdatastores.Adatastoreisanabstractionthatprovidesaccesstothevirtualdisksofa virtualmachine.Adatastoreisalogicalcontainer(analogoustoastoragevolume)forthevirtualdiskand otherfilesthatencapsulateavirtualmachine. ThevirtualSCSIdisksaretypicallycontainedinaVirtualMachineFileSystem(VMFS)volume.VMFSisa clusteredfilesystem,optimizedforvirtualmachinesandisthedefaultfilesystemforthesetoffilesthat encapsulateseachvirtualmachineonphysicalSCSIdisksorpartitions. AVMFSvolumecontainsfiles,directories,symboliclinks,rawdevicemappings(RDMs),andmetadataabout itscontents.AnRDMisaspecialfileonaVMFSvolumethatmediatescommandstorawdevices.Rawdevices canalsobeusedtostorevirtualmachinefiles,buttheRDMfilemustbeavailableonaVMFSfilesystem.
VMware, Inc.
99
Virtualmachinesusevirtualdisksfortheiroperatingsystem,applicationsoftware,andotherdatafiles. A virtualdiskisstoredasaVMDKfileinsideadatastore. Figure 111providesaconceptualoverviewofthevariousstoragearchitecturessupportedbyvSphereservers, whichinclude: Storageareanetworks(SAN).SANscanbeimplementedusingvarioustechnologies,includingFibre Channel(FC)andInternetSCSI(iSCSI). Networkattachedstorage(NAS).NASstorageusesfilebasedprotocolssuchasNFS(networkfile system),NTFS(NTfilesystem),orSMB/CIFS(Microsoftlegacyservermessageblock/commoninternet filesystem). Directattachedstorage(DAS).Alsocalledlocalstorage.Localstoragehassomelimitationswhen comparedtoSANandNASsystems. Figure 11-1. Overview of Local, NAS, and SAN Storage
NOTEFigure 111isforillustrationpurposesonly.Itisnotarecommendedconfiguration.Detailshavebeen oversimplifiedonpurpose. WhenyoucreateavirtualmachineusingthevSphereClient,awizardguidesyouthroughtheconfiguration ofallsettings,includingstorage.Bydefault,avirtualmachineiscreatedwithonevirtualharddiskandone virtualSCSIcontroller. VirtualmachinesalwaysuseavirtualSCSIadapterandcommunicateusingtheSCSIcommandsetregardless ofthetypeofphysicalstorageSCSI,iSCSI,fibrechannel,orfilesystembased.Atruntime,theguest operatingsystemrunningonthevirtualmachineissuesSCSIcommandstoitsvirtualdisks.Thevirtualization layertranslatestheSCSIcommandsintoVMFSfileoperations.
Requirements for Storage

AnytypeofnetworkattachedstoragerequirescompleteconfigurationofnetworkingintheVMkernel,to supportnetworkbasedaccesstothestoragemedia.TheVMkernelrequiresitsownIPaddress.
100
VMware, Inc.
Chapter 11 Managing Storage
Overview of Internet SCSI Storage

iSCSIpackagesSCSIcommandsinsideinternetprotocol(IP)packetsandsendsfromahosttoastorage volume. Figure 11-2. Overview of iSCSI Storage
Figure 112showstwodifferentapproachestoInternetSCSI(iSCSI)storagesupportedbyvSphereservers. HardwarebasediSCSIusesaniSCSIhostbusadapter(HBA),whichservesasthesource(orinitiator) ofSCSIcommands. SoftwarebasediSCSIusesahighspeednetworkinghardware,suchas1GBEthernetNICsandswitches. ESX/ESXihasitsowniSCSIinitiator,builtintotheVMkernel.Bydefault,thesoftwareiSCSI implementationintheVMkernelisdisabled.(TheisSoftwareBasedpropertyofthe HostInternetScsiHbaissettofalse. NOTEDonotuse100MBEthernetNICsforiSCSIbasedstorage:itistooslow.Use1GB(orfaster)Ethernet. Aninitiatorspropertiesincludeitsmodelname,IPaddress,iSCSIname,discoverymethods,iSCSIalias,and alistofanytargetsthatithasalreadydiscovered.
Introduction to Managed Objects that Support Storage

TheHostSystemmanagedobjecthasaconfigManagerpropertythatisdefinedasaninstanceofa HostConfigManagerdataobject.TheHostConfigManagerdataobjectcontainsclosetotwentyproperties, eachofwhichcomprisesamanagedobjectreferencetoaspecificserviceinterfaceforthehostsystem.A HostConfigManagerdataobjecthastwopropertiesassociatedwithmanagingstorageatthefilesystemlevel, theotheratthelogical(volume)managementlevel: ThedatastoreSystemproperty,whichprovidesamanagedobjectreferencetothe HostDatastoreSystemoftheserver.HostDatastoreSystemprovidesoperationsforcreating, configuring,extending,andremovingthedatastoresavailableforusebythehostsystem(ESX/ESXi). HostDatastoreSystemistheabstractionforlogicalstorage,thevolumes(Datastoremanagedobjects) thatcanbeusedbythehostforvirtualmachines.
VMware, Inc.
101
ThestorageSystemproperty,whichprovidesamanagedobjectreferencetotheHostStorageSystemof theserver.HostStorageSystemprovidesoperationsassociatedwiththeconfigurationandmanagement ofthephysicalstorageimplementation.Itprovidesoperationsforcreating,configuring,andmanaging thehostsstoragesubsystem.AHostStorageSystemistheserviceinterfacetousetomakestorage availableforvirtualmachines. TheHostStorageSystemobjectprovidesanabstractionforphysicalstorageresources. The HostDatastoreSystemprovidesaccesstostorageresourcesaspresentedbythefilesystem. TheDatastoremanagedentityprovidesoperationsformountingdatastores,browsingdatastores,and obtaininginformationaboutthedatastoresassociatedwithavirtualmachine. Figure 11-3. Datastore Managed Object As a ManagedEntity
Introduction to the HostStorageSystem Managed Object

TheHostStorageSystemmanagedobjectcanbeusedtoobtaininformationabout,configure,andmanagethe storagesystemsusedbyVMwarevSphereservers.SpecifictypesofstoragearemodelledinthevSphere managementobjectassubtypesoftheHostHostBusAdapterbasedataobjecttype.AsshowninFigure 114, thesesubtypessupportFibreChannel(FC),SCSI,internetSCSI,anddirectlyattachedstorage. Figure 11-4. HostHostBusAdapter Data Object Type and Subtypes
102
VMware, Inc.
Table 112liststheoperationsavailabletoHostStorageSystemmanagedobjects. Table 11-2. HostStorageSystem Operations Summary

Operation AddInternetScsiSendTargets AddInternetScsiStaticTargets Description Addssendtargetentriestothehostbusadapterdiscoverylistifthe DiscoveryProperties.sendTargetsDiscoveryEnabledflagissettotrue. Addsstatictargetentriestothehostbusadapterdiscoverylist. The DiscoveryProperty.staticTargetDiscoveryEnabledflagmustbesetto true. ExtendsaVMFSbyattachingadiskpartitionasanextent. Computesthediskpartitioninformationbasedonthespecifieddisklayout. The servercomputesanewpartitioninformationobjectforaspecificdisk representingthespecifiedlayout. Computesthediskpartitioninformationtosupportresizingagivenpartition. Disablesanenabledpathforalogicalunit.Usethepathnamefrom HostMultipathStateInfoPathorHostMultipathInfoPath. Enablesadisabledpathforalogicalunit.Usethepathnamefrom HostMultipathStateInfoPathorHostMultipathInfoPath. ExpandsaVMFSextentasspecifiedbythediskpartitionspecification. FormatsanewVMFSonadiskpartition. Obtainsthesetofpathselectionpolicyoptions.Theseoptionsdeterminethepath thatcanbeusedbyadevicemanagedbynativemultipathing.A HostMultipathInfodataobjectidentifiesthedevicesthataremanagedthrough nativemultipathing. Obtainsthesetofstoragearraytypepolicyoptions.Theseoptionsdeterminethe storagearraytypepoliciesthatcanbeusedbyadevicemanagedbynative multipathing.AHostMultipathInfodataobjectidentifiesthedevicesthatare managedthroughnativemultipathing. ObtainsthelistofunboundVMFSvolumes.Forsharingavolumeacrosshosts,a VMFSvolumeisboundtoitsunderlyingblockdevicestorage.Whenalowlevel blockcopyisperformedtocopyormovetheVMFSvolume,thecopiedvolumewill beunbound. Refreshthestorageinformationandsettingstopickupanychangesthatmight haveoccurred. Removessendtargetentriesfromthehostbusadapterdiscoverylist. The DiscoveryProperty.sendTargetsDiscoveryEnabledmustbesettotrue.If anyofthetargetsprovidedasparametersarenotfoundintheexistinglist,the othertargetsareremovedandanexceptionisthrown. Removestatictargetentriesfromthehostbusadapterdiscoverylist. The DiscoveryProperty.staticTargetDiscoveryEnabledmustbesettotrue. Ifanyofthetargetsprovidedasparametersarenotfoundintheexistinglist,the othertargetsareremovedandanexceptionisthrown. Issuearequesttorescanallvirtualmachinehostbusadaptersfornewstorage devices. Issuearequesttorescanaspecificvirtualmachinehostbusadapterfornewstorage devices. RescansfornewVMFSinstancesthatmighthavebeenadded. ResignatureorforcemountlistofunboundVMFSvolumes.VMFSvolumesare boundtotheirunderlyingblockstoragedevices. Returnsanarraycontaininginformationaboutthepartitionsonthehost(anarray ofHostDiskPartitionInfoobjects). UpdatesthepathselectionpolicyforaLogicalUnit.UsetheLUNUUIDfrom HostMultipathInfoLogicalUnit.
AttachVmfsExtent ComputeDiskPartitionInfo
ComputeDiskPartition InfoForResize DisableMultipathPath EnableMultipathPath ExpandVmfsExtent FormatVmfs QueryPathSelection PolicyOptions
QueryStorageArrayType PolicyOptions
QueryUnresolved VmfsVolume
RefreshStorageSystem RemoveInternetScsi SendTargets
RemoveInternetScsi StaticTargets
RescanAllHba RescanHba RescanVmfs ResolveMultiple Unresolved VmfsVolumes RetrieveDiskPartitionInfo SetMultipathLunPolicy
VMware, Inc.
103
Table 11-2. HostStorageSystem Operations Summary (Continued)

Operation UnmountForceMounted VmfsVolume Description UnmounttheforcemountedVMFSvolume.Whenalowlevelblockcopyis performedtocopyormovetheVMFSvolume,thecopiedvolumeisunresolved. FortheVMFSvolumetobeusable,aresolutionoperationisapplied.Aspartof resolutionoperation,usermaydecidetokeeptheoriginalVMFSUUID.Oncethe resolutionisapplied,theVMFSvolumeismountedonthehostforitsuse.Usercan unmounttheVMFSvolumeifitisnotbeingusedbyanyregisteredVMs. Changesthepartitionsonthediskbysupplyingapartitionspecificationandthe devicename. UpdatestheadvancedoptionstheiSCSIhostbusadapterorthediscovery addressesandtargetsassociatedwithit. UpdatesthealiasofaniSCSIhostbusadapter. Updatestheauthenticationpropertiesforoneormoretargetsordiscovery addressesassociatedwithaniSCSIhostbusadapter. UpdatesthedigestpropertiesfortheiSCSIhostbusadapterorthediscovery addressesandtargetsassociatedwithit. UpdatesthediscoverypropertiesforaniSCSIhostbusadapter. UpdatestheIPpropertiesforaniSCSIhostbusadapter. UpdatesthenameofaniSCSIhostbusadapter. UpdatethemutabledisplaynameassociatedwithaSCSILUN.TheSCSILUNto beupdatedisidentifiedusingthespecifiedUUID. EnablesanddisablessoftwareiSCSIintheVMkernel. UpgradestheVMFStothecurrentVMFSversion. Iteratesoverallregisteredvirtualmachines.ForeachVMwhichVMXfileislocated ontheserviceconsoleandalldisksareavailableonVMFS3orNAS,relocatesthe disksintodirectoriesifstoredintheROOT,andrelocatetheVMXfileintothe directorytoo.Eventsareloggedforeachvirtualmachinethatisrelocated.
UpdateDiskPartitions UpdateInternetScsi AdvancedOptions UpdateInternetScsiAlias UpdateInternetScsi AuthenticationProperties UpdateInternetScsiDigest Properties UpdateInternetScsiDiscovery Properties UpdateInternetScsiIP Properties UpdateInternetScsiName UpdateScsiLunDisplayName UpdateSoftware InternetScsiEnabled UpgradeVmfs UpgradeVmLayout
IftheDiscoveryProperties.sendTargetsDiscoveryEnabledflagissettotrue,the AddInternetScsiSendTargetoperationaddssendtargetentriestothestorageadaptersdiscoverylist. Toobtainmanagedobjectreferences,createaPropertyFilterSpectoobtainHostSystemmanagedobjects andtheappropriateproperty. To enable the VMkernel to support software iSCSI 1 2 ObtainamanagedobjectreferencetothehostsystemsHostStorageSystem. InvoketheUpdateSoftwareInternetScsiEnabledoperation,passingthereferencetothe HostStorageSystemandthevaluetrue.
iSCSIinitiatorsandtargetshaveunique,permanentiSCSInamesandaddresses.AniSCSInamecorrectly identifiesaspecificiSCSIinitiatorortarget,regardlessofphysicallocation.Namesconformtooneoftwo alternativeformatswhicharespecifictothestoragevendorshardware(Table 113).
104
VMware, Inc.
Table 11-3. Format for iSCSI Names

Description Extendeduniqueidentifier.A64bitglobalidentifierassignedbythe hardwaremanufacturer.AnEUIaddressincludesthe24bitcompany name(theorganizationallyuniqueidentifier,orOUI,assignedbythe IEEEtothevendor),anda40bituniqueID,suchasaserialnumber. iSCSIqualifiedname.Beginswithinitialsiqn followedbythe companydomaininreverseorder.Forexample, iqn.2000-04.com.qlogic:qle4060c.my-san-server55.1 Format eui.0123456789ABCDEF
Name EUI
IQN
iqn.yyyy-mm.com.company: san-server-name
To configure iSCSI Initiators 1 AccessthelistofavailableHBAsonthehostsystembyobtainingthenestedvalueforhostbusadapters configuredonthehost.YoucandothisbycreatingapropertycollectorwithHostSystemasthestarting point.FromtheHostSystemconfigproperty,youcanobtainthelist(array)ofhostbusadaptersby specifyingthispropertypath:

config.storageDevice.hostBusAdapter
Thispropertypathreturnsanarrayofhostbusadapters.Forexample:
hostBusAdapter["key-vim.host.BlockHba-vmhba32"] hostBusAdapter["key-vim.host.BlockHba-vmhba33"] hostBusAdapter["key-vim.host.BlockHba-vmhba34"] hostBusAdapter["key-vim.host.BlockHba-vmhba35"] hostBusAdapter["key-vim.host.BlockHba-vmhba1"] ...
2 3 4
Fromthearray,selectthehostbusadapter(instanceofHostHostBusAdapter)thatyouwanttoconfigure andobtainitskeyproperty,whichisastringconsistingofthedevicenameofthehostbusadapter. DeterminethecapabilitiesoftheiSCSIHostBusAdapterHBA. Configuretheinitiator. Forahardwareinitiator,configuretheIPaddress. Forasoftwareinitiator,enablethesoftwareinitiatorintheVMkernel.
5 6 7 8 9
ConfiguretheiSCSInameandalias. Configuretargetdiscovery. Settheauthenticationinformation.(SkipthisstepifyouarenotusingCHAP.) Configureaccesstothetargets. Invokearescanoperationonthehostbusadapters.RescanenablestheHBAstodiscoverthenewstorage devices.YoucaneitherissuearescanforasingleHBAusingtheRescanHbaoperationwiththeHBAID asaparameterorissuearescanonallHBAsusingRescanAllHba.
VMware, Inc.
105
Figure 11-5. HostHostBusAdapter Data Object and Associated Data Objects
Introduction to the HostDatastoreSystem Managed Object

Figure 116showssomeoftherelationshipsamongHostSystemmanagedobjects,datastores,andstorage. Figure 11-6. HostSystem and HostDatastoreSystem
Theobjectsreturneddependonthespecificsofthequery.Forexample,theQueryAvailableDisksForVmfs returnsanarrayofreferencestoanarrayofHostVmfsDatastoreOptiondataobjectsthatrepresentthe configuredstorageforthehost. Table 11-4. Summary of HostDatastoreSystem Operations

Operation ConfigureDatastore Principal Description Configuresdatastoreprincipaluserforthehost.Allvirtualmachinerelated fileI/Oisperformedunderthisuser.Usethisoperationifyouwanttothe virtualmachinefilesconfiguration,disk,andsoontobecheckedfor properaccess.Hostmustbeplacedinmaintenancemodeforthisoperation. Requiresareboottoeffectchanges.Doesnotapplytovirtualmachinefiles storedonNFS. Createsanewlocaldatastoreonthehostsystem,inthespecifieddirectory. Createsanewnetworkattachedstoragedatastoreusingthespecifications suppliedintheHostNasVolumeSpecdataobject. CreatesanewVMFSdatastoreusingthespecificationssuppliedinthe VmfsDatastoreCreateSpecdataobject.
CreateLocalDatastore CreateNasDatastore CreateVmfsDatastore
106
VMware, Inc.
Table 11-4. Summary of HostDatastoreSystem Operations (Continued)

Operation ExpandVmfsDatastore Description ExpandsanexistingVMFSdatastoreusingthespecificationprovidedinthe VmfsDatastoreExpandSpecdataobject(whichcontainsthenameofthe extentandpartitioninformation). ExtendsanexistingVMFSdatastoreusingthespecificationprovidedinthe VmfsDatastoreExtendSpecdataobject. ObtainlistofdisksthatcanbeusedtocontainVMFSdatastoreextents. Optionally,provideadatastorenametoobtainlistofdisksthatcancontain extentsforthespecifiedVMFSdatastore.Theoperationdoesnotreturndisks currentlyusedbytheVMFSdatastore,nordoesitreturnmanagementLUNs anddisksreferencedbyRDMs(whicharentusableforVMFSdatastores). ObtainthelistofunboundVMFSvolumes.Forsharingavolumeacrosshosts, aVMFSvolumeisboundtoitsunderlyingblockdevicestorage.Whenalow levelblockcopyisperformedtocopyormovetheVMFSvolume,thecopied volumewillbeunbound. ObtaininformationaboutoptionsforcreatinganewVMFSdatastoreforadisk. Obtaininformationaboutoptionsforexpandingtheextentsofanexisting VMFSdatastore. ObtaininformationaboutoptionsforextendinganexistingVMFSdatastore foradisk. Removesadatastorefromahost. AssignsanewDiskUuidtoaVMFSvolumebutkeepsitscontentsintact. This operationfacilitatessafevolumesharingacrosshosts.VMFSvolumesare boundtotheirunderlyingblockdevice. ChoosethelocalSwapDatastoreforthishost.Anychangetothissettingwill affectvirtualmachinesthatsubsequentlypoweronorresumefroma suspendedstateatthishost,orthatmigratetothishostwhilepoweredon. Virtualmachinesthatarecurrentlypoweredonatthishostarenotaffected.
ExtendVmfsDatastore QueryAvailableDisksForVmfs
QueryUnresolvedVmfsVolumes
QueryVmfsDatastoreCreateOptions QueryVmfsDatastoreExpandOptions QueryVmfsDatastoreExtendOptions RemoveDatastore ResignatureUnresolvedVmfs Volume_Task UpdateLocalSwapDatastore
TheExpandVmfsDatastoreoperationincreasesthesizeofthedatastoreuptothefullsizeprovisionedforthe datastore,ifnecessary. SeethevSphereAPIReferenceformoreinformationabouttheHostDatastoreSystemoperations,including constraintsandlimitations.
Obtaining Information about Configured Storage

Table 115listsseveralqueryoperationsavailableonHostDatastoreSystem.Usetheseoperationstofindout aboutexistingstorageconfiguredonanESX/ESXisystembeforecreatingnewstorageormodifyingexistingstorage. ThequeryoperationsforHostDatastoreSystemarespecifictothetypeofstorage,butmostworkinthesame generalway,typicallyrequiringthemanagedobjectreferencetotheHostDatastoreSystemandoneormore specificdataobjectsspecifyingtheconfigurationdetails. Table 11-5. HostDatastoreSystem Query Operations
Operation QueryAvailableDisks ForVmfs Parameter _this datastore _this devicePath Type MOR>HostDatastoreSystem MOR>Datastore MOR>HostDatastoreSystem string Description ReferencetotheHostDatastoreSystem. Referencetoanexistingdatastoreon whichtocreateoraddVMFSextents. ReferencetotheHostDatastoreSystem usedfortheinvocation. ThedevicePathofthediskonwhich datastorecreationoptionsaregenerated. Thedevicepathisafilepaththatcanbe openedtocreatepartitionsonthedisk.
QueryVmfsDatastore CreateOptions
VMware, Inc.
107
Table 11-5. HostDatastoreSystem Query Operations (Continued)

Operation QueryVmfsDatastore ExtendOptions Parameter _this datastore devicePath suppress Expand Candidates Type MOR>HostDatastoreSystem MOR>Datastore string boolean Description ReferencetotheHostDatastoreSystem usedtomakethemethodcall. Referencetothedatastoretoextend. ThedevicePathofthediskonwhich datastorecreationoptionsaregenerated. Indicateswhethertoexcludeoptionsthat canbeusedforeitherextendingor expandingextent. Settotruetoexcludefreespaceavailable forexpansion.
Freespacecanbeusedforaddinganextentorexpandinganexistingextent.Expandinganexistingextentis sometimesreferredtoasgrowingtheextent.
Creating New Datastores

TheHostDatastoreSystemprovidesseveraloperationsforcreatingnewdatastores(Table 116).Allofthe operationsrequireamanagedobjectreferencetoHostDatastoreSystem,andreturnareferencetothe Datastoreobjectafteritiscreated. Table 11-6. HostDatastoreSystem Creation Operations
Operation CreateLocalDatastore Parameter _this name path Type MOR>HostDatastoreSystem string string Description ReferencetotheHostDatastoreSystem ofthehostsystem. Hostwideuniquenameforthedatastore. Filepathtothedirectoryinwhichvirtual machinedata(specifically,VMXand otherfiles)willbelocated. ReferencetotheHostDatastoreSystem ofthehostsystem. Dataobjectthatdefinesthelocalpath, remotehost,andremotepathforthe datastore.SeeTable 117fordetails. ReferencetotheHostDatastoreSystem. Specificationforcreatingadatastore backedbyVMFS.Thedataobjectdefines theextent(ifappropriate,toappendtoan existingVMFSdatastore),thepartition, andtheVMFSpropertiesforthe datastore.
CreateNasDatastore
_this spec
MOR>HostDatastoreSystem HostNasVolumeSpec
CreateVmfsDatastore
_this spec
MOR>HostDatastoreSystem VmfsDatastoreCreateSpec
Table 117liststhepropertiesanddatatypesoftheHostNasVolumeSpecdataobject.Youcreateaninstanceof thisdataobjecttodefineanetworkattachedstoragebaseddatastoreonthesystem.
108
VMware, Inc.
Table 11-7. HostNasVolumeSpec Data Object

Property accessMode localPath Type string string Description and Usage Accessmodeforthemountpoint.AccessmodesincludestandardNFSfilepermissions. NameoftheNASdatastorethatwillbecreatedusingthisspecification. ESX/ESXisystems:Datastorenameisacomponentinthefilesystempathatwhichthe NASvolumecanbefound.Forexample,iflocalPathissettonas_volumethecreated NASdatastoreisnamed"nas_volume"anditcanbeaccessedusingthefilesystempath /vmfs/volumes/nas_volume. vCenterServersystem:DatastorenameislocalPath,butthedatastorenamemaynot beshowninthefilesystempathwheretheNASvolumeisaccessed. password remoteHost remotePath type userName string string string string string SettoCIFSifthepasswordfortheCIFSservershouldbeused.IftypeisNFS,thisfieldis ignored. FullyqualifiednameofthehostsupportingtheNFSserver. RemotepathtotheNFSmountpoint. Typeofnetworkattachedstoragevolume.DefaultisNFS.ValidtypesincludeCIFSand NFS. IftypeisCIFS,theusernametousewhenconnectingtotheCIFSserver.IftypeisNFS,this fieldisignored.
TocreateaVMFSbaseddatastore,youusetheCreateVmfsDatastoreoperation.Thisoperationtakesa VmfsDatastoreCreateSpecdataobjectthatconsistsofanextent,apartition,andavmfsproperty,allof whicharecomplexdataobjects.Forexample,thevmfspropertyisdefinedasaninstanceoftheHostVmfsSpec dataobject.Table 118liststhepropertiesanddatatypesoftheHostVmfsSpecdataobject. Table 11-8. HostVmfsSpec Data Object
Property blockSizeMb Type int Description and Usage Optional.VMFSblocksize,inmegabytes(MB).Controlsmaximumfilesize. ValidblocksizevariesbyVMFSversion: VMFS31MB VMFS21,2,4,8,16,32,64,128,256MB extent HostScsiDiskParti tion PrimaryextentthatidentifiestheVMFSinvmhbaI:T:Lformat.Thedatais notguaranteedtobestableacrossreboots,sodonottrytoidentifyVMFS usingthisdata.Instead,defineauniquevolumenameonthehostanduseit torefertotheVMFS.Or,usetheVMFSUUID(whichisimmutableafteritis created). VMFSversionnumber,suchas2or3.Versionnumbercanbeoptionally changedduringanupgrade.Upgradedfilesystemscannotbedowngraded. NameoftheVMFSvolume.
majorVersion volumeName
int string
Table 119liststhepropertiesanddatatypesfortheHostScsiDiskPartitiondataobject. Table 11-9. HostScsiDiskPartition Data Object

Property diskName Type string Description and Usage NameoftheSCSIdiskdeviceonwhichtheVMFSextentresides.Thename canbeathenameoftheHostScsiDiskdataobjectorthecanonicalName (propertyofScsiLundataobject). NumberoftheHostScsiDiskpartition.
partition
int
Definingthespecificationforadatastoretakesafairnumberofcomplexdataobjects,suchasthese.Seethe vSphereAPIReferenceformoreinformation.
VMware, Inc.
109
Modifying Datastore Configuration

Table 1110liststheoperationsavailabletochangetheHostDatastoreSystemconfiguration. Table 11-10. HostDatastoreSystem Modification Operations
Operation ConfigureDatastorePrincipal Parameter _this Type MOR>HostDatastoreSystem Description Referencetothe HostDatastoreSystem serviceinterface. Principal(user)nameforthe datastore. Optional.Passwordfor storagesystemsthatsupport userimpersonationand requirepassword. Referencetothe HostDatastoreSystem serviceinterface. ReferencetotheDatastoreto expand.Increasesthesizeof anexistingextent. Dataobjectdefiningthe extentsoftheDatastoreto expand. Referencetothe HostDatastoreSystem serviceinterface. ReferencetotheDatastoreto extendbyaddingnew extents. Dataobjectdefiningthe extentstoaddtothe Datastore. Referencetothe HostDatastoreSystem serviceinterface. ReferencetotheDatastoreto remove. Referencetothe HostDatastoreSystem serviceinterface. TheHUVRSdataobject containsastringarray comprisingthelistofdevice paths,eachofwhichspecifies aVMFSextent.
userName password
string string
ExpandVmfsDatastore
_this
MOR>HostDatastoreSystem
datastore
MOR>Datastore
spec
VmfsDatastoreExpandSpec
ExtendVmfsDatastore
_this
MOR > HostDatastoreSystem MOR>Datastore
datastore
spec
VmfsDatastoreExtendSpec
RemoveDatastore
_this
MOR>HostDatastoreSystem
datastore ResignatureUnresolvedVmfs Volume_Task _this
MOR>Datastore MOR>HostDatastoreSystem
resolutionSpec
HostUnresolvedVmfs ResignatureSpec
110
VMware, Inc.
12
Monitoring Performance
12
VMwarevSphereservershavebeeninstrumentedusingacomprehensivesystemthattracksutilizationof resourcesbyvariousobjects.Atruntime,statisticaldataisgeneratedbythevSphereserversperformance providers.Aperformanceproviderisanyentityonthesystemthatgeneratesutilizationorconsumption information.PerformanceprovidersincludeallthemanagedentitiessuchasHostSystemand VirtualMachineobjects,andthedevicesassociatedwiththem,suchasvirtualdisks. IMPORTANTSeveraldataobjects,includingHostListSummaryQuickStats,VirtualMachineQuickStats, andResourcePoolQuickStats,providenearrealtimesummaryinformationaboutperformanceor utilizationwithoutgoingthroughthePerformanceManager.Thesedataobjectsdonotsupportmonitoring. Thischapterincludesthesetopics: SampleCodeReferenceonpage 111 IntroductiontoPerformanceManageronpage 112 ObtainingStatisticsonpage 115 vCenterServerandPerformanceManageronpage 117

Table 121liststhesampleapplicationsincludedwiththevSphereWebServicesSDKthatdemonstratesome ofthetopicsdiscussedinthischapter. Table 12-1. Sample Applications that Demonstrate Using PerformanceManager Operations
Java SDK\samples\Axis\java\com\vmware\samples\performance Basics.java History.java PrintCounters.java Realtime.java VITop.java VIUsage.java C# SDK\samples\DotNet\cs Basics History PrintCounters QueryMemoryOverhead RealTime
VMware, Inc.
111
Introduction to PerformanceManager
ThePerformanceManageristheserviceinterfaceforobtainingstatisticaldataaboutvariousaspectsofsystem performance,asgeneratedandmaintainedbyvariousperformanceproviders. Table 12-2. PerformanceManager Properties
Property description Type PerformanceDescript ion PerfInterval[ ] Description Thedescriptionpropertyisacompositeobjectthatincludes informationaboutthetypesofcounters(counterType)and statistics(statsType)availableonthesystem. AnarrayofPerfIntervaldataobjectsthatdefinesthe performanceintervalsconfiguredforthesystem. ForanESX/ESXisystem,thearraycontainsasingleobjectthat definesthebaselinesamplingperiodfortheserver. ForavCenterServer,thisarraycontainsfourobjects.See HistoricalIntervalsonpage 117formoreinformation. perfCounter PerfCounterInfo[ ] AnarrayofPerfCounterInfodataobjectsthatcontainsallthe metadataassociatedwiththeperformancemetricsgeneratedon thesystem.
historicalInterval
InadditiontothepropertieslistedinTable 122,PerformanceManagerprovidesseveralqueryoperationsfor obtainingmetadatathatdefinesthestatistics,andforobtainingstatisticalvaluesaboutperformance. Table 12-3. PerformanceManager Operations

Operation QueryAvailablePerfMetric QueryPerf QueryPerfComposite Description ObtainsmetricscollectedforspecifictimeframesorhavingaspecificintervalId. Obtainsmetricsforaspecificlistofmanagedentities.Monitorspecificentitiesthat provideperformancedata. Obtainsmetricsforthespecifiedinventoryentityanditsfirstgenerationchild entities,suchasforahostanditsvirtualmachines.Thisoperationacceptsthe refreshRateforcurrentstatisticsortheintervalIdofoneofthehistorical intervals.SupportedforHostSystemmanagedentityonly. ObtainsPerfCounterInfodataobjectsforthespecifiedlistofcounterIDs. ObtainsPerfCounterInfodataobjectsforthespecifiedcollectionlevel. ObtainsthePerfProviderSummarydataobjectforthespecifiedmanagedobject.
QueryPerfCounter QueryPerfCounterByLevel QueryPerfProviderSummary
SeethevSphereAPIReferenceforVMwareWebServicesSDK4.0forcompletePerformanceManager documentation.
Overview of Counter Groups and the PerfCounterInfo Data Object

Theperformancemonitoringsystemwasdesignedformaximumflexibility.Eachperformanceproviderhas itsownsetofcountersthatprovidesmetadataabouttheperformancedataitmightgenerate.Countersare organizedbygroupsoffinitesystemresources,suchasmemory,CPU,disk,andsoon.ThevSphereAPI Referenceincludesdocumentationforthefollowingcountergroups: CPU DiskI/OCounters ManagementAgent Memory Network StorageUtilizationCounters VirtualMachineOperations
112
VMware, Inc.
Chapter 12 Monitoring Performance
Someofthesecountergroups,suchasstorageutilization,arenewinvSphere4.0.Thecountergroupsand specificcountersusedonanysystemdependonthespecificconfiguration.Notallcountergroupsareused, andyoumightfindavailablecountersthatarealsonotused.Disregardanyextraneouscounters. ThecountersaremodeledinthesystemusingthePerfCounterInfodataobject.Instancesofthisdataobject providethemetadatafortheruntimestatisticalvalues. Figure 12-1. PerfCounterInfo Data Object
ThePerfCounterInfodataobjectincludesadescription,theunitofmeasurethatthecounterrepresents,and theotherattributeslistedinTable 124. Table 12-4. PerfCounterInfo Data Object Properties

Property associatedCounterId Type int [ ] Description AnarrayofintegersthatlistscounterIDs (PerfCounterInfo.keyproperty)forothercountersrelatedto thisone.Thispropertyisnotusedincurrentreleases. Containsthenameoftheresourcegrouptowhichthiscounter belongs,suchasdisk,cpu,ormemory. Auniqueintegerthatidentifiesthecounter.Alsocalledthe counterID.Thevalueisnotstatic.Thecounterkeyonan ESX/ESXisystemmightnotbethesameasthecounterkeyforthe samecounteronthevCenterServersystemmanagingthe ESX/ESXihost.However,thesystemmapsthekeysfrom ESX/ESXitovCenterServersystemstransparently. Anumberfrom1to4thatidentifiesthelevelatwhichthis counterwillbeaggregatedwithothersofitskindintovCenter Serversystems. Adescriptivenameforthecounterthatcomprisesseveralnested properties. Identifiesthefunctionthatcontrolshowdataisconvertedasitis consolidatedfromoneintervalintothenextinterval.Some countersspecifyabsolutevalues,suchasthetotalnumberof secondsthatthesystemhasbeenrunningcontinuouslysince startup,andsonoconversionofvaluesoccurs.The PerfSummaryTypeisanenumerationcontainingvalidconstants forthisproperty.
groupInfo key
ElementDescription int
level
int
nameInfo rollupType
ElementDescription PerfSummaryType
VMware, Inc.
113
Table 12-4. PerfCounterInfo Data Object Properties (Continued)

Property statsType Type PerfStatsType Description Identifiesthetypeofstatisticaldatathatthevaluerepresents overthecourseoftheinterval,suchasanaverage,arate,the minimumvalue,themaximumvalue,summation,latest,or absolute.ThePerfStatsTypeisanenumerationcontaining validconstantsforthisproperty. Unitofmeasure,suchasmegahertz,kilobytes,kilobytesper second,andsoon.The ElementDescriptionskeypropertyis populatedusingoneoftheconstantsavailableinthe PerformanceManagerUnitenumeration.
unitInfo
ElementDescription
Eachcounterhaskeypropertythatidentifiesthemetricgeneratedbythesystem.Thevalueofkeyisunique andisnotstaticitmightchangebetweensystemreboots,forexample.Atruntime,thekeypropertyofa PerfCounterInfoinstanceisusedtopopulatethevalueofthecounterIdpropertyofaspecific PerfMetricIdinstance(Figure 122). Figure 12-2. PerfCounterInfo Key Matches a PerfMetricId CounterId
TheinstancevalueofPerfMetricIdassociatestheinstanceofthemetricwithitssource.Thestringforthe instancevalueisderivedfromconfigurationnamesforthedevice,butthisvaluemaybeempty.Forexample, formemoryandaggregatedmetricvalues,thispropertyisempty.ForaCPU,thispropertyidentifiesthe numericpositionwithintheCPUcore,suchas0,1,2,3.
Sampling Periods and Intervals

UnmanagedESX/ESXisystemsproviderealtimestatisticsforthecurrentdayonly.Managedhostssend statisticstothevCenterServersystemthatmanagesthem.ThevCenterServerconsolidatesthestatistical performancedatafromalltheESX/ESXisystemsthatitmanagesandstorestheinformationinitsdatabase. Table 12-5. Default Sampling Periods and Retention
Sampling Period 20seconds 5minutes 1hour 6hour 24hour Retention Period 1day 24hours 7days 30days 365days ESX, ESXi vCenter Server
114
VMware, Inc.
ThehistoricalIntervalisdefinedasanarrayofPerfIntervaldataobjects.ForanESX/ESXisystem,the arraycontainsasinglePerfIntervalobjectwiththepropertieslistedinTable 126. Table 12-6. Values of PerfInterval Data Object from an ESX/ESXi System
Property key name samplingPeriod length enabled level Value 1 PastDay 300 129600 true null Description NumericidentifierforthePerfInterval. NameofthePerfInterval. Numberofsecondsduringwhichthesystemsamplesperformance datatoproduceametric. Numberofsecondsthatstatisticsassociatedwiththeintervalarekept bythesystem. DenotesthatthisPerfIntervalisenabledonthesystem. Statisticscollectionlevel.ForanESX/ESXisystem,thispropertyis null.ThePerfIntervalobjectonanESX/ESXisystemdefinesthe baselineinterval.
SeeHistoricalIntervalsonpage 117forinformationaboutintervalsonmanagedhostsusingvCenterServer.
Obtaining Statistics
YouusetheQueryPerfandtheQueryPerfCompositeoperationsofPerformanceManagertoobtain statisticaldataaboutperformance.Theseoperationsbehavedifferently,inthefollowingways: TheQueryPerfoperationretrievesperformancestatisticsforoneormoreinventoryentities.Withoutan intervalIdaspartofthequery,theQueryPerfoperationsummarizesacrossallintervals.Youdefine oneoremorePerfQuerySpecobjectsforthequerySpecparameterforthisoperation,andtheserver returnsanarrayofoneormorePerfEntityMetricBaseobjects. TheQueryPerfCompositeoperationretrievesperformancestatisticsforanentityanditsfirstgeneration childentities. Forbothoperations,youmustdefinethestatisticsyouwanttoretrieveusingaPerfQuerySpecdataobject. ForQueryPerf,yousubmitanarrayofPerfQuerySpecobjects. ForQueryPerfComposite,yousubmitasinglePerfQuerySpecobject. Figure 12-3. Define a PerfQuerySpec to Obtain Statistics
TheQueryPerfCompositeoperationworksatthehostlevelonly.Youcanobtainstatisticsforahostandits associatedvirtualmachinesforthespecifiedinterval.Theclientcanlimitthereturnedinformationby specifyingalistofmetrics,andasampleintervalID.TheserveracceptstherefreshRatepropertyoroneof thehistoricalintervalsasinputinterval.

VMware, Inc. 115
QueryPerfCompositeisdesignedforefficientclientservercommunications.Intheory,itgeneratesless networktraffic(thanQueryPerf)becauseitreturnsalargegrainedobject,aPerfCompositeMetricdata objectthatcontainsallthedata(seeFigure 124,PerfEntityMetricBaseDataObject,onpage 116). Figure 12-4. PerfEntityMetricBase Data Object
BeforeusingQueryPerforQueryPerfComposite,youusetheQueryAvailablePerfMetricoperation beforeeitheroftheseoperations,toretrieveinformationaboutthemetricsthatareavailableforaspecified managedentitywithinagiventimeframe,soyoucanspecifythemetricsyouwanttoobtain. Table 127liststheparametersfortheQueryAvailablePerfMetricoperation. Table 12-7. QueryAvailablePerfMetric Operation

Parameter _this entity beginTime Type MOR>PerformanceManager MOR>ManagedEntity dateTime Description ReferencetothePerformanceManager. Referencetothemanagedentityforwhichavailablemetrics shouldbeobtained. Optional.Servertimefromwhichtostartgatheringavailable metrics.Ifnotspecified,firstavailablemetricsinthesystem arereturned. Optional.Servertimeatwhichtostopgatheringavailable metrics.Ifnotspecified,returnedmetricsincludesall metrics,uptothemostrecent. Optional.Identifieroftheintervalforwhichtoreturn availablemetrics.Validintervalsinclude: TherefreshratereturnedbyQueryProviderSummary operation OneoftheHistoricalIntervals Ifnotspecified,systemreturnsavailablehistoricalmetrics.
endTime
dateTime
intervalId
int
Usetheoptionalbeginandendtime,orspecifyanintervaltoobtaininformationaboutthemetricsavailable fortheinterval.ForunmanagedESX/ESXisystems,usetherefreshRate,whichyoucanobtainfromthe serviceprovider.
116
VMware, Inc.
vCenter Server and PerformanceManager

AvCenterServersystemaggregatesperformancedatafromalltheESX/ESXisystemsthatitmanages. The amountofdataaggregateddependsonthelevelsettingconfiguredforthevCenterServer.Thelevel settingsarereflectedinthehistoricalIntervalpropertyofthePerformanceManagerofthevCenter Serversystem.historicalIntervalisanarrayofPerfIntervaldataobjectsthatdefinefourdifferentlevel settings,1through4. Bydefault,thecollectionlevelissetto1foreachofthefourintervals.Bydefault,vCenterServersystemsretain thefollowinginformation: 5minutesamplesforthepastday 30minutesamplesforthepastweek 2hoursamplesforthepastmonth 1daysamplesforthepastyear DataolderthanayearispurgedfromthevCenterServerdatabase.
Historical Intervals
Table 128liststhedefaultvaluesofthehistoricalIntervalpropertyfromavCenterServersystem. Table 12-8. Values of PerfInterval Data Objects from a vCenter Server System
key 1 2 3 4 name PastDay PastWeek PastMonth PastYear sampling period 300 1800 7200 86400 length 86400 604800 2592000 31536000 enabled TRUE TRUE TRUE TRUE level 1 1 1 1
Table 129listssomeexamplesofthetypesofstatisticsthatcanbecollectedatvariouslevels.Theactual counterscanvaryfromversiontoversionoftheproduct. Table 12-9. Statistics Level Settings

Level 1 Description CountersdefinedwithaveragerolluptypeforCPU,Memory,Disk,andNetwork;pluscountersforSystem Uptime,SystemHeartbeat,andDRS(DistributedResourceScheduler,trackedintheclusterServices group).Doesnotincludecountersfordevices. Countersdefinedwithaverage,summation,andlatestrolluptypesforCPU,memory,disk,andnetwork; pluscountersforsystemuptime,systemheartbeat,andDRS(clusterServices).Doesnotincludecounters fordevices. Countersdefinedwithaverage,summation,andlatestrolluptypesforCPU,memory,disk,network,andall devices;pluscountersforsystemuptime,systemheartbeat,andDRS(clusterServices). Allcountersdefinedforallentitiesanddevices,foreveryrolluptype,includingminimumandmaximum.
3 4
TherollupTypeidentifiesthefunctionthatcontrolshowdataisconvertedasitisconsolidatedfromone intervaltothenext.
Modifying Historical Intervals

VMwarerecommendsthatyoudonotmodifythedefaulthistoricalintervals.ThePerfIntervaldataobjects inthehistoricalIntervalarraybuildincrementallyoneachobjectinthearray.Modifyingthespecificsof anygivenobjectinthearraycanresultinproblems.Also,changestoanintervalareglobalandapplytoall entitiesinthesystem.
VMware, Inc.
117
Ifyoumustmodifyanintervaltomeetaspecialrequirement,usetheUpdatePerfIntervaloperationof PerformanceManagerandfollowtheseguidelines. Theretentiontime(thelengthpropertyofPerfInterval)mustbeamultipleofthesamplingPeriod propertyvalue. Theretentionlengthofeachsuccessiveperiodmustbegreaterthantheretentionlengthoftheprevious intervalinthearray. ThevalueofthesamplingPeriodpropertyforanyPerfIntervalinstancecannotbechanged.
Optimizing Query Response Time

TheQueryPerfoperationofPerformanceManageronvCenterServerhasbeenoptimizedtoreturnresults fasterwhenthequeryissubmittedwithincertainparameters.Specifically,ifyoudefinethePerfQuerySpec dataobjectwiththefollowingparametersettings,thequerycircumventsvCenterServerandobtainsresults directlyfromeachoftheESX/ESXisystems: SetthevalueoftheintervalIdto300(thedefaultsamplinginterval). SetthevalueofstartTimeandendTimesothatthetimespanfallswithinthelast30minutesofthe currenttime. ThisoptimizationensuresthatvCenterServersystemisnotoverloaded.Considerusingthistechniquefor reportingoranyotherclientapplicationthatmightsubjectthesystemtorepeatedqueries. TheoptimizationisavailableinVirtualCenterServer2.5andsubsequentsystems.
118
VMware, Inc.
13
Using vCenter Server for Virtual Machine Operations
13
VMwarevCenterServersupportscomprehensivedeployment,management,monitoring,andotherservices formultipleESX/ESXisystems.vCenterServerrunsasadatabasebackedserviceonavarietyofWindows operatingsystems.ThesoftwarelicensingandinstallationprocessincludesaninstanceofMicrosoftSQL Server.vCenterServeralsosupportsintegrationwithOracleDatabaseServer. AvCenterServerpersistsstatus,configuration,performance,andotherinformationabouteachvirtual machine,host,cluster,virtualapplication,andotherentitiesthatitmanagestoitsdatabase.Historical performance,event,task,andotherdataisalsopreservedinthevCenterServerdatabase. TheAPIavailableonthevCenterServerincludesseveralserviceinterfacesthatarenotsupportedon unmanagedESX/ESXisystems,includingAlarmManagerandScheduledTaskManager.Theseservice interfaceshavebeenavailableinpriorreleasesofvCenterServer,butwithvCenterServer4.0andvSphereAPI 4.0,theysupportmanynewcapabilities. Forexample,controloverAlarmsettingismoregranularthanin priorreleases,falsealarmsorunnecessaryrepeatedtriggeringofanalarmhasbeenresolved.SeeUsingthe AlarmInfrastructureonpage 137. ManynewfeaturesofvSphere4.0areavailableonlythroughtheAPIavailableonthevCenterServerWeb service,includingClusterProfileManager,ProfileComplianceManager,HostProfileManager, IpPoolManager,HostSnmpManager,VirtualMachineCompatibilityChecker,and VirtualMachineProvisioningChecker,amongothers. vCenterServerprovidesarangeofoptionsfordeployingandconfiguringvirtualmachines,andfor organizingvirtualassets.vCenterServerprovidescontainerobjects,suchasfoldersanddatacenters,for organizingvirtualassetsinaninventorycomprisingmultipleESX/ESXisystems.vCenterServersupports deployingmultiplevirtualmachinesbyusingatemplatethatcodifiesastandardconfiguration.Thischapter providesinformationabouttheseapproaches.Itincludesthesetopics: SampleCodeReferenceonpage 120 OverviewoftheVirtualMachineManagedObjectTypeonpage 120 UsingTemplatestoDeployStandardVirtualMachinesonpage 124 MigratingVirtualMachinesUsingVMotiononpage 125 MovingStorageDynamicallyUsingStorageVMotiononpage 127
VMware, Inc.
119

Table 131liststhesampleapplicationsincludedwiththevSphereWebServicesSDKthatdemonstratesome ofthetopicsdiscussedinthischapter. Table 13-1. Sample Applications Demonstrating VirtualMachine Deployment Using vCenter Server Systems
Java SDK\samples\Axis\java\com\vmware\samples\vm VMClone.java VMDeltaDisk.java VMLinkedClone.java VMPromoteDisks.java VMRelocate.java VMotion.java VMotion25.java C# SDK\samples\DotNet\cs VMClone RecordSession VMPowerOps VMotion
Overview of the VirtualMachine Managed Object Type

AVirtualMachinemanagedobjectprovidesoperationsformanagingvirtualmachines,suchascreating snapshotsofitsstate,creatingnewinstancesofitselfbycloning,andparticipatingwithothervirtualmachine instancesinfaulttolerantdeployments. Figure 13-1. VirtualMachine Extends ManagedEntity Type
120
VMware, Inc.
Chapter 13 Using vCenter Server for Virtual Machine Operations
AVirtualMachinemanagedentityhasclosetofiftyoperations,manyofwhicharenewinvSphereAPI4.0 Figure 131showsonlysomeofthedetails.SeethevSphereAPIReferenceforcompleteinformation. Table 13-2. VirtualMachineConfigSpec Data Object

Property alternateGuestName annotation Type string string Description and Usage Fullnameforguest.UsedonlyifguestIdisspecifiedasother orother-64. Userprovideddescriptionofthevirtualmachine.Becausethis propertyisoptionalinthevirtualmachineconfiguration,itis necessarytopassanexplicitemptystringinaConfigSpec objecttoremoveanannotationthatisalreadypresentinthe VirtualMachineConfigInfoforavirtualmachine. Settingsthatcontrolthebootbehaviorofthevirtualmachine. Thesesettingstakeeffectduringthenextpoweronofthe virtualmachine. Settingtocontrolenabling/disablingchangedblocktracking forthevirtualdisksofthisVM.Thismayonlybesetifthe changeTrackingSupportedcapabilityistrueforthisvirtual machine.Anychangetothispropertywilltakeeffectthenext timethevirtualmachinepowerson,resumesfroma suspendedstate,performsasnapshotcreate/delete/revert operationormigrateswhilepoweredon. Ifspecified,thechangesareonlyappliedifthecurrent changeVersionmatchesthespecifiedchangeVersion.This fieldcanbeusedtoguardagainstupdatesthathavehappened betweenwhenconfigInfoisreadandwhenitisapplied. Legacyconsoleviewerpreferencesthatareusedwithpower operations.Forexample,poweron. AffinitysettingsforCPU. ResourcelimitsforCPU. SpecifiestheCPUfeaturecompatibilitymasks. Indicateswhethervirtualprocessorscanbeaddedtothe virtualmachinewhileitisrunning,ornot.Thisattributecan onlybesetwhenthevirtualmachineispoweredoff. Indicateswhethervirtualprocessorscanberemovedfromthe virtualmachinewhileitisrunning,ornot.Thisattributecan onlybesetwhenthevirtualmachineispoweredoff. Setofvirtualdevicesbeingmodifiedbytheconfiguration operation. Additionalconfigurationinformationforthevirtualmachine. Thisdescribesasetofmodificationstotheadditionaloptions. Anoptionisremovedifthekeyispresentbutthevalueisnot setorthevalueisanemptystring.Otherwise,thekeyissetto thenewvalue.Configurationkeysthatwouldconflictwith parametersthatareexplicitlyconfigurablethroughotherfields intheConfigSpecobjectaresilentlyignored. Informationaboutvirtualmachinefiles. Additionalflagsforavirtualmachine. Faulttolerancesettingsforthisvirtualmachine. Shortguestoperatingsystemidentifier.
bootOptions
VirtualMachineBoot Options boolean
changeTracking Enabled
changeVersion
string
consolePreferences cpuAffinity cpuAllocation cpuFeatureMask cpuHotAddEnabled
VirtualMachine ConsolePreferences VirtualMachine AffinityInfo ResourceAllocation Info VirtualMachine CpuIdInfoSpec[] boolean
cpuHotRemove Enabled deviceChange extraConfig
boolean
VirtualDevice ConfigSpec[] OptionValue[]
files flags ftInfo guestId
VirtualMachine FileInfo VirtualMachine FlagInfo FaultTolerance ConfigInfo string
VMware, Inc.
121
Table 13-2. VirtualMachineConfigSpec Data Object (Continued)

Property instanceUuid Type string Description and Usage 128bitUUIDofavirtualmachine,representedasa hexadecimalstring.ThisidentifierisusedbythevCenter Serversystemtouniquelyidentifyallvirtualmachine instancesinthevSphereenvironment,includingthosethat maysharethesameSMBIOSUUID.Normally,thispropertyis notsetbyaclient,allowingthevSphereenvironmenttoassign orchangeitwhenvCenterServerdetectsanidentifierconflict betweenvirtualmachines.Thisidentifiercanbemodifiedeven whenavirtualmachineispoweredon. 128bithashbasedonthevirtualmachinesconfigurationfile locationandtheUUIDofthehostassignedtorunthevirtual machine.Normally,thispropertyisnotsetbyaclient,allowing theVirtualInfrastructureenvironmenttoassignalocationID whenthevirtualmachineiscreated.However,ifthevirtual machinesconfigurationfilehasbeenmanuallymoved,itmay bedesirabletoclearthisproperty,settingittoanemptystring, sothepropertyisregenerated. Affinitysettingsformemory. Resourcelimitsformemory. Indicateswhethermemorycanbeaddedtothevirtualmachine whileitisrunning,ornot.Thisattributecanonlybesetwhen thevirtualmachineispoweredoff. Sizeofavirtualmachinesmemory,inMB. Displaynameofthevirtualmachine.Any%(percent) characterusedinthisnameparametermustbeescaped,unless itisusedtostartanescapesequence.Clientsmayalsoescape anyothercharactersinthisnameparameter.Snapshotsof virtualmachinesthathavespacesintheirnamesandare associatedwithESXServer2.xsystemsarenotsupported. Therefore,ifyouwanttheoptiontotakesnapshotsofthis virtualmachineandyouareassociatingitwithanESXServer 2.xsystems,donotusespacesinthename. Resourcelimitsfornetwork. TheNPIVnodeWWNstobeextendedfromtheoriginallistof WWNnumbers.Thispropertyshouldbesettotheaggregate ofexistingnumbersplusnewnumbers.DesiredNodeWWNs shouldalwaysbegreaterthantheexistingnumberofnode WWNs TheNPIVportWWNstobeextendedfromtheoriginallistof WWNnumbers.Thispropertyshouldbesettotheaggregate ofexistingplusnewnumbers.DesiredNodeWWNsshould alwaysbegreaterthantheexistingnumberofportWWNs TheNPIVnodeWWNtobeassignedtoavirtualmachine.This propertyshouldonlybeusedorsetwhenthevalueof npivWorldWideNameOppropertyisset.Otherwise,an InvalidVmConfigfaultisthrown.IfthespecifiednodeWWN iscurrentlybeingusedbyanothervirtualmachine,a VmWwnConflictfaultisthrown.Formoreinformationabout WWN,seenpivNodeWorldWideName. ThispropertyisusedtocheckwhethertheNPIVcanbe enabledontheVirtualmachinewithnonRDMdisksinthe configuration,sothisispotentiallynotenablingNPIVon VMFSdisks.ThispropertyisalsousedtocheckwhetherRDM isrequiredtogenerateWWNsforavirtualmachine.
locationId
string
memoryAffinity memoryAllocation memoryHotAddEnabled
VirtualMachine AffinityInfo ResourceAllocation Info boolean
memoryMB name
long string
networkShaper npivDesiredNodeWwns
VirtualMachine NetworkShaperInfo short
npivDesiredPortWwns
short
npivNodeWorldWideName
long[]
npivOnNonRdmDisks
boolean
122
VMware, Inc.

Property npivPortWorldWideName Type long[] Description and Usage TheNPIVportWWNtobeassignedtoavirtualmachine.This propertyshouldonlybeusedorsetwhenthevalueof npivWorldWideNameOppropertyisset.Otherwise,an InvalidVmConfigfaultisthrown.IfthespecifiedportWWN iscurrentlybeingusedbyanothervirtualmachine,a VmWwnConflictfaultisthrown.Fordetaildescriptionon WWN,seenpivPortWorldWideName. ThispropertyisusedtoenableordisabletheNPIVcapability onaspecificvirtualmachineonatemporarybasis.Whenthis propertyissetNPIVVportwillnotbeinstantiatedbytheVMX processofthevirtualmachine.Whenthispropertyissetport WWNsandnodeWWNsintheVMconfigurationare preserved. TheflagtoindicatewhattypeofNPIVWWNoperationis goingtobeperformedonthevirtualmachine.Ifunset,it indicatesnochangetoexistingNPIVWWNassignment(ornot assigned)inthevirtualmachine. Thispropertyisusedinternallyinthecommunicationbetween thevCenterServerandESX/ESXisystemtoindicatethesource fornpivNodeWorldWideNameandnpivPortWorldWideName whennpivWorldWideNameOpisset.Thispropertyshouldonly besetbythevCenterServer.Ifthispropertyissetinacalltoa vCenterServer,anInvalidVmConfigfaultwillalwaysbe thrown.InacalltoanESX/ESXisystem,anInvalidVmConfig faultisthrownifthevalueofnpivWorldWideNameOpisnotset toset. Numberofvirtualprocessorsinavirtualmachine. Configurationfordefaultpoweroperations. Whethertokeepthevirtualmachinesswapfilewhenitis poweredoff.Thismayonlybesettotrueifthe swapPreservationSupportedcapabilityistrueforthis virtualmachine. Adatastorepathtoadirectorythatmaybeusedtostorethe swapfileforthisvirtualmachine.Thismayonlybesetifthe swapPlacementSupportedcapabilityistrueforthisvirtual machine.Anychangetothispropertywilltakeeffectthenext timethevirtualmachinepowerson,resumesfroma suspendedstate,ormigrateswhilepoweredon. Virtualmachineswapfileplacementpolicy.Thismayonlybe setiftheswapPlacementSupportedcapabilityistrueforthis virtualmachine.Anychangetothispolicywilltakeeffectthe nexttimethevirtualmachinepowerson,resumesfroma suspendedstate,ormigrateswhilepoweredon. ConfigurationofVMwareToolsrunningintheguestoperating system. 128bitSMBIOSUUIDofavirtualmachinerepresentedasa hexadecimalstringin 12345678-abcd-1234-cdef-123456789abcformat. Normally,thispropertyisnotsetbyaclient,allowingthe vSphereenvironmenttoassignaUUIDwhenthevirtual machineiscreated.However,insomerarecases,suchasa manualcopyofavirtualmachine,itmaybenecessarytoset thisproperty.
npivTemporaryDisabled
boolean
npivWorldWideNameOp
string
npivWorldWideNameType
string
numCPUs powerOpInfo preserveSwapOnPowerOff
int VirtualMachine DefaultPowerOpInfo boolean
swapDirectory
string
swapPlacement
string
tools uuid
ToolsConfigInfo string
VMware, Inc.
123

Property vAssertsEnabled Type boolean Description and Usage Indicateswhetheruserconfiguredvirtualassertsaretriggered duringvirtualmachinereplay.Thissettingtakeseffectduring thenextreplayofthevirtualmachine.Enablingthis functionalitycanpotentiallycausesomeperformance overheadduringvirtualmachineexecution. Theversionstringforthisvirtualmachine.Thisisusedonly whilecreatinganewvirtualmachine,andcanbeupdatedby invokingUpgradeVM_Taskforthisvirtualmachine. ConfigurationofVServicemetadataforavirtualmachine Settotrue,iftheVServiceconfigurationshouldberemoved
version
string
vServiceConfig vServiceConfigRemoved
VmConfigSpec boolean
Using Templates to Deploy Standard Virtual Machines

AtemplateisinstanceofaVirtualMachinemanagedobjectthathasitstemplatepropertysettotrue. Templatesdonotconsumeresourcesandtheirpermissionsderivefromtheircontainingfolderonly,notfrom theirassociatedresourcepoolasdoVirtualMachineobjects. Table 133listsadvancedoperationsavailablethroughtheVirtualMachinemanagedobject. Table 13-3. Advanced VirtualMachine Operations Summary
Operation CloneVM_Task Description Createsacloneofthisvirtualmachine.Ifthevirtualmachineisusedasatemplate,this methodcorrespondstothedeploycommand.Any%(percent)characterusedinthis nameparametermustbeescaped,unlessitisusedtostartanescapesequence.Clients mayalsoescapeanyothercharactersinthisnameparameter. Obtainsanexportleaseonthisvirtualmachine.TheexportleasecontainsalistofURLs forthevirtualdisksforthisvirtualmachine,andaticketgivingaccesstotheURLs. ReturnstheOVFenvironmentforavirtualmachine.Ifthevirtualmachinehasno VServiceconfiguration,anemptystringisreturned.Also,sensitiveinformationis omitted,sothismethodisnotguaranteedtoreturnthecompleteOVFenvironment. MarksaVirtualMachineobjectasbeingusedasatemplate.Note:AVirtualMachine markedasatemplatecannotbepoweredon. ClearstheisTemplateflagandreassociatesthevirtualmachinewitharesourcepooland host. Removesthespecifiedsecondaryvirtualmachinefromthisfaulttolerantgroup.
ExportVm ExtractOvfEnvironment
MarkAsTemplate MarkAsVirtualMachine RemoveSecondaryVM_Task
Creating Templates
Youuseatemplatetocreatemultiplevirtualmachineshavingthesamecharacteristics,suchasamountof resourcesallocatedtoCPUandmemoryandtypeofvirtualhardwareattributessupported. Theonlypropertythatdistinguishesatemplatefromavirtualmachineisthetemplatepropertyofthe VirtualMachineConfigInfodataobjectthatcomprisestheconfigpropertyofaVirtualMachineinstance: AtemplateisaninstanceofaVirtualMachineobjectthathasitstemplatepropertysettotrue. Youuseoneofthesetwogeneralwaystocreateatemplate: Ifyounolongerneedaspecificinstanceofavirtualmachine,butyouwanttousethevirtualmachines configurationasatemplate,usetheMarkAsTemplateoperationonthevirtualmachineinstance.Youuse themanagedobjectreferenceofthevirtualmachinetoinvokethisoperation.Invokingthisoperationsets theconfig.templatepropertytotrue,andthevirtualmachineisdisabled. Ifyouwanttouseanexistingvirtualmachineasatemplate,yetalsokeepthevirtualmachine,usethe CloneVM_Taskoperationofthevirtualmachinefirst,tocreateaduplicateofthevirtualmachine Example 131demonstratesthecloningapproach,whichmakesthevirtualmachineinoperative.
124
VMware, Inc.
Example 13-1. Cloning a Virtual Machine to Use as a Template

... VirtualMachineRelocateSpec vmRelocSpec = new VirtualMachineRelocateSpec(); vmRelocSpec.setTransform(VirtualMachineRelocateTransformation.sparse); VirtualMachineCloneSpec vmCSpec = new VirtualMachineCloneSpec(); vmCSpec.setLocation(vmRelocSpec); vmCSpec.setTemplate(Boolean=TRUE); vmCSpec.setPowerOn(Boolean=FALSE); ManagedObjectReference taskMoRef = my_conn.cloneVM_Task(vmMoRef, folderMoRef, new String("Templ_1"), vmCSpec); ...
Example 131usestheVirtualMachineCloneSpec,whosepropertiesprovideinformationaboutwherethe datastoreinformationislocated,thetargethost,theresourcepool,andthekindoftransformation(flator sparse)toperformonthedisks.Ifdatastoreinformationisnotprovided,defaultsareprovided.Seethe VirtualMachineRelocateSpecinthevSphereAPIReferenceformoreinformation.
Reverting a Template to Its Active Virtual Machine Status

Youchangeatemplatebacktoanoperationalvirtualmachinebyusingtheappropriateoperation: InvoketheMarkAsVirtualMachineoperationonthetemplate.Thisclearsthebooleanpropertythat definesthevirtualmachineasatemplateandreassociatesthevirtualmachinewiththeresourcepooland hosttowhichithadoriginallybeenassociated.However,thetemplatenolongerexists. Toretainthetemplate,clonethetemplatebyinvokingtheCloneVM_Taskoperationonthetemplate.In theVirtualMachineCloneSpec(thespecparameter)fortheoperation,setthetemplatepropertyto false.
Migrating Virtual Machines Using VMotion

VMotionhasbeenacapabilityofVMwareserversforseveralreleasesoftheproduct,buthasmanynew featuresandcapabilitiessupportedinvSphere4.0,includingsupportfordistributedvirtualswitches. VMotionhasdependenciesonbothnetworkinginfrastructureandthehostsystemhardware. Migratingavirtualmachinefromonehosttoanotherrequiresproperlyconfigurednetworkingofallvirtual machinesandsourceandtargethosts.Thevirtualmachinecanbeinanystate,includingpoweredon,powered off,orsuspended. Table 133listsoperationsavailablethroughtheVirtualMachinemanagedobjectformigratingorrelocating virtualmachines. Table 13-4. VirtualMachine Operations for VMotion
Operation MigrateVM_Task Description MigratesavirtualmachinetoaspecificResourcePoolorHostSystem.Theprincipalassociated withthesessioninvokingtheoperationmusthavetheappropriateprivilegesforthestateofthe virtualmachine: Migratingavirtualmachinethatisrunning(stateispoweredOn)requiresthe Resource.HotMigrateprivilege. Migratingavirtualmachinethatisshutdownorsuspended(stateispoweredOffor suspended)requirestheResource.ColdMigrateprivilege. RelocateVM_Task Relocatesthevirtualdisksassociatedwiththespecifiedvirtualmachinetoanewlocation. Optionally,alsomovesthevirtualmachinetoadifferenthost. ForStorageVMotionwhenthevirtualmachineispoweredon,theprincipalinvokingthis operationrequirestheResource.HotMigrateprivilegeandtheDatastore.AllocateSpace privilegeonthetargetdatastore.
VMware, Inc.
125
Checking the Validity of a Migration In Advance

AsofvSphere4.0,youusetheVirtualMachineProvisioningCheckertodetermineifaproposedmigration isviableornot. Figure 13-2. VirtualMachineProvisioningChecker Service Interface
TheCheckMigrate_TaskoperationdetermineswhetheraproposedMigrateVM_Taskoperationispossible. SeethevSphereAPIReferenceformoreinformation.
Using the MigrateVM_Task Operation

TheMigrateVM_Taskoperationmovesalltheconfigurationfilesthatmakeupavirtualmachine.Thedisk filesthatmakeupthevirtualmachineremainintheiroriginallocation. Table 135liststheparametersfortheMigrateVM_Taskoperations.Youcanusethisoperationwithvirtual machinesthatarerunningornot.Youusethestateparametertoensurethatthevirtualmachineismovedonly ifitisinthestateyouspecify. Table 13-5. MigrateVM_Task Operation
Parameter _this pool Type MOR MOR>ResourcePool Description Managedobjectreferenceofthevirtualmachinethatyouwantto migratetoanewlocation. ManagedobjectreferencetothetargetResourcePoolforthevirtual machine.Ifthisparameterisnotset,thevirtualmachinestays assignedtoitscurrentResourcePool.Youmustspecifyahost withinthesamecomputeresource. ManagedobjectreferencetothetargetHostSystemforthevirtual machine.TheHostSystemmustbeassociatedwiththe object.Thetargethosttorunthevirtualmachine.Thismustspecify ahostthatisamemberoftheComputeResourceobjectindirectly specifiedbythepool.Forastandalonehostoraclusterwith VMwareDRS,thepropertycanbeunspecifiedandthesystem selectsadefaultfromthesameComputeResourceobjectasthe ResourcePoolspecifiedbythepoolparameter. priority VirtualMachineMovePriority Priorityofthemigration.Thepriorityvalueisoneofthe VirtualMachineMovePriorityenumeratedtypevalues, specifically,defaultPriority,highPriority,orlowPriority. Optional.Ifspecified,thevirtualmachineismovedtothetarget locationonlyifitsstatematchesthespecifiedstate.Thevalueof stateisoneoftheVirtualMachinePowerStateenumeratedtype values,specifically,poweredOff,poweredOn,orsuspended.
host
MOR>HostSystem
state
VirtualMachinePowerState
126
VMware, Inc.
Moving Storage Dynamically Using Storage VMotion

StorageVMotionallowsyoutomovearunningvirtualmachinefromoneVMFSvolumetoanother.Storage VMotionwasintroducedinVMwareInfrastructure3.5,andhasfullsupportinvSphere4.0. Neitherthevirtualmachinenoritsassociatedstorageneedtobetakenoffline.Alldatastoretypesare supported,includinglocalstorage,VMFS,andNAS(networkattachedstorage).StorageVMotionusesthe RelocateVM_Taskoperation(ofVirtualMachine).RelocateVM_Taskoperationmovesvirtualdiskstoa newstoragelocation,specifiedintheVirtualMachineRelocateSpecdataobject. Table 13-6. RelocateVM_Task Operation
Parameter _this spec priority Type ManagedObjectReference VirtualMachineRelocateSpec VirtualMachineMovePriority Description and Usage ReferencetotheVirtualMachineusedtomakethemethodcall. Thespecificationofwheretorelocatethevirtualmachine. Thepriorityoftheoperation,specifiedasoneofthethreepossible VirtualMachineMovePriorityenumerations: defaultPriority,highPriority,lowPriority.
Figure 133showsapartialUMLdiagramofVirtualMachineandsomeofthedataobjectsthatareusedwith RelocateVM_Task. Figure 13-3. VirtualMachine RelocateVM_Task Operation
ThedataobjectsandenumerationtotheleftoftheVirtualMachinemanagedobjecttyperepresentinputsto theoperation.Table 137liststhepropertiesoftheVirtualMachineRelocateSpecdataobject. Table 13-7. VirtualMachineRelocateSpec Data Object

Property datastore disk diskMove Type Type MOR>Datastore VirtualMachine RelocateSpecDiskLocator[] string Description and Usage Optional.Targetdatastoreforthevirtualmachine.Defaultsto currentdatastoreifthisparameterisnotspecified. Optional.Listthatspecifiesdatastorelocationforeachvirtualdisk. Optional.Specifiesthemannerinwhichtomovethevirtualdiskto thetargetdatastoreusingoneofthe VirtualMachineRelocateDiskMoveOptionsenumerations: createNewChildDiskBacking moveAllDiskBackingsAndAllowSharing moveAllDiskBackingsAndDisallowSharing moveChildMostDiskBacking Settingthispropertyrequiresthatthe deltaDiskBackingsSupportedpropertyofHostCapability be settotrue.Ifnotspecified,themovetypedefaultsto moveAllDiskBackingsAndDisallowSharing. Appliestoallthedisksassociatedwiththevirtualmachine.To overrideandspecifythemovetypeonaperdiskbasis,usethe diskMoveTypepropertyof VirtualMachineRelocateSpecDiskLocator.
VMware, Inc.
127
Table 13-7. VirtualMachineRelocateSpec Data Object (Continued)

Property host Type MOR>HostSystem Description and Usage Optional.Targethostforthevirtualmachine.Ifneitherhostnor resourcepoolisspecified,thecurrenthostisused.ifresourcepoolis specified,andthetargetpoolrepresentsastandalonehost,thehost isused.ifresourcepoolisspecified,andthetargetpoolrepresentsa DRSenabledcluster,ahostselectedbyDRSisused.ifresourcepool isspecifiedandthetargetpoolrepresentsaclusterwithoutDRS enabled,anInvalidArgumentexceptionbethrown. Targetresourcepoolforthevirtualmachine. Optionalforrelocatingorcloningtoavirtualmachine.Defaults tocurrentresourcepoolofvirtualmachineunlessspecified. Ignoredforcloningtoatemplate. Requiredtoclonefromatemplatetoavirtualmachine. transform VirtualMachine Relocate Transformation Optional.Specifieshowtotransformvirtualdisksduringcopy. (VirtualMachineRelocateTransformationisanenumerated datatypeconsistingofflatandsparseoptions.)Anyinvalid transformationsareignoredbythestoragesubsystem.
pool
MOR>ResourcePool
Tomovethediskfiles,usetheRelocateVM_Taskoperation.SeethesampleslistedinSampleCode Referenceonpage 120forexamplesofusingtheseoperations.
128
VMware, Inc.
14
Event and Task Management Using vCenter Server
14
AnEventisamessagegeneratedbymanagedentitiesduringoraftervariousoperations.TheEventManager istheserviceinterfacethatyoucanusetodefineyourownevents.Thischapterincludesthesetopics: SampleCodeReferenceonpage 129 UnderstandingEventManagerandtheEventDataObjectonpage 129 CreatingCustomEventsonpage 132 ObtainingInformationaboutEventsUsingaHistoryCollectoronpage 133

Table 141liststhesampleapplicationsincludedwiththevSphereWebServicesSDKthatdemonstratesome ofthetopicsdiscussedinthischapter. Table 14-1. Sample Applications that Demonstrate Event and EventManager
Java SDK\samples\Axis\java\com\vmware\samples\events EventFormat.java EventHistoryCollectorMonitor.java VMEventHistoryCollectorMonitor.java C# SDK\samples\DotNet\cs\ EventFormat EventHistoryCollectorMonitor VMEventHistoryCollectorMonitor
Understanding EventManager and the Event Data Object

AnEventisadataobjecttypethatcontainsinformationaboutstatechangesofmanagedentitiesandother objectsontheserver.Eventsincludeuseractionsandsystemactionsthatoccurondatacenters,datastores, clusters,hosts,resourcepools,virtualmachines,networks,anddistributedvirtualswitches.Forexample, thesecommonsystemactivitiesgenerateoneormoreEventdataobjects: Poweringavirtualmachineonoroff Creatingavirtualmachine InstallingVMwareToolsontheguestOSofavirtualmachine Reconfiguringacomputeresource AddinganewlyconfiguredESX/ESXisystemtoavCenterServer InformationfromEventobjectsgeneratedonanunmanagedESX/ESXisystemdisplayintheEventstabofthe vSphereClient.Formanagedhosts,informationfromEventobjectsdisplaysintheTasks&Eventstabof vSphereClient.Fordevelopers,theEventManagerprovidesaccesstoEventdataobjects.
VMware, Inc.
129
EventManager Managed Object

TheEventManageristheserviceinterfaceforworkingwiththeeventinfrastructure.Figure 141shows EventManagerandsomeofitsrelatedobjects.AnEventManagerhastheseproperties: AdescriptionpropertydefinedasaninstanceofaEventDescriptiondataobject,whichcontainsan eventcategoryandotherinformation. AlatestEventpropertythatcontainsthemostrecentEventdataobjectinmemory. AmaxCollectorpropertythatspecifiesthenumberofEventHistoryCollectorobjectsperclient sessionthatcanbecreated.Thisvalueissetbytheserver. Figure 14-1. EventManager Managed Object and Event Data Object
InvSphereAPI4.0,theeventinfrastructureincludesmanynewpropertiesanddataobjectstosupportnew capabilitiesofvSphere4.0. Forexample,changeTag,ds,dvs,andnetareallnewpropertiesdesignedtosupportenhancementstothe AlarmandEventinfrastructure,ortosupportnewcapabilities,suchasDistributedVirtualSwitch managedobject. SeethevSphereAPIReferenceformoreinformation.
Event Data Objects

TheEventdataobjecthasmanysubtypesthatdefinethespecifickindsofeventsthatthesystemgenerates. Figure 142,EventDataObjectisaBaseTypeUsedbyManyGenerationsofSubtypes,onpage 131,shows onlyafewofthesubtypesthatextendtheEventdataobject.Inmanycases,thesubtypecontainsnoadditional propertiesbeyondthoseoftheEventbasetype,butinothercases,thesubtypeprovidesadditional information. Forexample,theTaskEventisasubtypeofEvent.InadditiontocontainingallthepropertiesoftheEvent typethatareappropriateforthesystem,aTaskEventalsoincludesaninfopropertythatisdefinedasan instanceofaTaskInfoobject.TheTaskEventcontainsinformationsuchastheentityNameoftheobjectthat generatedtheevent.SeeUnderstandingtheTaskInfoDataObjectonpage 85formoreinformationaboutthe TaskInfodataobject. Thesearesomeexamplesofcommoneventobjectsoutputbyaconsolestyleclientapplication:
com.vmware.vim.VmPoweredOnEvent com.vmware.vim.VmStartingEvent com.vmware.vim.VmReconfiguredEvent com.vmware.vim.VmCreatedEvent com.vmware.vim.VmBeingCreatedEvent
130
VMware, Inc.
Chapter 14 Event and Task Management Using vCenter Server
TheVmPoweredOnEventisalsoshowninFigure 142.Asshownattheconsole,theeventdataobjectsarenot formattedanddonotprovideanycontextinformation. Figure 14-2. Event Data Object is a Base Type Used by Many Generations of Subtypes
Formatting Event Message Content

Toformataneventmessage,youcanusethepredefinedstringcontainedinthefullFormattedMessage propertyoftheEventobject. YoucanalsoformatanEventmessagebasedonthecontextualinformation.Atruntime,theeventsgenerated bythesystemarepopulatedwiththeappropriatevaluesfortheirsource,suchasthemanagedobjectreference ofthecomputeresourceassociatedwiththeevent.Thepropertiescontainingargumentsassociatedwiththe sourceofaneventincludethecomputeResource,datacenter,ds,dvs,host,net,andvmpropertiesofthe Eventdataobject(seeFigure 141,EventManagerManagedObjectandEventDataObject,onpage 130). YouusethepropertiesofanEventobjectinconjunctionwiththeEventDescriptionEventDetaildata objecttoformateventmessagecontentappropriateasoutputforyourapplication.Table 142liststhe propertiesofEventDescriptionEventDetaildataobject. Table 14-2. EventDescriptionEventDetail Data Object Type
Property category description Type string string Description CategoryoftheEvent,suchasinfo,error,user,orwarning. AlocalizeddescriptionoftheEventdesignedforpresentationtoendusers. Forexample,theEnglishdescriptionoftheVmPoweredOnEventmight readVM Powered On.Usewhencreatingeventbasedalarmstowhich endusersmustrespond. Descriptionpatternthatisappropriateinthecontextofaspecificcluster. Forexample,anEventgeneratedbypoweringonavirtualmachineina clusterusingthisformatthefollowingtextpattern: {vm.name} on {host.name} is powered on formatOnDatacenter string Descriptionpatternthatisappropriateinthecontextofaspecific datacenter.Forexample,arenamingeventthatusesthisformatusesthe followingpattern: Renamed {vm.name} from {oldName} to {newName} The{oldName}and{newName}arepropertiesofthesource VmRenamedEventobject.
formatOnComputeResource
string
VMware, Inc.
131
Table 14-2. EventDescriptionEventDetail Data Object Type (Continued)

Property formatOnHost Type string Description Descriptionpatternthatisappropriateinthecontextofaspecifichost.For example,anEventgeneratedbypoweringonavirtualmachineusesthe followingpattern: {vm.name} is powered on formatOnVm string Descriptionpatternthatisappropriateinthecontextofaspecificvirtual machine.Forexample,anEventgeneratedbypoweringonavirtual machineusesthefollowingpattern: Virtual machine on {host.name} is powered on fullFormat string Completedescriptionpatternthatincludesallcontextualinformationabout thesourceoftheEvent,includingdatacenter,hostname,andvirtual machinename.Forexample,thefollowingisafullyformattedtextpattern foraneventgeneratedbystartingavirtualmachine: {vm.name} on key string {host.name} in {datacenter.name} is powered on Typeofeventbeingdescribed.
ThenamepropertyinanyoftheformattedoutputisderivedfromcomputeResource,datacenter,ds,dvs, host,net,andvmpropertiesoftheEventobject. Forexamplesofdefininganeventmessagebasedoncontext,seetheEventFormat.javaorEventFormat.cs samplesinthevSphereWebServicesSDKpackage.
Creating Custom Events

TheEventManagerLogUserEventoperationenablesyoutocreatecustomEventobjectstoaugmentthe predefinedeventsorprovidingmarkersthatfacilitatebrowsingEventhistory.Youcanassociateyourcustom Eventwithanymanagedentity. To define a custom Event 1 ObtainthemanagedobjectreferencetotheEventManager.
.. ManagedObjectReference _svcRef = new ManagedObjectReference(); ServiceContent _sic = my_conn.retrieveServiceContent(_svcRef); ManagedObjectReference eMgrRef = _sic.getEventManager(); ...
2 3
ObtainthemanagedobjectreferencetotheentitywithwhichyouareassociatingtheEvent. InvoketheLogUserEventoperationusingboththesereferencesandastringconsistingoftheEvent messageforthemsgparameteroftheoperation.
UserdefinedEventobjectsdisplayinthevSphereClientamongtheothereventsonthesystem,withthe prefixUser logged event:followedbythetextsubmittedinyourmsgparameter.Inotherclient applications,suchasintheconsolebasedEventsampleapplications,customeventsdisplayas com.vmware.vim.GeneralUserEventobjects.
132
VMware, Inc.
Obtaining Information about Events Using a HistoryCollector

AnEventHistoryCollectorletsyougatherinformationabouttheeventsthathavebeengeneratedbythe server.YoucreateanEventHistoryCollectorusingtheCreateCollectorForEventsoperationof EventManager. To create an EventHistoryCollector 1 IdentifythetypeofEventobjectsthatyouwanttocollect,andcreateaninstanceofanEventFilterSpec dataobjectthatspecifiesyourfiltercriteria.TheEventFilterSpecincludesproperties,suchas eventTypeId,thatyouusetolimitthesetofcollectedeventobjectstospecifictypes.Youcanalsoprovide atimerangeintheEventFilterSpec,bydefininganEventFilterSpecByTimedataobjectforitstime property.SeethevSphereAPIReferencefordetails. ObtainthemanagedobjectreferencetotheEventManageronyourserverinstance. SubmitthefilterandthereferencetotheserverintheCreateEventHistoryCollectoroperation. The serverreturnsareferencetoaEventHistoryCollectorobject.
2 3
TheEventHistoryCollectorreturnedconsistsofthecollectionofobjectsfromthevCenterServerdatabase. TheEventHistoryCollectorconsistsofanarrayofoneormoreEventdataobjectsthatmeetthecriteria specified.ThelatestPagepropertyoftheEventHistoryCollectorobjecthasapropertythatconsistsofthe 1000mostrecentobjectsinthecollection.
Overview of HistoryCollector Managed Objects

AnEventHistoryCollectorisoneofthespecificsubtypesoftheHistoryCollectormanagedobjecttype. TheTaskHistoryCollectorisanother.Youdefinethespecificationtouseasthefilterandpassittothe CreateTaskHistoryCollectoroperationoftheTaskManager.Figure 143showstherelationshipof HistoryCollectortoitstwosubtypes. Figure 14-3. TaskHistoryCollector and EventHistoryCollector Descend from HistoryCollector
InadditiontothefilterpropertythattheyinheritfromtheHistoryCollectorbasetype,the EventHistoryCollectorandTaskHistoryCollectoreachhasalatestPagepropertyfortheirrespective objecttypes.TheHistoryCollectormanagedobjecttypeprovidesoperationsformanagingthelifecycle andscrollableviewofacollection. Table 14-3. Operations Common to HistoryCollector and Its Descendents
Operation DestroyCollector ResetCollector Description AHistoryCollectorexistsonlyforthecurrentsession.InvoketheDestroyCollector operationtoexplicitlydestroythecollectorbeforethesessionends. Adjuststhestartingpositionforthesubsetofobjectsfromthecollectortotheobject immediatelyprecedingthecurrentlatestPage.
VMware, Inc.
133
Table 14-3. Operations Common to HistoryCollector and Its Descendents (Continued)

Operation RewindCollector SetCollectorPageSize Description PositionsthelatestPagetotheoldestiteminthearray.WhenaHistoryCollectoris created,thisisthedefaultlocation. AcceptsanintegerparametertosetthesizeofthelatestPagepropertyofa HistoryCollector.ThedefaultsizeofaHistoryCollectorisanarraycomprisinga maximumof1000objectsoftheappropriatetype(Task,Event).Thearrayissortedby creationdateandtimeoftheobjects.
Table 144liststhepropertiesofTaskFilterSpec.TocreateaTaskHistoryCollector,youuseoneormore propertiesofTaskFilterSpecdataobjecttodefinefilterthatmeetsyourrequirements.Forexample,rather thanreturningallTaskobjectsassociatedwithvirtualmachines,youmightcreateafiltertocollectonlythose Taskobjectsassociatedwithvirtualmachinesthatwereexecutedbythebackupadministratorbetween2:00 and4:00a.m.onaspecificdate. Table 14-4. TaskFilterSpec Data Object
Property alarm entity eventChainId parentTaskKey rootTaskKey scheduledTask state Type MOR >Alarm TaskFilterSpecByEntity int[] string[] string[] MOR >ScheduledTask TaskInfoState[] Description and Usage Optional.Usetocreateafilterbasedonspecificinstanceofan Alarm. Optional.Usetocreateafilterbasedonspecificmanagedentity types.Defaultreturnsvaluesforallmanagedentities. Optional.UsetocreateafilterthatreturnsonlyTaskobjects associatedbyaspecificchainofevents. Optional.UsetocreateafilterthatreturnsonlythoseTaskobjects thathavethespecifiedparentTaskKey. Optional.UsetocreateafilterthatreturnsonlythoseTaskobjects thatcontainthespecifiedrootTaskKey. Optional.Usetocreateafilterthatreturnsareferenceonlytothe specifiedScheduledTask.DefaultreturnsallTaskobjects. Optional.UsetocreateafilterthatreturnsonlythoseTaskobjects inthespecifiedstate: error queued running success tag string[] Optional.UsetocreateafilterthatreturnsTaskobjectswiththe specifiedtag.Includeanemptystring()inthearraytoreturn Taskobjectswithoutatag. Optional.UsetocreateafilterthatreturnsTaskobjectswiththe specifiedtime.Ifnotspecified,thecollectorincludesallTask objects. Optional.UsetocreateafilterthatreturnsTaskobjectsfora specifieduseraccount.Ifnotprovided,thenthetasksbelongingto anyuserarecollected.
time
TaskFilterSpecByTime
userName
TaskFilterSpecByUsername
BeforeyoucancreateaTaskHistoryCollector,youmustcreateaninstanceofthefilterthatdefinesthe specificationsoftheTaskobjectsthatyouwanttocollect.Mostofthepropertiesareoptionalandcanbe submittedasnullvalues.TheTaskFilterSpecletsyoucollecttasksbasedonusername,entitytype,time, stateoftheTask,oranyoftheotherpropertieslistedinTable 144. Bydefault,whenaHistoryCollectorisinstantiated,theobjectsinthecollectionareretrievedinorderof oldesttonewest.ToaccessthecontentofaHistoryCollector,youuseaPropertyCollectortoobtainthe itemsfromthelatestPageproperty.
134
VMware, Inc.
New Objects Appended to a HistoryCollector

OnceaHistoryCollectorexists,theserverappendsnewobjectsthatmeetthefiltercriteriatothecollection astheyoccur.Thesystemappendsthenewobjecttothecollectionbyplacingitinthefirstpositionofthe latestPageanditremovestheoldestobjectfromthecollection.
Deleting a HistoryCollector
AHistoryCollectorexistsonlyforthedurationofthesessionthatinstantiatedit.Youinvokethe DestroyCollectoroperationtoexplicitlyeliminatethecollectorbeforethesessionends. SeethevSphereAPIReferenceforcompleteinformationaboutHistoryCollector,EventHistoryCollector, andTaskHistoryCollector.
VMware, Inc.
135
136
VMware, Inc.
15
Using the Alarm Infrastructure
15
VMwarevCenterServerprovidesacomprehensivealarminfrastructureforautomatingactionsandsending varioustypesofnotificationinresponsetospecifiedserverconditions.Youcancreatealarmsthatrespondto specificconditions,serverstate,oraspecifiedevent.Analarmmusthaveanexpressionthatevaluatestoa truefalsevalue.ThealarminfrastructureincludestheAlarmManagerserviceinterface,theAlarmmanaged objecttype,andmanyassociatedobjectsthatmakeupthedatastructuresrequiredtosupportdefiningthe serverconditionsthatmustexistforanalarmtobecomeactive.Thealarminfrastructureintegrateswithother servercomponents,suchaseventsandperformancecounters.WiththereleaseofvSphere4.0,thealarm infrastructureprovidesfinergrainedcontroloveralarmthresholdsettingsthaninpriorreleases.Many AlarmsexistbydefaultonvCenterServer. Thischapterincludesthesetopics: SampleCodeReferenceonpage 137 OverviewofAlarmManagerandAlarmManagedObjectsonpage 137

Table 151liststhesampleapplicationsincludedwiththevSphereWebServicesSDKthatdemonstratesome ofthetopicsdiscussedinthischapter. Table 15-1. Sample Applications that Use Alarm
Java SDK\samples\Axis\java\com\vmware\samples\alarms VMPowerStateAlarm.java C# SDK\samples\DotNet\cs\ VMPowerStateAlarm
Overview of AlarmManager and Alarm Managed Objects

TheAlarmManageristheserviceinterfaceforcreating,setting,andmanagingalarms.TheAlarmManager instantiatesanAlarmpopulatedwiththepropertiesyouspecifyandreturnsamanagedobjectreferencetothe Alarm. Figure 15-1. Alarm Managed Object
VMware, Inc.
137
Obtaining a List of Alarms

TheAlarmManagerprovidesoperationsforobtaininginformationaboutexistingalarms.Youusethe GetAlarmoperationtoobtainanarrayofreferencestoalltheAlarmmanagedobjectsdefinedforaspecific managedentity.TheparametersfortheoperationareareferencetotheAlarmManagerobjectandanoptional referencetoaspecificmanagedentity.Withoutareferencetoamanagedentity,theGetAlarmoperation returnsallAlarmobjectsforallentitiesthatarevisibletotheprincipalassociatedwiththesessioninvokingthe operation. AsshowninFigure 151,anAlarmisamanagedobjectwithoperationsforitsownreconfigurationand removal.ItalsohasaninfopropertythatconsistsofanAlarmInfodataobject.AswiththeTaskmanaged objectandTaskInfodataobject,youcanobtaininformationabouttheAlarmsthatareactiveonthesystemby collectingthepropertiesoftheAlarmInfodataobject. WhenyoucreatetheAlarm,youassociateitwithoneormorespecificmanagedentities,suchasvirtual machines,hosts,distributedvirtualswitches,datastores,andsoon.WhentheconditionsdefinedfortheAlarm occuronthesystem,theActionspecifiedforthealarmstarts.Theactionmightbesendinganemail,running ascript,orinvokinganoperationofoneoftheserviceinterfaces.
Defining an Alarm
Severaldifferentdataobjectsprovidethecomponentsneededtospecifythesettingsforanalarm.Thealarm infrastructureintegrateswithotherinfrastructureservices,suchastheperformancemonitoringsystemand theeventinfrastructure. Forexample,youcandefineanalarmthatmonitorsthevaluesofaspecificmetricgeneratedbyoneofthe performanceprovidersonthesystem,byspecifyingthemetricintheexpressionyoudefine.Youmightwant tocreateanAlarmthatsendsanalertemailmessagewhenCPUusageonaspecificvirtualmachineexceeds 99%formorethan30minutes. Figure 15-2. CreateAlarm Operation Returns a Reference to an Alarm Managed Object
To create an Alarm on a specific managed entity 1 2 ObtainamanagedobjectreferencetotheAlarmManagerofthevCenterServer. ObtainamanagedobjectreferenceoftheentityonwhichyouwanttosettheAlarm.
138
VMware, Inc.
Chapter 15 Using the Alarm Infrastructure
PopulatetheAlarmSpecdataobjectwiththedetailsfortheAlarm.Manyofthesepropertiesarenested dataobjectsthatyoumustcreateinyourcodebeforeyoucaninstantiatetheAlarmSpecdataobject.See Table 152,AlarmSpecProperties,onpage 139formoreinformationaboutthisdataobjecttype. PassthereferencesandthedataobjecttotheCreateAlarmoperation,asitsparameters.Thesystem returnsamanagedobjectreferencetotheAlarm,asshowninFigure 152.
Table 15-2. AlarmSpec Properties

Property action Type AlarmAction Description ActiontoinitiatewhentheAlarmbecomesactive.Specifyoneofthe Actionsubtypes,including: CreateTaskAction MethodAction RunScriptAction SendEmailAction SendSNMPAction SeeOverviewoftheAlarmActionDataObjectonpage 141. actionFrequency description enabled expression int string boolean AlarmExpression NumberofsecondsthattheAlarmremainsinthestaterequiredtoinitiate thespecifiedAction. Required.DescriptionoftheAlarm. Required.SettotruetoenabletheAlarm.Settofalsetodisablethe Alarm. Required.OneormoreoftheAlarmExpressiondataobjectscombined inawaythatevaluatestoatruefalseexpression. AndAlarmExpression OrAlarmExpression EventAlarmExpression MetricAlarmExpression StateAlarmExpression. SeeOverviewoftheAlarmExpressionDataObjectonpage 139. name setting string AlarmSetting Required.NameoftheAlarm. ToleranceandfrequencylimitsfortheAlarmdefinedinthe AlarmSettingdataobject.AlarmSettingcontainstwointeger properties: reportingFrequency,whichspecifiesthenumberofseconds betweenactivationofanalarm.Use0tospecifythatthealarmcan activateasfrequentlyasrequired. toleranceRange,whichspecifiestheacceptablerange(measuredin hundredthpercentage)aboveandbelowthespecifiedvaluedefined inaMetricAlarmExpression.
Overview of the AlarmSpec Data Object

YousetanAlarmonanentitybycreatingtheAlarmSpecdataobject.TheAlarmSpecdataobjectincludes propertiesforallaspectsofanAlarm,includingitsexpressionandtheactiontotakewhentheexpression evaluatestotrue.AsshowninTable 152,theexpressionandtheactionpropertiesaredefinedasinstances oftwoothercomplexdataobjecttypes,AlarmExpressionandAlarmAction,bothofwhichareabstractdata objecttypes.
Overview of the AlarmExpression Data Object

YouspecifytheconditionsthattriggertheactiondefinedforanAlarmbyprovidinganAlarmExpression dataobjectfortheexpressionpropertyoftheAlarmSpecdataobject.TheAlarmExpressiondataobjectis anabstracttype.Ithasseveralsubtypes(seeFigure 153,AlarmExpressionAbstractDataTypeandIts Subtypes,onpage 140).
VMware, Inc.
139
TheAlarmExpressionsubtypesallowyoutospecifythresholdsonobjects,stateofobjects,orspecifyspecific eventstomonitor.YouusetheAlarmExpressiondataobjecttypetospecifytheconditionsunderwhichyou wanttheAlarmtobecomeactive. Figure 15-3. AlarmExpression Abstract Data Type and Its Subtypes
ByusingtheappropriatesubtypeofAlarmExpression,youmightsetalarmsforavarietyofconditions, states,orevents,suchastheseexamples: Powerstateofavirtualmachineorthestateofadistributedvirtualswitch,byusinga StateAlarmExpressiondataobject Resourceutilizationmetricsthatexceedaspecifiedlimit,byusingaMetricAlarmExpression Eventssuchaspoweronorpoweroffofprimaryorsecondaryvirtualmachinesinafaulttolerantcluster, byusingtheEventAlarmExpression YoucreateinstancesoftheStateAlarmExpression,EventAlarmExpression,orMetricAlarmExpression dataobjectsspecifythresholdsthattriggerthealarm.Touseaspecifictypeofeventasthebasisforanalarm configuration,youusetheEventAlarmExpression.TheEventAlarmComparisondataobjectletsyouspecify thepropertyoftheEventthatshouldtriggerthealarmandtheoperatortouseasthebasisforcomparison. Figure 15-4. EventAlarmExpression
YoucansetanalarmtomonitorspecificperformancemetricsbyusingtheMetricAlarmExpressiondata object.YousetthemetricpropertytothePerfMetricIdofaspecificperformancemetricthatyouwantto monitoronthesystem. Settheredoryellowpropertiestoidentitythelevelatwhichthemetricvaluemovesfromgreen,toyellow, toredstatus.
140
VMware, Inc.
Chapter 15 Using the Alarm Infrastructure
Figure 15-5. MetricAlarmExpression Data Object
YoumustdefineeithertheredoryellowpropertyintheMetricAlarmExpressiondataobjectthatyou create.Youcanalsospecifybothproperties,ifappropriateforyourapplication.Forexample,usetheyellow propertytospecifyathresholdvaluethatsignifiesawarningcondition,andusetheredpropertytospecifya thresholdvaluethatsignifiesamoreseriouscondition.Useeachofthesepropertiesinconjunctionwiththe isAboveorisBelowMetricAlarmOperatorenumerationstocompletethedefinitionofthethreshold. Inconjunctionwithredandyellowproperties,youuseeitherredIntervaloryellowIntervalproperties. TheredIntervalandyellowIntervalpropertiesarebothnewinvSphereAPI4.0.Thesepropertiesenable youtosetthenumberofsecondsthattheperformancemetricmustbeinredoryellow,respectively,before theexpressionbecomestrue,thustriggeringthedefinedaction. UsingoneormoreinstancesoftheAndAlarmExpressionandtheOrAlarmExpressiondataobjects,you combinetheobjectsintoacompleteexpressionthatevaluatestoatruefalsevalue.
Overview of the AlarmAction Data Object

Thesystemcanrespondtothealarmssetonanyobjectinmanydifferentways: Byinvokingoperationsofotherserviceinterfaces Byrunningascript Bysendinganemailmessagetoaspecificemailaccount BygeneratinganSNMPtrap Toinvokeanoperationofoneoftheserviceinterfaces,youcreateaMethodActiondataobject.Torunascript, youcreateaninstanceoftheRunScriptActiondataobjectthatspecifiesthefullyqualifiedpathtotheshell scriptonthevCenterServer.Tosendanemailmessagetoasystemadministrator,youusethe SendEmailActiondataobject.Andsoon. YouspecifytheactionsthatthesystemshouldtakebysettingtheactionpropertyoftheAlarmSpecdata objecttotheAlarmActiondataobjectdefinedforthepurpose.YouusetheAlarmActiondataobjectin conjunctionwithoneormoreAlarmTriggeringActionTransitionSpecdataobjects. TheAlarmActiondataobjectisanabstracttypethathastwodescendentobjects,AlarmTriggeringAction andGroupAlarmAction.TheGroupAlarmActiondataobjectisanarrayversionoftheAlarmActionbase type,meaningthatyoucancreateasingleAlarmActioninstanceoranarrayofAlarmActioninstancestotake effectwhentheconditionsspecifiedforyouralarmaremetonthesystem. TheAlarmTriggeringActionhasanactionpropertyandatransitionSpecsproperty. The transitionSpecspropertyisnewinvSphereAPI4.0.ThetransitionSpecspropertyconsistsofan instanceofanAlarmTriggeringActionTransitionSpec,alsonewinvSphereAPI4.0. TheactionpropertyoftheScheduledTaskSpecisdefinedasaninstanceoftheActiondataobject. The Actiondataobjectisanabstracttypethathasseveraldescendentobjectsthatmodelspecificbehaviors.
VMware, Inc.
141
Figure 15-6. AlarmAction and Action Abstract Data Object Types and Subtypes
InvSphereAPI4.0,theAlarmTriggeringActiondataobjecthasanewproperty,transitionSpecs,that providesdiscretecontroloverthetiming,thresholds,andfrequencyofanAlarm.Ratherthanusing green2yellow,red2yellow,yellow2green,andyellow2redpropertiestotriggeralarms,usethe AlarmTriggeringActionTransitionSpectodefinestatechangeswithcompletecontrol. AlarmTriggeringActionTransitionSpechaspropertiesthatenableyoutodefineastartingstatusanda finalstatusforthestateoftheAlarm.ThestateofanalarmiscontainedinanAlarmStatedataobject.Youcan alsolimitthenumberofAlarmobjectsactuallytriggeredtoasingleAlarm,byspecifyingfalseforthe repeatspropertyoftheAlarmTriggeringActionTransitionSpec. Forexample,youcanusetheMethodActiondataobjecttypetoinvokeanoperationontheserver. The MethodActiondataobjectcontainstheseproperties: nameUsethenamepropertyofMethodArgumenttospecifythenameoftheoperationthatyouwantto invokeatthescheduledtime. argumentUsetheargumentpropertytopasstheparametersrequiredbytheoperation,ifany. The argumentpropertyisdefinedasanarrayofMethodArgumentActiondataobjects. Dependingontheentityassociatedwiththealarm,theargumentpropertyofMethodActionmightnotbe needed.Forexample,thePowerOffVM_Taskoperationnormallyrequiresthemanagedobjectreferenceofthe virtualmachineyouwanttoshutdown.Ifyouralarmactionisassociatedwithacontainerobject,suchasa FolderorDatacenter,aparameterspecifyingaspecificvirtualmachinereferenceisnotneeded. Whenanalarmisactivated,itgeneratesanEventthatgetspostedtotheEventhistorydatabase.The action initiatedbytheAlarmmightalsopostitsownEventtothedatabase,dependingontheActiontype. SeethevSphereAPIReferenceforcompleteinformation.
Deleting or Disabling an Alarm

AnAlarmremainsactiveuntilyoudeleteitordisableit.Todeletethealarm,obtainamanagedobjectreference totheAlarmandinvokeitsRemoveAlarmoperation. YoucandisabletheAlarmratherthandeletingit.ObtainamanagedobjectreferencetotheAlarmManagerand theentityonwhichtheAlarmisset,andinvoketheEnableAlarmActionsoperation,passingthevaluefalse fortheenabledparameter.TheEnableAlarmActionsoperationisnewinvSphereAPI4.0.
142
VMware, Inc.
16
Scheduling vCenter Server Operations
16
TheScheduledTaskManagerenablesyoutoscheduleoperationsonvCenterServer.Theoperationmightbe scheduledforaonetimerunorforaregularrepeatingschedule.TheScheduledTaskManagerissupported onvCenterServer.Thischapterincludesthesetopics: SampleCodeReferenceonpage 143 ScheduledTaskManagerManagedObjectonpage 143 CreatingaScheduledTaskObjectonpage 144 DefiningtheScheduleforthevCenterServerOperationonpage 145 Visibilityofmanyoftheobjectsandreturntypesdiscussedinthischapterdependsonthepermissions associatedwithuseraccountusingtheclientapplication.Avisibleentityisoneforwhichtheprincipal associatedwiththesessionhasviewprivileges.Formoreinformationaboutpermissions,seeOverviewof UserModelsandServerAccessControlConceptsonpage 33.

Table 161liststhesampleapplicationsincludedwiththevSphereWebServicesSDKthatdemonstratesome ofthetopicsdiscussedinthischapter. Table 16-1. Sample Applications that Demonstrate Using ScheduledTaskManager
Java SDK\samples\Axis\java\com\vmware\samples\scheduling DeleteOneTimeScheduledTask.java OneTimeScheduledTask.java WeeklyRecurrenceScheduledTask.java C# SDK\samples\DotNet\cs\ DeleteOneTimeScheduledTask OneTimeScheduledTask WeeklyRecurrenceScheduledTask
ScheduledTaskManager Managed Object

YoucanuseScheduledTaskManagertodefineactionstooccuronvCenterServeratmanydifferenttimes: WhenthevCenterServersystemstartsupoperations,suchasafterareboot Ataspecifictimeandday Athourly,daily,weekly,ormonthlyintervals Thetypeofactionsyouspecifytooccuratthescheduledtimeincluderunningscriptsontheserverorinvoking operationsusingoneoftheotherserviceinterfacesonthevCenterServersystem.Youapplythescheduled actiontoanentityintheinventory,suchasaspecificvirtualmachineorahostinadatacenter.ScheduledTask objectsdisplayinthevSphereClientTask&Eventstab. WithvSphere4.0,youcanapplyscheduledtaskstoanymanagedobject,notjustmanagedentities,byusing theCreateObjectScheduledTaskoperation.SeethevSphereAPIReferencefordetails.
VMware, Inc. 143
Figure 161showstheScheduledTaskManagerserviceinterfaceandassociateddataobjectsforitsproperties. Figure 16-1. ScheduleTaskManager and ScheduledTask Managed Object Types
ThescheduledTaskpropertycontainsanarrayoftheScheduledTaskobjectsconfiguredfortheserver.Ifyou havenoactionsscheduled,thispropertyisempty.ForanyScheduledTaskobjectsinthisarray,youcanuse theinfopropertyoftheScheduledTaskobjecttoobtaininformationaboutthestatusofthescheduledaction, includingitsprogress,state,previousandnextruntimes,andtheotherdetailscontainedinthe ScheduledTaskInfodataobject. IftheactionspecifiedforaScheduledTaskcreatesitsownTask(suchaswithanyoftheasynchronous operations(*_Task)operations),themanagedobjectreferencetotheTaskpopulatestheactiveTaskproperty ofScheduledTaskInfo.
Retrieving ScheduledTasks for a Specific Managed Entity

YoucanusetheRetrieveEntityScheduledTaskoperationobtainanarrayofallactionsscheduledfora specificmanagedentity. Table 16-2. RetrieveEntityScheduledTask Operation
Parameter ScheduledTaskManager entity Type MOR>ScheduledTaskManager MOR>managed entity Description ReferencetotheScheduledTaskManager. Optional.EntitywhoseScheduledTasksyouwantto obtain.Ifnoentityisspecified,thisoperationreturnsall ScheduledTasksthatarevisibletotheprincipal associatedwiththesession.
Creating a ScheduledTask Object

AScheduledTaskisamanagedobjecttype.ItiscreatedbytheScheduledTaskManagerbasedonthe specificationsyouprovideinaScheduledTaskSpecdataobject(seeFigure 162,Using ScheduledTaskManagertoCreateaScheduledTask,onpage 145). YoucreateaScheduledTaskbyinvokingtheCreateScheduledTaskoperationwiththemanagedobject referenceoftheScheduledTaskManager,themanagedobjectreferenceofthemanagedentityonwhichto applytheschedule,andaninstanceoftheScheduledTaskSpecobjectthatdefinesthescheduleandspecifies theactiontotakeatthespecifiedtime. Youcanscheduleactionsonanyentityintheinventory.TheScheduledTaskobjectisassociatedwiththe entityyouspecify,takingintoaccounttherelativelocationoftheentityintheinventoryhierarchy.Ascheduled actionappliestoanobjectbasedontheserules: Ifyouspecifyacontainerobjectastheentityforthescheduledaction,thescheduleappliestoallentities thataredirectdescendentsofthecontainer. Ifyouspecifyanodeobjectintheinventory,suchasavirtualmachine,thescheduleappliesonlytothe virtualmachine.
144
VMware, Inc.
Chapter 16 Scheduling vCenter Server Operations
YoucansetaScheduledTaskattheFolder,Datacenter,orVirtualApplevelandhavethescheduledaction applytoallentitiesassociatedwiththeFolder,Datacenter,orVirtualApp.SeeUnderstandingContainer ObjectsandtheInventoryonpage 26. Figure 16-2. Using ScheduledTaskManager to Create a ScheduledTask
Defining the Schedule for the vCenter Server Operation

TheScheduledTaskSpecdataobjectcontainsalltheinformationtocreateaScheduledTask. Table 16-3. ScheduledTaskSpec Data Object Properties
Property action Type Action Description SpecifiestheactiontotakewhentheScheduledTaskruns.TheAction dataobjectisanabstracttypethatisextendedbyseveralspecificaction types.SeeDefiningtheActionsonpage 146formoreinformation abouttheActiondataobject. DescriptionoftheScheduledTask. SettotruetoenabletheScheduledTask.Settofalsetodisablethe ScheduledTask. NameoftheScheduledTask. Optional.Usetospecifytheemailaddressforsendingnotification messagesabouttheScheduledTask.Tousenotifications,thevCenter ServermusthaveanSNMPemailgatewayconfigured.Bydefault,this propertyissettoanemptystring. Specifiesthetime,frequency,andotherdetailsoftheschedule.The TaskSchedulerdataobjectisthebasetypeforanumberofspecific scheduleobjects.SeeSchedulingRecurringOperationsonpage 146.
description enabled name notification
string boolean string string
scheduler
TaskScheduler
BothactionandschedulepropertiesofaScheduledTaskSpecobjectconsistoftwootherdataobjects,an ActionandTaskSchedulerdataobjects,respectively.SeeSchedulingRecurringOperationsonpage 146 foranoverviewoftheTaskSchedulerdataobjectanditssubtypes.
VMware, Inc.
145
Defining the Actions

TheActiondataobjectisanabstracttype.Youdefinethespecificactiontooccurontheserveraccordingto yourschedulebyusingofthespecificsubtypesofActiondataobject(seeFigure 163). Figure 16-3. Action Data Object and Its Subtypes
TheActiondataobjectsarealsousedbytheAlarminfrastructure.SeeOverviewoftheAlarmActionData Objectonpage 141formoreinformationaboutusingActionsubtypes. SeethevSphereAPIReferenceformoreinformation.
Scheduling Recurring Operations

TheTaskSchedulerdataobjectisabasetypethathasmanysubtypes.Tospecifythetimes,days,orfrequency ofscheduledtasks,createtheappropriateinstancesofTaskSchedulersubtypesthatyouneedandsetthe schedulerpropertyoftheScheduledTaskSpec. Figure 16-4. TaskScheduler Data Object Type and Subtypes
TheTaskSchedulerbasetypehastwoproperties: activeTimeisthetimeatwhichtheactionshouldoccur.Ifyouleavethispropertyunset,itdefaultsto thetimethatspecificationforthescheduledtaskwassubmittedtotheserver. expireTimeisthetimeafterwhichthescheduledactionshouldnotoccur.Bydefault,thispropertyis Unset,sothescheduledtaskdoesnotexpire.

146 VMware, Inc.
Chapter 16 Scheduling vCenter Server Operations
Table 164providessomeusageinformationabouttheTaskSchedulersubtypesshowninFigure 164.The examplesinthetableareJavacodesnippets. Table 16-4. TaskScheduler Data Object Subtypes
TaskScheduler subtype AfterStartupTaskScheduler Usage ScheduleatasktostartassoonasthevCenterServersystemisstarted,orata definedtimeafterstartup.Usetheminutepropertytospecifythenumberof minutes.Thevaluemustbezero(tasktriggeredatstartup)orhigher. AfterStartupTaskScheduler asts = new AfterStartupTaskScheduler(); asts.setMinute(10); OnceTaskScheduler Example:Scheduleatasktorun thirtyminutesafterthescheduleis submittedtotheserver. Scheduleanactiontorunonceonlyatthespecifieddateandtime. Calendar runTime= Calendar.getInstance(); runtime.add(Calendar.MINUTE, 30); OnceTaskScheduler ots = new OnceTaskScheduler (); ots.setRunAt(runTime); RecurrentTaskScheduler BasetypeforHourlyTaskScheduler,DailyTaskScheduler, WeeklyTaskScheduler,andMonthlyTaskSchedulerobjects.Settheinterval propertytodefinehowfrequentlyataskshouldrun.Forexample,settingthe intervalpropertyofanhourlytaskto4causesthetasktorunevery4hours. Scheduleatasktorunonceeveryhour(oreveryspecifiednumberofhours)ata specifiedtime.Settheintervalpropertytorunthetaskafteraspecifiednumber ofhours. HourlyTaskScheduler hts = new HourlyTaskScheduler(); hts.setMinute(30); hts.setInterval(4); DailyTaskScheduler Scheduleatasktorundailyoraspecifiednumberofdaysataspecifiedtime (hourandminutes).Useinconjunctionwiththeintervalpropertytorunthetask afteraspecifiednumberofdays. DailyTaskScheduler dts = new DailyTaskScheduler(); dts.setMinute(30); dts.setHour(14); WeeklyTaskScheduler Scheduleatasktoruneveryweek(oreveryspecifiednumberofweeks)ona specifiedday(ordays)ataspecifictime.ThehoursandminutesaresetasUTC values.Atleastoneofthebooleanvaluesmustbesettotrue.Youcanalsosetthe intervalpropertytorunthetaskafteraspecifiednumberofweeks. WeeklyTaskScheduler wts = new WeeklyTaskScheduler(); wts.setMonday(true); wts.setTuesday(true); wts.setWednesday(false); wts.setThursday(false); wts.setFriday(false); wts.setSaturday(false); wts.setSunday(true); dts.setMinute(30); dts.setHour(4); MonthlyByDayTaskScheduler Scheduleatasktoruneverymonth(oreveryspecifiednumberofmonths)ona specifieddayataspecifiedtime(hourandminutes).Youcanalsosettheinterval propertytorunthetaskafteraspecifiednumberofmonths. MonthlyByDayTaskScheduler mbdts = new MonthlyByDayTaskScheduler(); mbdts.setDay(31); mbdts.setInterval(3); mbdts.setMinute(30); mbdts.setHour(14);
Example:Scheduleatasktorun10 minutesaftervCenterServerstartup.
HourlyTaskScheduler
Example:Scheduleatasktorun every4hoursathalfpastthehour.
Example:Scheduleatasktorun dailyat9:30am(EST).
Example:Scheduleatasktorun everyTuesdayandSundayat30 minutespastmidnight.
Example:Scheduleatasktorun every3months(onthelastdayofthe month)at30minutespastnoon
VMware, Inc.
147
Table 16-4. TaskScheduler Data Object Subtypes (Continued)

TaskScheduler subtype MonthlyByWeekdayTaskScheduler Usage Scheduleatasktoruneverymonth(oreveryspecifiednumberofmonths)ona specifiedweek,weekday,andtime(hour:minutes).Youcanalsosettheinterval propertytorunthetaskafteraspecifiednumberofmonths. MonthlyByWeekdayTaskScheduler mbwts = new MonthlyByWeekdayTaskScheduler(); mbwts.setOffset(WeekOfMonth.last); mbwts.setWeekday(DayOfWeek.wednesday); mbwts.setHour(4); mbwts.setMinute(30);
Example:Scheduleatasktorunon thelastWednesdayofeachmonthat 30minutespastmidnight:
AsofvSphereAPI4.0,thehourandminutepropertiesofallobjectsthatextendtheRecurrentTaskSchedule dataobjectarespecifiedinCoordinatedUniversalTime(UTC)valuesratherthanthelocaltimeoftheserver. Whenyoudefinetheschedule,convertyourlocaltimetoaUTCvalue. Forexample,thecodeinExample 161definesaScheduledTaskthatpowersonvirtualmachinesdailyat4:15 a.m.,iftheserverlocaltimeisinthePacificStandardTime(PST)timezone.ForaserverintheEastern EuropeanSummerTime(EEST)zone,thesettingisreadbythesystemas3:15pm. Example 16-1. ScheduledTask for Powering-on Virtual Machines
... / Set the schedule using the DailyTaskScheduler subtype. DailyTaskScheduler dTScheduler = new DailyTaskScheduler(); dTScheduler.setHour(12); dTScheduler.setMinute(15); ScheduledTaskSpec tSpec = new ScheduledTaskSpec(); tSpec.setDescription("Start virtual machine as per schedule."); tSpec.setEnabled(Boolean=TRUE); tSpec.setName("Power On Virtual Machine"); tSpec.setAction(ma); tSpec.setScheduler(dTScheduler); tSpec.setNotification("admin@vmware.com"); my_conn.createScheduledTask(_sic.getScheduledTaskManager, vmRef, tSpec); ...
Deleting a Scheduled Task

TodeleteaScheduledTaskobjectyouneeditsmanagedobjectreferencetopasstothe RemoveScheduledTaskoperationoftheScheduledTask.TheRemoveScheduledTaskoperationcancelsonly thecurrentrunoftheScheduledTask.ItdoesnotcancelsubsequentrunsoftheScheduledTask. TocancelanupcomingrunofaScheduledTask,youusetheReconfigureScheduledTaskwithanew ScheduledTaskSpecdataobjectcontainingthenewspecificationsfortheschedule. TocancelaScheduledTaskthatspawnsitsownTaskandcanceltheTaskasitruns,youcreatea PropertyCollectortoobtainthereferencetotheTaskandinvokeitsCancelTaskoperation.TheTaskmust becancellable.SeeOverviewoftheTaskInfrastructureonpage 83.
148
VMware, Inc.
Managed Object Privileges Reference
VMwarevSpherecomponentsaresecuredthroughasystemofprivileges,roles,andpermissions(see Chapter 4,OverviewofUserModelsandServerAccessControlConcepts,onpage 33formoreinformation). Thissectionlistsprivilegesrequiredtoperformvariousoperations,andprivilegesrequiredtoreadproperties. Itincludesthesetopics: PrivilegesRequiredtoInvokeOperationsonpage 149 PrivilegesRequiredtoReadPropertiesonpage 156 PrivilegesDefinedfortheAdministratorRoleonpage 158
Privileges Required to Invoke Operations

Table A1liststheprivilegesrequiredtoperformvariousoperations.(Forprivilegesidentifiedasdynamic,see thevSphereAPIReference.)OperationscanbesupportedbyvCenterServer,ESX/ESXi,orboth,asshownin Table A1. Table A-1. Privileges Required for vCenter Server and ESX/ESXi Operations
Operation Privilege VS ESX/ESXi
AcquireLocalTicket AcquireMksTicket AddAuthorizationRole AddCustomFieldDef AddHost_Task AddInternetScsiSendTargets AddInternetScsiStaticTargets AddPortGroup AddServiceConsoleVirtualNic AddStandaloneHost_Task AddVirtualNic AddVirtualSwitch AnswerVM ApplyRecommendation AssignUserToGroup AttachVmfsExtent AutoStartPowerOff
System.Anonymous VirtualMachine.Interact.ConsoleInteract Authorization.ModifyRoles Global.ManageCustomFields Host.Inventory.AddHostToCluster Host.Config.Storage Host.Config.Storage Host.Config.Network Host.Config.Network Host.Inventory.AddStandaloneHost Host.Config.Network Host.Config.Network VirtualMachine.Interact.AnswerQuestion Resource.ApplyRecommendation Host.Local.ManageUserGroups Host.Config.Storage Host.Config.AutoStart
X X X X X X X X X X X X X X X X X
X X X
X X X X
X X X
X X X
VMware, Inc.
149
Table A-1. Privileges Required for vCenter Server and ESX/ESXi Operations (Continued)
Operation AutoStartPowerOn BrowseDiagnosticLog CancelTask CancelWaitForUpdates CheckCustomizationResources CheckCustomizationSpec CheckForUpdates CheckIfMasterSnmpAgentRunning CheckLicenseFeature CloneVM_Task Privilege Host.Config.AutoStart Global.Diagnostics Global.CancelTask System.View System.View VirtualMachine.Provisioning.Customize System.View Host.Config.Snmp Global.Licenses NONE. Privilegesarerequiredonthevirtualmachinebeing clonedanddependonwhetherthevirtualmachineisa template.SeeCloneVM_TaskinthevSphereAPI Referenceforspecificprivileges. YouneedtheVirtualMachine.Inventory.Create privilegeonthefolderwherethenewvirtualmachine islocated. ComputeDiskPartitionInfo ConfigureDatastorePrincipal ConfigureLicenseSource CreateAlarm Host.Config.Storage Host.Config.Maintenance Global.Licenses NONE. Createprivilegerequiredontheentityassociatedwith thealarm. CreateCluster CreateCollectorForEvents CreateCollectorForTasks CreateCustomizationSpec CreateDatacenter CreateDiagnosticPartition CreateFilter CreateFolder CreateGroup CreateLocalDatastore CreateNasDatastore CreatePerfInterval CreateResourcePool CreateScheduledTask Host.Inventory.CreateCluster System.View System.View VirtualMachine.Provisioning.ModifyCustSpecs Datacenter.Create Host.Config.Storage System.View Folder.Create Host.Local.ManageUserGroups Host.Config.Storage Host.Config.Storage Performance.ModifyIntervals Resource.CreatePool NONE. ScheduledTask.Createrequiredontheentity associatedwiththescheduledtask. CreateSnapshot_Task CreateUser CreateVM_Task VirtualMachine.State.CreateSnapshot Host.Local.ManageUserGroups VirtualMachine.Inventory.Create Also,Resource.AssignVMToPoolprivilegerequired ontheresourcepoolwithwhichthevirtualmachine willbeassociated. X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X VS X X X X X X X X X X X X X X ESX/ESXi X X
150
VMware, Inc.
Appendix A Managed Object Privileges Reference
Operation CreateVmfsDatastore CurrentTime CustomizationSpecItemToXml CustomizeVM_Task DeleteCustomizationSpec DeleteFile DeselectVnic Destroy_Task DestroyChildren DestroyCollector DestroyDatastore DestroyNetwork DestroyPropertyFilter DisableFeature DisableHyperThreading DisableMultipathPath DisableRuleSet DisconnectHost_Task DoesCustomizationSpecExist DuplicateCustomizationSpec EnableFeature EnableHyperThreading EnableMultipathPath EnableRuleset EnterMaintenanceMode_Task ExitMaintenanceMode_Task ExtendVmfsDatastore FindByDatastorePath FindByDnsName FindByInventoryPath FindByIp FindByUuid FindChild FormatVmfs GenerateLogBundles_Task GetAlarm GetAlarmState Privilege Host.Config.Storage System.View System.View VirtualMachine.Provisioning.Customize VirtualMachine.Provisioning.ModifyCustSpecs Datastore.DeleteFile Host.Config.Network SeeDestroy_TaskinthevSphereAPIReference. SeeDestroyChildreninthevSphereAPIReference. NONE Datastore.Delete Network.Delete NONE Global.Licenses Host.Config.HyperThreading Host.Config.Storage Host.Config.NetService Host.Config.Connection VirtualMachine.Provisioning.ReadCustSpecs VirtualMachine.Provisioning.ModifyCustSpecs Global.Licenses Host.Config.HyperThreading Host.Config.Storage Host.Config.NetService Host.Config.Maintenance Host.Config.Maintenance Host.Config.Storage System.View System.View System.View System.View System.View System.View Host.Config.Storage Global.Diagnostics System.View NONE System.Readprivilegeisrequiredontheentity associatedwiththealarm. GetCustomizationSpec Login VirtualMachine.Provisioning.ReadCustSpecs System.Anonymous X X X VS X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X ESX/ESXi X X
VMware, Inc.
151
Operation Logout LogUserEvent Privilege System.View NONE Global.LogEventrequiredontheentityassociated withtheevent. MarkAsTemplate MarkAsVirtualMachine VirtualMachine.Provisioning.MarkAsTemplate VirtualMachine.Provisioning.MarkAsVM Resource.AssignVMToPoolrequiredontheresource pooltoassociatewiththevirtualmachine. MergePermissions MigrateVM_Task MountToolsInstaller MoveHostInto_Task Authorization.ReassignRolePermissions SeeMigrateVM_TaskinthevSphereAPIReference. VirtualMachine.Interact.ToolsInstall Host.Inventory.EditCluster Host.Inventory.MoveHostrequiredonthehost beingmoved. MoveInto_Task Host.Inventory.EditCluster Host.Inventory.MoveHostrequiredonthehost beingmoved. MoveIntoFolder_Task MoveIntoResourcePool OverwriteCustomizationSpec PowerOffVM_Task PowerOnVM_Task QueryAvailableDisksForVmfs QueryAvailablePartition QueryAvailablePerfMetric SeeMoveIntoFolder_TaskinthevSphereAPIReference. SeeMoveIntoFolder_TaskinthevSphereAPIReference. VirtualMachine.Provisioning.ModifyCustSpecs VirtualMachine.Interact.PowerOff VirtualMachine.Interact.PowerOn Host.Config.Storage Host.Config.Storage NONE System.Readisrequiredontheentityforwhich availableperformancemetricsarequeried. QueryConfigOption QueryConfigOptionDescriptor QueryConfigTarget QueryConnectionInfo QueryDescriptions QueryEvents QueryHostConnectionInfo QueryLicenseSourceAvailability QueryLicenseUsage QueryMemoryOverhead QueryNetworkHint QueryOptions QueryPartitionCreateDesc QueryPartitionCreateOptions QueryPerf System.Read System.Read System.Read Host.Inventory.AddStandaloneHost Global.Diagnostics System.View System.Read Global.Licenses Global.Licenses System.Read Host.Config.Network System.Read Host.Config.Storage Host.Config.Storage NONE System.Readprivilegeisrequiredontheentitywhose performancestatisticsarebeingqueried. X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X VS X X ESX/ESXi X X
152
VMware, Inc.
Operation QueryPerfComposite Privilege NONE System.Readprivilegeisrequiredontheentitywhose performancestatisticsarebeingqueried. QueryPerfCounter QueryPerfProviderSummary System.View NONE System.Readprivilegeisrequiredontheentitywhose performancestatisticsarebeingqueried. QueryVmfsDatastoreCreateOptions QueryVmfsDatastoreExtendOptions QueryVMotionCompatibility ReadNextEvents ReadNextTasks ReadPreviousEvents ReadPreviousTasks RebootGuest RebootHost_Task RecommendHostsForVm ReconfigureAlarm ReconfigureAutostart ReconfigureCluster_Task ReconfigureHostForDAS_Task ReconfigureScheduledTask ReconfigureServiceConsoleReservation ReconfigVM_Task ReconnectHost_Task RefreshDatastore RefreshFirewall RefreshNetworkSystem RefreshServices RefreshStorageSystem RegisterVM_Task Host.Config.Storage Host.Config.Storage Resource.QueryVMotion NONE NONE NONE NONE VirtualMachine.Interact.Reset Host.Config.Maintenance System.Read Alarm.Edit Host.Config.AutoStart Host.Inventory.EditCluster Host.Config.Connection ScheduledTask.Edit Host.Config.Memory dynamic Host.Config.Connection System.Read Host.Config.NetService Host.Config.Network Host.Config.NetService Host.Config.Storage VirtualMachine.Inventory.Create Resource.AssignVMToPoolprivilegeisrequiredon theresourcepooltowhichthevirtualmachineshould beattached. ReleaseLease Reload RelocateVM_Task RemoveAlarm RemoveAllSnapshots_Task RemoveAuthorizationRole RemoveCustomFieldDef RemoveDatastore NONE. System.Read Resource.ColdMigrate Alarm.Delete VirtualMachine.State.RemoveSnapshot Authorization.ModifyRoles Global.ManageCustomFields Host.Config.Storage X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X VS X ESX/ESXi X
VMware, Inc.
153
Operation RemoveEntityPermission Privilege NONE Authorization.ModifyPermissionsprivilegeis requiredontheentityassociatedwiththepermission. RemoveGroup RemoveInternetScsiSendTargets RemoveInternetScsiStaticTargets RemovePerfInterval RemovePortGroup RemoveScheduledTask RemoveServiceConsoleVirtualNic RemoveSnapshot_Task RemoveUser RemoveVirtualNic RemoveVirtualSwitch Rename_Task RenameCustomFieldDef RenameCustomizationSpec RenameDatastore RenameSnapshot RenewLease RescanAllHba RescanHba RescanVmfs ResetCollector ResetEntityPermissions Host.Local.ManageUserGroups Host.Config.Storage Host.Config.Storage Performance.ModifyIntervals Host.Config.Network ScheduledTask.Delete Host.Config.Network VirtualMachine.State.RemoveSnapshot Host.Local.ManageUserGroups Host.Config.Network Host.Config.Network SeeRename_TaskinthevSphereAPIReference. Global.ManageCustomFields VirtualMachine.Provisioning.ModifyCustSpecs Datacenter.RenameDatastore VirtualMachine.State.RenameSnapshot NONE Host.Config.Storage Host.Config.Storage Host.Config.Storage NONE NONE Authorization.ModifyPermissionsprivilegeis requiredontheentityassociatedwiththepermission andtheentitysparent. ResetGuestInformation ResetVM_Task RestartMasterSnmpAgent RestartService RestartServiceConsoleVirtualNic RetrieveAllPermissions RetrieveDiskPartitionInfo RetrieveEntityPermissions VirtualMachine.Config.ResetGuestInfo VirtualMachine.Interact.Reset Host.Config.Snmp Host.Config.NetService Host.Config.Network System.View Host.Config.Storage NONE System.Readprivilegeisrequiredontheentitywhose performancestatisticsarebeingqueried. RetrieveEntityScheduledTask RetrieveProperties RetrieveRolePermissions RetrieveServiceContent System.View System.View System.View System.Anonymous X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X Allbut ESX2.x X X X X X X X X X X X X X X X X X VS X ESX/ESXi X
154
VMware, Inc.
Operation RetrieveUserGroups RevertToCurrentSnapshot_Task RevertToSnapshot_Task RewindCollector RunScheduledTask SearchDatastore_Task SearchDatastoreSubFolders_Task SelectActivePartition SelectVnic SetCollectorPageSize SetEntityPermissions Privilege System.View VirtualMachine.State.RevertToSnapshot VirtualMachine.State.RevertToSnapshot NONE ScheduledTask.Run Datastore.Browse Datastore.Browse Host.Config.Storage Host.Config.Network NONE NONE Authorization.ModifyPermissionsrequiredon entityassociatedwiththepermissionsanditsparent. SetField NONE Global.SetCustomFieldrequiredontheentity associatedwiththecustomfield. SetLicenseEdition SetLocale SetMultipathLunPolicy SetScreenResolution ShutdownGuest ShutdownHost_Task StandbyGuest StartService StopMasterSnmpAgent StopServiceq SuspendVM_Task TerminateSession UnassignUserFromGroup UninstallService UnmountToolsInstaller UnregisterAndDestroy_Task UnregisterVM UpdateAuthorizationRole UpdateChildResourceConfiguration UpdateConfig UpdateConsoleIpRouteConfig UpdateDefaultPolicy UpdateDiskPartitions UpdateDnsConfig UpdateInternetScsiAlias Global.Licenses System.View Host.Config.Storage VirtualMachine.Interact.ConsoleInteract VirtualMachine.Interact.PowerOff Host.Config.Maintenance VirtualMachine.Interact.Suspend Host.Config.NetService Host.Config.Snmp Host.Config.NetService VirtualMachine.Interact.Suspend Sessions.TerminateSession Host.Local.ManageUserGroups Host.Config.NetService VirtualMachine.Interact.ToolsInstall Folder.Delete
1
VS X X
ESX/ESXi X Onallbut ESX2.x X
X X X X X X X X
X X X X X X
X X X X X X X X X X X X X X X X X X X X X X X X X
X X X X X X X X X X X X X X X X X X X X X X X X X
VirtualMachine.Inventory.Delete Authorization.ModifyRoles SeeUpdateChildResourceConfigurationinthe vSphereAPIReference. SeeUpdateConfiginthevSphereAPIReference. Host.Config.Network Host.Config.Network Host.Config.Storage Host.Config.Network Host.Config.Storage
VMware, Inc.
155
Operation UpdateInternetScsiAuthenticationProperties UpdateInternetScsiDiscoveryProperties UpdateInternetScsiIPProperties UpdateInternetScsiName UpdateIpConfig UpdateIpRouteConfig UpdateNetworkConfig UpdateOptions UpdatePerfInterval UpdatePhysicalNicLinkSpeed UpdatePortGroup UpdateServiceConsoleVirtualNic UpdateServiceMessage UpdateServicePolicy UpdateSnmpConfig UpdateSoftwareInternetScsiEnabled UpdateSystemResources UpdateUser UpdateVirtualNic UpdateVirtualSwitch UpgradeTools_Task UpgradeVM_Task UpgradeVmfs UpgradeVmLayout ValidateMigration Privilege Host.Config.Storage Host.Config.Storage Host.Config.Storage Host.Config.Storage Host.Config.Network Host.Config.Network Host.Config.Network SeeUpdateOptionsinthevSphereAPIReference. Performance.ModifyIntervals Host.Config.Network Host.Config.Network Host.Config.Network Sessions.GlobalMessage Host.Config.NetService Host.Config.Snmp Host.Config.Storage Host.Config.Resources Host.Local.ManageUserGroups Host.Config.Network Host.Config.Network VirtualMachine.Interact.ToolsInstall VirtualMachine.Config.UpgradeVirtualHardware Host.Config.Storage Host.Config.Storage SeeValidateMigrationinthevSphereAPIReference. Resource.AssignVMToPoolrequiredonthetarget resourcepoolforthevirtualmachines. WaitForUpdates XmlToCustomizationSpecItem System.View System.View X X X VS X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X ESX/ESXi X X X X X X X
1. Theprivilegeisalsorequiredontheparentmanagedentity.
Privileges Required to Read Properties

Figure A2liststheprivilegesrequiredtoreadspecificmanagedobjectproperties. Table A-2. Privileges Required for Reading Object Properties
Object AlarmManager Property defaultExpression description AuthorizationManager privilegeList roleList description Privilege System.View System.View System.View System.View System.View
156
VMware, Inc.
Table A-2. Privileges Required for Reading Object Properties (Continued)

Object ComputeResource Property resourcePool host CustomFieldsManager CustomizationSpecManager field info encryptionKey Datacenter vmFolder hostFolder EventManager description latestEvent maxCollector Folder childType childEntity HostCpuSchedulerSystem HostDiagnosticSystem HostFirewallSystem HostMemoryManagerSystem HostNetworkSystem hyperThread activePartition firewallInfo consoleReservationInfo capabilities networkConfig networkInfo offloadCapabilities HostServiceSystem HostSnmpSystem HostStorageSystem serviceInfo snmpConfig fileSystemVolumeInfo storageDeviceInfo HostVMotionSystem netConfig ipConfig LicenseManager source sourceAvailable featureInfo ManagedEntity parent effectiveRole name PerformanceManager description historicalInterval perfCounter PropertyCollector ResourcePool ScheduledTaskManager filter owner scheduledTask description ServiceInstance serverClock capability Privilege System.View System.View System.View VirtualMachine.Provisioning.ReadCustSpecs System.View System.View System.View System.View System.View System.View System.View System.View Host.Config.HyperThreading Host.Config.Storage Host.Config.NetService Host.Config.Memory Host.Config.Network Host.Config.Network Host.Config.Network Host.Config.Network Host.Config.NetService Host.Config.Snmp Host.Config.Storage Host.Config.Storage Host.Config.Network Host.Config.Network Global.Licenses Global.Licenses Global.Licenses System.View System.View System.View System.View System.View System.View System.View System.View System.View System.View System.View System.View
VMware, Inc.
157
Table A-2. Privileges Required for Reading Object Properties (Continued)

Object SessionManager Property sessions currentSession message messageLocaleList supportedLocaleList defaultLocale TaskManager recentTask description maxCollector UserDirectory domainList Privilege Sessions.TerminateSession System.Anonymous System.View System.Anonymous System.Anonymous System.Anonymous System.View System.View System.View System.View
Privileges Defined for the Administrator Role

TheAdministratorroleasdefinedonavCenterServer4.0systemcontainsalltheprivilegeslistedinTable A3. Table A-3. Privileges Granted to the Administrator Role
Privilege Alarm.Acknowledge Alarm.Create Alarm.Delete Alarm.DisableActions Alarm.Edit Alarm.SetStatus Authorization.ModifyPermissions Authorization.ModifyRoles Authorization.ReassignRolePermissions Datacenter.Create Datacenter.Delete Datacenter.IpPoolConfig Datacenter.Move Datacenter.Rename Datastore.AllocateSpace Datastore.Browse Datastore.Delete Datastore.DeleteFile Datastore.FileManagement Datastore.Move Datastore.Rename DVPortgroup.Create DVPortgroup.Delete DVPortgroup.Modify DVPortgroup.PolicyOp Privilege Resource.AssignVAppToPool Resource.AssignVMToPool Resource.ColdMigrate Resource.CreatePool Resource.DeletePool Resource.EditPool Resource.HotMigrate Resource.MovePool Resource.QueryVMotion Resource.RenamePool ScheduledTask.Create ScheduledTask.Delete ScheduledTask.Edit ScheduledTask.Run Sessions.GlobalMessage Sessions.ImpersonateUser Sessions.TerminateSession Sessions.ValidateSession StorageViews.ConfigureService StorageViews.View System.Anonymous System.Read System.View Task.Create VApp.ApplicationConfig
158
VMware, Inc.
Table A-3. Privileges Granted to the Administrator Role (Continued)

Privilege DVPortgroup.ScopeOp DVSwitch.Create DVSwitch.Delete DVSwitch.HostOp DVSwitch.Modify DVSwitch.Move DVSwitch.PolicyOp DVSwitch.PortConfig DVSwitch.PortSetting DVSwitch.Vspan Extension.Register Extension.Unregister Extension.Update Folder.Create Folder.Delete Folder.Move Folder.Rename Global.CancelTask Global.CapacityPlanning Global.Diagnostics Global.DisableMethods Global.EnableMethods Global.GlobalTag Global.Health Global.Licenses Global.LogEvent Global.ManageCustomFields Global.Proxy Global.ScriptAction Global.ServiceManagers Global.SetCustomField Global.Settings Global.SystemTag Global.VCServer Host.Cim.CimInteraction Host.Config.AdvancedConfig Host.Config.AutoStart Host.Config.Connection Host.Config.DateTime Host.Config.Firmware Host.Config.HyperThreading
VMware, Inc.
Privilege VApp.AssignResourcePool VApp.AssignVApp VApp.AssignVM VApp.Clone VApp.Create VApp.Delete VApp.Export VApp.ExtractOvfEnvironment VApp.Import VApp.InstanceConfig VApp.Move VApp.PowerOff VApp.PowerOn VApp.Rename VApp.ResourceConfig VirtualMachine.Config.AddExistingDisk VirtualMachine.Config.AddNewDisk VirtualMachine.Config.AddRemoveDevice VirtualMachine.Config.AdvancedConfig VirtualMachine.Config.ChangeTracking VirtualMachine.Config.CPUCount VirtualMachine.Config.DiskExtend VirtualMachine.Config.DiskLease VirtualMachine.Config.EditDevice VirtualMachine.Config.HostUSBDevice VirtualMachine.Config.Memory VirtualMachine.Config.QueryUnownedFiles VirtualMachine.Config.RawDevice VirtualMachine.Config.RemoveDisk VirtualMachine.Config.Rename VirtualMachine.Config.ResetGuestInfo VirtualMachine.Config.Resource VirtualMachine.Config.Settings VirtualMachine.Config.SwapPlacement VirtualMachine.Config.UpgradeVirtualHardware VirtualMachine.Interact.AnswerQuestion VirtualMachine.Interact.Backup VirtualMachine.Interact.ConsoleInteract VirtualMachine.Interact.CreateScreenshot VirtualMachine.Interact.CreateSecondary VirtualMachine.Interact.DefragmentAllDisks
159
Table A-3. Privileges Granted to the Administrator Role (Continued)

Privilege Host.Config.Maintenance Host.Config.Memory Host.Config.NetService Host.Config.Network Host.Config.Patch Host.Config.PciPassthru Host.Config.Resources Host.Config.Settings Host.Config.Snmp Host.Config.Storage Host.Config.SystemManagement Host.Inventory.AddHostToCluster Host.Inventory.AddStandaloneHost Host.Inventory.CreateCluster Host.Inventory.DeleteCluster Host.Inventory.EditCluster Host.Inventory.MoveCluster Host.Inventory.MoveHost Host.Inventory.RemoveHostFromCluster Host.Inventory.RenameCluster Host.Local.CreateVM Host.Local.DeleteVM Host.Local.InstallAgent Host.Local.ManageUserGroups Host.Local.ReconfigVM Network.Assign Network.Config Network.Delete Network.Move Performance.ModifyIntervals Profile.Clear Profile.Create Profile.Delete Profile.Edit Profile.View Resource.ApplyRecommendation Privilege VirtualMachine.Interact.DeviceConnection VirtualMachine.Interact.DisableSecondary VirtualMachine.Interact.EnableSecondary VirtualMachine.Interact.MakePrimary VirtualMachine.Interact.PowerOff VirtualMachine.Interact.PowerOn VirtualMachine.Interact.Record VirtualMachine.Interact.Replay VirtualMachine.Interact.Reset VirtualMachine.Interact.SetCDMedia VirtualMachine.Interact.SetFloppyMedia VirtualMachine.Interact.Suspend VirtualMachine.Interact.TerminateFaultTolerantVM VirtualMachine.Interact.ToolsInstall VirtualMachine.Interact.TurnOffFaultTolerance VirtualMachine.Inventory.Create VirtualMachine.Inventory.Delete VirtualMachine.Inventory.Move VirtualMachine.Provisioning.Clone VirtualMachine.Provisioning.CloneTemplate VirtualMachine.Provisioning.CreateTemplateFromVM VirtualMachine.Provisioning.Customize VirtualMachine.Provisioning.DeployTemplate VirtualMachine.Provisioning.DiskRandomAccess VirtualMachine.Provisioning.DiskRandomRead VirtualMachine.Provisioning.GetVmFiles VirtualMachine.Provisioning.MarkAsTemplate VirtualMachine.Provisioning.MarkAsVM VirtualMachine.Provisioning.ModifyCustSpecs VirtualMachine.Provisioning.PromoteDisks VirtualMachine.Provisioning.PutVmFiles VirtualMachine.Provisioning.ReadCustSpecs VirtualMachine.State.CreateSnapshot VirtualMachine.State.RemoveSnapshot VirtualMachine.State.RenameSnapshot VirtualMachine.State.RevertToSnapshot
160
VMware, Inc.
Diagnostics and Troubleshooting
ThissectionprovidesinformationaboutusingtheDiagnosticManagerserviceinterfacetofacilitate troubleshooting.Thisappendixincludesthesetopics: BestPracticesforTroubleshootingonpage 161 OverviewofConfigurationFilesandLogFilesonpage 162 ModifyingtheLogLeveltoObtainDetailedInformationonpage 164 UnderstandingandUsingtheDiagnosticManageronpage 167
Best Practices for Troubleshooting

Approachtroubleshootingandproblemsolvingsystematically,andtakenotessoyoucantraceyoursteps. Followtheseindustrystandardguidelineswheneveryouneedtoresolveanissuewithyourclientapplication. Dontchangemorethanonethingatatime,anddocumenteachchangeanditsresult.Trytoisolatethe problem:Doesitseemtobelocal,totheclient?Anerrormessagegeneratedfromtheserver?Anetwork probleminbetweenclientandserver? Usetheappropriateloggingfacilitiesforyourprogramminglanguagetocaptureruntimeinformationfor theclientapplication.SeetheLog.csandLog.javafilesforC#andJavalogclassimplementations,as usedbythevariousSDKsampleapplications.Thesefilesarelocatedinthe\samplessubdirectoryofthe vSphereWebServicesSDK: C#clientloggingexample:\SDK\samples\DotNet\cs\ClientUtils\Log.cs Javaclientloggingexample:\SDK\samples\Axix\java\com\vmware\apputils\Log.java UsethetoolsprovidedbyVMwareforanalysisandtofacilitatedebugging.Thefollowingtoolsprovide accesstologginginformation.TheyrequireESXorvCenterServeradministratorprivileges. UsetheVMwarevSphereClient.ThevSphereClientprovidesagraphicaluserinterfacethatenables administratorstoexamineallESXandvCenterServerlogfile,includinglogfilesforvirtualmachines, changetheloglevelsettingsifnecessary.ThevSphereClientprovidesmenuselectionsforcreating reportsthatsummarizeconfigurationinformation,performance,andotherdetails,andforexporting diagnosticbundles.ThevSphereClientapplicationmaintainsitsownlocallogfiles. UsetheMOB.TheMOBprovidesdirectaccesstoliveruntimeserversideobjects.Youcanusethe MOBtodrilldownintothevariousobjectsandobtainpropertyvalues.SeeChapter 2,Usingthe ManagedObjectBrowsertoExploretheObjectModel,onpage 16foranoverviewoftheMOB. UsetheAPI.ThevSphereobjectmodelprovidesaDiagnosticManagerserviceinterfacethatenables youtoobtaininformationfromtheserverlogfiles,andtocreateadiagnosticbundlethatcontainsall systemlogfilesandallserverconfigurationinformation.ThevSphereClientandtheMOBprovide graphicalandwebbasedaccesstotheDiagnosticManager.
VMware, Inc.
161
Overview of Configuration Files and Log Files

ESXandvCenterServerbothhavevariousconfigurationfilesthatcontrolthebehaviorofthesystem.Most configurationfilesettingsaresetduringinstallationbutcanbemodifiedafterinstallation.Thelogfilescapture messagesgeneratedbythekernelandvarioussubsystemsandservices.BothESXandvCenterServerservices maintaintheirownlogfiles.Table B1listsvariouslogfilesorreports,theirlocationsandassociated configurationfiles. Table B-1. Server and System Logs Reference
Description ESXservicelog VirtualCenter Agentlog VirtualMachine KernelCorefile syslogdlog Log location /var/log/vmware/ /var/log/vmware/vpx/ /root/ Filename or names hostd.log [hostd-0.log, ...hostd-9.log] vpxa.log vmkernel-core.<date> vmkernel-log.<date> /var/log/ messages [messages.1,... messages.4] ServiceConsole Availabilityreport VMkernel Messages VMkernelAlerts andAvailability report VMkernelWarning /var/log/ /var/log/vmkernel /var/log/vmkernel vmkernel [vmkernel.1, ... vmkernel.8] syslog.conf, logrotate.conf syslog.conf, logrotate.conf syslog.conf, logrotate.conf vmkwarning [vmkwarning.1 ... 4 for history] vmware.log syslog.conf, logrotate.conf <vm_name>/<vm_name>.vmx syslog.conf, logrotate.conf, various other syslog.conf, logrotate.conf Configuration file config.xml
/var/log/
VirtualMachine logfile
vmfs/volume/<vm_name>
Fordevelopers,thefollowingarethemostrelevantlogfiles: hostd.log,whichcanbeusedassomethingofaSOAPmonitor(whensettotrivialoglevelasGenerating Logsonpage 166) vpxa.log(filelocatedonamanagedESXhostsystem,placedbythevCenterServer) vmware.log Inadditiontoviewinglogfilesinrealtime,usingthevSphereClient(Administration>SystemLogstab),you canalsogeneratereportsandcompletediagnosticbundles. TogenerateadiagnosticbundleusingthevSphereClient,selectFile>Export>ExportDiagnosticData. ForcompleteinformationaboutESXandvCenterServerconfigurationandsystemsadministration,seethe vSpheredocumentationlibrary,inparticular,thevSphereBasicSystemAdministrationmanual.
162
VMware, Inc.
Appendix B Diagnostics and Troubleshooting
ESX Log File

TheESXlog(hostd.log)capturesinformationofvaryingspecificityanddetail,dependingontheloglevel. Eachrequesttotheserverislogged. Figure B-1. ESX Log (hostd.log) Displayed using vSphere Client
TherawtextformofanESX(hostd)logfileisshowninExample B1. Example B-1. Sample ESX Log (hostd.log) File Data
... [2008-05-07 09:50:04.857 'SOAP' 2260 trivia] Received soap response from [TCP:myservername.vmware.com:443]: GetInterfaceVersion [2008-05-07 09:50:04.857 'ClientConnection' 2260 info] UFAD interface version is vmware-converter-4.0.0 [2008-05-07 09:50:04.857 'SOAP' 2260 trivia] Sending soap request to [TCP:myservername.eng.vmware.com:443]: logout [2008-05-07 09:50:04.857 'ProxySvc Req00588' 3136 trivia] Client HTTP stream read error [2008-05-07 09:50:04.872 'ProxySvc Req00612' 3136 trivia] Request header: POST /vmc/sdk HTTP/1.1 User-Agent: VMware-client Content-Length: 435 Content-Type: text/xml; charset=utf-8 Cookie: vmware_soap_session="F127B435-56C7-4580-BAC4-3034DA1E67B6"; $Path=/ Host: myservername.vmware.com
[2008-05-07 [2008-05-07 [2008-05-07 [2008-05-07
09:50:04.872 'ProxySvc Req00588' 3816 trivia] Closed 09:50:08.450 'App' 3560 verbose] [VpxdHeartbeat] Invalid heartbeat from 10.17.218.46 09:50:10.013 'App' 3560 verbose] [VpxdHeartbeat] Queuing 10.17.218.45:829 (host-55) 09:50:10.013 'App' 1928 verbose] [HeartbeatHandler] 50208862-2752-d94c-2a73-fa2ec9e38ecc:829 (host-55)
Virtual Machine Log Files

Eachvirtualmachinerunningonahostsystemhasitsownlogfile,vmware.log,storedontheVMFSvolume. Bydefault,thelogfileisrotatedwheneverthevirtualmachineispoweredon,butfilerotationisconfigurable. Herearesomepointstonoteaboutvirtualmachinelogs: ESXmaintainssixlogfilesthatrotateateachpowercycle(thedefault)orataconfiguredfilesize. ESXcanbeconfiguredtomaintainaspecificnumberoflogfiles.Whenthelimitisreached,theoldestfile isautomaticallydeleted. VMwarerecommendsalogfilesizeof500KB. MessagesgeneratedbyVMwareToolsmessagesareloggedseparately.
VMware, Inc.
163
Example B-2. VMkernel Availability Report

Availability Report for <servername> Feb 27, 2008 - May 7, 2008 Availability: 99.949% Total time: 69 days, 15 hours Uptime: 69 days, 14 hours Downtime: 51 minutes Note: Downtime is any time the system isn't capable of running Virtual Machines. This includes reboots, crashes, configuration and running linux Downtime Analysis: 0.1% (51 minutes) downtime caused by: 13.1% (6 minutes) scheduled downtime 86.9% (44 minutes) unscheduled downtime Reasons for scheduled downtime: 84.9% server rebooting (1 instance) 9.4% VMkernel unloaded (1 instance) 5.7% server booting (3 instances) Reasons for unscheduled downtime: 100.0% unknown (powerfail / reset?) (1 instance) Stats: Current uptime: 8 days, 11 hours Longest uptime: 61 days, 2 hours Shortest uptime: 38 minutes Average uptime: 23 days, 4 hours Longest downtime: 44 minutes Shortest downtime: 7 seconds Average downtime: 8 minutes Maximum VMs Sampled: 1 Average VMs Sampled: 0.94 Server Information: Number of CPUs: 4 logical 4 cores 2 packages, Intel(R) Xeon(R) CPU 5150 @ 2.66GHz Installed Memory: 2096416 kB Current Build: 78591 Report generated Wed May 7 04:02:04 PDT 2008
vCenter Server Log Files

vCenterServerlogfilesarelocatedbydefaultintheDocumentsandSettingssubdirectoryoftheWindows accountusedtoinstallthesoftware.Forexample:
C:\Documents and Settings\Administrator\Local Settings\Application Data\VMware\
IMPORTANTVMwarerecommendscreatingauseraccountespeciallyforvCenterServersystems. Bydefault,systemfilesandfoldersarenotvisibleintheWindowsExplorerofFileManager.TolocateVMware logfiles,youmightneedtochangethesetting.FromtheWindowsExplorer,selectTools>FolderOptions> ViewpropertiespageandselecttheShowhiddenfilesandfoldersoption.
Modifying the Log Level to Obtain Detailed Information

TheservicerunningonESXsystemsthatgeneratesloginformationiscalledhostd(hostdaemon).Thedefault loglevelsettingforhostdinfo(Table B2).ThevCenterServerlogsarecontrolledbysettingsthroughthe vSphereClient.Thissectionprovidesinformationaboutchangingloglevelsfromthedefaults.
164
VMware, Inc.
Log Level Settings

Theamountofinformationcapturedinthelogfilesvaries,dependingonthelevelsetting. Table B-2. Log Level Settings
Log Level Setting None Error Warning Info Verbose Trivia Description Disableslogging. Logginglimitedtoerrormessagesonly. Errormessagespluswarningmessagesarelogged. DefaultsettingforloggingonESXandvCenterServersystems.Errors,warnings,plusinformational messagesaboutnormaloperationsarelogged.Acceptableforproductionenvironments. Canfacilitatetroubleshootinganddebugging.Notrecommendedforproductionenvironments. Extendedverboselogging.Providescompletedetail,includingcontentofallSOAPmessages betweenclientandserver.SeeExample B5,SOAPMessageContainedinGeneratedESXLog,on page 167.Usefordebuggingandtofacilitateclientapplicationdevelopmentonly.Not recommendedforproductionenvironments.
Setting the Log Level on ESX Systems

TheESXlogsarecontrolledbyasettingintheconfig.xmlfile,locatedinthe/etc/vmware/hostdsubdirectory ofanESXsystem(Example B3). Example B-3. ESX Config.xml File Excerpt Showing Default Log Level Setting
<config> <vmacore> <threadPool> <MaxFdsPerThread>2048</MaxFdsPerThread> </threadPool> <ssl> <doVersionCheck> false </doVersionCheck> </ssl> <vmdb> <maxConnectionCount>8</maxConnectionCount> </vmdb> <loadPlugins> true </loadPlugins> </vmacore> <workingDir> /var/log/vmware/ </workingDir> <log> <directory>/var/log/vmware/</directory> <name>hostd</name> <outputToConsole>false</outputToConsole> <level>info</level> </log> ,,, </config>
Bydefault,theloglevelsettingisinfo.Ifyourunintoissuesduringdevelopment,youcansettheloglevelto triviatoobtainSOAPmessagecontenttouseindebugging. YoucanalsousethistechniquetoanalyzeanoperationinvokedusingthehevSphereClientandthenread throughtheextensivelogfilestoextrapolatehowyoumightaccomplishthesametasksinyourowncode. NOTETheprocessdescribedbelowrequiresasystemrestart. To change the log level in config.xml for hostd 1 2 ConnecttoESXusingputtyorothersecureshell. Navigatetothelocationoftheconfig.xmlfile:
cd /etc/vmware/hostd
VMware, Inc.
165
Usevioreditorofyourchoicetoopentheconfig.xmlfile:
vi config.xml
Theconfig.xmlfileopensforediting(Example B3). 4 Scrollthroughthefiletothe<log>element.Forexample:

<log> <directory>/var/log/vmware/</directory> <name>hostd</name> <outputToConsole>false</outputToConsole> <level>info</level> </log>
5 6 7
Change<level>info</level>to<level>trivia</level>. Saveandclosethefile. Navigatetotheinit.ddirectory:

cd /etc/init.d
Restartthehostagent:
./mgmt-vmware restart
Aftertheservicerestarts,thenewloglevelisineffect.Example B4showstheentireprocess. Example B-4. Editing the ESX Configuration File and Restarting the Server
login as: root root@sdkpubslab-01.eng.vmware.com's password: Last login: Tue May 6 03:40:58 2008 from 10.16.250.244 [root@sdkpubslab-01 root]# cd /etc/vmware/hostd [root@sdkpubslab-01 hostd]# vi config.xml ... [root@sdkpubslab-01 hostd]# cd /etc/init.d [root@sdkpubslab-01 init.d]# ./mgmt-vmware restart Stopping VMware ESX Management services: VMware ESX Host Agent Watchdog [ OK VMware ESX Host Agent [ OK Starting VMware ESX Management services: VMware ESX Host Agent (background) [ OK Availability report startup (background) [root@sdkpubslab-01 init.d]#
] ] ] [
OK
Generating Logs
IfyouareconnectedtoESX,youcanusethetailcommandtoexplicitlycreatealogfilethatcapturesthe completedetailofanyactionsthatfollow.Forexample,youcanusethevSphereClienttocreateanewvirtual machineandthenusethecontentfromthelogasamodelforhowtocreateyourowncode. To start the logging process and capture content to a file 1 Navigatetothelocationofthehostd.logfile:
cd /var/log/vmware
Runthetailcommand(startscapturingnewlogdatafromtheendofthefile),passingafilenameinwhich tocaptureoutput:
tail -f hostd.log > yourfilenamehere
UsethevSphereClienttoperformwhateveractionyouarehavingdifficultymodelinginyourowncode. Forexample,createanewvirtualmachine.Aftertheoperationcompletes,stopthetailprocessby entering:

<ctrl><c>
166
VMware, Inc.
ThefilecontainstheSOAPmessagecontentandotherlogmessagessentandreceivedbyhostdduringthe execution.Example B5showsanexcerptofaSOAPmessage(hostd)associatedwithcreatinganewvirtual machine. Example B-5. SOAP Message Contained in Generated ESX Log
<soap:Body> <CreateVM_Task xmlns="urn:internalvim25"> <_this type="Folder">ha-folder-vm</_this> <config> <name>TestVM_06</name> <version>vmx-04</version> <guestId>rhel3_64Guest</guestId> <alternateGuestName>Red Hat Enterprise Linux 3 (64-bit)</alternateGuestName> <files> <vmPathName>[sdkpubslab-01:storage1]</vmPathName> </files> <tools> <afterPowerOn>true</afterPowerOn> <afterResume>true</afterResume> <beforeGuestStandby>true</beforeGuestStandby> <beforeGuestShutdown>true</beforeGuestShutdown> <beforeGuestReboot>true</beforeGuestReboot> </tools> <numCPUs>1</numCPUs> <memoryMB>384</memoryMB> ... </config> <pool type="ResourcePool">ha-root-pool</pool> </CreateVM_Task> ...
Besuretochangetheloglevelbacktoinfoafterobtainingtheinformationyouneedfromthelogfile.
Setting the Log Level on vCenter Server System

TochangeloglevelsettingsonvCenterServer,youmustusethevSphereClient.ConnecttothevCenterServer instance. To set logging level for vCenter Server using the VMware vSphere Client 1 2 ChooseAdministrationandclickServerSettings>LoggingOptions. ChooseTriviafromthepopupmenuandclickOK.
Understanding and Using the DiagnosticManager

ThevSphereAPIprovidesaccesstotheDiagnosticManager,theserviceinterfaceforobtaininginformation fromthelogfilesandforgeneratingdiagnosticbundles.Thelogsarepopulatedbasedonconfiguration settings,suchasinfo,trivia,andsoon.SeeLogLevelSettingsonpage 165fordetails. TheDiagnosticManagerisasingletonmanagedobjectthatworksservicewide,ratherthanonapersession basis.TheDiagnosticManagerhasnoproperties,butprovidesoperationsforobtaininginformationabout thelogsandhowtheyhavebeendefined,andforinitiatingtheprocessofgeneratingadiagnosticbundlethat canbesenttoVMwaresupportforanalysis.
VMware, Inc.
167
Figure B2showsaUMLclassdiagramforDiagnosticManager.TheDiagnosticManagerisavailableon bothESXandvCenterServersystems. Figure B-2. DiagnosticManager Managed Object and Associated Data Objects
AsshowninFigure B2,thethreeoperationsavailablethroughDiagnosticManagerare: BrowseDiagnosticLog GenerateLogBundleTask QueryDescriptions SeethevSphereAPIReferenceforcompletedocumentation. Thecreatorofthelogisthesystemorsubsystemthatcontrolsthespecificlog.Forexample,hostdandvpxa aretwoexamplesoflogcreators. ThecreatorvalueispopulatedfromtheDiagnosticManagerLogCreatorenumeration.Table B3listsall stringvaluescurrentlyavailablefromtheDiagnosticManagerLogCreatorenumerationthatcanpopulate thecreatorpropertyoftheDiagnosticManagerLogDescriptordataobject. Table B-3. DiagnosticManagerLogCreator Enumeration
Name hostd install recordLog serverd vpxa vpxClient vpxd Description Hostagent Installation SystemRecordLog Hostserveragent VirtualCenteragent Virtualinfrastructureclient VirtualCenterservice
Table B-4. ESX Sample DiagnosticManager Log Descriptor Values

creator hostd hostd hostd hostd file name /var/log/vmware/hostd.log /var/log/messages /var/log/vmkernel /var/log/vmksummary.txt format plain plain plain plain info.label ESXLog ESXLog ESXLog ESXLog info.summary ESXloginplain format ESXloginplain format ESXloginplain format ESXloginplain format key hostd messages vmkernel vmksummary mime type text/plain text/plain text/plain text/plain
168
VMware, Inc.
Table B-4. ESX Sample DiagnosticManager Log Descriptor Values (Continued)

creator hostd vpxa file name /var/log/vmkwarning /var/log/vmware/vpx/vpxa .log format plain plain info.label ESXLog VirtualCenter AgentLog info.summary ESXloginplain format VirtualCenter agentlogin plainformat key vmkwarning vpxa mime type text/plain text/plain
Using the MOB to Explore the DiagnosticManager

YoucanaccesstheDiagnosticManagerdirectlyfromtheESXorvCenterServerinstanceusingtheMOB.See NavigatingtheObjectModelintheMOBonpage 17forinformationaboutusingtheMOBtonavigateto theServiceContentdataobject,ifnecessary. IntheServiceContentdataobject,clickthelink(ha-diagnosticmanagerorDiagMgr)intheValuecolumn forthediagnosticManagerproperty,tonavigatetotheDiagnosticManagerforthesystem. ThelinknameisthemanagedobjectIDforthemanagedobjectreference.ThemanagedobjectIDnamevaries dependingonwhetheryouareaccessingavCenterServerorESXsystem: ForESX,ha-diagnosticsmanageristhemanagedobjectID. ForvCenterServer,DiagMgristypicallythemanagedobjectID. ClickthelinktothereferencetodisplaythemanagedobjectreferencetotheDiagnosticManagerintheMOB (Figure B3).DiagnosticManagerprovidesthreeoperationsthatenableyoutoobtaininformationaboutthe descriptionscurrentlyavailableinthelogfileandlogfilecontent. Figure B-3. Managed Object Reference to DiagnosticManager
Figure B3showstheDiagnosticManagerforavCenterServerinstance. ThevCenterServerDiagnosticManagertracksmultipleESXhostsystems,soyoucanusethe QueryDescriptionsoperationtoreturnthenamesofkeysusedforallhosts.Fromthisarray,selectthekey forthehostfromwhichyouwanttoobtainthelogfile(Figure B4).
VMware, Inc.
169
Figure B-4. Using the MOB to Invoke DiagnosticManager Operations
WhenyouclicktheInvokeMethodlink,thecontentsofthelogfilefortheselectedhostarereturnedbythe vCenterServersystem(Figure B5).ThecontentsarereturnedasastringarrayforthelineTextpropertyof DiagnosticManagerLogHeader. ThestringarrayreturnedthroughtheMOBinthiswayisthecontentofthelogfile.Thecontentcontainedin thelogfileisthesamecontentthatisavailablethroughthefollowingothermechanisms: DisplayedinthevSphereClient IncludedintheadiagnosticbundlecreatedthroughtheGenerateLogBundles_Task Availableinthehostd.log Returnedtoaclientapplicationthatyouwrite Figure B-5. DiagnosticManager Operations Available Through the MOB
170
VMware, Inc.
ThevSphereClientprovidesgraphicaluserinterfaceaccesstothesesameoperations.Example B6showsthe contentofalogfilewhentheloglevelissettoverbose. Example B-6. Sample Verbose Log File Data
...[2008-05-06 09:44:42.005 'TaskManager' 15227824 info] Task Created : haTask-ha-folder-vm-vim.Folder.createVm-755 [2008-05-06 09:44:42.005 'PropertyJournal' 19266480 verbose] PropertyJournalImpl::HasChanged: Overflow [N5Vmomi19PropertyJournalImplE:0xbb3cac0] recentTask ...'vm:/vmfs/volumes/47c5b0d6-16d11128-a260-0019b9c4369f/TestVM_05/TestVM_05.vmx' 15227824 verbose] Adding task: haTask-ha-folder-vm-vim.Folder.createVm-755 [2008-05-06 09:44:42.196 'ha-host' 15227824 verbose] ModeMgr::Begin: op = normal, current = normal, count = 1 [2008-05-06 09:44:42.201 'ha-eventmgr' 15227824 info] Event 17 : Creating TestVM_05 on host sdkpubslab-01.eng.vmware.com in ha-datacenter [2008-05-06 09:44:42.218 'HostsvcPlugin' 15227824 verbose] CreateEntry '112' [2008-05-06 09:44:42.222 'ResourcePool ha-root-pool' 15227824 verbose] Added child 112 to pool [2008-05-06 09:44:42.222 'Vmsvc' 15227824 verbose] Create VM initiated [112]: /vmfs/volumes/47c5b0d6-16d11128-a260-0019b9c4369f/TestVM_05/TestVM_05.vmx...
Table B5liststheDiagnosticManagerLogDescriptorobjectpropertiesandvalues.AllfilesareVCenter Serverlogsinplainformat. Table B-5. vCenter Server DiagnosticManagerLogDescriptor Values

creator vpxd vpxd vpxd vpxd vpxd vpxd vpxd vpxd vpxd vpxd vpxd file name vpxd-0.log vpxd-1.log vpxd-2.log vpxd-3.log vpxd-4.log vpxd-5.log vpxd-6.log vpxd-7.log vpxd-8.log vpxd-9.log vpxd-index format plain plain plain plain plain plain plain plain plain plain plain info.label VirtualCenter ServerLog VirtualCenter ServerLog VirtualCenter ServerLog VirtualCenter ServerLog VirtualCenter ServerLog VirtualCenter ServerLog VirtualCenter ServerLog VirtualCenter ServerLog VirtualCenter ServerLog VirtualCenter ServerLog VirtualCenter ServerLog key vpxd:vpxd-0.log vpxd:vpxd-1.log vpxd:vpxd-2.log vpxd:vpxd-3.log vpxd:vpxd-4.log vpxd:vpxd-5.log vpxd:vpxd-6.log vpxd:vpxd-7.log vpxd:vpxd-8.log vpxd:vpxd-9.log vpxd:vpxd-index mime type text/plain text/plain text/plain text/plain text/plain text/plain text/plain text/plain text/plain text/plain text/plain
Generating Diagnostic Bundles

Typically,diagnosticbundlesaregeneratedattherequestofVMwaretechnicalsupport,bycustomershaving problems.However,thesediagnosticbundlescanalsoprovideaquickwayfordeveloperstoobtainall configurationfilesandlogfilesinacompletepackage. Thegeneratedcompressedfilesarepackagedinafilehavingthefollowingpattern:
<fqdn-hostname>-esxsupport-yyyy-mm-dd@hh-mm-ss.tgz
VMware, Inc.
171
To export diagnostic data using the vSphere Client 1 2 LaunchthevSphereClientandconnecttotheESXorvCenterServersystem. SelectAdministration>ExportDiagnosticData. ForvCenterServer,youcanfilterforspecifichostswhoselogsyouwanttoexportandthelocation forstoringthelogfiles. ForESXhostsystems,youcanspecifythelocationforthebundle. 3 ClickOK.
To collect ESX VMkernel files IftheVMkernelfails,errormessagestypicallydisplaybriefly,andthenthevirtualmachinereboots. IfyouspecifiedVMwarecoredumppartitionaspartofyourvirtualmachineconfiguration,theVMkernelalso generatesacoredumpanderrorlog. Inrarecircumstances,veryseriousVMkernelproblemscanfreezetheserverwithoutraisingerrormessages ordumpingthesystemcore. To use the command line to collect ESX log files 1 2 3 UseputtyorotherSSHtooltoconnecttotheserviceconsole. Navigatetothe/usr/binsubdirectory. Runthe vm-supportscript: /usr/bin/vm-support 4 ThisscriptcollectsallrelevantESX3systemlogfiles,configurationfiles,andotherserverdetailsintoa compressedfile(thediagnosticbundle)whosenameincludesthedateandtime.
ToobtainamanagedobjectreferencetotheDiagnosticManager,firstobtainamanagedobjectreferenceto ServiceContent.EachServiceContentdataobjecthasadiagnosticManagerproperty,whichisdefined asamanagedobjectreferencetoaninstanceofDiagnosticManagerspecificforthesession.
172
VMware, Inc.
Deploying Client Applications
Thisappendixexplainshowtodeployclientapplications.Itincludesthesetopics: UnderstandingtheClientApplicationDeploymentModelonpage 173 CredentialStoreAdministrationToolforNonInteractiveClientsonpage 173
Understanding the Client Application Deployment Model

ThevSphereWebServicesSDKincludesWSDLfilesandothersoftwareartifactsthatyoucanusetodevelop clientapplications.IncludedwiththeSDKareprecompiledclientsidelibrariescontainingtheproxycode neededtointeractwiththeWebservicesAPI. TheVMwarevSphereservers(ESX/ESXi,vCenterServer,forexample)targetedbyanyclientapplicationsyou developmustbeappropriatelylicensed.However,youdonotneedanyspeciallicensefromVMwaretocreate softwareusingtheVMwarevSphereWebServicesSDKforsuchenvironments. DeployyourapplicationsasyouwouldanyWebservicesbasedclient.
Credential Store Administration Tool for Non-Interactive Clients

ThevSphereWebServicesSDKincludesaJavaadministrationtool(commandlineinterface)thatcanbeused byVMwarevSphereadministratorstomanagethecredentialstoreforanyclientapplicationsoragents.Ifyou haveanapplicationthatstartsup,automaticallyaWindowsorotherservice,forexample,oracronjobthat launchesanapplicationthatmustconnecttoESX/ESXiorvCenterServer,youcanusetheCredentialStore AdministrationTooltostoretheuseraccountanditspasswordlocally. Forexample,sayyouareusingVCB(VMwareCentralBackup)inyourenvironment,andyouwantto configureacronjobtoinitiatethebackupprocesseachnightat3:00a.m.tolauncheachnight ThetooliscontainedintheunpackedvSphereWebServicesSDKdownloadfileatthislocation:
%SDKHOME%\samples\Axis\java\com\vmware\security\credstore\CredentialStoreAdmin.java
Guidelines for Using the CredentialStoreAdmin Tool

TheCredentialStoreAdmintoolprovidescompleteaccesstothecredentialstorebackingfileonthelocal machine.ThisistheactualtextbasedXMLfilethatiscreated,opened,manipulated,andclosedbythe interfacesandimplementationsprovidedinthevariouscredstoreclassesinthevSphereWebServicesSDK. IMPORTANTNeverusetheCredentialStoreAdmintooltostoretherootorAdministratoruseraccountand passwordinthecredentialstore.Createspecialuseraccountsforanyautomatedoragentsoftwareandcreate specialroles(oruseappropriatelyprivileged,nonAdministratorroles)toapplytotheseuseraccounts. Accountscreatedexpresslyforthepurposeofrunningautomatedapplicationsoragentsaretheonlytypeof accountthatshouldgenerallybestoredinthecredentialstore.
VMware, Inc.
173
BeforeusingtheCredentialStoreAdmintool,besureyoufullyunderstanditsbehavior. CAUTIONTheCredentialStoreAdmintoolcandisplayuseraccountsandpasswordsstoredinthecredential storeincleartext,attheconsoleprompt.Donotallowthistooltobeusedbynonadministratorusers.Keep thistoolinapasswordprotectedsubdirectorythatonlyyouorappropriateadministratorcanaccess.
CredentialStoreAdmin Tool and the Backing File

TheCredentialStoreAdmintoolletsyouaccessthelocalcredentialstorebackingfile.Thebackingfileisan XMLformattedtextfilecontaininghosts(targetservers)andassociatedusernames,withtheirrespective passwords(Example C1). Example C-1. Populated Credential Store Backing File
<?xml version="1.0" encoding="UTF-8" standalone="no" ?> - <viCredentials> <version>1.0</version> - <passwordEntry> <host>myTestServer</host> <username>root</username> <password>8Ofo8/bh8IPLnlD/YpB+mYV/jhIYm4V4+ulVwSVgK2BGPPV3U65i5IC2xxOYVYVnQ+2sgbzdvnT4brs +pu+HhqkYdrXuyCs3NceT5mrrTPP5m0XEo1ZsZEup6t1PSVcO53ddrN+dnZqEUqNA8FFDhV4B OKTkBAGQhCnRb0GBA0c=</password> </passwordEntry> - <passwordEntry> <host>192.168.25.14></host> <username>user94</username> <password>ChsJCQ0eS0pIeqB+6K6uv/gvaxqmzJJvL0ltudLnqBOz+2WQGvAadQ9ZS6gdGg6jWGTTOuoS+OE1Zsx A37dv1MqRpvabWzAK0YQIPwysKLijkF9Nc7yP8/GQCQBL1nBXOSZLk4HTemZMOHzZE7ojMqu4 l/GUI1PfS9zNs4m44dY=</password> </passwordEntry> </viCredentials>
ThehostsinthefilecanbespecifiedbyservernameorbyIPaddressbothIPv4andIPv6aresupported.At runtime,whenyoureaccessingthecredentialstoreandtryingtoobtainthepasswordfortheusername associatedwiththehost,youmustspecifythehostinthesameformasitisstoredinthebacking filehostnameorIPaddress. Forexample,ifyoustorebyhostname,youmustenterthehostnameintheapplication.OrifyouuseIP address,youmustusethesamestyleofIPaddressasisinthefile(IPv6,IPv4). Table C-1. Specify the Server by Hostname or by IP Address
Host prodserver.mycompany.com prodserver IPv4 192.168.28.124 IPv6 2001:0db8:3c4d:0015:0000:0000:abcd:ef12
Youdonotneedtousefullyqualifieddomainnames(FQDN)ifyourlocalsystemcanfindtheserver.Ifyou douseFQDNtospecifyservernames,youmustusethesamenameswithyourapplicationcodeaswiththe CredentialStoreAdmintool. Passwordsareobfuscated(Example C1)butnotencrypted,soitsimportantthatuserskeeptheircredential storefilesprotectedontheirlocalfilesystems. CAUTIONNeveremailthecredentialstorebackingfileunlessyouencryptthefile.Thecredentialstoreclient APIsdonotencryptthecontentsofthisfile. Furthermore,theCredentialStoreAdmintooldisplaysthepasswordincleartext,notinitsobfuscatedform, sobecarefulwhenusingthetooltodisplaypasswords. TheJavaruntime(JRE)mustbeinlocalpathtorunthetool.
174
VMware, Inc.
Appendix C Deploying Client Applications
PerlandPowerShellversionsofthiscommandlinetoolarealsoavailablewiththeVMwarevSphereSDKfor PerlandwiththeVMwarevSpherePowerCLI. To run the Java Credential Store Administration Tool on a client machine 1 InstalltheCredentialStoreAdmintoolfromthevSphereWebServicesSDKintoadirectoryontheclient machinethatwillruntheagentsoftware. Installingthetoolmeanstocopythecontentsofthe\credstoresubdirectorytoadirectoryonthelocal machineandsetthepathsothattheJavaruntimecanloadtheclassandrunit. 2 3 4 Ontheclientmachine,openacommandprompt. NavigatetothesubdirectorycontainingtheCredentialStoreadministrationtool. LaunchtheCredentialStoreAdmintoolfromacommandpromptasfollows:
java com.vmware.security.credstore.CredentialStoreAdmin add -h <servername> -u <username> -p <password>
Table C2listsallthecommandsavailabletotheCredentialStoreAdmintool. Inadditiontotheargumentslistedinthetable,eachofthesecommandscantakethefargument,tospecify thenameofthebackingfile.UsethefoptiontocreateaCredentialStorebackingfileusinganameofyour choice,includingdirectorypath. Ifyoucreateacredentialstoreusingacustomfilename,youmustpassthefilenametothecommandwhen youinvokeit. Table C-2. CredentialStoreAdmin Command Summary
Command clear add ~ -h -u -p get -h -u help <command> Arguments ~ host username password host username Forthespecifiedhostnameandusername,obtainsthepasswordfromthe credentialstore. Displaysatthecommandpromptthesamebasictextascapturedinthis table.Currently,enteringacommandnamewiththehelpcommandhasno effectontheoutputofthehelpcommand. Displaysatthecommandpromptthecontentsofthecredentialstore. Withoutanyarguments,displaysallhostnameswitheachuseraccount. Usethe--showpwargumenttodisplaythepasswordsincleartext.(Be mindfulofthesecurityissuesassociatedwithdoingthis.)Theshowpw argumentusestwodashes. Usethe-hargumentwiththespecifichostnametoobtaintheuser namestoredinthecredentialstoreforthathost.Enterthehostnamein thesame remove -h -u host username Forthespecifiedhostnameandusername,deletestheusernameand passwordfromthecredentialstore. Forthespecifiedhostname,addstothelocalcredentialstorethespecified useraccountandpassword. Description
list
--showpw -h host
EachtimeaclientapplicationortheCredentialStoreAdmintoolitselfaccessesthecredentialstorewhether toreaditscontentsorwritenewdatatoitthebackingfileislocked.Afterthereadorwritecompletes,the fileisstoredagaintodisk.Thisensuresthatreadersandwritersbothhaveacompletefiletoworkwithand donotstartreadingfromamidpoint,orcorruptthedatainthefilebywritingtoafilethatsopenforaread.
VMware, Inc.
175
176
VMware, Inc.
Index
A
access, limiting 70 accessing property values 49 accessor methods 52 accounts 70 Action object 142, 146 Active Directory 37 AddAuthorizationRole operation 42 Administrator role 158 Alarm managed object 137, 138 AlarmAction object 141, 142 AlarmExpression object 139, 140 AlarmManager object 137 alarms 137, 138 actions 146 deleting 142 disabling 142 list 138 samples 137 AlarmSpec object 139 properties 139 API version supported 64 applying permission to an entity 71 asynchronous applications 46 authenticating users 39 authentication 33 authorization 33 AuthorizationManager limiting access 70 managed object 40 operations 41, 43 overview 39 automating client application login 67
B
backing file 174
C
C# datatypes,map to XML 53 helper classes 65 cancelling tasks 88 changing permissions 43 CheckForUpdates operation 79 checking migration validity 126
client applications characteristics 46 deploying 173 pattern 59 patterns 59 client data, synchronizing 78 client library 51 client-side proxy code 51 cloning virtual machines 125 closing server connection 60 collection performance 79 complex content 55 config.xml file 165 configuration files 162, 166 configured storage 107 connection object 59 container object 26 cookie 63 counter groups 112 CreateAlarm operation 138 CreateFilter 57, 77 CreateUser sample 69 creating a VirtualMachineConfigSpec 94 creating custom events 132 creating datastores 108 creating new user accounts 70 creating roles 41 creating ScheduledTask object 144 creating snapshots 97 creating templates 124 creating UserAccount objects 71 creating virtual machines 93 credential store 69 administration tool 173 backing file 68, 174 backing file structure 68 client API libraries 67 client API methods 68 CreateUser sample 69 default locations 70 file format 68 introduction 67 least privilege 69 SimpleAgent sample 69
VMware, Inc.
177
CredentialStoreAdmin commands 175 tool 70
D
Datacenter managed object type 26 Datastore managed object 102 datastores configuration 110 creating 108 datatypes for MOB usage 58 default log level setting 165 deleting alarms 142 deleting HistoryCollector 135 deleting permissions 43 deleting roles 41 deleting scheduled tasks 148 deploying client applications 173 deploying virtual machines 124 deployment model 173 deployment sample 120 deprecated items 51 diagnostic bundles 171 DiagnosticManager 167 log descriptor values 168 managed object 168 operations 170 operations available through the MOB 170 DiagnosticManagerLogCreator enumeration 168 diagnostics 161 disabling alarms 142 distributed virtual switch 12
EventDescriptionEventDetail data object type 131 EventHistoryCollector 133 EventManager object 129, 130 samples 129 events creating 132 exported from ESX/ESXi system 92 formatting messages 130 management 129 message content 131 examples generated accessor and mutator methods 52 returned object displayed in MOB 54
F
file access 34 file format, credential store 68 Folder object 27, 30 folder object 26 format for iSCSI names 105
G
generated accessor and mutator methods 52 generating logs 166 granting privileges 42 group permissions 44 groups 37 management 36 membership 44 permissions 44
H
helper classes 65 C#
E
enabling single sign-on support 37 Escape characters 53 ESX/ESXi config.xml file 165 configuration file 166 events 92 inventory 30 log 163 log file 163 log level 165 PerfInterval 115 sample log 163 user model 35 Event object 129, 130 objects 92, 130, 131 samples 129 EventAlarmExpression 140
sample applications
java
65 65
sample applications
sample applications 64 historical intervals 117 HistoryCollector 133 appending objects 135 deleting 135 operations 133 overview 133 host name 174 host provisioning 12 hostd.log 163 HostDatastoreSystem creation operations 108 modification operations 110 query operations 107
178
VMware, Inc.
Index
HostDatastoreSystem object 106 HostDatastoreSystem operations 106 HostHostBusAdapter data object 102, 106 HostLocalAccountManager object 35 operations 36 HostNasVolumeSpec data object 109 HostScsiDiskPartition data object 109 HostStorageSystem object 102 operations 103 HostSystem object 106 HostVmfsSpec data object 109 HTTP-based file access 34
settings 165 vCenter Server system 167 login 67 logs 163 generating 166 server 162 system 162
M
managed object browser 17 managed object references 24 managed objects 101 handling local user accounts 38 ManagedEntity 26 descendents 13 ManagedEntity subtypes 25 permission objects 29 ManagedObjectReference default methods 52 diagram 46 Type property 46 valid string values 52 XML schema 55 managing storage 99 mapping WSDL to client-side proxy code 51 mapping XML datatypes to java and C# datatypes 53 maximum allowed resource usage 94 messages (event), formatting 130 MetricAlarmExpression data object 141 Microsoft Active Directory 37 MigrateVM_Task operation 126 migrating virtual machines 125, 126 minimum available resources 94 mo_ref 22 MOB 17, 54, 58 invoking DiagnosticManager operations 170 invoking operations 53 navigating object model 17 passing complex datatypes to operations 55 passing primitive datatypes to operations 54 monitoring performance 111 MOR (managed object reference, abbreviation for) 22 MOR>ManagedObject 22 MoRef 22 multiple API versions 63 mutator methods 52
I
Import statements 51 includes 51 intervals 117 inventory 25, 26, 30 introduction 30 permissions 29 privileges 28 root folders 27 invoking operations through MOB 53 IP address 174 iSCSI names 105 overview 101
J
java datatypes, map to XML 53 helper classes 65 TaskList application 90
L
limit 94 limiting access 70 local storage 100 local user accounts 38 locale, setting 60 localization 60 log descriptor values 168 log files overview 162 sample 171 vCenter Server 164 virtual machines 163 log level default settings 165 ESX system 165 modifying 164
VMware, Inc.
N
NAS storage overview 100 nested data objects 57 nested properties 50, 52 nested TraversalSpec 76 new features 12
179
O
ObjectContent data object 76, 77 ObjectSpec definition as XML Schema 57 obtaining statistics 115 operations HistoryCollector 133 passing complex datatypes 55 passing primitive datatypes 54 privileges required 149 required privileges for 149 optimizing query response time 118
P
passing complex datatypes to operations 55 passing primitive datatypes to operations 54 PerfCounterInfo data object 113 matching PerfMetricId CounterId 114 overview 112 properties 113 PerfEntityMetricBase data object 116 PerfInterval data objects ESX/ESXi system 115 vCenter Server system 117 PerfMetricId CounterId 114 performance 79, 111 performance counter groups 112 PerformanceManager operations 112 overview 117 properties 112 samples 111 PerfQuerySpec 115 permissions 29, 42, 43, 44, 71 changing 43 deleting 43 group membership 44 setting 43 users and groups 44 physical storage 99 powering on VM 148 predefined user roles 41 privileges 28, 40, 42 Administrator role 158 and security management 28 definition format 28 ESX/ESXi
properties, required for 156 reading object properties 156 vCenter Server operations 149 profiles 12 property values 49 PropertyCollector 77, 89 managed object type 74, 81 operations 74 operations 74 operations, compared 78 performance 79 samples 73 PropertyFilter managed object type 74 PropertyFilterSpec 56, 75, 89 introduction 75 XML schema definition 56 PropertySpec XML schema 56 provisioning 12
Q
QueryAvailablePerfMetric operation 116
R
recent tasks 89 recentTask Array 90 recurring operations 146 recursion 76 RelocateVM_Task operation 127 removing permissions 43 reservation 94 ResourceAllocationInfo, properties 94 restarting server 166 RetrieveEntityScheduledTask operation 144 RetrieveProperties operation 76 return datatypes 50 revert to snapshot 97 roles 40, 41 and security management 40 creating 42 modifying 42 root folders 27
S
sample applications 64 sample ESX log 163 samples Alarm 137 datastore operations 99 Event 129 EventManager 129 multiple API versions 64 overview 83 PerformanceManager 111
VMware, Inc.
operations
149
examples 28 format 28, 34 invoking operations 149 operations, required for 149
180
Index
PropertyCollector 73 ScheduledTaskManager 143 SearchIndex 73 storage operations 99 verbose log file 171 virtual machine deployment 120 VirtualMachine 93 sampling intervals 114 sampling periods 114 ScheduledTask 144, 145 cancelling 88 deleting 148 power on VM 148 retrieving 144 ScheduledTaskManager creating ScheduledTask 145 samples 143 ScheduledTaskSpec object 145 ScheduleTaskManager 144 scheduling recurring operations 146 scheduling vCenter Server operations 145 SDK 2.5 client applications 14 SDK 2.5 clients and vSphere 4.0 servers 13 SearchIndex 80 object 81 operations 81 samples 73 security 69 server access control 33 server connection, closing 60 server logs 162 ServiceContent data object 18, 19 property names 20 return types 20 values 20 ServiceInstance object 23 properties 18 session token 63 session tokens 59, 60, 63 SessionManager managed object 39 setting permissions 43 shares 94 simple client application 62 SimpleAgent sample 69 single sign-on support 37 snapshots 97 special characters 53 specifying server 174 statistics 115 statistics level settings 117
storage 101, 107 requirements 100 storage VMotion 127 supported version 64 synchronizing client data 78 system logs 162 system privileges 34 system roles 40, 41
T
target server, specifying 174 task infrastructure 83 task management 129 Task object 84, 85 TaskFilterSpec data object 134 TaskHistoryCollector 133 TaskInfo object 85 properties 88 properties 85 TaskInfoState values 90 TaskList java application 90 TaskManager 88 object 84, 85 properties 84 tasks, cancelling 88 TaskScheduler subtypes 147 templates 124, 125 retrieving 125 tokens 60, 63 TraversalSpec 76 troubleshooting 161
U
Unified Modeling Language 21 Update operation 77 UpdateAuthorizationRole operation 42 updating roles 41 user accounts 38, 70 user management 36 user models 33 User permissions 44 UserAccount object 71 UserDirectory 37 UserDirectory managed object 37 UserManager operations 38 server source data 37 users overview 37 permissions 44
VMware, Inc.
181
V
vCenter Server DiagnosticManagerLogDescriptor values 171 inventory 30 log files 164 scheduling operations 145 user model, overview 36 virtual machine operations 119 version information 64 versions 51, 64 sample using multiple versions 64 VI SDK 2.5-based clients 14 View object 80 View objects 79 ViewManager object 80 ViewManager objects 79 vimServiceVersions.xml 63 virtual machines cloning 125 creating 93 deployment using vCenter Server 120 log files 163 managing 93 migrating 126 migration 125 operations 119 powering on 148 templates 124 virtual storage 99 VirtualMachine ConfigSpec data object 121 nested properties 50 operations 95 operations 124 operations for VMotion 125 overview 50 RelocateVM_Task operation 127 samples 93 VirtualMachine managed object overview 120 VirtualMachineConfigSpec 94 VirtualMachineProvisioningChecker service interface 126 VirtualMachineRelocateSpec data object 127 VMkernel availability report 164 VMotion 125 vNetwork Distributed Switch See distributed virtual switch 12 vSphere 4.0 servers and SDK 2.5 clients 13
vSphere Client connected to ESX/ESXi 16 Connected to vCenter Server 16 vSphere components 11 vSphere object model 15
W
WaitForUpdates operation 79 Web Server, reusing session token 63 web service connecting 59 overview 45, 50 WSDL file 45 map to client-side proxy code 51
X
XML schema 55 ManagedObjectReference 55 PropertyFilterSpec 56 PropertySpec 56 XML Schema Primitives to .NET mapping 53 XML Schema Primitives to java mapping 53
182
VMware, Inc.

S DK 40 Programming Guide

Uploaded by

Copyright:

Available Formats

S DK 40 Programming Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

S DK 40 Programming Guide

Uploaded by

Copyright:

Available Formats

vSphere Web Services SDK Programming Guide

vSphere Web Services SDK 4.0

vSphere Web Services SDK Programming Guide

VMware, Inc. 3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com

vSphere Web Services SDK Programming Guide

GrantingPrivilegesthroughPermissions 42 ObtainingInformationaboutPermissions 43 Setting,Changing,orDeletingPermissions 43 ImpactofGroupMembershiponPermissions 44

vSphere Web Services SDK Programming Guide

vCenterServerandPerformanceManager 117 HistoricalIntervals 117 ModifyingHistoricalIntervals 117 OptimizingQueryResponseTime 118

vSphere Web Services SDK Programming Guide

About This Book

Technical Support and Education Resources

Online and Telephone Support

vSphere Web Services SDK Programming Guide

VMware Professional Services

Introduction to the Virtual Datacenter

Virtualization and VMware vSphere Components

Virtualizationprovidesanabstractionlayerbetweencomputingresources,physicalstorage,andnetworking hardware,andtheapplicationsthatusealloftheseresources.Forexample,virtualmemoryenablessoftware tousemorememorythanisphysicallyinstalledinacomputerbyswappingdatafromphysicalmemoryto physicaldisk.

vSphere Web Services SDK Programming Guide

Summary of New Features for Developers Using the SDK

Chapter 1 Introduction to the Virtual Datacenter

New Managed Entities

Support for Previous APIs in vSphere 4.0

Interoperability of SDK 2.5 Clients and vSphere 4.0 Servers

vSphere Web Services SDK Programming Guide

Client Libraries and Existing SDK 2.5 Client Applications

vSphere Object Model

Using the VMware vSphere Client to Explore the Object Model

vSphere Web Services SDK Programming Guide

Figure 2-1. vSphere Client Connected to an ESX/ESXi System

Using the Managed Object Browser to Explore the Object Model

Chapter 2 vSphere Object Model

Accessing the MOB

Navigating the Object Model in the MOB

vSphere Web Services SDK Programming Guide

Understanding the ServiceContent Data Object

Chapter 2 vSphere Object Model

vSphere Web Services SDK Programming Guide

Table 2-2. ServiceContent Property Names, Return Types, and Values

Chapter 2 vSphere Object Model

Understanding the Object Model as Data Structures

Understanding the Unified Modeling Language Used in this Guide

vSphere Web Services SDK Programming Guide

Figure 2-5. Legend for UML Class Diagrams

The Managed Object Type as Data Structure and Service Interface

Chapter 2 vSphere Object Model

ServiceInstance Managed Object as Starting Point to Other Service Interfaces

Figure 27showsamoredetailedUMLdiagramofServiceInstanceandServiceContent. ServiceContent,Capability,andAboutInfoarealldataobjects,denotedbythetildeinsectionoftheclass definitionwhereoperations(methods)aredepictedformanagedobjects.

vSphere Web Services SDK Programming Guide

References to Managed Objects

Understanding the Inventory

Overview of Managed Entities

vSphere Web Services SDK Programming Guide

Understanding Container Objects and the Inventory

Chapter 3 Understanding the Inventory

ChildentitiesareidentifiedthroughtheirchildEntityproperty,throughaparentproperty,orthrougha specificfolderreferenceinthecontainingobject. Figure 3-4. Parent-Child Associations Among Inventory Objects

vSphere Web Services SDK Programming Guide

Inventory Objects and Privileges

Chapter 3 Understanding the Inventory

vSphere Web Services SDK Programming Guide