Scripting Object - VcVirtualMachine

Scripting-object corresponding to
VirtualMachine
Attribute of
_VcPlugin, VcApplyStorageRecommendationResult, VcAutoStartPowerInfo, VcCheckResult, VcClusterAffinityRuleSpec, VcClusterAntiAffinityRuleSpec, VcClusterAttemptedVmInfo, VcClusterDasVmConfigInfo, VcClusterDrsFaultsFaultsByVirtualDisk, VcClusterDrsFaultsFaultsByVm, VcClusterDrsMigration, VcClusterDrsVmConfigInfo, VcClusterNotAttemptedVmInfo, VcClusterVmGroup, VcDatastore, VcDistributedVirtualPortgroup, VcDVSSummary, VcFaultTolerancePrimaryConfigInfo, VcFaultToleranceSecondaryConfigInfo, VcFaultToleranceSecondaryOpResult, VcHostSystem, VcHostVmciAccessManagerAccessSpec, VcNetwork, VcResourcePool, VcSdkConnection, VcStorageDrsVmConfigInfo, VcStorageMigrationAction, VcStoragePlacementAction, VcStoragePlacementSpec, VcVirtualApp, VcVirtualDiskId, VcVirtualMachineDiskDeviceInfo, VcVirtualMachineIdeDiskDeviceInfo, VcVirtualMachineScsiDiskDeviceInfo, VcVirtualMachineSnapshotTree, VcVirtualMachineSummary, VcVmEventArgument
Parameter to
acquireCredentialsInGuest, changeFileAttributesInGuest, checkCompatibility_Task, checkMigrate_Task, checkRelocate_Task, createTemporaryDirectoryInGuest, createTemporaryFileInGuest, deleteDirectoryInGuest, deleteFileInGuest, disableSecondaryVM_Task, enableSecondaryVM_Task, initiateFileTransferFromGuest, initiateFileTransferToGuest, listFilesInGuest, listProcessesInGuest, makeDirectoryInGuest, makePrimaryVM_Task, moveDirectoryInGuest, moveFileInGuest, powerOnMultiVM_Task, queryVMotionCompatibilityEx_Task, readEnvironmentVariableInGuest, recommendHostsForVm, releaseCredentialsInGuest, startProgramInGuest, terminateFaultTolerantVM_Task, terminateProcessInGuest, validateCredentialsInGuest
Returned by
findByDatastorePath, getAllVirtualMachines, getAllVirtualMachines

Scripting Object Description

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

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

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

Attributes

Name Type Description
alarmActionsEnabled*boolean

Whether alarm actions are enabled for this entity. True if enabled; false otherwise.
availableField*VcCustomFieldDef []

List of custom field definitions that are valid for the object's type. The fields are sorted by VcCustomFieldDef.
capabilityVcVirtualMachineCapability

Information about the runtime capabilities of this virtual machine.
config*VcVirtualMachineConfigInfo

Configuration of this virtual machine, including the name and UUID.

This property is set when a virtual machine is created or when the VcVirtualMachine 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.

configIssue*VcEvent []

Current configuration issues that have been detected for this entity. Typically, these issues have already been logged as events. The entity stores these events as long as they are still current. The VcManagedEntity property provides an overall status based on these events.
configStatusVcManagedEntityStatus

The configStatus indicates whether or not the system has detected a configuration issue involving this entity. For example, it might have detected a duplicate IP address or MAC address, or a host in a cluster might be out of compliance. The meanings of the configStatus values are:
  • red: A problem has been detected involving the entity.
  • yellow: A problem is about to occur or a transient condition has occurred (For example, reconfigure fail-over policy).
  • green: No configuration issues have been detected.
  • gray: The configuration status of the entity is not being monitored.
A green status indicates only that a problem has not been detected; it is not a guarantee that the entity is problem-free.

The VcManagedEntity property contains a list of the problems that have been detected.

customValue*VcCustomFieldValue []

Custom field values.
datastore*VcDatastore []

