Managed Object - VirtualMachine

Property of
AutoStartPowerInfo, ClusterAffinityRuleSpec, ClusterAntiAffinityRuleSpec, ClusterDasVmConfigInfo, ClusterDrsMigration, ClusterDrsVmConfigInfo, Datastore, HostSystem, MountError, Network, ResourcePool, VirtualMachineDiskDeviceInfo, VirtualMachineSnapshotTree, VirtualMachineSummary, VmEventArgument
Parameter to
QueryVMotionCompatibility, RecommendHostsForVm, ValidateMigration
Returned by
CloneVM_Task, CreateVM_Task, FindByDatastorePath, RegisterVM_Task
Extends
ManagedEntity
See also
CustomizationSpec, Datastore, EnvironmentBrowser, Folder, GuestInfo, HostSystem, ManagedEntityStatus, Network, ResourceConfigSpec, ResourcePool, VirtualMachineCapability, VirtualMachineCloneSpec, VirtualMachineConfigInfo, VirtualMachineConfigSpec, VirtualMachineFileLayout, VirtualMachineMksTicket, VirtualMachineMovePriority, VirtualMachinePowerState, VirtualMachineRelocateSpec, VirtualMachineRuntimeInfo, VirtualMachineSnapshot, VirtualMachineSnapshotInfo, VirtualMachineSummary

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
capabilityVirtualMachineCapability 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 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*ManagedObjectReference[]
to a Datastore[]
A collection of references to the subset of datastore objects in the datacenter that is used by this virtual machine.
environmentBrowserManagedObjectReference
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.
guestHeartbeatStatusManagedEntityStatus 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 Detailed information about the files that comprise this virtual machine.
network*ManagedObjectReference[]
to a Network[]
A collection of references to the subset of network objects in the datacenter that is used by this virtual machine.
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.

runtimeVirtualMachineRuntimeInfo 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:

summaryVirtualMachineSummary Basic information about this virtual machine. This includes:
  • runtimeInfo
  • guest
  • basic configuration
  • alarms
  • performance information
Properties inherited from ManagedEntity
configIssue, configStatus, customValue, declaredAlarmState, disabledMethod, effectiveRole, name, overallStatus, parent, permission, recentTask, triggeredAlarmState
*May not be present

Methods

Methods defined in this Managed Object
AcquireMksTicket, AnswerVM, CheckCustomizationSpec, CloneVM_Task, CreateSnapshot_Task, CustomizeVM_Task, MarkAsTemplate, MarkAsVirtualMachine, MigrateVM_Task, MountToolsInstaller, PowerOffVM_Task, PowerOnVM_Task, RebootGuest, ReconfigVM_Task, RelocateVM_Task, RemoveAllSnapshots_Task, ResetGuestInformation, ResetVM_Task, RevertToCurrentSnapshot_Task, SetScreenResolution, ShutdownGuest, StandbyGuest, SuspendVM_Task, UnmountToolsInstaller, UnregisterVM, UpgradeTools_Task, UpgradeVM_Task
Methods inherited from ManagedEntity
Destroy_Task, Reload, Rename_Task

AcquireMksTicket

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

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.

Return Value

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

Faults

Type Description
NotSupportedThrown if it cannot retrieve TCP binding information about the client connection. For example, TCP binding information is not available for a client connection that is not TCP-based.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition



AnswerVM

Responds to a question that is blocking this virtual machine.
Required Privileges
VirtualMachine.Interact.AnswerQuestion

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.
questionIdxsd:string The value from QuestionInfo.id that identifies the question to answer.
answerChoicexsd:string The contents of the QuestionInfo.choice.value array element that identifies the desired answer.

Return Value

Type Description
None

Faults

Type Description
ConcurrentAccessThrown if the question has been or is being answered by another thread or user.
InvalidArgumentThrown if the questionId does not apply to this virtual machine. For example, this can happen if another client already answered the message.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition



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

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.
specCustomizationSpec The customization specification to check.

Return Value

Type Description
None

Faults

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

Show WSDL type definition



CloneVM_Task

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

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

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

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

The Resource.AssignVMToPool privilege is also required for the resource pool specified in the CloneSpec, if the destination is not a template.

Required Privileges
None

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.
folder PManagedObjectReference
to a Folder
The location of the new virtual machine.
namexsd:string The name of the new virtual machine.
specVirtualMachineCloneSpec Specifies how to clone the virtual machine.
P Required privilege: VirtualMachine.Inventory.Create

Return Value

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

Faults

