Scripting Object - VcVirtualMachine

Scripting-object corresponding to
VirtualMachine
Attribute of
VcApplyStorageRecommendationResult, VcAutoStartPowerInfo, VcCannotChangeDrsBehaviorForFtSecondary, VcCannotChangeHaSettingsForFtSecondary, VcCannotComputeFTCompatibleHosts, VcCannotPowerOffVmInCluster, VcCbrcDeviceSpec, VcCheckResult, VcClusterAffinityRuleSpec, VcClusterAntiAffinityRuleSpec, VcClusterAttemptedVmInfo, VcClusterDasFailoverLevelAdvancedRuntimeInfoVmSlots, VcClusterDasVmConfigInfo, VcClusterDiagnoseResourceAllocationResultVmStaticEntitlement, VcClusterDrsFaultsFaultsByVirtualDisk, VcClusterDrsFaultsFaultsByVm, VcClusterDrsMigration, VcClusterDrsVmConfigInfo, VcClusterNotAttemptedVmInfo, VcClusterVmGroup, VcClusterVmOrchestrationInfo, VcDatastore, VcDistributedVirtualPortgroup, VcDVSSummary, VcDvsVnicAllocatedResource, VcEsxAgentConfigManagerAgentVmInfo, VcFailToLockFaultToleranceVMs, VcFaultToleranceCannotEditMem, VcFaultTolerancePrimaryConfigInfo, VcFaultTolerancePrimaryPowerOnNotAttempted, VcFaultToleranceSecondaryConfigInfo, VcFaultToleranceSecondaryOpResult, VcFaultToleranceVmNotDasProtected, VcFeatureRequirementsNotMet, VcHbrManagerVmReplicationCapability, VcHostGraphicsInfo, VcHostPlacedVirtualNicIdentifier, VcHostSystem, VcHostVmciAccessManagerAccessSpec, VcInvalidDasRestartPriorityForFtVm, VcInvalidDrsBehaviorForFtVm, VcInvalidVmState, VcMountError, VcNetwork, VcNoHostSuitableForFtSecondary, VcNotSupportedDeviceForFT, VcOpaqueNetwork, VcPlacementAction, VcPlacementAffinityRule, VcPlacementSpec, VcPowerOnFtSecondaryFailed, VcPowerOnFtSecondaryTimedout, VcReplicationDiskConfigFault, VcReplicationVmConfigFault, VcReplicationVmFault, VcReplicationVmInProgressFault, VcResourcePool, VcSourceNodeSpec, VcStorageDrsVmConfigInfo, VcStorageMigrationAction, VcStoragePlacementAction, VcStoragePlacementSpec, VcVirtualApp, VcVirtualDiskId, VcVirtualMachineDiskDeviceInfo, VcVirtualMachineIdeDiskDeviceInfo, VcVirtualMachineInstantCloneParentParentVirtualMachineInGroup, VcVirtualMachineScsiDiskDeviceInfo, VcVirtualMachineSnapshot, VcVirtualMachineSnapshotTree, VcVirtualMachineSummary, VcVmAlreadyExistsInDatacenter, VcVmEventArgument, VcVmWwnConflict
Parameter to
acquireCredentialsInGuest, addGuestAlias, changeFileAttributesInGuest, checkClone_Task, checkCompatibility_Task, checkDasAdmission, checkMigrate_Task, checkRelocate_Task, createNamespace, createRegistryKeyInGuest, createTemporaryDirectoryInGuest, createTemporaryFileInGuest, deleteAllNamespaces, deleteDirectoryInGuest, deleteFileInGuest, deleteNamespace, deleteRegistryKeyInGuest, deleteRegistryValueInGuest, deployVM, disableSecondaryVM_Task, enableSecondaryVM_Task, fetchEventsFromGuest, findRulesForVm, fTManagerDisableSecondaryVM_Task, fTManagerEnableSecondaryVM_Task, fTManagerGetPeerVMCompHealth, fTManagerGoLivePeerVM, fTManagerMakePrimaryVM_Task, fTManagerRegisterSecondaryVM_Task, fTManagerSetLocalVMCompHealth, fTManagerStartSecondaryOnRemoteHost_Task, fTManagerTerminateFaultTolerantVM_Task, fTManagerUnregisterSecondaryVM_Task, fTManagerUnregisterVM, getVRPofVM, hbrCreateInstance_Task, hbrDisableReplication_Task, hbrEnableReplication_Task, hbrFullSync_Task, hbrPauseReplication_Task, hbrQueryReplicationCapabilities, hbrQueryReplicationState, hbrReconfigureReplication_Task, hbrResumeReplication_Task, hbrRetrieveReplicationConfig, hbrStartOfflineInstance_Task, hbrStopOfflineInstance, initiateFileTransferFromGuest, initiateFileTransferToGuest, internalQueryLatestVmStats, listFilesInGuest, listGuestAliases, listGuestMappedAliases, listNamespaces, listProcessesInGuest, listRegistryKeysInGuest, listRegistryValuesInGuest, lookupVmOverheadMemory, lowLevelConsolidateDisks_Task, lowLevelPromoteDisks_Task, makeDirectoryInGuest, makePrimaryVM_Task, moveDirectoryInGuest, moveFileInGuest, nfcGetVmFiles, nfcPutVmFiles, nfcRandomAccessOpenDisk, nfcRandomAccessOpenReadonly, notifyPowerOn, pause, powerOnMultiVM_Task, powerOnPaused_Task, prepareSource, prepareSourceEx_Task, queryAgentVmInfo, queryCompatibilityForFaultTolerance, queryFaultToleranceCompatibleDatastores, queryFaultToleranceCompatibleHosts, queryGuestOperationsDisabledMethods, queryNamespace, queryVMotionCompatibility, queryVMotionCompatibilityEx_Task, readEnvironmentVariableInGuest, recommendHostsForVm, releaseCredentialsInGuest, reloadDisks_Task, removeGuestAlias, removeGuestAliasByCert, retrieveData, retrieveGrantedServices, retrievePublicOvfEnvironmentSections, sendEventToGuest, setRegistryValueInGuest, startProgramInGuest, terminateFaultTolerantVM_Task, terminateProcessInGuest, undeployVM, unpause, updateData, updateNamespace, upgradeDestination_Task, validateCredentialsInGuest, validateMigration, verifyFaultToleranceConfigSpec
Returned by
findByDatastorePath, getAllVirtualMachines, getAllVirtualMachines, importOvf, queryAccessToService

