Scripting Object - VcHostSystem

Scripting-object corresponding to
HostSystem
Attribute of
_VcPlugin, VcCheckResult, VcClusterComputeResource, VcClusterDasAamNodeState, VcClusterDasFailoverLevelAdvancedRuntimeInfoHostSlots, VcClusterDasHostRecommendation, VcClusterDpmHostConfigInfo, VcClusterDrsMigration, VcClusterFailoverHostAdmissionControlInfoHostStatus, VcClusterFailoverHostAdmissionControlPolicy, VcClusterHostGroup, VcClusterHostRecommendation, VcClusterInitialPlacementAction, VcComputeResource, VcDatastoreHostMount, VcDiagnosticManagerBundleInfo, VcDistributedVirtualPort, VcDistributedVirtualPortgroup, VcDistributedVirtualSwitchHostMemberConfigInfo, VcDistributedVirtualSwitchHostMemberConfigSpec, VcDistributedVirtualSwitchManagerCompatibilityResult, VcDistributedVirtualSwitchManagerHostArrayFilter, VcDvsOperationBulkFaultFaultOnHost, VcDVSSummary, VcHostConfigInfo, VcHostEventArgument, VcHostListSummary, VcHostProfile, VcHostProfileHostBasedConfigSpec, VcHostVmfsRescanResult, VcHostVMotionCompatibility, VcNetwork, VcOvfCreateImportSpecParams, VcProfileReferenceHostChangedEvent, VcSdkConnection, VcVAppCloneSpec, VcVirtualMachineConfigOptionDescriptor, VcVirtualMachineRelocateSpec, VcVirtualMachineRuntimeInfo
Parameter to
applyHostConfig_Task, browseDiagnosticLog, checkCompatibility_Task, checkLicenseFeature, checkMigrate_Task, configureLicenseSource, createChildVM_Task, createChildVM_Task, createSecondaryVM_Task, createVM_Task, disableFeature, enableFeature, enableSecondaryVM_Task, executeHostProfile, generateConfigTaskList, generateLogBundles_Task, importVApp, importVApp, markAsVirtualMachine, migrateVM_Task, moveHostInto_Task, moveInto_Task, powerOnVM_Task, queryConfigOption, queryConfigTarget, queryDescriptions, queryDvsConfigTarget, queryIORMConfigOption, queryLicenseSourceAvailability, queryLicenseUsage, querySupportedFeatures, queryTargetCapabilities, queryVMotionCompatibilityEx_Task, rectifyDvsHost_Task, rectifyDvsHost_Task, registerChildVM_Task, registerChildVM_Task, registerVM_Task, revertToCurrentSnapshot_Task, revertToSnapshot_Task, setLicenseEdition, updateReferenceHost, validateHost
Returned by
getAllHostSystems, getAllHostSystems, queryCompatibleHostForExistingDvs, queryCompatibleHostForNewDvs

Scripting Object Description

The HostSystem managed object type provides access to a virtualization host platform.

Invoking destroy on a HostSystem of standalone type throws a NotSupported fault. A standalone HostSystem can be destroyed only by invoking destroy on its parent ComputeResource. Invoking destroy on a failover host throws a VcDisallowedOperationOnFailoverHost fault. See VcClusterFailoverHostAdmissionControlPolicy.

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.
capability*VcHostCapability

Host capabilities. This might not be available for a disconnected host.
config*VcHostConfigInfo

Host configuration information. This might not be available for a disconnected host.
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.
configManagerVcHostConfigManager

Host configuration systems.
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 are available in this HostSystem.
datastoreBrowserVcHostDatastoreBrowser

DatastoreBrowser to browse datastores for this host.
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.
hardware*VcHostHardwareInfo

Hardware configuration of the host. This might not be available for a disconnected host.
idstring

returns the id of this ManagedObject
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 are available in this HostSystem.
network_DistributedVirtualPortgroupDistributedVirtualPortgroup []

Filtered attribute 'network' with only DistributedVirtualPortgroup objects
network_NetworkNetwork []

Filtered attribute 'network' with only Network objects
overallStatusVcManagedEntityStatus