A collection of references to the subset of datastore objects in the datacenter that is used by this virtual machine.
declaredAlarmState*VcAlarmState []

A set of alarm states for alarms that apply to this managed entity. The set includes alarms defined on this entity and alarms inherited from the parent entity, or from any ancestors in the inventory hierarchy.

Alarms are inherited if they can be triggered by this entity or its descendants. This set does not include alarms that are defined on descendants of this entity.

disabledMethod*string []

List of operations that are disabled, given the current runtime state of the entity. For example, a power-on operation always fails if a virtual machine is already powered on. This list can be used by clients to enable or disable operations in a graphical user interface.

Note: This list is determined by the current runtime state of an entity, not by its permissions.

This list may include the following operations for a HostSystem:

This list may include the following operations for a VirtualMachine:

This list may include the following operations for a ResourcePool:

This list may include the following operations for a VirtualApp:

effectiveRole*number []

Access rights the current session has to this entity.
environmentBrowserVcEnvironmentBrowser

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 VcComputeResource to which this virtual machine belongs.
guest*VcGuestInfo

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

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

returns the id of this ManagedObject
layout*VcVirtualMachineFileLayoutDeprecated.

Detailed information about the files that comprise this virtual machine.


As of vSphere API 4.0, use VcVirtualMachine instead.

layoutEx*VcVirtualMachineFileLayoutEx

Detailed information about the files that comprise this virtual machine.

Can be explicitly refreshed by the VcVirtualMachine operation.

namestring

Name of this entity, unique relative to its parent.

Any / (slash), \ (backslash), character used in this name element will be escaped. Similarly, any % (percent) character used in this name element will be escaped, unless it is used to start an escape sequence. A slash is escaped as %2F or %2f. A backslash is escaped as %5C or %5c, and a percent is escaped as %25.

network*VcNetwork []

A collection of references to the subset of network objects in the datacenter that is used by this virtual machine.
overallStatusVcManagedEntityStatus

General health of this managed entity. The overall status of the managed entity is computed as the worst status among its alarms and the configuration issues detected on the entity. The status is reported as one of the following values:
  • red: The entity has alarms or configuration issues with a red status.
  • yellow: The entity does not have alarms or configuration issues with a red status, and has at least one with a yellow status.
  • green: The entity does not have alarms or configuration issues with a red or yellow status, and has at least one with a green status.
  • gray: All of the entity's alarms have a gray status and the configuration status of the entity is not being monitored.
parent*VcManagedEntity

Parent of this entity.

This value is null for the root object and for VcVirtualMachine objects that are part of a VcVirtualApp.

parentVApp*VcManagedEntity

Reference to the parent vApp.
permission*VcPermission []

List of permissions defined for this entity.
recentTask*VcTask []

The set of recent tasks operating on this managed entity. This is a subset of VcTaskManager belong to this entity. A task in this list could be in one of the four states: pending, running, success or error.

This property can be used to deduce intermediate power states for a virtual machine entity. For example, if the current powerState is "poweredOn" and there is a running task performing the "suspend" operation, then the virtual machine's intermediate state might be described as "suspending."

Most tasks (such as power operations) obtain exclusive access to the virtual machine, so it is unusual for this list to contain more than one running task. One exception, however, is the task of cloning a virtual machine.

referenceVcManagedObjectReference

returns the ManagedObjectReference of this ManagedObject
resourceConfig*VcResourceConfigSpec

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

To change the configuration, use VcResourcePool.

resourcePool*VcResourcePool

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*VcVirtualMachineSnapshot []

The roots of all snapshot trees for the virtual machine.
runtimeVcVirtualMachineRuntimeInfo

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

returns the parent SdkConnection
snapshot*VcVirtualMachineSnapshotInfo

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:

storage*VcVirtualMachineStorageInfo

Storage space used by the virtual machine, split by datastore. Can be explicitly refreshed by the VcVirtualMachine operation.
summaryVcVirtualMachineSummary

