Local Properties	Local Methods
Managed Object Types	Data Object Types	All Properties	All Methods

Managed Object - VirtualMachine(vim.VirtualMachine)

Property of

ApplyStorageRecommendationResult, AutoStartPowerInfo, CannotChangeDrsBehaviorForFtSecondary, CannotChangeHaSettingsForFtSecondary, CannotComputeFTCompatibleHosts, CannotPowerOffVmInCluster, CheckResult, ClusterAffinityRuleSpec, ClusterAntiAffinityRuleSpec, ClusterAttemptedVmInfo, ClusterDasFailoverLevelAdvancedRuntimeInfoVmSlots, ClusterDasVmConfigInfo, ClusterDrsFaultsFaultsByVm, ClusterDrsMigration, ClusterDrsVmConfigInfo, ClusterNotAttemptedVmInfo, ClusterPreemptibleVmPairInfo, ClusterVmGroup, ClusterVmOrchestrationInfo, CryptoManagerKmipCryptoKeyStatus, Datastore, DVSSummary, DvsVnicAllocatedResource, FailToLockFaultToleranceVMs, FaultsByVM, FaultToleranceCannotEditMem, FaultTolerancePrimaryConfigInfo, FaultTolerancePrimaryPowerOnNotAttempted, FaultToleranceSecondaryConfigInfo, FaultToleranceSecondaryOpResult, FaultToleranceVmNotDasProtected, FeatureRequirementsNotMet, HbrManagerVmReplicationCapability, HostAssignableHardwareBinding, HostGraphicsInfo, HostPlacedVirtualNicIdentifier, HostSystem, HostVmciAccessManagerAccessSpec, InvalidDasRestartPriorityForFtVm, InvalidDrsBehaviorForFtVm, InvalidVmState, MountError, Network, NoHostSuitableForFtSecondary, NotSupportedDeviceForFT, PlacementAction, PlacementAffinityRule, PlacementSpec, PowerOnFtSecondaryFailed, PowerOnFtSecondaryTimedout, ReplicationDiskConfigFault, ReplicationVmConfigFault, ReplicationVmFault, ResourcePool, SourceNodeSpec, StorageDrsVmConfigInfo, StorageMigrationAction, StoragePlacementAction, StoragePlacementSpec, VirtualDiskId, VirtualMachineDiskDeviceInfo, VirtualMachineSnapshot, VirtualMachineSnapshotTree, VirtualMachineSummary, VmAlreadyExistsInDatacenter, VmEventArgument, VmWwnConflict

Parameter to

AbortCustomization_Task, AcquireCredentialsInGuest, AddGuestAlias, ChangeFileAttributesInGuest, CheckClone_Task, CheckCompatibility_Task, CheckInstantClone_Task, CheckMigrate_Task, CheckPowerOn_Task, CheckRelocate_Task, CheckVmConfig_Task, CreateRegistryKeyInGuest, CreateTemporaryDirectoryInGuest, CreateTemporaryFileInGuest, CustomizeGuest_Task, DeleteDirectoryInGuest, DeleteFileInGuest, DeleteRegistryKeyInGuest, DeleteRegistryValueInGuest, DisableSecondaryVM_Task, EnableSecondaryVM_Task, FindRulesForVm, InitiateFileTransferFromGuest, InitiateFileTransferToGuest, ListFilesInGuest, ListGuestAliases, ListGuestMappedAliases, ListProcessesInGuest, ListRegistryKeysInGuest, ListRegistryValuesInGuest, LookupVmOverheadMemory, MakeDirectoryInGuest, MakePrimaryVM_Task, MoveDirectoryInGuest, MoveFileInGuest, PowerOnMultiVM_Task, QueryVMotionCompatibility, QueryVMotionCompatibilityEx_Task, ReadEnvironmentVariableInGuest, RecommendHostsForVm, ReleaseCredentialsInGuest, RemoveGuestAlias, RemoveGuestAliasByCert, SetRegistryValueInGuest, StartGuestNetwork_Task, StartProgramInGuest, TerminateFaultTolerantVM_Task, TerminateProcessInGuest, ValidateCredentialsInGuest, ValidateMigration

Returned by

CloneVM_Task, CreateChildVM_Task, CreateVM_Task, FindByDatastorePath, InstantClone_Task, RegisterChildVM_Task, RegisterVM_Task

Extends

ManagedEntity

See also

CustomizationSpec, Datastore, DiskChangeInfo, EnvironmentBrowser, FaultToleranceConfigSpec, FaultToleranceSecondaryOpResult, Folder, GuestInfo, HostFeatureMask, HostSystem, HttpNfcLease, ID, ManagedEntity, ManagedEntityStatus, MethodFault, Network, ResourceConfigSpec, ResourcePool, SnapshotSelectionSpec, StorageRequirement, UsbScanCodeSpec, VirtualDisk, VirtualMachineCapability, VirtualMachineCloneSpec, VirtualMachineConfigInfo, VirtualMachineConfigSpec, VirtualMachineConnection, VirtualMachineDisplayTopology, VirtualMachineFileLayout, VirtualMachineFileLayoutEx, VirtualMachineGuestQuiesceSpec, VirtualMachineInstantCloneSpec, VirtualMachineMksTicket, VirtualMachineMovePriority, VirtualMachinePowerState, VirtualMachineRelocateSpec, VirtualMachineRuntimeInfo, VirtualMachineSnapshot, VirtualMachineSnapshotInfo, VirtualMachineStorageInfo, VirtualMachineSummary, VirtualMachineTicket

Since

2.0

Managed 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.

Properties

Name	Type	Description
capability	VirtualMachineCapability	Information about the runtime capabilities of this virtual machine.
config*	VirtualMachineConfigInfo	Configuration of this virtual machine, including the name and UUID. This property is set when a virtual machine is created or when the ReconfigVM_Task method is called. The virtual machine configuration is not guaranteed to be available. For example, the configuration information would be unavailable if the server is unable to access the virtual machine files on disk, and is often also unavailable during the initial phases of virtual machine creation.
datastore* P	ManagedObjectReference[] to a Datastore[]	A collection of references to the subset of datastore objects in the datacenter that is used by this virtual machine.
environmentBrowser	ManagedObjectReference to a EnvironmentBrowser	The current virtual machine's environment browser object. This contains information on all the configurations that can be used on the virtual machine. This is identical to the environment browser on the ComputeResource to which this virtual machine belongs.
guest*	GuestInfo	Information about VMware Tools and about the virtual machine from the perspective of VMware Tools. Information about the guest operating system is available in VirtualCenter. Guest operating system information reflects the last known state of the virtual machine. For powered on machines, this is current information. For powered off machines, this is the last recorded state before the virtual machine was powered off.
guestHeartbeatStatus	ManagedEntityStatus	The guest heartbeat. The heartbeat status is classified as: gray - VMware Tools are not installed or not running. red - No heartbeat. Guest operating system may have stopped responding. yellow - Intermittent heartbeat. May be due to guest load. green - Guest operating system is responding normally. The guest heartbeat is a statistics metric. Alarms can be configured on this metric to trigger emails or other actions.
layout*	VirtualMachineFileLayout	Deprecated. As of vSphere API 4.0, use LayoutEx instead. In releases after vSphere API 5.0, vSphere Servers might not generate property collector update notifications for this property. To obtain the latest value of the property, you can use PropertyCollector methods RetrievePropertiesEx or WaitForUpdatesEx. If you use the PropertyCollector.WaitForUpdatesEx method, specify an empty string for the version parameter. Any other version value will not produce any property values as no updates are generated. Detailed information about the files that comprise this virtual machine.
layoutEx*	VirtualMachineFileLayoutEx	Detailed information about the files that comprise this virtual machine. Can be explicitly refreshed by the RefreshStorageInfo operation. In releases after vSphere API 5.0, vSphere Servers might not generate property collector update notifications for this property. To obtain the latest value of the property, you can use PropertyCollector methods RetrievePropertiesEx or WaitForUpdatesEx. If you use the PropertyCollector.WaitForUpdatesEx method, specify an empty string for the version parameter. Any other version value will not produce any property values as no updates are generated. Since vSphere API Release 4.0
network* P	ManagedObjectReference[] to a Network[]	A collection of references to the subset of network objects in the datacenter that is used by this virtual machine.
parentVApp*	ManagedObjectReference to a ManagedEntity	Reference to the parent vApp. Since vSphere API Release 4.1
resourceConfig*	ResourceConfigSpec	The resource configuration for a virtual machine. The shares in this specification are evaluated relative to the resource pool to which it is assigned. This will return null if the product the virtual machine is registered on does not support resource configuration. To retrieve the configuration, you typically use ChildConfiguration. To change the configuration, use UpdateChildResourceConfiguration.
resourcePool*	ManagedObjectReference to a ResourcePool	The current resource pool that specifies resource allocation for this virtual machine. This property is set when a virtual machine is created or associated with a different resource pool. Returns null if the virtual machine is a template or the session has no access to the resource pool.
rootSnapshot*	ManagedObjectReference[] to a VirtualMachineSnapshot[]	The roots of all snapshot trees for the virtual machine. Since vSphere API Release 4.1
runtime	VirtualMachineRuntimeInfo	Execution state and history for this virtual machine. The contents of this property change when: the virtual machine's power state changes. an execution message is pending. an event occurs.
snapshot*	VirtualMachineSnapshotInfo	Current snapshot and tree. The property is valid if snapshots have been created for this virtual machine. The contents of this property change in response to the methods: CreateSnapshot_Task RevertToCurrentSnapshot_Task RemoveSnapshot_Task RevertToSnapshot_Task RemoveAllSnapshots_Task
storage*	VirtualMachineStorageInfo	Storage space used by the virtual machine, split by datastore. Can be explicitly refreshed by the RefreshStorageInfo operation. In releases after vSphere API 5.0, vSphere Servers might not generate property collector update notifications for this property. To obtain the latest value of the property, you can use PropertyCollector methods RetrievePropertiesEx or WaitForUpdatesEx. If you use the PropertyCollector.WaitForUpdatesEx method, specify an empty string for the version parameter. Any other version value will not produce any property values as no updates are generated. Since vSphere API Release 4.0
summary	VirtualMachineSummary	Basic information about this virtual machine. This includes: runtimeInfo guest basic configuration alarms performance information
Properties inherited from ManagedEntity
alarmActionsEnabled, configIssue, configStatus, customValue, declaredAlarmState, disabledMethod, effectiveRole, name, overallStatus, parent, permission, recentTask, tag, triggeredAlarmState
Properties inherited from ExtensibleManagedObject
availableField, value