General health of this managed entity. The value combines the status of all the alarms attached to a managed entity.

If any of the alarms has a gray status, the overall status of the managed entity is gray. Otherwise, if any of the alarms has a red status, the overall status of the managed entity is red. Otherwise, if any of the alarms has a yellow status, the overall status of the managed entity is yellow. Otherwise, the overall status of the managed entity is green.

parent*VcManagedEntity

Parent of this entity.

This value is null for the root object.

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
resourcePool_ResourcePoolResourcePool []

Filtered attribute 'resourcePool' with only ResourcePool objects
resourcePool_VirtualAppVirtualApp []

Filtered attribute 'resourcePool' with only VirtualApp objects
runtimeVcHostRuntimeInfo

Runtime state information about the host such as connection state.
sdkConnectionVcSdkConnection

returns the parent SdkConnection
summaryVcHostListSummary

Basic information about the host, including connection state.
systemResources*VcHostSystemResourceInfo

Reference for the system resource hierarchy, used for configuring the set of resources reserved to the system and unavailable to virtual machines.
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
vm*VcVirtualMachine []

List of virtual machines associated with this host.
*May not be present

Methods

Methods defined in this Scripting Object
acquireCimServicesTicket, createTrigger, destroy_Task, disconnectHost_Task, enterLockdownMode, enterMaintenanceMode_Task, exitLockdownMode, exitMaintenanceMode_Task, powerDownHostToStandBy_Task, powerUpHostFromStandBy_Task, queryHostConnectionInfo, queryMemoryOverhead, queryMemoryOverheadEx, rebootHost_Task, reconfigureHostForDAS_Task, reconnectHost_Task, reload, rename_Task, retrieveHardwareUptime, setCustomValue, shutdownHost_Task, updateFlags, updateIpmi, updateSystemResources

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

queryHostConnectionInfo

Connection-oriented information about a host.

Parameters

NameTypeDescription
None

Return Value

Type Description
VcHostConnectInfo

updateSystemResources

Update the configuration of the system resource hierarchy.

Parameters

NameTypeDescription
resourceInfoVcHostSystemResourceInfo


Return Value

Type Description
None

reconnectHost_Task

Reconnects to a host. This process reinstalls agents and reconfigures the host, if it has gotten out of date with VirtualCenter. The reconnection process goes through many of the same steps as addHost: ensuring the correct set of licenses for the number of CPUs on the host, ensuring the correct set of agents is installed, and ensuring that networks and datastores are discovered and registered with VirtualCenter.

The client can change the IP address and port of the host when doing a reconnect operation. This can be useful if the client wants to preserve existing metadata, even though the host is changing its IP address. For example, clients could preserve existing statistics, alarms, and privileges.

This method can also be used to change the SSL thumbprint of a connected host without disconnecting it.

This method is only supported through VirtualCenter.

Parameters

NameTypeDescription
cnxSpec*VcHostConnectSpec

Includes the parameters to use, including user name and password, when reconnecting to the host. If this parameter is not specified, the default connection parameters is used.
*Need not be set

Return Value

Type Description
VcTask

disconnectHost_Task

Disconnects from a host and instructs the server to stop sending heartbeats.

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

enterMaintenanceMode_Task

Puts the host in maintenance mode. While this task is running and when the host is in maintenance mode, no virtual machines can be powered on and no provisioning operations can be performed on the host. Once the call completes, it is safe to turn off a host without disrupting any virtual machines.

The task completes once there are no powered-on virtual machines on the host and no provisioning operations in progress on the host. The operation does not directly initiate any operations to evacuate or power-down powered-on virtual machines. However, if the host is part of a cluster with VMware DRS enabled, DRS provides migration recommendations to evacuate the powered-on virtual machines. If DRS is in fully-automatic mode, these are automatically scheduled.

If the host is part of a cluster and the task is issued through VirtualCenter with evacuatePoweredOffVms set to true, the task will not succeed unless all the powered-off virtual machines are reregistered to other hosts. If VMware DRS is enabled, VC will automatically evacuate powered-off virtual machines. The task is cancellable.