Basic information about this virtual machine. This includes:
  • runtimeInfo
  • guest
  • basic configuration
  • alarms
  • performance information
tag*VcTag []

The set of tags associated with this managed entity. Experimental. Subject to change.
triggeredAlarmState*VcAlarmState []

A set of alarm states for alarms triggered by this entity or by its descendants.

Triggered alarms are propagated up the inventory hierarchy so that a user can readily tell when a descendant has triggered an alarm.

value*VcCustomFieldValue []

List of custom field values. Each value uses a key to associate an instance of a VcCustomFieldStringValue with a custom field definition.
vimHostVcSdkConnection

returns the parent SdkConnection (deprecated)
vimTypestring

returns the type of this ManagedObject
*May not be present

Methods

Methods defined in this Scripting Object
acquireMksTicket, acquireTicket, answerVM, checkCustomizationSpec, cloneVM_Task, consolidateVMDisks_Task, createScreenshot_Task, createSecondaryVM_Task, createSnapshot_Task, customizeVM_Task, defragmentAllDisks, destroy_Task, disableSecondaryVM_Task, enableSecondaryVM_Task, estimateStorageForConsolidateSnapshots_Task, exportVm, extractOvfEnvironment, makePrimaryVM_Task, markAsTemplate, markAsVirtualMachine, migrateVM_Task, mountToolsInstaller, powerOffVM_Task, powerOnVM_Task, promoteDisks_Task, queryChangedDiskAreas, queryFaultToleranceCompatibility, queryUnownedFiles, rebootGuest, reconfigVM_Task, refreshStorageInfo, reload, reloadVirtualMachineFromPath_Task, relocateVM_Task, removeAllSnapshots_Task, rename_Task, resetGuestInformation, resetVM_Task, revertToCurrentSnapshot_Task, setCustomValue, setDisplayTopology, setScreenResolution, shutdownGuest, standbyGuest, startRecording_Task, startReplaying_Task, stopRecording_Task, stopReplaying_Task, suspendVM_Task, terminateFaultTolerantVM_Task, turnOffFaultToleranceForVM_Task, unmountToolsInstaller, unregisterVM, upgradeTools_Task, upgradeVM_Task

reload

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

Parameters

NameTypeDescription
None

Return Value

Type Description
None

rename_Task

Renames this managed entity.

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


See VcManagedEntity

Parameters

NameTypeDescription
newNamestring


See VcManagedEntity

Return Value

Type Description
VcTask

destroy_Task

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

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

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

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

setCustomValue

Assigns a value to a custom field. The setCustomValue method requires whichever updatePrivilege is defined as one of the VcCustomFieldDef for the CustomFieldDef whose value is being changed.

Parameters

NameTypeDescription
keystring

The name of the field whose value is to be updated.
valuestring

Value to be assigned to the custom field.

Return Value

Type Description
None

refreshStorageInfo

Explicitly refreshes the storage information of this virtual machine, updating properties VcVirtualMachine, VcVirtualMachine and VcVirtualMachineSummary.

Parameters

NameTypeDescription
None

Return Value

Type Description
None

createSnapshot_Task

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

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

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

Parameters

NameTypeDescription
namestring

The name for this snapshot. The name need not be unique for this virtual machine.
description*string

A description for this snapshot. If omitted, a default description may be provided.
memoryboolean

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.

VcVirtualMachineConfigOption indicates whether or not this virtual machine supports this operation.

quiesceboolean

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

Return Value

Type Description
VcTask

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.

Parameters

NameTypeDescription
host*VcHostSystem

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

*Need not be set

Return Value

Type Description
VcTask

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.

Parameters

NameTypeDescription
consolidate*boolean

(optional) If set to true, the virtual disks of the deleted snapshot will be merged with other disk if possible. Default to true.

*Need not be set

Return Value

Type Description
VcTask

consolidateVMDisks_Task