*May not be presentP Required privilege: System.View

Methods

Methods defined in this Managed Object
AcquireMksTicket, AcquireTicket, AnswerVM, ApplyEvcModeVM_Task, AttachDisk_Task, CheckCustomizationSpec, CloneVM_Task, ConsolidateVMDisks_Task, CreateScreenshot_Task, CreateSecondaryVM_Task, CreateSecondaryVMEx_Task, CreateSnapshot_Task, CreateSnapshotEx_Task, CryptoUnlock_Task, CustomizeVM_Task, DefragmentAllDisks, DetachDisk_Task, DisableSecondaryVM_Task, DropConnections, EnableSecondaryVM_Task, EstimateStorageForConsolidateSnapshots_Task, ExportVm, ExtractOvfEnvironment, InstantClone_Task, MakePrimaryVM_Task, MarkAsTemplate, MarkAsVirtualMachine, MigrateVM_Task, MountToolsInstaller, PowerOffVM_Task, PowerOnVM_Task, PromoteDisks_Task, PutUsbScanCodes, QueryChangedDiskAreas, QueryConnections, QueryFaultToleranceCompatibility, QueryFaultToleranceCompatibilityEx, QueryUnownedFiles, RebootGuest, ReconfigVM_Task, RefreshStorageInfo, reloadVirtualMachineFromPath_Task, RelocateVM_Task, RemoveAllSnapshots_Task, ResetGuestInformation, ResetVM_Task, RevertToCurrentSnapshot_Task, SendNMI, SetDisplayTopology, SetScreenResolution, ShutdownGuest, StandbyGuest, StartRecording_Task, StartReplaying_Task, StopRecording_Task, StopReplaying_Task, SuspendVM_Task, TerminateFaultTolerantVM_Task, TerminateVM, TurnOffFaultToleranceForVM_Task, UnmountToolsInstaller, UnregisterVM, UpgradeTools_Task, UpgradeVM_Task
Methods inherited from ManagedEntity
Destroy_Task, Reload, Rename_Task
Methods inherited from ExtensibleManagedObject
setCustomValue

AcquireMksTicket(acquireMksTicket)

Deprecated. As of vSphere API 4.1, use AcquireTicket instead.

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.

Required Privileges

VirtualMachine.Interact.ConsoleInteract

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
VirtualMachineMksTicket	A one-time credential used in establishing a remote mouse-keyboard-screen connection.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