Type Description
CustomizationFaultThrown if a customization error happens. Typically, a specific subclass of this exception is thrown.
FileFaultThrown if there is an error accessing the virtual machine files.
InsufficientResourcesFaultThrown if this operation would violate a resource usage policy.
InvalidArgumentThrown if the host cannot run this virtual machine.
InvalidDatastoreThrown if the operation cannot be performed on the target datastores.
InvalidPowerStateThrown if the virtual machine is powered on.
InvalidStateThrown 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.
MigrationFaultThrown 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.
NotSupportedThrown if the operation is not supported by the current agent.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgressThrown if the virtual machine is busy.
VmConfigFaultThrown if the virtual machine is not compatible with the destination host. Typically, a specific subclass of this exception is thrown, such as IDEDiskNotSupported.

Show WSDL type definition



CreateSnapshot_Task

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

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

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.
namexsd:string The name for this snapshot. The name need not be unique for this virtual machine.
description*xsd:string A description for this snapshot. If omitted, a default description may be provided.
memoryxsd: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.

quiescexsd: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 virutal machine is powered off or VMware Tools are not available, the quiesce flag is ignored.
*Need not be set

Return Value

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

Faults

Type Description
FileFaultThrown if there is a problem with creating or accessing one or more files needed for this operation.
InvalidNameThrown if the specified snapshot name is invalid.
InvalidPowerStateThrown if the operation cannot be performed in the current power state of the virtual machine.
InvalidStateThrown if the operation cannot be performed because of the virtual machine's current state. For example, the virtual machine configuration information is not available.
NotSupportedThrown if the host product does not support snapshots or if the host does not support quiesced snapshots and the quiesce parameter is set to true.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
SnapshotFaultThrown if an error occurs during the snapshot operation. Typically, a more specific fault like MultipleSnapshotsNotSupported is thrown.
TaskInProgressThrown if the virtual machine is busy.
VmConfigFaultThrown if the virtual machine's configuration is invalid. Typically, a more specific fault like InvalidSnapshotState is thrown.

Show WSDL type definition



CustomizeVM_Task

Customizes a virtual machine's guest operating system.
Required Privileges
VirtualMachine.Provisioning.Customize

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.
specCustomizationSpec The customization specification object.

Return Value

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

Faults

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

Show WSDL type definition



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

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.

Return Value

Type Description
None

Faults

Type Description
InvalidPowerStateThrown if the virtual machine is not powered off.
InvalidStateThrown 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.
NotSupportedThrown if marking a virtual machine as a template is not supported.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
VmConfigFaultThrown if the template is incompatible with the host, such as the files are not accessible.

Show WSDL type definition



MarkAsVirtualMachine

Clears the 'isTemplate' flag and reassociates the virtual machine with a resource pool and host.
Required Privileges
VirtualMachine.Provisioning.MarkAsVM

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.
pool PManagedObjectReference
to a ResourcePool
Resource pool to associate with the virtual machine.
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.
*Need not be set P Required privilege: Resource.AssignVMToPool

Return Value

Type Description
None

Faults

Type Description
FileFaultThrown if we failed to access the virtual machine files.
InvalidDatastoreThrown if the operation cannot be performed on the target datastores.
InvalidStateThrown if the virtual machine is not marked as a template.
NotSupportedThrown if marking a template as a virtual machine is not supported.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
VmConfigFaultThrown 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.

Show WSDL type definition



MigrateVM_Task

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. Also requires Resource.AssignVMToPool on the virtual machine if the optional pool argument it set.

Required Privileges
Dynamic - See discussion above

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.
pool* PManagedObjectReference
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.
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.
priorityVirtualMachineMovePriority The priority of the migration task.
state*VirtualMachinePowerState If specified, the virtual machine migrates only if its state matches the specified state.
*Need not be set P Required privilege: Resource.AssignVMToPool

Return Value

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

Faults

Type Description
FileFaultThrown 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.
InsufficientResourcesFaultThrown if this operation would violate a resource usage policy.
InvalidArgumentThrown if the target host and target pool are not associated with the same compute resource or if the host parameter is left unset when the target pool is associated with a non-DRS cluster.
InvalidPowerStateThrown if the state argument is set and the virtual machine does not have that power state.
InvalidStateThrown 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.
MigrationFaultThrown 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.
NoActiveHostInClusterThrown 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.
NotSupportedThrown if the virtual machine is marked as a template.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TimedoutThrown if one of the phases of the migration process times out.
VmConfigFaultThrown if the virtual machine is not compatible with the destination host. Typically, a specific subclass of this exception is thrown, such as IDEDiskNotSupported.

Show WSDL type definition



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 (@see vim.vm.guest.toolsStatus).
Required Privileges
VirtualMachine.Interact.ToolsInstall

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.

Return Value

Type Description
None

Faults

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

Show WSDL type definition



PowerOffVM_Task