Consolidate the virtual disk files of the virtual machine by finding hierarchies of redo logs that can be combined without violating data dependency. The redundant redo logs after merging are then deleted. Consolidation improves I/O performance since less number of virtual disk files need to be traversed; it also reduces the storage usage. However additional space is temporarily required to perform the operation. Use VcVirtualMachine 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.

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

estimateStorageForConsolidateSnapshots_Task

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

This method can be used prior to invoke consolidation via VcVirtualMachine.

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

reconfigVM_Task

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

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

Creating a virtual machine may require the following privileges: In addition, this operation may require the following privileges:

Parameters

NameTypeDescription
specVcVirtualMachineConfigSpec

The new configuration values.

Return Value

Type Description
VcTask

upgradeVM_Task

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

Parameters

NameTypeDescription
version*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
VcTask

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.

Parameters

NameTypeDescription
None

Return Value

Type Description
string

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 VcDrsBehavior). Because this method does not return a DRS VcClusterRecommendation, no vmotion nor host power operations will be done as part of a DRS-facilitated power on. To have DRS consider such operations use VcDatacenter.

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.

Parameters

NameTypeDescription
host*VcHostSystem

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

powerOffVM_Task

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

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

suspendVM_Task

Suspends execution in this virtual machine.

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

resetVM_Task

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

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

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

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.

Parameters

NameTypeDescription
None

Return Value

Type Description
None

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.

Parameters

NameTypeDescription
None

Return Value

Type Description
None

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.

Parameters

NameTypeDescription
None

Return Value

Type Description
None

answerVM

Responds to a question that is blocking this virtual machine.

Parameters

NameTypeDescription
questionIdstring

The value from QuestionInfo.id that identifies the question to answer.
answerChoicestring

The contents of the QuestionInfo.choice.value array element that identifies the desired answer.

Return Value

Type Description
None

customizeVM_Task

Customizes a virtual machine's guest operating system.

Parameters

NameTypeDescription
specVcCustomizationSpec

The customization specification object.

Return Value

Type Description
VcTask

checkCustomizationSpec

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

Parameters

NameTypeDescription
specVcCustomizationSpec

The customization specification to check.

Return Value

Type Description
None

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.

Parameters

NameTypeDescription
pool*VcResourcePool

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*VcHostSystem

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

The task priority (@see vim.VirtualMachine.MovePriority).
state*VcVirtualMachinePowerState

If specified, the virtual machine migrates only if its state matches the specified state.
*Need not be set

Return Value

Type Description
VcTask

relocateVM_Task

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

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.

Parameters

NameTypeDescription
specVcVirtualMachineRelocateSpec

The specification of where to relocate the virtual machine.
priority*VcVirtualMachineMovePriority

The task priority (@see vim.VirtualMachine.MovePriority).
*Need not be set

Return Value

Type Description
VcTask

cloneVM_Task

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

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

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

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

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

Parameters

NameTypeDescription
folderVcFolder

The location of the new virtual machine.
namestring

The name of the new virtual machine.
specVcVirtualMachineCloneSpec

Specifies how to clone the virtual machine.

Return Value

Type Description
VcTask

exportVm

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

See VcHttpNfcLease for information on how to use the lease.

Parameters

NameTypeDescription
None

Return Value

Type Description
VcHttpNfcLease

markAsTemplate

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

Parameters

NameTypeDescription
None

Return Value

Type Description
None

markAsVirtualMachine

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

Parameters

NameTypeDescription
poolVcResourcePool

Resource pool to associate with the virtual machine.
host*VcHostSystem

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

Return Value

Type Description
None

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.

Parameters

NameTypeDescription
None

Return Value

Type Description
None

resetGuestInformation

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

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

Parameters

NameTypeDescription
None

Return Value

Type Description
None

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, VcGuestInfo and VcGuestInfo

Parameters

NameTypeDescription
None

Return Value

Type Description
None

unmountToolsInstaller

Unmounts VMware Tools installer CD.

Parameters

NameTypeDescription
None

Return Value

Type Description
None

upgradeTools_Task

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

Parameters