AcquireTicket(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:

• VirtualMachine.Interact.DeviceConnection if requesting a device ticket.
• VirtualMachine.Interact.GuestControl if requesting a guestControl or guestIntegrity ticket.
• VirtualMachine.Interact.ConsoleInteract if requesting an mks or webmks ticket.
• VirtualMachine.Interact.DnD if requesting a drag and drop ticket.

Required Privileges

None

Since

vSphere API Release 4.1

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
ticketType	xsd:string	The type of service to acquire, the set of possible values is described in VirtualMachineTicketType. Since vSphere API Release 4.1

Return Value

Type	Description
VirtualMachineTicket	A one-time credential used in establishing a remote connection to this virtual machine.

Faults

Type	Description
InvalidState	Thrown if the virtual machine is not connected.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

AnswerVM(answer)

Responds to a question that is blocking this virtual machine.

Required Privileges

VirtualMachine.Interact.AnswerQuestion

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
questionId	xsd:string	The value from QuestionInfo.id that identifies the question to answer. Since 2.0
answerChoice	xsd:string	The contents of the QuestionInfo.choice.value array element that identifies the desired answer. Since 2.0

Return Value

Type	Description
None

Faults

Type	Description
ConcurrentAccess	Thrown if the question has been or is being answered by another thread or user.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

ApplyEvcModeVM_Task(applyEvcMode)

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. See featureMask for the list of masks to provide. These can be retrieved from supportedEVCMode, which is accessible in Capability.

This operation is only supported if perVmEvcSupported is true.

Required Privileges

VirtualMachine.Config.Settings

Since

vSphere API Release 6.7

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
mask*	HostFeatureMask[]	The feature masks to apply to the virtual machine. An empty set of masks will clear EVC settings. Since vSphere API Release 6.7
completeMasks*	xsd:boolean	Defaults to true if not set. A true value implies that any unspecified feature will not be exposed to the guest. A false value will expose any unspecified feature to the guest with the value of the host. Since vSphere API Release 6.7

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a SmsTask

Faults

Type	Description
InvalidPowerState	Thrown if the power state is not poweredOff.
InvalidState
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

AttachDisk_Task(attachDisk)

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 DeviceUnsupportedForVmVersion fault will be thrown.

Required Privileges

VirtualMachine.Config.AddExistingDisk

Since

vSphere API Release 6.5

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
diskId	ID	The ID of the virtual disk to be operated. See ID Since vSphere API Release 6.5
datastore	ManagedObjectReference to a Datastore	The datastore where the virtual disk is located. Since vSphere API Release 6.5
controllerKey*	xsd:int	Key of the controller the disk will connect to. It can be unset if there is only one controller (SCSI or SATA) with the available slot in the virtual machine. If there are multiple SCSI or SATA controllers available, user must specify the controller; if there is no available controllers, a MissingController fault will be thrown. Since vSphere API Release 6.5
unitNumber*	xsd:int	The unit number of the attached disk on its controller. If unset, the next available slot on the specified controller or the only available controller will be assigned to the attached disk. Since vSphere API Release 6.5

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a SmsTask

Faults

Type	Description
DeviceUnsupportedForVmVersion	Thrown if the virtual machine's version is incompatible for the given device.
FileFault	Thrown if there is a problem creating or accessing the virtual machine's files for this operation.
InvalidController	Thrown if the specified controller cannot be found or the specified unitNumber is already taken, or the controller has no free slots.
InvalidDatastore	Thrown if the datastore cannot be found or inaccessible.
InvalidState	Thrown if the operation cannot be performed in the current state of the virtual machine. For example, because the virtual machine's configuration is not available.
MissingController	Thrown if the virtual machine has no or more than one available controllers when controllerKey is unset.
NotFound	Thrown if the disk object cannot be found.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
VmConfigFault	Thrown if the virtual machine's configuration is invalid.

Events

Type
None

CheckCustomizationSpec(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.

Required Privileges

VirtualMachine.Provisioning.Customize

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
spec	CustomizationSpec	The customization specification to check. Since 2.0

Return Value

Type	Description
None

Faults

Type	Description
CustomizationFault	A subclass of CustomizationFault is thrown.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

CloneVM_Task(clone)

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:

• source is virtual machine, destination is virtual machine - VirtualMachine.Provisioning.Clone
• source is virtual machine, destination is template - VirtualMachine.Provisioning.CreateTemplateFromVM
• source is template, destination is virtual machine - VirtualMachine.Provisioning.DeployTemplate
• source is template, destination is template - VirtualMachine.Provisioning.CloneTemplate
• source is encrypted virtual machine - Cryptographer.Clone

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.

Required Privileges

None

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
folder P	ManagedObjectReference to a Folder	The location of the new virtual machine. Since 2.0
name	xsd:string	The name of the new virtual machine. Since 2.0
spec	VirtualMachineCloneSpec	Specifies how to clone the virtual machine. The folder specified in the spec takes precedence over the folder parameter. Since 2.0

P Required privilege: VirtualMachine.Inventory.CreateFromExisting

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation. The result property in the Task contains the newly added VirtualMachine upon success.

Faults

Type	Description
CustomizationFault	Thrown if a customization error happens. Typically, a specific subclass of this exception is thrown.
FileFault	Thrown if there is an error accessing the virtual machine files.
InsufficientResourcesFault	Thrown if this operation would violate a resource usage policy.
InvalidDatastore	Thrown if the operation cannot be performed on the target datastores.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state. For example, if the virtual machine configuration information is not available.
MigrationFault	Thrown if it is not possible to migrate the virtual machine to the destination host. This is typically due to hosts being incompatible, such as mismatch in network polices or access to networks and datastores. Typically, a more specific subclass is thrown.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.
VmConfigFault	Thrown if the virtual machine is not compatible with the destination host. Typically, a specific subclass of this exception is thrown, such as IDEDiskNotSupported.

Events

Type
None

ConsolidateVMDisks_Task(consolidateDisks)

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 EstimateStorageForConsolidateSnapshots_Task 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.

Required Privileges

VirtualMachine.State.RemoveSnapshot

Since

vSphere API Release 5.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
FileFault	Thrown if if there is a problem creating or accessing the virtual machine's files for this operation. Typically a more specific fault for example NoDiskSpace is thrown.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state. For example, if the virtual machine configuration information is not available.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.
VmConfigFault	Thrown if a virtual machine configuration issue prevents consolidation. Typically, a more specific fault is thrown such as InvalidDiskFormat if a disk cannot be read, or InvalidSnapshotFormat if the snapshot configuration is invalid.

Events

Type
None

CreateScreenshot_Task(createScreenshot)

Create a screen shot of a virtual machine.

Required Privileges

VirtualMachine.Interact.CreateScreenshot

Since

vSphere API Release 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
ManagedObjectReference to a SmsTask

Faults

Type	Description
FileFault	Thrown if there is a problem with creating or accessing one or more files needed for this operation.
InvalidPowerState	Thrown if the virtual machine is not powered on.
InvalidState	Thrown if the virtual machine is not ready to respond to such requests.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.

Events

Type
None

CreateSecondaryVM_Task(createSecondary)

Deprecated. As of vSphere API 6.0, use CreateSecondaryVMEx_Task instead.

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 ClusterRecommendation) 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 ApplyRecommendation. Failure to power on the secondary virtual machine will not fail the creation of the secondary.

Required Privileges

VirtualMachine.Interact.CreateSecondary

Since

vSphere API Release 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
host*	ManagedObjectReference to a HostSystem	The host where the secondary virtual machine is to be created and powered on. If no host is specified, a compatible host will be selected by the system. If a host cannot be found for the secondary or the specified host is not suitable, the secondary will not be created and a fault will be returned. Since vSphere API Release 4.0

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation. The result property in the Task returns an instance of the FaultToleranceSecondaryOpResult data object, which contains a reference to the created VirtualMachine and the status of powering it on, if attempted.

Faults

Type	Description
FileFault	Thrown if there is a problem accessing the virtual machine on the filesystem.
InsufficientResourcesFault	Thrown if this operation would violate a resource usage policy.
InvalidState	Thrown if the virtual machine's configuration information is not available.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.
VmConfigFault	Thrown if a configuration issue prevents creating the secondary. Typically, a more specific fault such as VmConfigIncompatibleForFaultTolerance is thrown.
VmFaultToleranceIssue	Thrown if any error is encountered with the fault tolerance configuration of the virtual machine. Typically, a more specific fault like FaultToleranceNotLicensed is thrown.

Events

Type
None

CreateSecondaryVMEx_Task(createSecondaryEx)

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 ClusterRecommendation) 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 ApplyRecommendation. Failure to power on the secondary virtual machine will not fail the creation of the secondary.

Required Privileges

VirtualMachine.Interact.CreateSecondary

Since

vSphere API Release 6.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
host*	ManagedObjectReference to a HostSystem	The host where the secondary virtual machine is to be created and powered on. If no host is specified, a compatible host will be selected by the system. If a host cannot be found for the secondary or the specified host is not suitable, the secondary will not be created and a fault will be returned. Since vSphere API Release 6.0
spec*	FaultToleranceConfigSpec	This parameter FaultToleranceVMConfigSpec can be used to specify the storage location of the fault tolerance tie-breaker file, secondary configuration file and secondary disks. If the virtual machine is on a vSAN datastore, then the Fault Tolerance secondary virtual machine and the tie-breaker file also have to be placed on that same vSAN datastore. Conversely, if a primary VM is not using vSAN datastore, then its Fault Tolerance secondary virtual machine can not be placed on a vSAN datastore. Fault Tolerance is not supported for VMs that are using both vSAN and non-vSAN datastores for its configuration and disks. If the virtual machine is using persistent memory for any of its disks, then its corresponding secondary disk placement entry should not be specified in the FaultToleranceVMConfigSpec. The system will automatically place the corresponding secondary disk on persistent memory. Since vSphere API Release 6.0

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation. The result property in the Task returns an instance of the FaultToleranceSecondaryOpResult data object, which contains a reference to the created VirtualMachine and the status of powering it on, if attempted.

Faults

Type	Description
FileFault	Thrown if there is a problem accessing the virtual machine on the filesystem.
InsufficientResourcesFault	Thrown if this operation would violate a resource usage policy.
InvalidState	Thrown if the virtual machine's configuration information is not available.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.
VmConfigFault	Thrown if a configuration issue prevents creating the secondary. Typically, a more specific fault such as VmConfigIncompatibleForFaultTolerance is thrown.
VmFaultToleranceIssue	Thrown if any error is encountered with the fault tolerance configuration of the virtual machine. Typically, a more specific fault like FaultToleranceNotLicensed is thrown.

Events

Type
None

CreateSnapshot_Task(createSnapshot)

Deprecated. As of vSphere 8.0GA, this method is deprecated. Please use CreateSnapshotEx_Task instead.

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.

Required Privileges

VirtualMachine.State.CreateSnapshot

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
name	xsd:string	The name for this snapshot. The name need not be unique for this virtual machine. Since 2.0
description*	xsd:string	A description for this snapshot. If omitted, a default description may be provided. Since 2.0
memory	xsd:boolean	If TRUE, a dump of the internal state of the virtual machine (basically a memory dump) is included in the snapshot. Memory snapshots consume time and resources, and thus take longer to create. When set to FALSE, the power state of the snapshot is set to powered off. capabilities indicates whether or not this virtual machine supports this operation. For a virtual machine in suspended state we always include memory unless diskOnlySnapshotOnSuspendedVMSupported is true. Since 2.0
quiesce	xsd:boolean	If TRUE and the virtual machine is powered on when the snapshot is taken, VMware Tools is used to quiesce the file system in the virtual machine. This assures that a disk snapshot represents a consistent state of the guest file systems. If the virtual machine is powered off or VMware Tools are not available, the quiesce flag is ignored. Since 2.0

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation. The result property in the Task contains the newly created VirtualMachineSnapshot upon success.

Faults

Type	Description
FileFault	Thrown if there is a problem with creating or accessing one or more files needed for this operation.
InvalidName	Thrown if the specified snapshot name is invalid.
InvalidPowerState	Thrown if the operation cannot be performed in the current power state of the virtual machine.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state. For example, the virtual machine configuration information is not available.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
SnapshotFault	Thrown if an error occurs during the snapshot operation. Typically a more specific fault like MultipleSnapshotsNotSupported is thrown.
TaskInProgress	Thrown if the virtual machine is busy.
VmConfigFault	Thrown if the virtual machine's configuration is invalid. Typically, a more specific fault like InvalidSnapshotState is thrown.

Events

Type
None

CreateSnapshotEx_Task(createSnapshotEx)

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.

Required Privileges

VirtualMachine.State.CreateSnapshot

Since