Parameters

NameTypeDescription
timeoutnumber

The task completes when the host successfully enters maintenance mode or the timeout expires, and in the latter case the task contains a Timeout fault. If the timeout is less than or equal to zero, there is no timeout. The timeout is specified in seconds.
evacuatePoweredOffVms*boolean

This is a parameter only supported by VirtualCenter. If set to true, for a DRS disabled cluster, the task will not succeed unless all powered-off virtual machines have been manually reregistered; for a DRS enabled cluster, VirtualCenter will automatically reregister powered-off virtual machines and a powered-off virtual machine may remain at the host only for two reasons: (a) no compatible host found for reregistration, (b) DRS is disabled for the virtual machine. If set to false, powered-off virtual machines do not need to be moved.
*Need not be set

Return Value

Type Description
VcTask

exitMaintenanceMode_Task

Takes the host out of maintenance mode. This blocks if any concurrent running maintenance-only host configurations operations are being performed. For example, if VMFS volumes are being upgraded.

The task is cancellable.

Parameters

NameTypeDescription
timeoutnumber

Number of seconds to wait for the exit maintenance mode to succeed. If the timeout is less than or equal to zero, there is no timeout.

Return Value

Type Description
VcTask

rebootHost_Task

Reboots a host. If the command is successful, then the host has been rebooted. If connected directly to the host, the client never receives an indicator of success in the returned task but simply loses connection to the host, upon success.

This command is not supported on all hosts. Check the host capability VcHostCapability.

Parameters

NameTypeDescription
forceboolean

Flag to specify whether or not the host should be rebooted regardless of whether it is in maintenance mode. If true, the host is rebooted, even if there are virtual machines running or other operations in progress.

Return Value

Type Description
VcTask

shutdownHost_Task

Shuts down a host. If the command is successful, then the host has been shut down. Thus, the client never receives an indicator of success in the returned task if connected directly to the host.

This command is not supported on all hosts. Check the host capability VcHostCapability.

Parameters

NameTypeDescription
forceboolean

Flag to specify whether or not the host should be shut down regardless of whether it is in maintenance mode. If true, the host is shut down, even if there are virtual machines running or other operations in progress.

Return Value

Type Description
VcTask

powerDownHostToStandBy_Task

Puts the host in standby mode, a mode in which the host is in a standby state from which it can be powered up remotely. While this task is running, no virtual machines can be powered on and no provisioning operations can be performed on the host.

The task completes only if there are no powered-on virtual machines on the host, no provisioning operations in progress on the host, and the host stopped responding. The operation does not directly initiate any operations to evacuate or power-down powered-on virtual machines. However, if a dynamic recommendation generation module is running, if possible, it will provide, and depending on the automation level, it will execute migrations of powered-on virtual machine. Furthermore, VMware power management module may evacute and put a host in standby mode to save power. If the host is part of a cluster and the task is issued through VirtualCenter with evacuatePoweredOffVms set to true, the task will not succeed unless all the powered-off virtual machines are reregistered to other hosts. If VMware DRS is enabled, VC will automatically evacuate powered-off virtual machines.

The task is cancellable.

This command is not supported on all hosts. Check the host capability VcHostCapability.

Parameters

NameTypeDescription
timeoutSecnumber

The task completes when the host successfully enters standby mode and stops sending heartbeat signals. If heartbeats are still coming after timeoutSecs seconds, the host is declared timedout, and the task is assumed failed.
evacuatePoweredOffVms*boolean

This is a parameter used only by VirtualCenter. If set to true, for a DRS disabled cluster, the task will not succeed unless all powered-off virtual machines have been manually reregistered; for a DRS enabled cluster, VirtualCenter will automatically reregister powered-off virtual machines and a powered-off virtual machine may remain at the host only for two reasons: (a) no compatible host found for reregistration, (b) DRS is disabled for the virtual machine.
*Need not be set

Return Value

Type Description
VcTask

powerUpHostFromStandBy_Task

Takes the host out of standby mode. If the command is successful, the host wakes up and starts sending heartbeats. This method may be called automatically by a dynamic recommendation generation module to add capacity to a cluster, if the host is not in maintenance mode.