Scripting Object Description

VirtualMachine is the managed object type for manipulating virtual machines, including templates that can be deployed (repeatedly) as new virtual machines. This type provides methods for configuring and controlling a virtual machine.

VirtualMachine extends the ManagedEntity type because virtual machines are part of a virtual infrastructure inventory. The parent of a virtual machine must be a folder, and a virtual machine has no children.

Destroying a virtual machine disposes of all associated storage, including the virtual disks. To remove a virtual machine while retaining its virtual disk storage, a client must remove the virtual disks from the virtual machine before destroying it.

Attributes

Name Type Description
alarmActionsEnabledBoolean

@since vSphere API 4.0
annotationString

@since Unknown
availableFieldVcCustomFieldDef []

@since VI API 2.5
biosIdString

128-bit SMBIOS UUID of a virtual machine represented as a hexadecimal string in "12345678-abcd-1234-cdef-123456789abc" format. @since Unknown
capabilityVcVirtualMachineCapability

@since VI API 2.5
committedStorageString

@since Unknown
configVcVirtualMachineConfigInfo

@since VI API 2.5
configIssueVcEvent []

@since VI API 2.5
configStatusVcManagedEntityStatus

@since VI API 2.5
connectionStateString

@since Unknown
cpuString

@since Unknown
customValueVcCustomFieldValue []

@since VI API 2.5
datastoreVcDatastore []

@since VI API 2.5
declaredAlarmStateVcAlarmState []

@since VI API 2.5
disabledMethodString []

@since VI API 2.5
displayNameString

@since Unknown
effectiveRoleNumber []

@since VI API 2.5
environmentBrowserVcEnvironmentBrowser

@since VI API 2.5
guestVcGuestInfo

@since VI API 2.5
guestHeartbeatStatusVcManagedEntityStatus

@since VI API 2.5
guestMemoryUsageString

@since Unknown
guestOSString

@since Unknown
hostMemoryUsageString

@since Unknown
hostNameString

@since Unknown
idString

@since Unknown
instanceIdString

VirtualCenter-specific 128-bit UUID of a virtual machine, represented as a hexademical string. This identifier is used by VirtualCenter to uniquely identify all virtual machine instances, including those that may share the same SMBIOS UUID. @since Unknown
ipAddressString

@since Unknown
isTemplateBoolean

@since Unknown
layoutVcVirtualMachineFileLayout

@since VI API 2.5
layoutExVcVirtualMachineFileLayoutEx

@since vSphere API 4.0
memString

@since Unknown
memoryString

@since Unknown
memoryOverheadString

@since Unknown
morefVcManagedObjectReference

returns the ManagedObjectReference of this ManagedObject @since Unknown
nameString

@since VI API 2.5
nativeSnapshotCapableBoolean

Check if native delta disk format can be used to create a snapshot for this virtual machine.

@since vSphere API 5.0

networkVcNetwork []

@since VI API 2.5
overallCpuUsageString

@since Unknown
overallStatusVcManagedEntityStatus

@since VI API 2.5
parentVcManagedEntity

@since VI API 2.5
parentVAppVcManagedEntity

@since vSphere API 4.1
permissionVcPermission []

@since VI API 2.5
productFullVersionString

@since Unknown
productNameString

@since Unknown
productVendorString

@since Unknown
recentTaskVcTask []

@since VI API 2.5
resourceConfigVcResourceConfigSpec

@since VI API 2.5
resourcePoolVcResourcePool

@since VI API 2.5
rootSnapshotVcVirtualMachineSnapshot []

@since vSphere API 4.1
runtimeVcVirtualMachineRuntimeInfo

@since VI API 2.5
sdkConnectionVcSdkConnection

@since Unknown
sdkIdString

@since Unknown
snapshotVcVirtualMachineSnapshotInfo

@since VI API 2.5
stateString

@since Unknown
storageVcVirtualMachineStorageInfo

@since vSphere API 4.0
summaryVcVirtualMachineSummary

@since VI API 2.5
tagVcTag []

@since vSphere API 4.0
totalStorageString

@since Unknown
triggeredAlarmStateVcAlarmState []

@since VI API 2.5
typeStringDeprecated.

Returns the name for the this managed object's vim type @since Unknown
unsharedStorageString

@since Unknown
valueVcCustomFieldValue []

@since VI API 2.5
vimHostVcSdkConnection

@since Unknown
vimIdString

@since Unknown
vimTypeString

@since Unknown
vmSnapshotObject []

@since Unknown
vmToolsStatusString

@since Unknown
vmToolsVersionStatusString

@since Unknown
vmVersionString

@since Unknown

Methods