vSphere API Release 6.5

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
name	xsd:string	The name for this snapshot. The name need not be unique for this virtual machine. Since vSphere API Release 6.5
description*	xsd:string	A description for this snapshot. If omitted, a default description may be provided. Since vSphere API Release 6.5
memory	xsd:boolean	If TRUE, a dump of the internal state of the virtual machine (basically a memory dump) is included in the snapshot. Memory snapshots consume time and resources, and thus take longer to create. When set to FALSE, the power state of the snapshot is set to powered off. capabilities indicates whether or not this virtual machine supports this operation. For a virtual machine in suspended state we always include memory unless diskOnlySnapshotOnSuspendedVMSupported is true. Since vSphere API Release 6.5
quiesceSpec*	VirtualMachineGuestQuiesceSpec	Spec for granular control over quiesce details. If quiesceSpec is set and the virtual machine is powered on when the snapshot is taken, VMware Tools is used to quiesce the file system in the virtual machine. This assures that a disk snapshot represents a consistent state of the guest file systems. If the virtual machine is powered off or VMware Tools are not available, the quiesce spec is ignored. If the spec type is VirtualMachineGuestQuiesceSpec, the default quiescing process will be applied. If the spec type is VirtualMachineWindowsQuiesceSpec and Guest OS is Windows, the parameters will control the VSS process. Since vSphere API Release 6.5

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation. The result property in the Task contains the newly created VirtualMachineSnapshot upon success.

Faults

Type	Description
FileFault	Thrown if there is a problem with creating or accessing one or more files needed for this operation.
InvalidName	Thrown if the specified snapshot name is invalid.
InvalidPowerState	Thrown if the operation cannot be performed in the current power state of the virtual machine.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state. For example, the virtual machine configuration information is not available.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
SnapshotFault	Thrown if an error occurs during the snapshot operation. Typically a more specific fault like MultipleSnapshotsNotSupported is thrown.
TaskInProgress	Thrown if the virtual machine is busy.
VmConfigFault	Thrown if the virtual machine's configuration is invalid. Typically, a more specific fault like InvalidSnapshotState is thrown.

Events

Type
None

CryptoUnlock_Task(cryptoUnlock)

Unlocks an encrypted virtual machine by sending the encryption keys for the Virtual Machine Home and all the Virtual Disks to the ESX Server.

Required Privileges

Cryptographer.RegisterVM

Since

vSphere API Release 6.7

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
ManagedObjectReference to a SmsTask

Faults

Type	Description
InvalidState	when the required Key Management Server is not configured.
InvalidVmState	when the virtual machine failed to unlock.
NotSupported	Thrown if the ESX server doesn't support encryption.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

CustomizeVM_Task(customize)

Customizes a virtual machine's guest operating system.

Required Privileges

VirtualMachine.Provisioning.Customize

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
spec	CustomizationSpec	The customization specification object. Since 2.0

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
CustomizationFault	A subclass of CustomizationFault is thrown.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

DefragmentAllDisks(defragmentAllDisks)

Defragment all virtual disks attached to this virtual machine.

Required Privileges

VirtualMachine.Interact.DefragmentAllDisks

Since

VI API 2.5

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
FileFault	Thrown if there is an error accessing the disk files.
InvalidPowerState	Thrown if the virtual machine is poweredOn.
InvalidState	Thrown if the virtual machine is not connected.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.

Events

Type
None

Show WSDL type definition

DetachDisk_Task(detachDisk)

Detach a disk from this virtual machine.

Required Privileges

VirtualMachine.Config.RemoveDisk

Since

vSphere API Release 6.5

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
diskId	ID	The ID of the virtual disk to be operated. See ID Since vSphere API Release 6.5

Return Value

Type	Description
ManagedObjectReference to a SmsTask

Faults

Type	Description
FileFault	Thrown if there is a problem creating or accessing the virtual machine's files for this operation.
InvalidState	Thrown if the operation cannot be performed in the current state of the virtual machine. For example, because the virtual machine's configuration is not available.
NotFound	Thrown if the disk object cannot be found.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
VmConfigFault	Thrown if the virtual machine's configuration is invalid.

Events

Type
None

DisableSecondaryVM_Task(disableSecondary)

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.

Required Privileges

VirtualMachine.Interact.DisableSecondary

Since

vSphere API Release 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
vm	ManagedObjectReference to a VirtualMachine	The secondary virtual machine specified will be disabed. This field must specify a secondary virtual machine that is part of the fault tolerant group that this virtual machine is currently associated with. It can only be invoked from the primary virtual machine in the group. Since vSphere API Release 4.0

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
InvalidState	Thrown if the host is in maintenance mode or if the virtual machine's configuration information is not available.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.
VmFaultToleranceIssue	Thrown if any error is encountered with the fault tolerance configuration of the virtual machine. Typically, a more specific fault like InvalidOperationOnSecondaryVm is thrown.

Events

Type
None

DropConnections(dropConnections)

Force the virtual machine to drop the specified connections. Attempt to drop the specified virtual machine connections. An attempt will be made to drop all of the specified connections before returning.

Required Privileges

VirtualMachine.Interact.ConsoleInteract

Since

vSphere API Release 7.0.1.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
listOfConnections*	VirtualMachineConnection[]	Since vSphere API Release 7.0.1.0

*Need not be set

Return Value

Type	Description
xsd:boolean	true All of the specified connections have been dropped.

Faults

Type	Description
InvalidPowerState	Thrown if the virtual machine is not powered on. No connection drop actions will have been attempted if this is thrown.
InvalidState
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

EnableSecondaryVM_Task(enableSecondary)

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 DisableSecondaryVM_Task 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 ClusterRecommendation) 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 ApplyRecommendation.

Required Privileges

VirtualMachine.Interact.EnableSecondary

Since

vSphere API Release 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
vm	ManagedObjectReference to a VirtualMachine	The secondary virtual machine specified will be enabled. This field must specify a secondary virtual machine that is part of the fault tolerant group that this virtual machine is currently associated with. It can only be invoked from the primary virtual machine in the group. Since vSphere API Release 4.0
host*	ManagedObjectReference to a HostSystem	The host on which the secondary virtual machine is to be enabled and possibly powered on. If no host is specified, a compatible host will be selected by the system. If the secondary virtual machine is not compatible with the specified host, the secondary will not be re-enabled and a fault will be returned. Since vSphere API Release 4.0

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation. The result property in the Task returns an instance of the FaultToleranceSecondaryOpResult data object, which contains a reference to the VirtualMachine and the status of powering it on, if attempted.

Faults

Type	Description
InvalidState	Thrown if the virtual machine's configuration information is not available, if the secondary virtual machine is not disabled, or if a power-on is attempted and one is already in progress.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.
VmConfigFault	Thrown if a configuration issue prevents enabling the secondary. Typically, a more specific fault such as VmConfigIncompatibleForFaultTolerance is thrown.
VmFaultToleranceIssue	Thrown if any error is encountered with the fault tolerance configuration of the virtual machine. Typically, a more specific fault like InvalidOperationOnSecondaryVm is thrown.

Events

Type
None

EstimateStorageForConsolidateSnapshots_Task(estimateStorageRequirementForConsolidate)

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 ConsolidateVMDisks_Task.

Required Privileges

VirtualMachine.State.RemoveSnapshot

Since

vSphere API Release 5.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
FileFault	Thrown if if there is a problem accessing the virtual machine's files for this operation. Typically a more specific fault FileLocked is thrown.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state. For example, if the virtual machine configuration information is not available.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.
VmConfigFault	Thrown if a virtual machine configuration issue prevents the estimation. Typically, a more specific fault is thrown.

Events

Type
None