Note that, depending on the implementation of the wakeup method, the client may never receive an indicator of success in the returned task. In some cases, it is not even possible to ensure that the wakeup request has made it to the host.

The task is cancellable.

Parameters

NameTypeDescription
timeoutSecnumber

The task completes when the host successfully exits standby state and sends a heartbeat signal. If nothing is received from the host for timeoutSec seconds, the host is declared timedout, and the task is assumed failed.

Return Value

Type Description
VcTask

queryMemoryOverhead

Deprecated.

Determines the amount of memory overhead necessary to power on a virtual machine with the specified characteristics.

Parameters

NameTypeDescription
memorySizenumber

The amount of virtual system RAM, in bytes. For an existing virtual machine, this value can be found (in megabytes) as the memoryMB property of the VcVirtualHardware.
videoRamSize*number

The amount of virtual video RAM, in bytes. For an existing virtual machine on a host that supports advertising this property, this value can be found (in kilobytes) as the videoRamSizeInKB property of the VcVirtualMachineVideoCard. If this parameter is left unset, the default video RAM size for virtual machines on this host is assumed.
numVcpusnumber

The number of virtual CPUs. For an existing virtual machine, this value can be found as the numCPU property of the VcVirtualHardware.
*Need not be set

Return Value

Type Description
number

queryMemoryOverheadEx

Determines the amount of memory overhead necessary to power on a virtual machine with the specified characteristics.

Parameters

NameTypeDescription
vmConfigInfoVcVirtualMachineConfigInfo

The configuration of the virtual machine.

Return Value

Type Description
number

reconfigureHostForDAS_Task

Reconfigures the host for VMware HA.

If the host is part of a HA cluster, this operation reconfigures the host for HA. For example, this operation may be used if a host is added to a HA enabled cluster and the automatic HA configuration system task fails. Automatic HA configuration may fail for a variety of reasons. For example, the host is configured incorrectly.

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

updateFlags

Update flags that are part of the VcHostFlagInfo object.

Parameters

NameTypeDescription
flagInfoVcHostFlagInfo


Return Value

Type Description
None

enterLockdownMode

Modifies the permissions on the host, so that it will only be accessible through local console or an authorized centralized management application. Any user defined permissions found on the host are lost.

Access via a VI client connected to the host is blocked. Access though other services running on the host is also blocked.

If the operation is successful, VcHostConfigInfo will be set to true. This API is not supported on the host, If invoked directly on a host, a NotSupported fault will be thrown.
See VcAuthorizationManager

Parameters

NameTypeDescription
None

Return Value

Type Description
None

exitLockdownMode

Restores Administrator permission for the local administrative account for the host that was removed by prior call to VcHostSystem. If the operation is successful, VcHostConfigInfo will be set to false. This API is not supported on the host. If invoked directly on a host, a NotSupported fault will be thrown.
See VcAuthorizationManager

Parameters

NameTypeDescription
None

Return Value

Type Description
None

acquireCimServicesTicket

Creates and returns a one-time credential used to establish a remote connection to a CIM interface. The port to connect to is the standard well known port for the service.

Parameters

NameTypeDescription
None

Return Value

Type Description
VcHostServiceTicket

updateIpmi

Update fields that are part of the VcHostIpmiInfo object.

Parameters

NameTypeDescription
ipmiInfoVcHostIpmiInfo


Return Value

Type Description
None

retrieveHardwareUptime

Return the hardware uptime of the host in seconds. The harware uptime of a host is not affected by NTP and changes to its wall clock time and can be used by clients to provide a common time reference for all hosts.

Parameters

NameTypeDescription
None

Return Value

Type Description
number

createTrigger

Create a trigger from this ManagedObject

Parameters

NameTypeDescription
timeoutnumber

Waiting timout in seconds
filterstring

The monitored vCenter API filter
conditionstring

The condition in OGNL language
filterToSync*string

The vCenter API filter used to synchronize the content of the session
*Need not be set

Return Value

Type Description
Trigger