Methods defined in this Scripting Object
_getRef, acquireMksTicket, acquireTicket, addTag, answerVM, applyEvcModeVM_Task, attachDisk_Task, checkCustomizationSpec, cloneVM_Task, configureQuorumFilePathPrefix_Task, consolidateVMDisks_Task, createForkChild_Task, createImportLease, createScreenshot_Task, createSecondaryVM_Task, createSecondaryVMEx_Task, createSnapshot_Task, createSnapshotEx_Task, createTrigger, customizeVM_Task, defragmentAllDisks, destroy_Task, detachDisk_Task, disableForkParent_Task, disableSecondaryVM_Task, enableForkParent_Task, enableSecondaryVM_Task, estimateStorageForConsolidateSnapshots_Task, exportVm, extractOvfEnvironment, injectOvfEnvironment, invokeFSR_Task, makePrimaryVM_Task, markAsTemplate, markAsVirtualMachine, migrateVM_Task, mountToolsInstaller, mountToolsInstallerImage, powerOffVM_Task, powerOnVM_Task, promoteDisks_Task, putUsbScanCodes, queryChangedDiskAreas, queryFaultToleranceCompatibility, queryFaultToleranceCompatibilityEx, queryUnownedFiles, rebootGuest, reconfigVM_Task, refreshStorageInfo, reload, reloadEx_Task, reloadVirtualMachineFromPath_Task, relocateVM_Task, removeAllSnapshots_Task, removeTag, rename_Task, resetGuestInformation, resetVM_Task, retrieveBackupAgent, retrieveCustomValues, retrieveForkChildren_Task, retrieveForkParent_Task, retrieveQuorumFilePathPrefix, revertToCurrentSnapshot_Task, sendNMI, setCustomValue, setDisplayTopology, setScreenResolution, shrinkDisk_Task, shutdownGuest, standbyGuest, startRecording_Task, startReplaying_Task, stopRecording_Task, stopReplaying_Task, suspendVM_Task, terminateFaultTolerantVM_Task, terminateVM, turnOffFaultToleranceForVM_Task, unmountToolsInstaller, unregisterVM, upgradeTools_Task, upgradeToolsFromImage_Task, upgradeVM_Task, wipeDisk_Task

setDisplayTopology

Sets the console window's display topology as specified. @since vSphere API 4.0

Parameters

NameTypeDescription
arg0VcVirtualMachineDisplayTopology []


Return Value

Type Description
None

acquireMksTicket

Creates and returns a one-time credential used in establishing a remote mouse-keyboard-screen connection to this virtual machine. The correct function of this method depends on being able to retrieve TCP binding information about the server end of the client connection that is requesting the ticket. If such information is not available, the NotSupported fault is thrown. This method is appropriate for SOAP and authenticated connections, which are both TCP-based connections. @since VI API 2.5

Parameters

NameTypeDescription
None

Return Value

Type Description
VcVirtualMachineMksTicket

markAsTemplate

Marks a VirtualMachine object as being used as a template. Note: A VirtualMachine marked as a template cannot be powered on. @since VI API 2.5

Parameters

NameTypeDescription
None

Return Value

Type Description
None

markAsVirtualMachine

Clears the 'isTemplate' flag and reassociates the virtual machine with a resource pool and host. @since VI API 2.5

Parameters

NameTypeDescription
arg0VcResourcePool

arg1VcHostSystem


Return Value

Type Description
None

refreshStorageInfo