ExportVm(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 HttpNfcLease for information on how to use the lease.

Required Privileges

VApp.Export

Since

vSphere API Release 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
ManagedObjectReference to a HttpNfcLease	The export lease on this VirtualMachine. The export task continues running until the lease is completed by the caller.

Faults

Type	Description
FileFault	Thrown if there is an error accessing the virtual machine files.
InvalidPowerState	Thrown if the virtual machine is powered on.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state. For example, if the virtual machine configuration information is not available.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.

Events

Type
None

Show WSDL type definition

ExtractOvfEnvironment(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.

Required Privileges

VApp.ExtractOvfEnvironment

Since

vSphere API Release 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
xsd:string

Faults

Type	Description
InvalidState	Thrown if the virtual machine is not running
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

InstantClone_Task(instantClone)

Creates a powered-on Instant Clone of a virtual machine. The new virtual machine will be created on the same host and start with the identical running point as the original virtual machine, sharing memory state when possible and sharing disk state. The original virtual machine must be in a powered-on state. The privilege required for Instant Clone operation are:

• VirtualMachine.Provisioning.Clone
• VirtualMachine.Interact.PowerOn
• VirtualMachine.Inventory.CreateFromExisting
• Datastore.AllocateSpace
• Resource.AssignVMToPool

Required Privileges

VirtualMachine.Provisioning.Clone

Since

vSphere API Release 6.7

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
spec	VirtualMachineInstantCloneSpec	Is a VirtualMachineInstantCloneSpec. It specifies the cloned virtual machine's configuration. Since vSphere API Release 6.7

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
DisallowedMigrationDeviceAttached	Thrown if any of the devices attached to the source virtual machine are not supported for the Instant Clone operation or if device change specification contains changes that are not supported.
FileFault	Thrown if there is an error accessing the virtual machine files.
InsufficientResourcesFault	Thrown if this operation would violate a resource usage policy.
InvalidDatastore	Thrown if the operation cannot be performed on the target datastores.
InvalidState	Thrown if the operation cannot be performed because of the host or virtual machine's current state. For example, if the host is in maintenance mode or if the source virtual machine is not powered on.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress

Events

Type
None

MakePrimaryVM_Task(makePrimary)

Makes the specified secondary virtual machine from this fault tolerant group as the primary virtual machine.

Required Privileges

VirtualMachine.Interact.MakePrimary

Since

vSphere API Release 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
vm	ManagedObjectReference to a VirtualMachine	The secondary virtual machine specified will be made the primary virtual machine. This field must specify a secondary virtual machine that is part of the fault tolerant group that this virtual machine is currently associated with. It can only be invoked from the primary virtual machine in the group. Since vSphere API Release 4.0

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
InvalidState	Thrown if the host is in maintenance mode or if the virtual machine's configuration information is not available.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.
VmFaultToleranceIssue	Thrown if any error is encountered with the fault tolerance configuration of the virtual machine. Typically, a more specific fault like InvalidOperationOnSecondaryVm is thrown.

Events

Type
None

MarkAsTemplate(markAsTemplate)

Marks a VirtualMachine object as being used as a template. Note: A VirtualMachine marked as a template cannot be powered on.

Required Privileges

VirtualMachine.Provisioning.MarkAsTemplate

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
FileFault	Thrown if there is an error accessing the virtual machine files.
InvalidPowerState	Thrown if the virtual machine is not powered off.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state. For example, if the virtual machine configuration information is not available.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
VmConfigFault	Thrown if the template is incompatible with the host, such as the files are not accessible.

Events

Type
None

Show WSDL type definition

MarkAsVirtualMachine(markAsVirtualMachine)

Clears the 'isTemplate' flag and reassociates the virtual machine with a resource pool and host.

Required Privileges

VirtualMachine.Provisioning.MarkAsVM

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
pool P	ManagedObjectReference to a ResourcePool	Resource pool to associate with the virtual machine. Since 2.0
host*	ManagedObjectReference to a HostSystem	The target host on which the virtual machine is intended to run. The host parameter must specify a host that is a member of the ComputeResource indirectly specified by the pool. For a stand-alone host or a cluster with DRS, it can be omitted and the system selects a default. Since 2.0

*Need not be set P Required privilege: Resource.AssignVMToPool

Return Value

Type	Description
None

Faults

Type	Description
FileFault	Thrown if there is an error accessing the virtual machine files.
InvalidDatastore	Thrown if the operation cannot be performed on the target datastores.
InvalidState	Thrown if the virtual machine is not marked as a template.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
VmConfigFault	Thrown if the virtual machine is not compatible with the host. For example, a DisksNotSupported fault if the destination host does not support the disk backings of the template.

Events

Type
None

Show WSDL type definition

MigrateVM_Task(migrate)

Deprecated. As of vSphere 6.5, use RelocateVM_Task instead.

Migrates a virtual machine's execution to a specific resource pool or host.

Requires Resource.HotMigrate privilege if the virtual machine is powered on or Resource.ColdMigrate privilege if the virtual machine is powered off or suspended.

Required Privileges

None

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
pool* P	ManagedObjectReference to a ResourcePool	The target resource pool for the virtual machine. If the pool parameter is left unset, the virtual machine's current pool is used as the target pool. Since 2.0
host*	ManagedObjectReference to a HostSystem	The target host to which the virtual machine is intended to migrate. The host parameter may be left unset if the compute resource associated with the target pool represents a stand-alone host or a DRS-enabled cluster. In the former case the stand-alone host is used as the target host. In the latter case, the DRS system selects an appropriate target host from the cluster. Since 2.0
priority	VirtualMachineMovePriority	The task priority (@see vim.VirtualMachine.MovePriority). Since 2.0
state*	VirtualMachinePowerState	If specified, the virtual machine migrates only if its state matches the specified state. Since 2.0

*Need not be set P Required privilege: Resource.AssignVMToPool

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
FileFault	Thrown if, in a case where the virtual machine configuration file must be copied, the destination location for that file does not have the necessary file access permissions.
InsufficientResourcesFault	Thrown if this operation would violate a resource usage policy.
InvalidPowerState	Thrown if the state argument is set and the virtual machine does not have that power state.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state or the target host's current state. For example, if the virtual machine configuration information is not available or if the target host is disconnected or in maintenance mode.
MigrationFault	Thrown if it is not possible to migrate the virtual machine to the destination host. This is typically due to hosts being incompatible, such as mismatch in network polices or access to networks and datastores. Typically, a more specific subclass is thrown.
NoActiveHostInCluster	Thrown if a target host is not specified and the cluster associated with the target pool does not contain at least one potential target host. A host must be connected and not in maintenance mode in order to be considered as a potential target host.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
Timedout	Thrown if one of the phases of the migration process times out.
VmConfigFault	Thrown if the virtual machine is not compatible with the destination host. Typically, a specific subclass of this exception is thrown, such as IDEDiskNotSupported.

Events

Type
None

MountToolsInstaller(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, toolsVersionStatus and toolsRunningStatus

Required Privileges

VirtualMachine.Interact.ToolsInstall

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
InvalidState	Thrown if the virtual machine is not running, or the VMware Tools CD is already mounted.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
VmConfigFault
VmToolsUpgradeFault	Thrown if the VMware Tools CD failed to mount.

Events

Type
None

Show WSDL type definition

PowerOffVM_Task(powerOff)

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.

Required Privileges

VirtualMachine.Interact.PowerOff

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
InvalidPowerState	Thrown if the power state is not poweredOn.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state. For example, if the virtual machine configuration information is not available.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.

Events

Type
None

PowerOnVM_Task(powerOn)

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 DrsBehavior). Because this method does not return a DRS ClusterRecommendation, no vmotion nor host power operations will be done as part of a DRS-facilitated power on. To have DRS consider such operations use PowerOnMultiVM_Task. As of vSphere API 5.1, use of this method with vCenter Server is deprecated; use PowerOnMultiVM_Task 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.

Required Privileges

VirtualMachine.Interact.PowerOn

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
host*	ManagedObjectReference to a HostSystem	(optional) The host where the virtual machine is to be powered on. If no host is specified, the current associated host is used. This field must specify a host that is part of the same compute resource that the virtual machine is currently associated with. If this host is not compatible, the current host association is used. Since 2.0

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
FileFault	Thrown if there is a problem accessing the virtual machine on the filesystem.
InsufficientResourcesFault	Thrown if this operation would violate a resource usage policy.
InvalidPowerState	Thrown if the power state is poweredOn.
InvalidState	Thrown if the host is in maintenance mode or if the virtual machine's configuration information is not available or if the virtual machine is already powering on
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.
VmConfigFault	Thrown if a configuration issue prevents the power-on. Typically, a more specific fault, such as UnsupportedVmxLocation, is thrown.

Events

Type
None

PromoteDisks_Task(promoteDisks)

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 deltaDiskBackingsSupported is true.

This operation is only supported on VirtualCenter. If no work is required, an invocation completes successfully.

Required Privileges

VirtualMachine.Provisioning.PromoteDisks

Since

vSphere API Release 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
unlink	xsd:boolean	If true, then these disks will be unlinked before consolidation. Since vSphere API Release 4.0
disks*	VirtualDisk[]	The set of disks that are to be promoted. If this value is unset or the array is empty, all disks which have delta disk backings are promoted. Since vSphere API Release 4.0

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a SmsTask

Faults

Type	Description
InvalidPowerState
InvalidState	Thrown if the virtual machine's power state changes during the execution of this method.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.

Events

Type
None

PutUsbScanCodes(putUsbScanCodes)

Inject a sequence of USB HID scan codes into the keyboard.

Required Privileges

VirtualMachine.Interact.PutUsbScanCodes

Since

vSphere API Release 6.5

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
spec	UsbScanCodeSpec	Since vSphere API Release 6.5

Return Value

Type	Description
xsd:int	Number of keys injected.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

QueryChangedDiskAreas(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.

Required Privileges

VirtualMachine.Provisioning.DiskRandomRead

Since

vSphere API Release 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
snapshot*	ManagedObjectReference to a VirtualMachineSnapshot	Snapshot for which changes that have been made sine "changeId" should be computed. If not set, changes are computed against the "current" snapshot of the virtual machine. However, using the "current" snapshot will only work for virtual machines that are powered off. Since vSphere API Release 4.0
deviceKey	xsd:int	Identifies the virtual disk for which to compute changes. Since vSphere API Release 4.0
startOffset	xsd:long	Start Offset in bytes at which to start computing changes. Typically, callers will make multiple calls to this function, starting with startOffset 0 and then examine the "length" property in the returned DiskChangeInfo structure, repeatedly calling queryChangedDiskAreas until a map forthe entire virtual disk has been obtained. Since vSphere API Release 4.0
changeId	xsd:string	Identifyer referring to a point in the past that should be used as the point in time at which to begin including changes to the disk in the result. A typical use case would be a backup application obtaining a changeId from a virtual disk's backing info when performing a backup. When a subsequent incremental backup is to be performed, this change Id can be used to obtain a list of changed areas on disk. Since vSphere API Release 4.0

*Need not be set

Return Value

Type	Description
DiskChangeInfo	Returns a data structure specifying extents of the virtual disk that have changed since the thime the changeId string was obtained.

Faults

Type	Description
FileFault	Thrown if the virtual disk files cannot be accessed/queried.
NotFound	Thrown if the snapshot specified does not exist.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

QueryConnections(queryConnections)

Ask the virtual machine for a list of connections. The virtual machine returns a list of connections. It is possible for the array returned to be empty - a virtual machine may have no connections.

Required Privileges

VirtualMachine.Interact.ConsoleInteract

Since

vSphere API Release 7.0.1.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
VirtualMachineConnection[]

Faults

Type	Description
InvalidPowerState	Thrown if the virtual machine is not powered on.
InvalidState
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
Timedout	Thrown if the the virtual machine did not respond to the request in a timely manner.
VmConfigFault	Thrown if an error occurred.

Events

Type
None

Show WSDL type definition

QueryFaultToleranceCompatibility(queryFaultToleranceCompatibility)

Deprecated. as of vSphere API 6.0

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.

Required Privileges

VirtualMachine.Config.QueryFTCompatibility

Since

vSphere API Release 4.1

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
MethodFault[]

Faults

Type	Description
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
VmConfigFault	Thrown if the virtual machine's configuration is invalid.

Events

Type
None

Show WSDL type definition

QueryFaultToleranceCompatibilityEx(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.

Required Privileges

VirtualMachine.Config.QueryFTCompatibility

Since

vSphere API Release 6.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
forLegacyFt*	xsd:boolean	checks for legacy record-replay FT compatibility only if this is set to true. Since vSphere API Release 6.0

*Need not be set

Return Value

Type	Description
MethodFault[]

Faults

Type	Description
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
VmConfigFault	Thrown if the virtual machine's configuration is invalid.

Events

Type
None

Show WSDL type definition

QueryUnownedFiles(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 ConfigureDatastorePrincipal

Required Privileges

VirtualMachine.Config.QueryUnownedFiles

Since

vSphere API Release 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
xsd:string[]	The list of file paths for vm files whose ownership is not correct. Use ChangeOwner to set the file ownership.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

RebootGuest(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.

Required Privileges

VirtualMachine.Interact.Reset

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
InvalidPowerState	Thrown if the power state is not powered on.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state. For example, if the virtual machine configuration information is not available.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.
ToolsUnavailable	Thrown if VMware Tools is not running.

Events

Type
None

Show WSDL type definition

ReconfigVM_Task(reconfigure)

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:

• VirtualMachine.Interact.DeviceConnection if changing the runtime connection state of a device as embodied by the Connectable property.
• VirtualMachine.Interact.SetCDMedia if changing the backing of a CD-ROM device
• VirtualMachine.Interact.SetFloppyMedia if changing the backing of a floppy device
• VirtualMachine.Config.Rename if renaming the virtual machine
• VirtualMachine.Config.Annotation if setting annotation a value
• VirtualMachine.Config.AddExistingDisk if adding a virtual disk device that is backed by an existing virtual disk file
• VirtualMachine.Config.AddNewDisk if adding a virtual disk device for which the backing virtual disk file is to be created
• VirtualMachine.Config.RemoveDisk if removing a virtual disk device that refers to a virtual disk file
• VirtualMachine.Config.CPUCount if changing the number of CPUs
• VirtualMachine.Config.Memory if changing the amount of memory
• VirtualMachine.Config.RawDevice if adding, removing or editing a raw device mapping (RDM) or SCSI passthrough device
• VirtualMachine.Config.AddRemoveDevice if adding or removing any device other than disk, raw, or USB device
• VirtualMachine.Config.EditDevice if changing the settings of any device
• VirtualMachine.Config.Settings if changing any basic settings such as those in ToolsConfigInfo, FlagInfo, or DefaultPowerOpInfo
• VirtualMachine.Config.Resource if changing resource allocations, affinities, or setting network traffic shaping or virtual disk shares
• VirtualMachine.Config.AdvancedConfig if changing values in extraConfig
• VirtualMachine.Config.SwapPlacement if changing swapPlacement
• VirtualMachine.Config.HostUSBDevice if adding, removing or editing a VirtualUSB device backed by the host USB device.
• VirtualMachine.Config.DiskExtend if extending an existing VirtualDisk device.
• VirtualMachine.Config.ChangeTracking if enabling/disabling changed block tracking for the virtual machine's disks.
• VirtualMachine.Config.MksControl if toggling display connection limits or the guest auto-lock feature.
• DVSwitch.CanUse if connecting a VirtualEthernetAdapter to a port in a DistributedVirtualSwitch.
• DVPortgroup.CanUse if connecting a VirtualEthernetAdapter to a DistributedVirtualPortgroup.
• Cryptographer.Encrypt if vm home folder is encrypted or existing disk is encryted.
• Cryptographer.Decrypt if vm home folder is decrypted or existing disk is decryted.
• Cryptographer.Recrypt if vm home folder is recrypted or existing disk is recryted.
• Cryptographer.AddDisk if encrypted disk is attached to the vm.
• Cryptographer.RegisterHost on the host if the virtual machine is encrypted, but encryption is not enabled on the host.

Creating a virtual machine may require the following privileges:

• VirtualMachine.Config.RawDevice if adding a raw device
• VirtualMachine.Config.AddExistingDisk if adding a VirtualDisk and the fileOperation is unset
• VirtualMachine.Config.AddNewDisk if adding a VirtualDisk and the fileOperation is set
• VirtualMachine.Config.HostUSBDevice if adding a VirtualUSB device backed by the host USB device.

In addition, this operation may require the following privileges:

• Datastore.AllocateSpace on any datastore where virtual disks will be created or extended.
• Network.Assign on any network the virtual machine will be connected to.

To create a VirtualDisk on a persistent memory storage, the storage must be specified via profile while the datastore property of corresponding VirtualDisk backing must be unset.

To create a VirtualNVDIMM device, the storage profile must be set to the default persistent memory storage profile while the datastore property of the device backing must be unset.

Required Privileges

None

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
spec	VirtualMachineConfigSpec	The new configuration values. Since 2.0

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
ConcurrentAccess	Thrown if the changeVersion does not match the server's changeVersion for the configuration.
CpuHotPlugNotSupported	Thrown if the current configuration of the VM does not support hot-plugging of CPUs.
DuplicateName	Thrown if the specified name already exists in the parent folder.
FileFault	Thrown if there is a problem creating or accessing the virtual machine's files for this operation. Typically a more specific fault like NoDiskSpace or FileAlreadyExists is thrown.
InsufficientResourcesFault	Thrown if this operation would violate a resource usage policy.
InvalidDatastore
InvalidName	Thrown if the specified name is invalid.
InvalidPowerState	Thrown if the power state is poweredOn and the virtual hardware cannot support the configuration changes.
InvalidState	Thrown if the operation cannot be performed in the current state of the virtual machine. For example, because the virtual machine's configuration is not available.
MemoryHotPlugNotSupported	Thrown if the current configuration of the VM does not support hot-plugging of memory.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.
TooManyDevices	Thrown if the device specifications exceed the allowed limits.
VmConfigFault	Thrown if the spec is invalid. Typically, a more specific subclass is thrown.
VmWwnConflict	Thrown if the WWN of the virtual machine has been used by other virtual machines.

Events

Type
None

RefreshStorageInfo(refreshStorageInfo)

Explicitly refreshes the storage information of this virtual machine, updating properties Storage, LayoutEx and storage. This is an asynchronous operation which will return immediately; changes may not be reflected in vCenter for some time.

Required Privileges

System.Read

Since

vSphere API Release 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

reloadVirtualMachineFromPath_Task(reloadFromPath)

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.

Required Privileges

VirtualMachine.Config.ReloadFromPath

Since

vSphere API Release 4.1

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
configurationPath	xsd:string	Since vSphere API Release 4.1

Return Value

Type	Description
ManagedObjectReference to a SmsTask

Faults

Type	Description
AlreadyExists	Thrown if the virtual machine is already registered.
FileFault	Thrown if there is a problem creating or accessing the files needed for this operation.
InvalidPowerState	Thrown if the virtual machine is powered on.
InvalidState	Thrown if the virtual machine is busy or not ready to respond to such requests.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.
VmConfigFault	Thrown if the format / configuration of the virtual machine is invalid. Typically, a more specific fault is thrown such as InvalidFormat if the configuration file cannot be read, or InvalidDiskFormat if the disks cannot be read.

Events

Type
None

RelocateVM_Task(relocate)

Relocates a virtual machine to the location specified by VirtualMachineRelocateSpec. Starting from VCenter 5.1, this API also supports relocating a template to a new host should the current host become inactive. Starting from vCenter 6.0 this API also supports relocating a VM to a new vCenter service.

Requires the following additional permissions:

• Resource.HotMigrate if the virtual machine is powered on.
• Datastore.AllocateSpec if the virtual machine or its disks are being relocated to a new datastore.
• Resource.AssignVMToPool if the resource pool is changing.
• VirtualMachine.Inventory.Register against the destination folder if the virtual machine is moving to a new vCenter service.
• VirtualMachine.Inventory.Move against the virtual machine, source folder, and destination folder if the virtual machine is changing folders within the same vCenter service.
• Network.Assign against the new network if the virtual machine is changing networks.

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 spec specifies only compute location change, these virtual disks will be automatically moved to a persistent memory storage in destination host that supports the profile.
• If spec specifies primary datastore change via datastore, unlike regular virtual disks, these disks will not be automatically moved to the specified datastore, instead they will stay on a persistent memory storage in destination host that supports the profile.
• To explicityly move these disks to a location other than persistent memory storage, use disk locator to specify the new destination datastore along with a storage profile that removes the persistent memory storage requirement. Note that this downgrades the disk I/O performance.
• On the other hand, to move a virtual disk from a regular storage to persistent memory, use deviceChange to specify a storage profile of persistent memory storage. Note that this upgrades the disk I/O performance.

Required Privileges

Resource.ColdMigrate

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
spec	VirtualMachineRelocateSpec	The specification of where to relocate the virtual machine (see VirtualMachineRelocateSpec). Since 2.0
priority*	VirtualMachineMovePriority	The task priority (see VirtualMachineMovePriority). Since 2.0

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
FileFault	Thrown if there is an error accessing the virtual machine files.
InsufficientResourcesFault	Thrown if this operation would violate a resource usage policy.
InvalidDatastore	Thrown if the operation cannot be performed on the target datastores.
InvalidState	Thrown if the operation cannot be performed because of the host or virtual machine's current state. For example, if the host is in maintenance mode, or if the virtual machine's configuration information is not available.
MigrationFault	Thrown if it is not possible to migrate the virtual machine to the destination host. This is typically due to hosts being incompatible, such as mismatch in network polices or access to networks and datastores. Typically, a more specific subclass is thrown.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
Timedout	Thrown if one of the phases of the relocate process times out.
VmConfigFault	Thrown if the virtual machine is not compatible with the destination host. Typically, a specific subclass of this exception is thrown, such as IDEDiskNotSupported.

Events

Type
None

RemoveAllSnapshots_Task(removeAllSnapshots)

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

Required Privileges

VirtualMachine.State.RemoveSnapshot

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
consolidate*	xsd:boolean	(optional) If set to true, the virtual disks of the deleted snapshot will be merged with other disk if possible. Default to true. Since 2.0
spec*	SnapshotSelectionSpec	(optional) When provided, only snapshots satisfying the criteria described by the spec will be removed. If unset, all snapshots will be removed. Since 2.0

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
InvalidPowerState	Thrown if the operation cannot be performed in the current power state of the virtual machine.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state. For example, if the virtual machine configuration information is not available.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
SnapshotFault	Thrown if an error occurs during the snapshot operation. Typically, a more specific fault like InvalidSnapshotFormat is thrown.
TaskInProgress	Thrown if the virtual machine is busy.

Events

Type
None

ResetGuestInformation(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.

Required Privileges

VirtualMachine.Config.ResetGuestInfo

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
InvalidState	Thrown if the virtual machine is not powered off.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

ResetVM_Task(reset)

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.

Required Privileges

VirtualMachine.Interact.Reset

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
InvalidPowerState	Thrown if the power state is suspended or poweredOff.
InvalidState	Thrown if the host is in maintenance mode.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.

Events

Type
None

RevertToCurrentSnapshot_Task(revertToCurrentSnapshot)

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.

Required Privileges

VirtualMachine.State.RevertToSnapshot

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
host*	ManagedObjectReference to a HostSystem	(optional) Choice of host for the virtual machine, in case this operation causes the virtual machine to power on. If a snapshot was taken while a virtual machine was powered on, and this operation is invoked after the virtual machine was powered off, the operation causes the virtual machine to power on to reach the snapshot state. This parameter can be used to specify a choice of host where the virtual machine should power on. If this parameter is not set, and the vBalance feature is configured for automatic load balancing, a host is automatically selected. Otherwise, the virtual machine keeps its existing host affiliation. This is not supported for virtual machines associated with hosts on ESX 2.x servers. Since 2.0
suppressPowerOn*	xsd:boolean	(optional) If set to true, the virtual machine will not be powered on regardless of the power state when the current snapshot was created. Default to false. Since 2.0

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
InsufficientResourcesFault	Thrown if this operation would violate a resource usage policy.
InvalidPowerState	Thrown if the operation cannot be performed in the current power state of the virtual machine.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state. For example, if the virtual machine configuration information is not available or if an OVF consumer is blocking the operation.
NotFound	Thrown if the virtual machine does not have a current snapshot.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
SnapshotFault	Thrown if an error occurs during the snapshot operation. Typically, a more specific fault like InvalidSnapshotFormat is thrown.
TaskInProgress	Thrown if the virtual machine is busy.
VmConfigFault	Thrown if a configuration issue prevents the power-on. Typically, a more specific fault, such as UnsupportedVmxLocation, is thrown.

Events

Type
None

SendNMI(sendNMI)

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

Required Privileges

VirtualMachine.Interact.GuestControl

Since

vSphere API Release 6.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
InvalidState	Thrown if the virtual machine is not powered on.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

SetDisplayTopology(setDisplayTopology)

Sets the console window's display topology as specified.

Required Privileges

VirtualMachine.Interact.ConsoleInteract

Since

VI API 2.5 U2

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
displays	VirtualMachineDisplayTopology[]	The topology for each monitor that the virtual machine's display must span. Since VI API 2.5 U2

Return Value

Type	Description
None

Faults

Type	Description
InvalidPowerState	Thrown if the power state is not poweredOn.
InvalidState	Thrown if the virtual machine is not connected.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
ToolsUnavailable	Thrown if VMware Tools is not running.

Events

Type
None

Show WSDL type definition

SetScreenResolution(setScreenResolution)

Sets the console window's resolution as specified.

Required Privileges

VirtualMachine.Interact.ConsoleInteract

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
width	xsd:int	The screen width that should be set. Since 2.0
height	xsd:int	The screen height that should be set. Since 2.0

Return Value

Type	Description
None

Faults

Type	Description
InvalidPowerState	Thrown if the power state is not poweredOn.
InvalidState	Thrown if the virtual machine is not connected.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
ToolsUnavailable	Thrown if VMware Tools is not running.

Events

Type
None

Show WSDL type definition

ShutdownGuest(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.

Required Privileges

VirtualMachine.Interact.PowerOff

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
InvalidPowerState	Thrown if the power state is not powered on.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state. For example, if the virtual machine configuration information is not available.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.
ToolsUnavailable	Thrown if VMware Tools is not running.

Events

Type
None

Show WSDL type definition

StandbyGuest(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.

Required Privileges

VirtualMachine.Interact.Suspend

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
InvalidPowerState	Thrown if the power state is not powered on.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state. For example, if the virtual machine configuration information is not available.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.
ToolsUnavailable	Thrown if VMware Tools is not running.

Events

Type
None

Show WSDL type definition

StartRecording_Task(startRecording)

Deprecated. As of vsphere API 5.1

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.

Required Privileges

VirtualMachine.Interact.Record

Since

vSphere API Release 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
name	xsd:string	The name for the snapshot associated with this recording. The name need not be unique for this virtual machine. Since vSphere API Release 4.0
description*	xsd:string	A description for the snapshot associated with this recording. If omitted, a default description may be provided. Since vSphere API Release 4.0

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation. The result property in the Task contains the newly created VirtualMachineSnapshot associated with the recording on success.

Faults

Type	Description
FileFault	Thrown if there is a problem with creating or accessing one or more files needed for this operation.
HostIncompatibleForRecordReplay	Thrown if the virtual machine is located on a host that does not support record/replay.
InvalidName	Thrown if the specified snapshot name is invalid.
InvalidPowerState	Thrown if the operation cannot be performed in the current power state of the virtual machine.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state. For example, the virtual machine configuration information is not available.
RecordReplayDisabled	Thrown if the record/replay config flag has not been enabled for this virtual machine.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
SnapshotFault	Thrown if an error occurs during the snapshot operation. Typically, a more specific fault like MultipleSnapshotsNotSupported is thrown.
TaskInProgress	Thrown if the virtual machine is busy.
VmConfigFault
VmConfigIncompatibleForRecordReplay	Thrown if the virtual machine configuration is incompatible for recording.

Events

Type
None

StartReplaying_Task(startReplaying)

Deprecated. As of vsphere API 5.1

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.

Required Privileges

VirtualMachine.Interact.Replay

Since

vSphere API Release 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
replaySnapshot	ManagedObjectReference to a VirtualMachineSnapshot	The snapshot from which to start the replay. This snapshot must have been created by a record operation on the virtual machine. Since vSphere API Release 4.0

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
FileFault	Thrown if there is a problem with creating or accessing one or more files needed for this operation.
HostIncompatibleForRecordReplay	Thrown if the virtual machine is located on a host that does not support record/replay.
InvalidPowerState	Thrown if the operation cannot be performed in the current power state of the virtual machine.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state. For example, the virtual machine configuration information is not available.
NotFound	Thrown if replaySnapshot is no longer present.
RecordReplayDisabled	Thrown if the record/replay config flag has not been enabled for this virtual machine.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
SnapshotFault	Thrown if an error occurs during the snapshot operation. Typically, a more specific fault like InvalidSnapshotFormat is thrown.
TaskInProgress	Thrown if the virtual machine is busy.
VmConfigFault
VmConfigIncompatibleForRecordReplay	Thrown if the virtual machine configuration is incompatible for replaying.

Events

Type
None

StopRecording_Task(stopRecording)

Deprecated. As of vsphere API 5.1

Stops a currently active recording session on this virtual machine.

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

Required Privileges

VirtualMachine.Interact.Record

Since

vSphere API Release 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
FileFault	Thrown if there is a problem with creating or accessing one or more files needed for this operation.
InvalidPowerState	Thrown if the operation cannot be performed in the current power state of the virtual machine.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state. For example, the virtual machine does not have an active recording session.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
SnapshotFault	Thrown if an error occurs during the snapshot operation. Typically, a more specific fault like InvalidSnapshotFormat is thrown.
TaskInProgress	Thrown if the virtual machine is busy.

Events

Type
None

StopReplaying_Task(stopReplaying)

Deprecated. As of vsphere API 5.1

Stops a replay session on this virtual machine.

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

Required Privileges

VirtualMachine.Interact.Replay

Since

vSphere API Release 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
FileFault	Thrown if there is a problem with creating or accessing one or more files needed for this operation.
InvalidPowerState	Thrown if the operation cannot be performed in the current power state of the virtual machine.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state. For example, the virtual machine does not have an active recording session.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
SnapshotFault	Thrown if an error occurs during the snapshot operation. Typically, a more specific fault like InvalidSnapshotFormat is thrown.
TaskInProgress	Thrown if the virtual machine is busy.

Events

Type
None

SuspendVM_Task(suspend)

Suspends execution in this virtual machine.

Required Privileges

VirtualMachine.Interact.Suspend

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
InvalidPowerState	Thrown if the power state is not poweredOn.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state. For example, if the virtual machine configuration information is not available.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.

Events

Type
None

TerminateFaultTolerantVM_Task(terminateFaultTolerantVM)

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.

Required Privileges

VirtualMachine.Interact.TerminateFaultTolerantVM

Since

vSphere API Release 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
vm*	ManagedObjectReference to a VirtualMachine	The secondary virtual machine specified will be terminated, allowing fault tolerance to activate. If no virtual machine is specified, all secondary virtual machines will be terminated. If vm is a primary, InvalidArgument exception is thrown. This field must specify a virtual machine that is part of the fault tolerant group that this virtual machine is currently associated with. It can only be invoked from the primary virtual machine in the group. If the primary virtual machine is terminated, an available secondary virtual machine will be promoted to primary. If no secondary exists, an exception will be thrown and the primary virtual machine will not be terminated. If a secondary virtual machine is terminated, it may be respawned on a potentially different host. Since vSphere API Release 4.0

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
InvalidState	Thrown if the host is in maintenance mode or if the virtual machine's configuration information is not available.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.
VmFaultToleranceIssue	Thrown if any error is encountered with the fault tolerance configuration of the virtual machine. Typically, a more specific fault like InvalidOperationOnSecondaryVm is thrown.

Events

Type
None

TerminateVM(terminate)

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.

Required Privileges

VirtualMachine.Interact.PowerOff

Since

vSphere API Release 5.1

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
InvalidState	Thrown if the VM is not powered on or another issue prevents the operation from being performed.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.

Events

Type
None

Show WSDL type definition

TurnOffFaultToleranceForVM_Task(turnOffFaultTolerance)

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.

Required Privileges

VirtualMachine.Interact.TurnOffFaultTolerance

Since

vSphere API Release 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
InvalidState	Thrown if the host is in maintenance mode or if the virtual machine's configuration information is not available.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.
VmFaultToleranceIssue	Thrown if any error is encountered with the fault tolerance configuration of the virtual machine. Typically, a more specific fault like InvalidOperationOnSecondaryVm is thrown.

Events

Type
None

UnmountToolsInstaller(unmountToolsInstaller)

Unmounts VMware Tools installer CD.

Required Privileges

VirtualMachine.Interact.ToolsInstall

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
InvalidState	Thrown if the virtual machine is not running, VMware Tools is not running or the VMware Tools CD is already mounted.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
VmConfigFault

Events

Type
None

Show WSDL type definition

UnregisterVM(unregister)

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.

Required Privileges

VirtualMachine.Inventory.Unregister

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
InvalidPowerState	Thrown if the virtual machine is powered on.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.

Events

Type
None

Show WSDL type definition

UpgradeTools_Task(upgradeTools)

Begins the tools upgrade process. To monitor the status of the tools install, clients should check the tools status, toolsVersionStatus and toolsRunningStatus.

Required Privileges

VirtualMachine.Interact.ToolsInstall

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
installerOptions*	xsd:string	Command line options passed to the installer to modify the installation procedure for tools. Since 2.0

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
InvalidState	Thrown if the virtual machine is not running or is suspended.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if an upgrade is already taking place.
ToolsUnavailable	Thrown if VMware Tools is not running.
VmConfigFault
VmToolsUpgradeFault	Thrown if the upgrade failed.

Events

Type
None

UpgradeVM_Task(upgradeVirtualHardware)

Upgrades this virtual machine's virtual hardware to the latest revision that is supported by the virtual machine's current host.

Required Privileges

VirtualMachine.Config.UpgradeVirtualHardware

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualMachine used to make the method call.
version*	xsd:string	If specified, upgrade to that specified version. If not specified, upgrade to the most current virtual hardware supported on the host. Since 2.0

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a SmsTask	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
AlreadyUpgraded	Thrown if the virtual machine's hardware is already up-to-date.
InvalidPowerState	Thrown if the power state is not poweredOff.
InvalidState	Thrown if the host is in maintenance mode, if an invalid version string is specified, or if the virtual machine is in a state in which the operation cannot be performed. For example, if the configuration information is not available.
NoDiskFound	Thrown if no virtual disks are attached to this virtual machine.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.

Events

Type
None

Top of page		Local Properties	Local Methods
Managed Object Types	Data Object Types	All Properties	All Methods