NameTypeDescription
installerOptions*string

Command line options passed to the installer to modify the installation procedure for tools.
*Need not be set

Return Value

Type Description
VcTask

acquireMksTicket

Deprecated.

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.

Parameters

NameTypeDescription
None

Return Value

Type Description
VcVirtualMachineMksTicket

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:

Parameters

NameTypeDescription
ticketTypestring

The type of service to acquire, the set of possible values is described in VcVirtualMachineTicketType.

Return Value

Type Description
VcVirtualMachineTicket

setScreenResolution

Sets the console window's resolution as specified.

Parameters

NameTypeDescription
widthnumber

The screen width that should be set.
heightnumber

The screen height that should be set.

Return Value

Type Description
None

defragmentAllDisks

Defragment all virtual disks attached to this virtual machine.

Parameters

NameTypeDescription
None

Return Value

Type Description
None

createSecondaryVM_Task

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

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

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

Parameters

NameTypeDescription
host*VcHostSystem

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

Return Value

Type Description
VcTask

turnOffFaultToleranceForVM_Task

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

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

makePrimaryVM_Task

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

Parameters

NameTypeDescription
vmVcVirtualMachine

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.

Return Value

Type Description
VcTask

terminateFaultTolerantVM_Task

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

Parameters

NameTypeDescription
vm*VcVirtualMachine

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

Return Value

Type Description
VcTask

disableSecondaryVM_Task

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

Parameters

NameTypeDescription
vmVcVirtualMachine

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.

Return Value

Type Description
VcTask

enableSecondaryVM_Task

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

This operation is used to enable a secondary virtual machine that was previously disabled by the VcVirtualMachine 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 VcClusterRecommendation) 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 VcClusterComputeResource.

Parameters

NameTypeDescription
vmVcVirtualMachine

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.
host*VcHostSystem

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

Return Value

Type Description
VcTask

setDisplayTopology

Sets the console window's display topology as specified.

Parameters

NameTypeDescription
displaysVcVirtualMachineDisplayTopology []

The topology for each monitor that the virtual machine's display must span.

Return Value

Type Description
None

startRecording_Task

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

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

Parameters

NameTypeDescription
namestring

The name for the snapshot associated with this recording. The name need not be unique for this virtual machine.
description*string

A description for the snapshot associated with this recording. If omitted, a default description may be provided.
*Need not be set

Return Value

Type Description
VcTask

stopRecording_Task

Stops a currently active recording session on this virtual machine.

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

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

startReplaying_Task

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

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

Parameters

NameTypeDescription
replaySnapshotVcVirtualMachineSnapshot

The snapshot from which to start the replay. This snapshot must have been created by a record operation on the virtual machine.

Return Value

Type Description
VcTask

stopReplaying_Task

Stops a replay session on this virtual machine.

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

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

promoteDisks_Task

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

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

Promoting does two things

  1. If the unlink parameter is true, any disk backing which is shared shared by multiple virtual machines is copied so that this virtual machine has its own unshared version. Copied files always end up in the virtual machine's home directory.
  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 VcHostCapability is true.

This operation is only supported on VirtualCenter.

Parameters

NameTypeDescription
unlinkboolean

If true, then these disks will be unlinked before consolidation.
disks*VcVirtualDisk []

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

Return Value

Type Description
VcTask

createScreenshot_Task

Create a screen shot of a virtual machine.

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

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.

Parameters

NameTypeDescription
snapshot*VcVirtualMachineSnapshot

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

Identifies the virtual disk for which to compute changes.
startOffsetnumber

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

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

Return Value

Type Description
VcDiskChangeInfo

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 VcHostDatastoreSystem

Parameters

NameTypeDescription
None

Return Value

Type Description
string []

reloadVirtualMachineFromPath_Task

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

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

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

Parameters

NameTypeDescription
configurationPathstring


Return Value

Type Description
VcTask

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.

Parameters

NameTypeDescription
None

Return Value

Type Description
VcMethodFault []