How to browse the internal vSphere APIs

Version 4

    Table of Contents:

    • Initial Findings

    • Update 1 - More hidden goodies

    • Update 2 - Configure and enable/disable EVC

     

    Ever wonder if you could browse and see some of the internal vSphere API data objects, methods, properties, etc?

     

    You can by looking on your local ESX(i) host which has some python bindings which describes some of the internal APIs that aren't exposed via the public API

     

    Initial Findings

     

    [root@himalaya ~]# vmware -v
    VMware ESX 4.0.0 build-164009
    

     

     

    [root@himalaya ~]# cd /usr/lib/python2.4/site-packages/pyVmomi/
    

     

     

    [root@himalaya pyVmomi]# ls -l
    total 1176
    -rw-r--r-- 1 root root    804 Apr 30  2009 Cache.py
    -rw-r--r-- 1 root root   9104 Apr 30  2009 CoreTypes.py
    -rw-r--r-- 1 root root   7602 Jun 28 16:40 CoreTypes.pyc
    -rw-r--r-- 1 root root   8431 Apr 30  2009 Differ.py
    -rw-r--r-- 1 root root   9624 Apr 30  2009 DynamicTypeManagerHelper.py
    -rw-r--r-- 1 root root    729 Apr 30  2009 __init__.py
    -rw-r--r-- 1 root root    725 Jun 28 16:40 __init__.pyc
    -rw-r--r-- 1 root root  17152 Apr 30  2009 InternalServerObjects.py
    -rw-r--r-- 1 root root   8571 Jun 28 16:40 InternalServerObjects.pyc
    -rw-r--r-- 1 root root 649350 Apr 30  2009 ServerObjects.py
    -rw-r--r-- 1 root root 372577 Jun 28 16:40 ServerObjects.pyc
    -rw-r--r-- 1 root root  17850 Apr 30  2009 SoapAdapter.py
    -rw-r--r-- 1 root root  13391 Jun 28 16:40 SoapAdapter.pyc
    -rw-r--r-- 1 root root  21953 Apr 30  2009 VmomiSupport.py
    -rw-r--r-- 1 root root  18668 Jun 28 16:40 VmomiSupport.pyc
    

     

     

    *.py are python scripts and *.pyc are compiled python which can not be viewed. One interesting data object that's described in ServerObjects.py is the following:

     

    CreateDataType("vim.InternalServiceInstanceContent", "InternalServiceInstanceContent", "DynamicData", "vim.version.version1", )
    

     

     

    This is actually an internal version of ServiceContent with additional managed object references/etc. which can be retrieved with the following method from the ServiceInstance: retrieveInternalContent()

     

    From this, you can actually invoke this method via the MOB (Managed Object Browser)

     

    Here's the URL you'll invoke:

     

    https://<esx(i)_vcenter_ip_or_hostname>/mob/?moid=ServiceInstance&method=retrieveInternalContent
    

     

     

    You then need to click on the Invoke Method and you'll see the following if you're connecting directly to ESX(i) host, you'll see few less if you connect to vCenter

     

     

    From here you'll notice some local properties of the ESX(i) host such as manageing vCenter agent, ftManager, vDS, nfc service, etc.

     

    One interesting MoRef that surprised me is the ftManager:

     

     

    I've always wondered if there was a way to enable/disable FT (Fault Tolerance) on a VM once it's been abled within vCenter on individual ESX(i) host. It looks like you might be able to and being able to do so.

     

    Though these extra properties/objects are not documented nor supported in any of the available vSphere bindings: vSphere SDK for Perl, PowerCLI, etc. you would need to manually create the mappings and update the stubs to actually be able to make use of these internal APIs.

     

    Happy Browsing

     

    Update 1 - More hidden goodies

     

    Spent some time digging around the python directories and found some more interesting stuff ....

     

    Managed Object References

     

    • ha-dynamic-type-manager

     

    http://img259.imageshack.us/img259/9830/dynmgr.png

     

    • ha-dynamic-type-manager-python

     

    http://img259.imageshack.us/img259/430/managerpython.png

     

    • ha-dynamic-type-manager-local-cli

     

    http://img705.imageshack.us/img705/3269/localcli.png

     

    • ha-cli-info-python

     

    http://img686.imageshack.us/img686/4503/infopython.png

     

    • ha-vmotionmgr

     

    http://img197.imageshack.us/img197/4275/vmotionmgr.png

     

    • ha-system-debug-manager

     

    http://img130.imageshack.us/img130/3694/debugmanager.png

     

    Functions

     

    Managed Object: VirtualMachine

    • notifySnapshot()

    • abortBackup() - VM Backups?

    • startBackup() - VM Backups?

    • CreateLinkedClone_Task() - Linked Clone creation?

          

    Managed Object: HostSystem

    • retrieveInternalConfigManager()

    • retrieveInternalCapability()

    • enableAdmin() - This actually disables Lockdown mode on ESXi host (contricts the function name)

    • disableAdmin() - This actually enables Lockdown mode on ESXi host (contricts the function name)

               

    API Differences (least the ones I can find)

     

    I downloaded the vSphere SDK reference docs and did a diff between the known object,methods,properties against the ones I've found along with some manual tweaks I've foudn the following undocumented API calls (I'm sure there are more, but these were the ones that I've found):

     

    vim.internal.DynamicTypeManager
    vim.internal.DynamicTypeManager.Annotation
    vim.internal.DynamicTypeManager.PropertyTypeInfo
    vim.internal.DynamicTypeManager.PropertyTypeInfo.AnnotationType
    vim.internal.DynamicTypeManager.DataTypeInfo
    vim.internal.DynamicTypeManager.ParamTypeInfo
    vim.internal.DynamicTypeManager.ParamTypeInfo.AnnotationType
    vim.internal.DynamicTypeManager.MethodTypeInfo
    vim.internal.DynamicTypeManager.MethodTypeInfo.AnnotationType
    vim.internal.DynamicTypeManager.ManagedTypeInfo
    vim.internal.DynamicTypeManager.EnumTypeInfo
    vim.internal.DynamicTypeManager.AllTypeInfo
    vim.internal.DynamicTypeManager.MoInstance
    vim.internal.DynamicTypeManager.TypeFilterSpec
    vim.internal.DynamicTypeManager.MoFilterSpec
    vim.internal.EsxSupportSystem
    vim.internal.MockupSystem
    vim.version.drs
    vim.version.dvs
    vim.version.fed
    vim.version.ft
    vim.version.iorm
    vim.version.ipv6
    vim.version.lc
    vim.version.logan
    vim.version.policy
    vim.version.svm
    vim.version.uber
    vim.AgentManager
    vim.AuthorizationManager.DisabledMethodSource
    vim.AuthorizationManager.DisabledMethodInfo
    vim.AuthorizationManager.EntityDisabledMethodInfo
    vim.AuthorizationManager.DisabledMethodRequest
    vim.FileManager.FileType
    vim.ImageLibraryManager
    vim.ImageLibraryManager.MediaType
    vim.ImageLibraryManager.MediaInfo
    vim.InternalStatsCollector
    vim.InternalStatsCollector.StatsValue
    vim.InternalStatsCollector.StatsSet
    vim.MediaAnalysisManager
    vim.version.logan
    vim.MediaAnalysisManager.InstallerInfo
    vim.NfcService
    vim.OvfManager.ValidateHostParams
    vim.OvfManager.ParseDescriptorParams
    vim.PolicyManager
    vim.version.policy
    vim.PolicyManager.PolicyStates
    vim.PolicyManager.PolicyConditionType
    vim.PolicyManager.PolicySummary
    vim.ProxyService
    vim.ProxyService.AccessMode
    vim.ProxyService.EndpointSpec
    vim.ProxyService.RedirectSpec
    vim.ProxyService.RedirectSpec.RedirectType
    vim.ProxyService.ServiceSpec
    vim.ProxyService.NamedPipeServiceSpec
    vim.ProxyService.RemoteServiceSpec
    vim.ProxyService.LocalServiceSpec
    vim.ProxyService.TunnelSpec
    vim.ProxyService.NamedPipeTunnelSpec
    vim.ProxyService.RemoteTunnelSpec
    vim.ProxyService.LocalTunnelSpec
    vim.version.iorm
    vim.ServiceDirectory
    vim.ServiceDirectory.ServiceProtocol
    vim.ServiceDirectory.ServiceEndpoint
    vim.InternalServiceInstanceContent
    vim.ServiceManager
    vim.ServiceManager.ServiceInfo
    vim.SimpleCommand
    vim.SimpleCommand.Encoding
    vim.StorageIOAllocationInfo
    vim.cluster.DasAdmissionResult
    vim.cluster.DasHostInfos
    vim.cluster.TransitionalEVCManager
    vim.cluster.TransitionalEVCManager.EVCState
    vim.dvs.DistributedVirtualPort.OverlayParameter
    vim.version.dvs
    vim.dvs.DistributedVirtualPort.ConfigInfos
    vim.dvs.DistributedVirtualPort.OverlayParameterPolicy
    vim.dvs.HostMembert
    VimAccountPasswordChangedEvents
    vim.event.ChangeOwnerOfFileFailedEvent
    vim.event.ChangeOwnerOfFileEvent
    vim.event.EntityEventArguments
    vim.event.DatacenterEventArguments
    vim.event.AlarmEventArguments
    vim.event.EventFilterSpec.ByTimes
    vim.event.LastEventFilterSpec
    vim.fault.LicenseFault
    vim.fault.PolicyViolated
    vimAccountName
    vimAccountPassword
    vim.host.DiskBlockInfo
    vim.host.DiskBlockInfo.Extent
    vim.host.DiskBlockInfo.Mapping
    vim.host.DiskBlockInfo.ScsiMapping
    vim.host.DiskBlockInfo.VmfsMapping
    vim.host.DiskManager
    vim.host.DiskManager.Lease
    vim.host.DiskManager.LeaseInfo
    vim.host.FaultToleranceManager
    vim.host.IntegrityReport
    vim.host.IntegrityReport.QuoteInfo
    vim.host.IntegrityReport.QuoteData
    vim.host.InternalCapability
    vim.host.InternalConfigManager
    vim.host.IpSecConfig
    vim.version.ipv6
    vim.host.IpSecConfig.UpperLayerProtocolType
    vim.host.IpSecConfig.IpSecSAMode
    vim.host.IpSecConfig.EncryptionAlgorithm
    vim.host.IpSecConfig.IntegrityAlgorithm
    vim.host.IpSecConfig.EncryptionMethod
    vim.host.IpSecConfig.IntegrityMethod
    vim.host.IpSecConfig.PortRange
    vim.host.IpSecConfig.EndPoint
    vim.host.IpSecConfig.SAKeyingType
    vim.host.IpSecConfig.SecurityAssociationConfig
    vim.host.IpSecConfig.IpSecPolicy
    vim.host.LocalAccountManager.AccountSpecifications
    vim.host.NetworkPolicy.TrafficShapingPolicys
    vim.host.PlugStoreTopology.Devices
    vim.host.SignatureInfo
    vim.host.SignatureInfo.SigningMethodType
    vim.host.SystemDebugManager
    vim.host.SystemDebugManager.ProcessKey
    vim.host.SystemDebugManager.ProcessInfo
    vim.host.TargetTransports
    vim.host.TpmManager
    vim.host.TpmManager.KeyParams
    vim.host.TpmManager.EncryptedBlob
    vim.host.VirtualSwitch.BeaconConfigs
    vim.host.WakeOnLanConfig
    vim.profile.PolicyOptions
    vim.profile.cluster.ClusterProfile.ConfigSpecs
    vim.profile.host.VirtualSwitchProfile.LinkProfiles
    vim.profile.host.VirtualSwitchProfile.NumPortsProfiles
    vim.profile.host.PortGroupProfile.VlanProfiles
    vim.profile.host.PortGroupProfile.VirtualSwitchSelectionProfiles
    vim.profile.host.NetworkPolicyProfiles
    vim.profile.host.HostProfile.ConfigSpecs
    vim.scheduler.MonthlyByWeekdayTaskScheduler.DayOfWeeks
    vim.vm.BackupAgent
    vim.vm.BackupEventInfo
    vim.vm.BackupEventInfo.BackupEventType
    vim.vm.customization.GuestInstallManager
    vim.vm.customization.GuestInstallManager.UnattendedInstallSpecs
    vim.vm.customization.GuestInstallManager.UnattendedWindowsInstallSpec
    vim.vm.customization.GuestInstallManager.UnattendedRedHatInstallSpec
    vim.vm.customization.IpGenerators
    vim.vm.device.VirtualDevice.BackingInfos
    vim.vm.device.VirtualDeviceOption.RemoteDeviceBackingOptiont
    vim.vm.device.VirtualDeviceSpec.Operations
    vim.vm.device.VirtualDiskOption.SparseVer2BackingOptiont
    vim.LicenseAssignmentManager.EntityFeaturePair
    vim.LicenseAssignmentManager.FeatureLicenseAvailability
    vim.LicenseAssignmentManager.LicenseFileDescriptor
    vim.NetworkBandwidthAllocationInfo
    vim.VirtualDiskManager.ReparentSpec
    vim.cluster.RuleInfos
    vim.fault.DrsPlacementRequiresVmsInTopologicalOrder
    vim.fault.EVCConfigFaul
    vim.fault.EVCModeIllegalByVendor
    vim.fault.EVCModeUnsupportedByHosts
    vim.fault.HeterogenousHostsBlockingEVC
    vim.fault.HostIncompatibleForFaultTolerancet
    vim.fault.HttpFaul
    vim.fault.InvalidIpfixConfig
    vim.fault.InvalidKey
    vim.fault.InvalidKeyCombination
    vim.fault.InvalidKeyValue
    vim.fault.InvalidTicket
    vim.fault.LeaseFault
    vim.fault.LibraryFault
    vim.fault.LibraryOperation
    vim.fault.LicenseEntityAlreadyExists
    vim.fault.MisfeaturedHostsBlockingEVC
    vim.fault.PolicyUrnInvalid
    vim.fault.PolicyViolatedDetail
    vim.fault.PoweredOnCloneNotSupported
    vim.fault.PoweredOnCloneNotSupported.UnsupportedOperation
    vim.fault.SwitchIpUnset
    vim.fault.TooManyTickets
    vim.fault.TooManyWrites
    vim.fault.UnableToPlaceAtomicVmGroup
    vim.fault.UnableToPlacePrerequisiteGroup
    vim.fault.VspanPortConflict
    vim.host.VmfsDatastoreOption.Infos
    vim.host.VMotionManager
    vim.host.VMotionManager.VMotionType
    vim.host.VMotionManager.Spec
    vim.host.VMotionManager.DestinationState
    vim.host.VMotionManager.VMotionResult
    vim.host.VMotionManager.ReparentSpec
    vim.DistributedVirtualSwitch.OverlayInstance
    vim.DistributedVirtualSwitch.OverlayConfigSpec
    vim.dvs.VmwareDistributedVirtualSwitch.VspanPorts
    vim.dvs.VmwareDistributedVirtualSwitch.VspanSession
    vim.dvs.VmwareDistributedVirtualSwitch.IpfixConfig
    vim.dvs.VmwareDistributedVirtualSwitch.VlanIdSpect
    vim.dvs.VmwareDistributedVirtualSwitch.PvlanPortTypet
    vim.dvs.VmwareDistributedVirtualSwitch.VspanConfigSpec
    vim.fault.ActiveVMsBlockingEVC
    vim.fault.CollectorAddressUnset
    vim.fault.DisconnectedHostsBlockingEVC
    vim.fault.InvalidLibraryResponse
    vim.fault.PolicyDisallowsOperation
    vim.fault.PolicyViolatedByValue
    vim.fault.PolicyViolatedValueCannotEqual
    vim.fault.PolicyViolatedValueNotEqual
    vim.fault.PolicyViolatedValueNotInRange
    vim.fault.PolicyViolatedValueNotInSet
    vim.fault.PolicyViolatedValueTooBig
    vim.fault.PolicyViolatedValueTooSmall
    vim.fault.VMotionEncryptionNotSupported
    vimAccountNameRequired
    vim.dvs.HostDistributedVirtualSwitchManager
    vim.dvs.HostDistributedVirtualSwitchManager.PortData
    vim.dvs.HostDistributedVirtualSwitchManager.PortCloneSpec
    vim.dvs.HostDistributedVirtualSwitchManager.PortDeleteSpec
    vim.dvs.HostDistributedVirtualSwitchManager.VmwareDVSSettingSpec
    vim.dvs.HostDistributedVirtualSwitchManager.DVSConfigSpec
    vim.dvs.HostDistributedVirtualSwitchManager.DVSCreateSpecs
    vim.dvs.HostDistributedVirtualSwitchManager.DVPortgroupConfigSpec
    vim.host.DiagnosticPartition.CreateSpect
    vim.dvs.HostDistributedVirtualSwitchManager
    vim.dvs.HostDistributedVirtualSwitchManager.PortData
    vim.dvs.HostDistributedVirtualSwitchManager.PortCloneSpec
    vim.dvs.HostDistributedVirtualSwitchManager.PortDeleteSpec
    vim.dvs.HostDistributedVirtualSwitchManager.VmwareDVSSettingSpec
    vim.dvs.HostDistributedVirtualSwitchManager.DVSConfigSpec
    vim.dvs.HostDistributedVirtualSwitchManager.DVSCreateSpecs
    vim.dvs.HostDistributedVirtualSwitchManager.DVPortgroupConfigSpec
    vim.version.drs
    vim.version.fed
    vim.version.ft
    vim.version.lc
    vim.version.svm
    vim.version.uber
    

     

    Some interesting strings that might be of interest are these:

     

    vim.version.drs - Distributed Resource Scheduler
    vim.version.dvs - Distributed Virtual Switch
    vim.version.fed
    vim.version.ft - Fault Tolerance
    vim.version.iorm
    vim.version.ipv6 - IPv6
    vim.version.lc
    vim.version.logan
    vim.version.policy
    vim.version.svm
    vim.version.uber
    

     

    Not sure about the rest .... are these upcoming or hidden features?

     

    Update 2 - Configure and enable/disable EVC

     

    In the current exposed vSphere API, there is no way to configure and enable/disable EVC for a VMware Cluster. Though from the above, you might have seen something called TransitionalEVCManager which makes me believe the functiolnality is there, just not public exposed! With some digging, I've found where the methods are for configuring EVC, I'll demonstrate using MOB:

     

    1. Connect to your vCenter MOB and traverse to a cluster such as the following (note the MOID will be different in your specific cluster)

     

    http://img11.imageshack.us/img11/2056/clusterinfo.png

     

    2. Now replace the URL with the following while substituting the cluster MOID that you see in your browser:

     

    https://reflex.primp-industries.com/mob/?moid=domain-c1550&method=transitionalEVCManager
    

     

    and hit enter and you'll be brought to TransitionalEVCManager() method, you'll then want to click on the "Invoke Method". Once you do so, you should be returned with a task object and you'll have a link to something like evcdomain-cXXXX. Click on this and you'll be brough to ClusterTransitionalEVCManager

     

    http://img638.imageshack.us/img638/5483/clustertevc.png

     

    3. From here you'll have have some basica evcState information which you can click on to see what the current EVC configuration is set to, guaranteedCPUFeatures and valid EVC Modes (the last part will be important for reconfiguring EVC)

     

    http://img42.imageshack.us/img42/994/evcstate.png

     

    4. Now let's say the cluster currently has EVC Mode set to intel-merom and you would like to change it to Nehalem, you would need to retrieve the key from the previous page, in our example it's intel-nehalem. You'll now want to click on the method link called ConfigureEVC_Task which is pretty straight forward, it just accepts the EVC Mode Key, enter the string and click on "Invoke Method" and now your cluster will be reconfigured if you go back to the evcState or look at your vCenter task. You can also disable EVC by using DisableEVC_Task

     

    http://img705.imageshack.us/img705/6664/reconfigureevc.png

     

    There you have it, VMware hiding all the goodies!