Powers off this virtual machine.
Required Privileges
VirtualMachine.Interact.PowerOff

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.

Return Value

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

Faults

Type Description
InvalidPowerStateThrown if the power state is not poweredOn.
InvalidStateThrown 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.
NotSupportedThrown if the virtual machine is marked as a template.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgressThrown if the virtual machine is busy.

Show WSDL type definition



PowerOnVM_Task

Powers on this virtual machine. If the virtual machine is suspended, this method resumes execution from the suspend point. When powering on a virtual machine in a cluster, the system might implicitly or due to the host argument, do an implicit relocation of the virtual machine to another host. Hence, errors related to this relocation can be thrown.
Required Privileges
VirtualMachine.Interact.PowerOn

Parameters

NameTypeDescription
_thisManagedObjectReference 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.
*Need not be set

Return Value

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

Faults

Type Description
FileFaultThrown if there is a problem accessing the virtual machine on the filesystem.
InsufficientResourcesFaultThrown if this operation would violate a resource usage policy.
InvalidPowerStateThrown if the power state is poweredOn.
InvalidStateThrown if the host is in maintenance mode or if the virtual machine's configuration information is not available.
NotEnoughLicensesThrown if there are not enough licenses to power on this virtual machine.
NotSupportedThrown if the virtual machine is marked as a template.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgressThrown if the virtual machine is busy.
VmConfigFaultThrown if a configuration issue prevents the power-on. Typically, a more specific fault, such as UnsupportedVmxLocation, is thrown.

Show WSDL type definition



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

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.

Return Value

Type Description
None

Faults

Type Description
InvalidPowerStateThrown if the power state is not powered on.
InvalidStateThrown 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.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgressThrown if the virtual machine is busy.
ToolsUnavailableThrown if VMware Tools is not running.

Show WSDL type definition



ReconfigVM_Task

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

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

Creating a virtual machine may require the following privileges:
Required Privileges
Dynamic - See discussion above

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.
specVirtualMachineConfigSpec The new configuration values.

Return Value

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

Faults

Type Description
ConcurrentAccessThrown if the changeVersion does not match the server's changeVersion for the configuration.
DuplicateNameThrown if the specified name already exists in the parent folder.
FileFaultThrown 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.
InsufficientResourcesFaultThrown if this operation would violate a resource usage policy.
InvalidDatastore
InvalidNameThrown if the specified name is invalid.
InvalidPowerStateThrown if the power state is poweredOn and the virtual hardware cannot support the configuration changes.
InvalidStateThrown 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.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgressThrown if the virtual machine is busy.
TooManyDevicesThrown if the device specifications exceed the allowed limits.
VmConfigFaultThrown if the spec is invalid. Typically, a more specific subclass is thrown.

Show WSDL type definition



RelocateVM_Task

Relocates a virtual machine's virtual disks to a specific location; optionally moves the virtual machine to a different host as well.

Requires Resource.ColdMigrate privilege

Required Privileges
Resource.ColdMigrate

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.
specVirtualMachineRelocateSpec The specification of where to relocate the virtual machine.

Return Value

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

Faults

Type Description
FileFaultThrown if there is an error accessing the virtual machine files.
InsufficientResourcesFaultThrown if this operation would violate a resource usage policy.
InvalidArgumentin the following cases:
  • the target host and target pool are not associated with the same compute resource
  • the target pool represents a cluster without DRS enabled, and the host is not specified
  • Datastore in a diskLocator entry is not specified
  • the specified device ID cannot be found in the virtual machine's current configuration
  • the object specified in relocate cannot be found
InvalidDatastoreThrown if the operation cannot be performed on the target datastores.
InvalidPowerStateThrown if the virtual machine is not in a powered off or suspended state.
InvalidStateThrown 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.
MigrationFaultThrown 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.
NotSupportedThrown if the virtual machine is marked as a template.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TimedoutThrown if one of the phases of the relocate process times out.
VmConfigFaultThrown if the virtual machine is not compatible with the destination host. Typically, a specific subclass of this exception is thrown, such as IDEDiskNotSupported.

Show WSDL type definition



RemoveAllSnapshots_Task

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

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.

Return Value

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

Faults

Type Description
InvalidPowerStateThrown if the operation cannot be performed in the current power state of the virtual machine.
InvalidStateThrown 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.
NotSupportedThrown if the host product does not support snapshots.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
SnapshotFaultThrown if an error occurs during the snapshot operation. Typically, a more specific fault like InvalidSnapshotFormat is thrown.
TaskInProgressThrown if the virtual machine is busy.

Show WSDL type definition



ResetGuestInformation