Explicitly refreshes the storage information of this virtual machine, updating properties {@link #storage}, {@link #layoutEx} and {@link vim.vm.Summary#storage}. @since vSphere API 4.0

Parameters

NameTypeDescription
None

Return Value

Type Description
None

createImportLease

Obtains an import lease on this virtual machine. The method will be used as part of vCenter's ImportVApp(), so that the user can be pointed at hostd NFC endpoint, instead of vpxa.

See {@link vim.HttpNfcLease} for information on how to use the lease. @since vim unstable version

Parameters

NameTypeDescription
None

Return Value

Type Description
VcHttpNfcLease

retrieveForkChildren_Task

Retrieve all fork children of this virtual machine. @since vSphere API 6.0

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

injectOvfEnvironment

By calling this method, the caller can specify the OVF environment that will be injected into a virtual machine (privateOvfEnv) and returned by the {@link #extractOvfEnvironment extractOvfEnvironment} method (publicOvfEnv). Calling this method with a non-empty privateOvfEnv will disable the internal vCenter generated OVF environment. Calling this method with privateOvfEnv set to the empty string will renable the built-in OVF environment.

This method is intended to be used by solutions that builds on top of vCenter, e.g., vCloud. @since vSphere API 5.0

Parameters

NameTypeDescription
arg0String

arg1String


Return Value

Type Description
None

revertToCurrentSnapshot_Task

Reverts the virtual machine to the current snapshot. This is equivalent to doing snapshot.currentSnapshot.revert.

If no snapshot exists, then the operation does nothing, and the virtual machine state remains unchanged. @since VI API 2.5

Parameters

NameTypeDescription
arg0VcHostSystem

arg1Boolean


Return Value

Type Description
VcTask

powerOnVM_Task

Powers on this virtual machine. If the virtual machine is suspended, this method resumes execution from the suspend point.

When powering on a virtual machine in a cluster, the system might implicitly or due to the host argument, do an implicit relocation of the virtual machine to another host. Hence, errors related to this relocation can be thrown. If the cluster is a DRS cluster, DRS will be invoked if the virtual machine can be automatically placed by DRS (see {@link vim.cluster.DrsConfigInfo.DrsBehavior}). Because this method does not return a DRS {@link vim.cluster.Recommendation}, no vmotion nor host power operations will be done as part of a DRS-facilitated power on. To have DRS consider such operations use {@link vim.Datacenter#powerOnVm}. As of vSphere API 5.1, use of this method with vCenter Server is deprecated; use {@link vim.Datacenter#powerOnVm} instead.

If this virtual machine is a fault tolerant primary virtual machine, its secondary virtual machines will be started on system-selected hosts. If the virtual machines are in a VMware DRS enabled cluster, then DRS will be invoked to obtain placements for the secondaries but no vmotion nor host power operations will be considered for these power ons. @since VI API 2.5

Parameters

NameTypeDescription
arg0VcHostSystem


Return Value

Type Description
VcTask

attachDisk_Task

Attach an existing disk to this virtual machine. A minimum virtual machine version of 'vmx-13' is required for this operation to succeed. If a compatible VM version is not satisfied, a {@link vim.fault.DeviceUnsupportedForVmVersion} fault will be thrown. @since vSphere API 6.5

Parameters

NameTypeDescription
arg0VcID

arg1VcDatastore

arg2Number

arg3Number


Return Value

Type Description
VcTask

_getRef

@since Unknown

Parameters

NameTypeDescription
None

Return Value

Type Description
VcManagedObjectReference

estimateStorageForConsolidateSnapshots_Task

Estimate the temporary space required to consolidation disk files. The estimation is a lower bound if the childmost writable disk file will be consolidated for an online virtual machine, it is accurate for all other situations. This is because the space requirement depending on the size of the childmost disk file and how write intensive the guest is.

This method can be used prior to invoke consolidation via {@link vim.VirtualMachine#consolidateDisks}. @since vSphere API 5.0

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

queryUnownedFiles

For all files that belong to the vm, check that the file owner is set to the current datastore principal user, as set by {@link vim.host.DatastoreSystem#configureDatastorePrincipal HostDatastoreSystem.ConfigureDatastorePrincipal} @since vSphere API 4.0

Parameters

NameTypeDescription
None

Return Value

Type Description
String []

startRecording_Task

Initiates a recording session on this virtual machine. As a side effect, this operation creates a snapshot on the virtual machine, which in turn becomes the current snapshot.

This is an experimental interface that is not intended for use in production code.

@since vSphere API 4.0

Parameters

NameTypeDescription
arg0String

arg1String


Return Value

Type Description
VcTask

wipeDisk_Task

This operation will "wipe" any wipeable disks attached to the virtual machine, by unmapping unused filesystem blocks. These unmapped blocks can then be freed with a subsequent shrinkDisk operation. wipeDisk is issued within the Guest OS, and requires that the virtual machine be powered on. Operations that modify the state of the VM will be disallowed while a wipeDisk is in progress. wipeDisk will return a WipeResult array, which contains one element per disk attached to the virtual machine. If an error occurs while wiping, a WipeDiskFault will be thrown. @since vSphere API 5.1

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

putUsbScanCodes

Inject a sequence of USB HID scan codes into the keyboard. @since vSphere API 6.5

Parameters

NameTypeDescription
arg0VcUsbScanCodeSpec


Return Value

Type Description
Number

unregisterVM

Removes this virtual machine from the inventory without removing any of the virtual machine's files on disk. All high-level information stored with the management server (ESX Server or VirtualCenter) is removed, including information such as statistics, resource pool association, permissions, and alarms.

Use the Folder.RegisterVM method to recreate a VirtualMachine object from the set of virtual machine files by passing in the path to the configuration file. However, the VirtualMachine managed object that results typically has different objects ID and may inherit a different set of permissions. @since VI API 2.5

Parameters

NameTypeDescription
None

Return Value

Type Description
None

queryChangedDiskAreas

Get a list of areas of a virtual disk belonging to this VM that have been modified since a well-defined point in the past. The beginning of the change interval is identified by "changeId", while the end of the change interval is implied by the snapshot ID passed in.

Note that the result of this function may contain "false positives" (i.e: flag areas of the disk as modified that are not). However, it is guaranteed that no changes will be missed. @since vSphere API 4.0

Parameters

NameTypeDescription
arg0VcVirtualMachineSnapshot

arg1Number

arg2Number

arg3String


Return Value

Type Description
VcDiskChangeInfo

removeAllSnapshots_Task

Remove all the snapshots associated with this virtual machine. If the virtual machine does not have any snapshots, then this operation simply returns successfully. @since VI API 2.5

Parameters

NameTypeDescription
arg0Boolean


Return Value

Type Description
VcTask

enableSecondaryVM_Task

Enables the specified secondary virtual machine in this fault tolerant group.

This operation is used to enable a secondary virtual machine that was previously disabled by the {@link vim.VirtualMachine#disableSecondary} call. The specified secondary will be automatically started whenever the primary is powered on.

If the primary virtual machine (i.e., this virtual machine) is powered on when the secondary is enabled, an attempt will be made to power on the secondary. If a host was specified in the method call, this host will be used. If a host is not specified, one will be selected by the system. In the latter case, if the cluster is a DRS cluster, DRS will be invoked to obtain a placement for the new secondary virtual machine. If the DRS recommendation (see {@link vim.cluster.Recommendation}) is automatic, it will be executed. Otherwise, the recommendation will be returned to the caller of this method and the secondary will remain powered off until the recommendation is approved using {@link ClusterComputeResource#applyRecommendation}. @since vSphere API 4.0

Parameters

NameTypeDescription
arg0VcVirtualMachine

arg1VcHostSystem


Return Value

Type Description
VcTask

sendNMI

Send a non-maskable interrupt (NMI). Currently, there is no way to verify if the NMI was actually received by the guest OS. @since vSphere API 6.0

Parameters

NameTypeDescription
None

Return Value

Type Description
None

reload

Reload the entity state. Clients only need to call this method if they changed some external state that affects the service without using the Web service interface to perform the change. For example, hand-editing a virtual machine configuration file affects the configuration of the associated virtual machine but the service managing the virtual machine might not monitor the file for changes. In this case, after such an edit, a client would call "reload" on the associated virtual machine to ensure the service and its clients have current data for the virtual machine. @since VI API 2.5

Parameters

NameTypeDescription
None

Return Value

Type Description
None

retrieveCustomValues

Retrieve Custom field values based on specified custom field keys. If there is no key specified, all custom values associated to this ManagedEntity will be returned. @since vSphere API 6.5

Parameters

NameTypeDescription
arg0Number []


Return Value

Type Description
VcCustomFieldValue []

mountToolsInstaller

Mounts the VMware Tools CD installer as a CD-ROM for the guest operating system. To monitor the status of the tools install, clients should check the tools status, {@link vim.vm.GuestInfo#toolsVersionStatus} and {@link vim.vm.GuestInfo#toolsRunningStatus} @since VI API 2.5

Parameters

NameTypeDescription
None

Return Value

Type Description
None

suspendVM_Task

Suspends execution in this virtual machine. @since VI API 2.5

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

upgradeTools_Task

Begins the tools upgrade process. To monitor the status of the tools install, clients should check the tools status, {@link vim.vm.GuestInfo#toolsVersionStatus} and {@link vim.vm.GuestInfo#toolsRunningStatus}. @since VI API 2.5

Parameters

NameTypeDescription
arg0String


Return Value

Type Description
VcTask

enableForkParent_Task

Enable this virtual machine to create children. @since vSphere API 6.0

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

addTag

Add a set of tags to this object that can be queried later. The tag must be of the form "system/" or "global/ Parameters

NameTypeDescription
arg0VcTag []


Return Value

Type Description
None

rename_Task

Renames this managed entity.

Any % (percent) character used in this name parameter must be escaped, unless it is used to start an escape sequence. Clients may also escape any other characters in this name parameter.

@since VI API 2.5

Parameters

NameTypeDescription
arg0String


Return Value

Type Description
VcTask

disableForkParent_Task

Disable this virtual machine to create children. @since vSphere API 6.0

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

startReplaying_Task

Starts a replay session on this virtual machine. As a side effect, this operation updates the current snapshot of the virtual machine.

This is an experimental interface that is not intended for use in production code.

@since vSphere API 4.0

Parameters

NameTypeDescription
arg0VcVirtualMachineSnapshot


Return Value

Type Description
VcTask

setScreenResolution

Sets the console window's resolution as specified. @since VI API 2.5

Parameters

NameTypeDescription
arg0Number

arg1Number


Return Value

Type Description
None

retrieveForkParent_Task

Retrieve the fork parent of this virtual machine. @since vSphere API 6.0

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

unmountToolsInstaller

Unmounts VMware Tools installer CD. @since VI API 2.5

Parameters

NameTypeDescription
None

Return Value

Type Description
None

upgradeToolsFromImage_Task

Begins the tools upgrade process. To monitor the status of the tools install, clients should check the tools status, {@link vim.vm.GuestInfo#toolsVersionStatus} and {@link vim.vm.GuestInfo#toolsRunningStatus}. @since vim unstable version

Parameters

NameTypeDescription
arg0String

arg1VcVirtualDeviceBackingInfo

arg2VcGuestAuthentication


Return Value

Type Description
VcTask

queryFaultToleranceCompatibility

This API can be invoked to determine whether a virtual machine is compatible for legacy Fault Tolerance. The API only checks for VM-specific factors that impact compatibility for RecordReplay based Fault Tolerance. Other requirements for Fault Tolerance such as host processor compatibility, logging nic configuration and licensing are not covered by this API. The query returns a list of faults, each fault corresponding to a specific incompatibility. If a given virtual machine is compatible for Fault Tolerance, then the fault list returned will be empty. @since vSphere API 4.1

Parameters

NameTypeDescription
None

Return Value

Type Description
VcLocalizedMethodFault []

extractOvfEnvironment

Returns the OVF environment for a virtual machine. If the virtual machine has no vApp configuration, an empty string is returned. Also, sensitive information is omitted, so this method is not guaranteed to return the complete OVF environment. @since vSphere API 4.0

Parameters

NameTypeDescription
None

Return Value

Type Description
String

removeTag

Removes a set of tags from this object. @since vSphere API 4.0

Parameters

NameTypeDescription
arg0VcTag []


Return Value

Type Description
None

reconfigVM_Task

Reconfigures this virtual machine. All the changes in the given configuration are applied to the virtual machine as an atomic operation.

Reconfiguring the virtual machine may require any of the following privileges depending on what is being changed:

Creating a virtual machine may require the following privileges: In addition, this operation may require the following privileges: To create a VirtualDisk on a persistent memory storage, the storage must be specified via {@link vim.vm.device.VirtualDeviceSpec#profile profile} while the datastore property of corresponding VirtualDisk backing must be unset.

To create a VirtualNVDIMM device, the storage {@link vim.vm.device.VirtualDeviceSpec#profile profile} must be set to the default persistent memory storage profile while the datastore property of {@link vim.vm.device.VirtualNVDIMM#backing the device backing} must be unset.

@since VI API 2.5

Parameters

NameTypeDescription
arg0VcVirtualMachineConfigSpec


Return Value

Type Description
VcTask

terminateVM

Do an immediate power off of a VM.

This API issues a SIGKILL to the vmx process of the VM. Pending synchronous I/Os may not be written out before the vmx process dies depending on accessibility of the datastore.

@since vSphere API 5.0

Parameters

NameTypeDescription
None

Return Value

Type Description
None

destroy_Task

Destroys this object, deleting its contents and removing it from its parent folder (if any).

NOTE: The appropriate privilege must be held on the parent of the destroyed entity as well as the entity itself.

This method can throw one of several exceptions. The exact set of exceptions depends on the kind of entity that is being removed. See comments for each entity for more information on destroy behavior. @since VI API 2.5

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

defragmentAllDisks

Defragment all virtual disks attached to this virtual machine. @since VI API 2.5

Parameters

NameTypeDescription
None

Return Value

Type Description
None

shutdownGuest

Issues a command to the guest operating system asking it to perform a clean shutdown of all services. Returns immediately and does not wait for the guest operating system to complete the operation. @since VI API 2.5

Parameters

NameTypeDescription
None

Return Value

Type Description
None

terminateFaultTolerantVM_Task

Terminates the specified secondary virtual machine in a fault tolerant group. This can be used to test fault tolerance on a given virtual machine, and should be used with care. @since vSphere API 4.0

Parameters

NameTypeDescription
arg0VcVirtualMachine


Return Value

Type Description
VcTask

queryFaultToleranceCompatibilityEx

This API can be invoked to determine whether a virtual machine is compatible for Fault Tolerance. The API only checks for VM-specific factors that impact compatibility for Fault Tolerance. Other requirements for Fault Tolerance such as host processor compatibility, logging nic configuration and licensing are not covered by this API. The query returns a list of faults, each fault corresponding to a specific incompatibility. If a given virtual machine is compatible for Fault Tolerance, then the fault list returned will be empty. @since vSphere API 6.0

Parameters

NameTypeDescription
arg0Boolean


Return Value

Type Description
VcLocalizedMethodFault []

applyEvcModeVM_Task

Applies the EVC mode masks to the virtual machine. Existing masks will be replaced by the input masks. If the mask parameter is not set, then the masks on the virtual machine are removed.

This operation is only supported if {@link vim.vm.Capability#perVmEvcSupported} is true. @since vim unstable version

Parameters

NameTypeDescription
arg0VcHostFeatureMask []


Return Value

Type Description
VcTask

rebootGuest

Issues a command to the guest operating system asking it to perform a reboot. Returns immediately and does not wait for the guest operating system to complete the operation. @since VI API 2.5

Parameters

NameTypeDescription
None

Return Value

Type Description
None

resetGuestInformation

Clears cached guest information. Guest information can be cleared only if the virtual machine is powered off.

This method can be useful if stale information is cached, preventing an IP address or MAC address from being reused. @since VI API 2.5

Parameters

NameTypeDescription
None

Return Value

Type Description
None

createTrigger

@since Unknown

Parameters

NameTypeDescription
timeoutNumber

filterString

conditionString

filterToSyncString


Return Value

Type Description
Trigger

stopRecording_Task

Stops a currently active recording session on this virtual machine.

This is an experimental interface that is not intended for use in production code.

@since vSphere API 4.0

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

answerVM

Responds to a question that is blocking this virtual machine. @since VI API 2.5

Parameters

NameTypeDescription
arg0String

arg1String


Return Value

Type Description
None

stopReplaying_Task

Stops a replay session on this virtual machine.

This is an experimental interface that is not intended for use in production code.

@since vSphere API 4.0

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

createSnapshotEx_Task

Creates a new snapshot of this virtual machine. As a side effect, this updates the current snapshot.

Snapshots are not supported for Fault Tolerance primary and secondary virtual machines.

Any % (percent) character used in this name parameter must be escaped, unless it is used to start an escape sequence. Clients may also escape any other characters in this name parameter.

@since vSphere API 6.5

Parameters

NameTypeDescription
arg0String

arg1String

arg2Boolean

arg3VcVirtualMachineGuestQuiesceSpec


Return Value

Type Description
VcTask

resetVM_Task

Resets power on this virtual machine. If the current state is poweredOn, then this method first performs powerOff(hard). Once the power state is poweredOff, then this method performs powerOn(option).

Although this method functions as a powerOff followed by a powerOn, the two operations are atomic with respect to other clients, meaning that other power operations cannot be performed until the reset method completes. @since VI API 2.5

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

powerOffVM_Task

Powers off this virtual machine. If this virtual machine is a fault tolerant primary virtual machine, this will result in the secondary virtual machine(s) getting powered off as well. @since VI API 2.5

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

migrateVM_Task

Migrates a virtual machine's execution to a specific resource pool or host. This does not support cross-datacenter moves - call {@link vim.VirtualMachine#relocate} instead.

Requires Resource.HotMigrate privilege if the virtual machine is powered on or Resource.ColdMigrate privilege if the virtual machine is powered off or suspended. @since VI API 2.5

Parameters

NameTypeDescription
arg0VcResourcePool

arg1VcHostSystem

arg2VcVirtualMachineMovePriority

arg3VcVirtualMachinePowerState


Return Value

Type Description
VcTask

createSnapshot_Task

Creates a new snapshot of this virtual machine. As a side effect, this updates the current snapshot.

Snapshots are not supported for Fault Tolerance primary and secondary virtual machines.

Any % (percent) character used in this name parameter must be escaped, unless it is used to start an escape sequence. Clients may also escape any other characters in this name parameter.

@since VI API 2.5

Parameters

NameTypeDescription
arg0String

arg1String

arg2Boolean

arg3Boolean


Return Value

Type Description
VcTask

invokeFSR_Task

Initiate a fast-suspend-resume operation on the virtual machine. @since vSphere API 4.1

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

createForkChild_Task

Create a powered-off child of this virtual machine. The child will fork off from its parent when powering on and share both disk and memory with its parent virtual machine.

Only limited operations will be supported on both the parent and child virtual machines. Support is dependent on whether the virtual machine is a parent or a child and whether it's powered-on/off.

To create a child, {@link vim.vm.ForkConfigInfo#parentEnabled} property of this virtual machine must be true. When creating persistent children, additional requirements apply:

@since vSphere API 6.0

Parameters

NameTypeDescription
arg0String

arg1VcVirtualMachineCreateChildSpec


Return Value

Type Description
VcTask

reloadVirtualMachineFromPath_Task

Reloads the configuration for this virtual machine from a given datastore path. This is equivalent to unregistering and registering the virtual machine from a different path. The virtual machine's hardware configuration, snapshots, guestinfo variables etc. will be replaced based on the new configuration file. Other information associated with the virtual machine object, such as events and permissions, will be preserved.

This method is only supported on vCenter Server. It can be invoked on inaccessible or orphaned virtual machines, but it cannot be invoked on powered on, connected virtual machines. Both the source virtual machine object and the destination path should be of the same type i.e. virtual machine or template. Reloading a virtual machine with a template or vice-versa is not supported.

Note: Since the API replaces the source configuration with that of the destination, if the destination configuration does not refer to a valid virtual machine, it will create an invalid virtual machine object. This API should not be invoked on fault tolerant virtual machines since doing so will leave the original virtual machine's configuration in an invalid state. It is recommended that you turn off fault tolerance before invoking this API.

@since vSphere API 4.1

Parameters

NameTypeDescription
arg0String


Return Value

Type Description
VcTask

relocateVM_Task

Relocates a virtual machine's virtual disks to a specific location; optionally moves the virtual machine to a different host as well. Starting from VCenter 5.1, this API also supports relocating a template to a new host should the current host becomes inactive. If spec.host is specified, this API attempts to relocate the template to the specified host; otherwise, this API will select a suitable host. Starting from vCenter 6.0 this API also supports relocating a VM to a new vCenter service.

Additionally requires the Resource.HotMigrate privilege if the virtual machine is powered on (for Storage VMotion), and Datastore.AllocateSpace on any datastore the virtual machine or its disks are relocated to.

If the "pool" field of the RelocateSpec is set, additionally requires the Resource.AssignVMToPool privilege held on the specified pool.

If this virtual machine is configured with a VirtualNVDIMM device, and if the virtual machine will be moved to a different host, the VirtualNVDIMM will be automatically relocated to the destination host's Non-Volatile Memory storage. If this Virtual machine is configured with virtual disks via persistent memory storage profile:

If moving to a new vCenter service, additionally requires the VirtualMachine.Inventory.Create privilege on the destination folder and if changing the network requires the Network.Assign privilege on the new network. @since VI API 2.5

Parameters

NameTypeDescription
arg0VcVirtualMachineRelocateSpec

arg1VcVirtualMachineMovePriority


Return Value

Type Description
VcTask

disableSecondaryVM_Task

Disables the specified secondary virtual machine in this fault tolerant group. The specified secondary will not be automatically started on a subsequent power-on of the primary virtual machine. This operation could leave the primary virtual machine in a non-fault tolerant state. @since vSphere API 4.0

Parameters

NameTypeDescription
arg0VcVirtualMachine


Return Value

Type Description
VcTask

shrinkDisk_Task

This operation will remove all unused filesystem blocks of a virtual disk that were previously unmapped by a WipeDisk operation, and shrink the overall size of the virtual disk. The input for this operation is an array of disk ids for the virtual disks that the operation will be invoked against. If the API is invoked with a null input parameter, then all disks which are attached to the virtual machine will get shrunk. If an error occurs, a ShrinkDiskFault will be thrown. Operations that modify the state of the virtual machine will be disallowed while a shrinkDisk operation is in progress. @since vSphere API 5.1

Parameters

NameTypeDescription
arg0Number []


Return Value

Type Description
VcTask

setCustomValue

Assigns a value to a custom field. The setCustomValue method requires whichever updatePrivilege is defined as one of the {@link CustomFieldsManager.FieldDef#fieldInstancePrivileges} for the CustomFieldDef whose value is being changed. @since VI API 2.5

Parameters

NameTypeDescription
arg0String

arg1String


Return Value

Type Description
None

configureQuorumFilePathPrefix_Task

Configures the the quorum-file path prefix that will be used for breaking ties between virtual machines. The user of this feature must ensure that the VMs which use this facility have access to the datastore that hosts the file. By default, the file path prefix will not be carried over as part of operations that involve virtual machine relocation or creating a new virtual machine instance. @since vSphere API 5.0

Parameters

NameTypeDescription
arg0String


Return Value

Type Description
VcTask

customizeVM_Task

Customizes a virtual machine's guest operating system. @since VI API 2.5

Parameters

NameTypeDescription
arg0VcCustomizationSpec


Return Value

Type Description
VcTask

createScreenshot_Task

Create a screen shot of a virtual machine. @since vSphere API 4.0

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

upgradeVM_Task

Upgrades this virtual machine's virtual hardware to the latest revision that is supported by the virtual machine's current host. @since VI API 2.5

Parameters

NameTypeDescription
arg0String


Return Value

Type Description
VcTask

reloadEx_Task

Reload the virtual machine state. Clients only need to call this method if they changed some external state that affects the service without using Virtual Center to perform the change. For example, hand-editing a virtual machine configuration file affects the configuration of the associated virtual machine but the service managing the virtual machine might not monitor the file for changes. In this case, after such an edit, a client would call "reloadEx" on the associated virtual machine to ensure that Virtual Center and its clients have current data for the virtual machine. @since vim unstable version

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

checkCustomizationSpec

Checks the customization specification against the virtual machine configuration. For example, this is used on a source virtual machine before a clone operation to catch customization failure before the disk copy. This checks the specification's internal consistency as well as for compatibility with this virtual machine's configuration. @since VI API 2.5

Parameters

NameTypeDescription
arg0VcCustomizationSpec


Return Value

Type Description
None

promoteDisks_Task

Promotes disks on this virtual machine that have delta disk backings.

A delta disk backing is a way to preserve a virtual disk backing at some point in time. A delta disk backing is a file backing which in turn points to the original virtual disk backing (the parent). After a delta disk backing is added, all writes go to the delta disk backing. All reads first try the delta disk backing and then try the parent backing if needed.

Promoting does two things

  1. If the unlink parameter is true, any disk backing which is shared shared by multiple virtual machines is copied so that this virtual machine has its own unshared version. Copied files always end up in the virtual machine's home directory. To promote the disks of a powered on VM, the VM cannot have snapshots.
  2. Any disk backing which is not shared between multiple virtual machines and is not associated with a snapshot is consolidated with its child backing.

If the unlink parameter is true, the net effect of this operation is improved read performance, at the cost of disk space. If the unlink parameter is false the net effect is improved read performance at the cost of inhibiting future sharing.

This operation is only supported if {@link vim.host.Capability#deltaDiskBackingsSupported} is true.

This operation is only supported on VirtualCenter. If no work is required, an invocation completes successfully. @since vSphere API 4.0

Parameters

NameTypeDescription
arg0Boolean

arg1VcVirtualDisk []


Return Value

Type Description
VcTask

acquireTicket

Creates and returns a one-time credential used in establishing a specific connection to this virtual machine, for example, a ticket type of mks can be used to establish a remote mouse-keyboard-screen connection.

A client using this ticketing mechanism must have network connectivity to the ESX server where the virtual machine is running, and the ESX server must be reachable to the management client from the address made available to the client via the ticket.

Acquiring a virtual machine ticket requires different privileges depending on the types of ticket:

@since vSphere API 4.1

Parameters

NameTypeDescription
arg0String


Return Value

Type Description
VcVirtualMachineTicket

consolidateVMDisks_Task

Consolidate the virtual disk files of the virtual machine by finding hierarchies of redo logs that can be combined without violating data dependency. The redundant redo logs after merging are then deleted. Consolidation improves I/O performance since less number of virtual disk files need to be traversed; it also reduces the storage usage. However additional space is temporarily required to perform the operation. Use {@link vim.VirtualMachine#estimateStorageRequirementForConsolidate} to estimate the temporary space required. Consolidation can be I/O intensive, it is advisable to invoke this operation when guest is not under heavy I/O usage. @since vSphere API 5.0

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

turnOffFaultToleranceForVM_Task

Removes all secondary virtual machines associated with the fault tolerant group and turns off protection for this virtual machine. This operation can only be invoked from the primary virtual machine in the group. @since vSphere API 4.0

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

retrieveBackupAgent

The backup agent for the virtual machine. @since vSphere API 4.0

Parameters

NameTypeDescription
None

Return Value

Type Description
VcVirtualMachineBackupAgent

createSecondaryVMEx_Task

Creates a secondary virtual machine to be part of this fault tolerant group.

If a host is specified, the secondary virtual machine will be created on it. Otherwise, a host will be selected by the system.

If a FaultToleranceConfigSpec is specified, the virtual machine's configuration files and disks will be created in the specified datastores.

If the primary virtual machine (i.e., this virtual machine) is powered on when the secondary is created, an attempt will be made to power on the secondary on a system selected host. If the cluster is a DRS cluster, DRS will be invoked to obtain a placement for the new secondary virtual machine. If the DRS recommendation (see {@link vim.cluster.Recommendation}) is automatic, it will be automatically executed. Otherwise, the recommendation will be returned to the caller of this method and the secondary will remain powered off until the recommendation is approved using {@link ClusterComputeResource#applyRecommendation}. Failure to power on the secondary virtual machine will not fail the creation of the secondary. This method creates a Record-Replay FT VM for single vCPU VMs only when vm.useLegacyFt is set to true in vm.config.extraConfig. @since vSphere API 6.0

Parameters

NameTypeDescription
arg0VcHostSystem

arg1VcFaultToleranceConfigSpec


Return Value

Type Description
VcTask

exportVm

Obtains an export lease on this virtual machine. The export lease contains a list of URLs for the virtual disks for this virtual machine, as well as a ticket giving access to the URLs.

See {@link vim.HttpNfcLease} for information on how to use the lease. @since vSphere API 4.0

Parameters

NameTypeDescription
None

Return Value

Type Description
VcHttpNfcLease

cloneVM_Task

Creates a clone of this virtual machine. If the virtual machine is used as a template, this method corresponds to the deploy command.

Any % (percent) character used in this name parameter must be escaped, unless it is used to start an escape sequence. Clients may also escape any other characters in this name parameter.

The privilege required on the source virtual machine depends on the source and destination types:

If customization is requested in the CloneSpec, then the VirtualMachine.Provisioning.Customize privilege must also be held on the source virtual machine.

The Resource.AssignVMToPool privilege is also required for the resource pool specified in the CloneSpec, if the destination is not a template. The Datastore.AllocateSpace privilege is required on all datastores where the clone is created. @since VI API 2.5

Parameters

NameTypeDescription
arg0VcFolder

arg1String

arg2VcVirtualMachineCloneSpec


Return Value

Type Description
VcTask

mountToolsInstallerImage

Mounts the specified image as a CD-ROM for the guest operating system. To monitor the status of the tools install, clients should check the tools status, {@link vim.vm.GuestInfo#toolsVersionStatus} and {@link vim.vm.GuestInfo#toolsRunningStatus} @since vim unstable version

Parameters

NameTypeDescription
arg0VcVirtualDeviceBackingInfo

arg1VcGuestAuthentication


Return Value

Type Description
None

createSecondaryVM_Task

Creates a secondary virtual machine to be part of this fault tolerant group.

If a host is specified, the secondary virtual machine will be created on it. Otherwise, a host will be selected by the system.

If the primary virtual machine (i.e., this virtual machine) is powered on when the secondary is created, an attempt will be made to power on the secondary on a system selected host. If the cluster is a DRS cluster, DRS will be invoked to obtain a placement for the new secondary virtual machine. If the DRS recommendation (see {@link vim.cluster.Recommendation}) is automatic, it will be automatically executed. Otherwise, the recommendation will be returned to the caller of this method and the secondary will remain powered off until the recommendation is approved using {@link ClusterComputeResource#applyRecommendation}. Failure to power on the secondary virtual machine will not fail the creation of the secondary. @since vSphere API 4.0

Parameters

NameTypeDescription
arg0VcHostSystem


Return Value

Type Description
VcTask

retrieveQuorumFilePathPrefix

Retrieves the quorum file path prefix if one was configured. @since vSphere API 5.0

Parameters

NameTypeDescription
None

Return Value

Type Description
String

standbyGuest

Issues a command to the guest operating system asking it to prepare for a suspend operation. Returns immediately and does not wait for the guest operating system to complete the operation. @since VI API 2.5

Parameters

NameTypeDescription
None

Return Value

Type Description
None

detachDisk_Task

Detach a disk from this virtual machine. @since vSphere API 6.5

Parameters

NameTypeDescription
arg0VcID


Return Value

Type Description
VcTask

makePrimaryVM_Task

Makes the specified secondary virtual machine from this fault tolerant group as the primary virtual machine. @since vSphere API 4.0

Parameters

NameTypeDescription
arg0VcVirtualMachine


Return Value

Type Description
VcTask