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.

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.

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.

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.

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.

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.

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

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.

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.

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.

CreateSecondaryVM_Task

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

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

If the primary virtual machine (i.e., this virtual machine) is powered on when
the secondary is created, an attempt will be made to power on the secondary on
a system selected host. If the cluster is a DRS cluster, DRS will be
invoked to obtain a placement for the new secondary virtual machine. If the DRS
recommendation (see 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.

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.

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.

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.

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.

Thrown 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; or if the virtual machine is a Fault Tolerance primary or secondary

DisableSecondaryVM_Task

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

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.

EnableSecondaryVM_Task

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Thrown if the virtual machine is not compatible with the destination host. Typically, a specific subclass of this exception is thrown, such as IDEDiskNotSupported.

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

PowerOnVM_Task

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

When powering on a virtual machine in a cluster, the system might implicitly
or due to the host argument, do an implicit relocation of the virtual machine
to another host. Hence, errors related to this relocation can be thrown. If the
cluster is a DRS cluster, DRS will be invoked if the virtual machine can be
automatically placed by DRS (see 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.

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.

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

Thrown if a configuration issue prevents the power-on. Typically, a more specific fault, such as UnsupportedVmxLocation, is thrown.

PromoteDisks_Task

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

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

Promoting does two things

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.

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.

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.

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.

deviceKey

xsd:int

Identifies the virtual disk for which to compute changes.

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.

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.

QueryFaultToleranceCompatibility

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.

reloadVirtualMachineFromPath_Task

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

This method is only supported on vCenter Server. It can be invoked on
inaccessible or orphaned virtual machines, but it cannot be invoked on
powered on, connected virtual machines.

Note: If the referenced configuration path does not refer to a
valid virtual machine, configuration information for the virtual machine
object may be lost.

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.

RelocateVM_Task

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

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

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

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.

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.

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.

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

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.

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.

Thrown if any error is encountered with the fault tolerance configuration of the virtual machine. Typically, a more specific fault like InvalidOperationOnSecondaryVm is thrown.

TurnOffFaultToleranceForVM_Task

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

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.

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.