Clears cached guest information. Guest information can be cleared only if VMware Tools is not running; that is, the virtual machine is powered off, suspended, or running without VMware Tools.

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

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.

Return Value

Type Description
None

Faults

Type Description
InvalidStateThrown if VMware Tools is running.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition



ResetVM_Task

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

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

Required Privileges
VirtualMachine.Interact.Reset

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.

Return Value

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

Faults

Type Description
InvalidPowerStateThrown if the power state is suspended.
InvalidStateThrown if the host is in maintenance mode.
NotEnoughLicensesThrown if there are not enough licenses to reset this virtual machine.
NotSupportedThrown if the virtual machine is marked as a template.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgressThrown if the virtual machine is busy.

Show WSDL type definition



RevertToCurrentSnapshot_Task

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

If no snapshot exists, then the operation does nothing, and the virtual machine state remains unchanged.

Required Privileges
VirtualMachine.State.RevertToSnapshot

Parameters

NameTypeDescription
_thisManagedObjectReference 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.

*Need not be set

Return Value

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

Faults

Type Description
InsufficientResourcesFaultThrown if this operation would violate a resource usage policy.
InvalidPowerStateThrown if the operation cannot be performed in the current power state of the virtual machine.
InvalidStateThrown 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.
NotFoundThrown if the virtual machine does not have a current snapshot.
NotSupportedThrown if the host product does not support snapshots.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
SnapshotFaultThrown if an error occurs during the snapshot operation. Typically, a more specific fault like InvalidSnapshotFormat is thrown.
TaskInProgressThrown if the virtual machine is busy.
VmConfigFaultThrown if a configuration issue prevents the power-on. Typically, a more specific fault, such as UnsupportedVmxLocation, is thrown.

Show WSDL type definition



SetScreenResolution

Sets the console window's resolution as specified.
Required Privileges
VirtualMachine.Interact.ConsoleInteract

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.
widthxsd:int The screen width that should be set.
heightxsd:int The screen height that should be set.

Return Value

Type Description
None

Faults

Type Description
InvalidPowerStateThrown if the power state is not poweredOn.
NotSupportedThrown if the Guest Operating system does not support setting the screen resolution.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
ToolsUnavailableThrown if VMware Tools is not running.

Show WSDL type definition



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

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.

Return Value

Type Description
None

Faults

Type Description
InvalidPowerStateThrown if the power state is not powered on.
InvalidStateThrown 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.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgressThrown if the virtual machine is busy.
ToolsUnavailableThrown if VMware Tools is not running.

Show WSDL type definition



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

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.

Return Value

Type Description
None

Faults

Type Description
InvalidPowerStateThrown if the power state is not powered on.
InvalidStateThrown 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.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgressThrown if the virtual machine is busy.
ToolsUnavailableThrown if VMware Tools is not running.

Show WSDL type definition



SuspendVM_Task

Suspends execution in this virtual machine.
Required Privileges
VirtualMachine.Interact.Suspend

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.

Return Value

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

Faults

Type Description
InvalidPowerStateThrown if the power state is not poweredOn.
InvalidStateThrown 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.
NotSupportedThrown if the virtual machine is marked as a template.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgressThrown if the virtual machine is busy.

Show WSDL type definition



UnmountToolsInstaller

Unmounts VMware Tools installer CD.
Required Privileges
VirtualMachine.Interact.ToolsInstall

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.

Return Value

Type Description
None

Faults

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

Show WSDL type definition



UnregisterVM

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

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

Required Privileges
VirtualMachine.Inventory.Delete

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the VirtualMachine used to make the method call.

Return Value

Type Description
None

Faults

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

Show WSDL type definition



UpgradeTools_Task

Begins the tools upgrade process. To monitor the status of the tools install, clients should check the tools status (@see vim.vm.guest.toolsStatus).
Required Privileges
VirtualMachine.Interact.ToolsInstall

Parameters

NameTypeDescription
_thisManagedObjectReference 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.
*Need not be set

Return Value

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

Faults

Type Description
InvalidStateThrown if the virtual machine is not running or an upgrade is already taking place.
NotSupportedThrown if upgrading tools is not supported.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress
ToolsUnavailableThrown if VMware Tools is not running.
VmToolsUpgradeFault

Show WSDL type definition



UpgradeVM_Task

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

NameTypeDescription
_thisManagedObjectReference 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.
*Need not be set

Return Value

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

Faults

Type Description
AlreadyUpgradedThrown if the virtual machine's hardware is already up-to-date.
InvalidPowerStateThrown if the power state is not poweredOff.
InvalidStateThrown 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.
NoDiskFoundThrown if no virtual disks are attached to this virtual machine.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgressThrown if the virtual machine is busy.

Show WSDL type definition