Managed Object - HostSystem(vim.HostSystem)

Property of: ActiveVMsBlockingEVC, AnswerFileStatusResult, ApplyHostProfileConfigurationResult, ApplyHostProfileConfigurationSpec, CannotEnableVmcpForCluster, CheckResult, ClusterComputeResourceClusterConfigResult, ClusterComputeResourceHCIConfigInfo, ClusterComputeResourceHostConfigurationInput, ClusterComputeResourceHostConfigurationValidation, ClusterComputeResourceVcsSlots, ClusterDasAamNodeState, ClusterDasFailoverLevelAdvancedRuntimeInfoHostSlots, ClusterDasFdmHostState, ClusterDasHostRecommendation, ClusterDpmHostConfigInfo, ClusterDrsMigration, ClusterEVCManagerCheckResult, ClusterFailoverHostAdmissionControlInfoHostStatus, ClusterFailoverHostAdmissionControlPolicy, ClusterHostGroup, ClusterHostRecommendation, ClusterInitialPlacementAction, ComputeResource, ComputeResourceHostSPBMLicenseInfo, CpuIncompatible, CryptoManagerKmipCryptoKeyStatus, DasHeartbeatDatastoreInfo, DatastoreHostMount, DatastoreNotWritableOnHost, DiagnosticManagerBundleInfo, DisallowedOperationOnFailoverHost, DistributedVirtualPort, DistributedVirtualSwitchHostMemberConfigInfo, DistributedVirtualSwitchHostMemberConfigSpec, DistributedVirtualSwitchManagerCompatibilityResult, DistributedVirtualSwitchManagerHostArrayFilter, DistributedVirtualSwitchPortCriteria, DrsVmotionIncompatibleFault, DvsOperationBulkFaultFaultOnHost, DVSSummary, EnvironmentBrowserConfigOptionQuerySpec, EVCModeUnsupportedByHosts, EVCUnsupportedByHostHardware, EVCUnsupportedByHostSoftware, FaultsByHost, FaultToleranceAntiAffinityViolated, FeatureRequirementsNotMet, FolderBatchAddHostsToClusterResult, FolderBatchAddStandaloneHostsResult, FolderFailedHostResult, FtIssuesOnHost, HostConfigInfo, HostEventArgument, HostListSummary, HostMemberRuntimeInfo, HostProfile, HostProfileCompleteConfigSpec, HostProfileHostBasedConfigSpec, HostProfileManagerHostToConfigSpecMap, HostProfileSerializedHostProfileSpec, HostProfileValidationFailureInfo, HostProtocolEndpoint, HostSpecification, HostSpecificationOperationFailed, HostVmfsRescanResult, HostVMotionCompatibility, IncompatibleHostForFtSecondary, InsufficientHostCapacityFault, InvalidHostState, InvalidProfileReferenceHost, IoFilterHostIssue, IORMNotSupportedHostOnDatastore, MigrationFeatureNotSupported, Network, NoCompatibleHost, NodeDeploymentSpec, NotEnoughLogicalCpus, NotSupportedDeviceForFT, OvfCreateImportSpecParams, PlacementAction, PlacementSpec, ProfileReferenceHostChangedEvent, QuiesceDatastoreIOForHAFailed, RuleViolation, StoragePlacementSpec, ThirdPartyLicenseAssignmentFailed, VAppCloneSpec, VirtualHardwareVersionNotSupported, VirtualMachineConfigOptionDescriptor, VirtualMachineRelocateSpec, VirtualMachineRuntimeInfo, VmAlreadyExistsInDatacenter, VMotionInterfaceIssue, VmWwnConflict, VsanHostConfigInfo, VsanUpgradeSystemAPIBrokenIssue, VsanUpgradeSystemAutoClaimEnabledOnHostsIssue, VsanUpgradeSystemHostsDisconnectedIssue, VsanUpgradeSystemMissingHostsInClusterIssue, VsanUpgradeSystemNetworkPartitionInfo, VsanUpgradeSystemUpgradeHistoryItem, VsanUpgradeSystemWrongEsxVersionIssue, VVolHostPE
Parameter to: ApplyHostConfig_Task, BatchAddHostsToCluster_Task, BrowseDiagnosticLog, CertMgrRefreshCACertificatesAndCRLs_Task, CertMgrRefreshCertificates_Task, CertMgrRevokeCertificates_Task, CheckAnswerFileStatus_Task, CheckCompatibility_Task, CheckLicenseFeature, CheckMigrate_Task, CheckPowerOn_Task, CheckVmConfig_Task, ClusterEnterMaintenanceMode, ConfigureLicenseSource, CreateChildVM_Task, CreateSecondaryVM_Task, CreateSecondaryVMEx_Task, CreateVM_Task, DeleteHostSpecification, DeleteHostSubSpecification, DisableFeature, EnableFeature, EnableSecondaryVM_Task, ExecuteHostProfile, ExportAnswerFile_Task, GenerateConfigTaskList, GenerateHostProfileTaskList_Task, GenerateLogBundles_Task, ImportVApp, LookupVmOverheadMemory, MarkAsVirtualMachine, MigrateVM_Task, MoveHostInto_Task, MoveInto_Task, PerformVsanUpgrade_Task, PowerOnVM_Task, QueryAnswerFileStatus, QueryConfigOption, QueryConfigTarget, QueryDescriptions, QueryDvsConfigTarget, QueryIORMConfigOption, QueryLicenseSourceAvailability, QueryLicenseUsage, QuerySupportedFeatures, QueryTargetCapabilities, QueryVMotionCompatibility, QueryVMotionCompatibilityEx_Task, RectifyDvsHost_Task, RectifyDvsOnHost_Task, RegisterChildVM_Task, RegisterVM_Task, ResolveInstallationErrorsOnHost_Task, RetrieveAnswerFile, RetrieveAnswerFileForProfile, RetrieveHostCustomizations, RetrieveHostCustomizationsForProfile, RetrieveHostSpecification, RevertToCurrentSnapshot_Task, RevertToSnapshot_Task, SetLicenseEdition, UpdateAnswerFile_Task, UpdateHostSpecification, UpdateHostSubSpecification, UpdateReferenceHost, ValidateHCIConfiguration, ValidateHost, ValidateMigration
Returned by: AddHost_Task, HostSpecGetUpdatedHosts, QueryCompatibleHostForExistingDvs, QueryCompatibleHostForNewDvs, QueryHostsWithAttachedLun, QueryUnmonitoredHosts
Extends: ManagedEntity
See also: AnswerFileStatusResult, ApplyHostProfileConfigurationResult, ApplyHostProfileConfigurationSpec, ComplianceResult, CryptoKeyId, CryptoKeyPlain, Datastore, HostCapability, HostConfigInfo, HostConfigManager, HostConnectInfo, HostConnectSpec, HostDatastoreBrowser, HostFlagInfo, HostHardwareInfo, HostIpmiInfo, HostLicensableResourceInfo, HostListSummary, HostMaintenanceSpec, HostRuntimeInfo, HostServiceTicket, HostSystemComplianceCheckState, HostSystemReconnectSpec, HostSystemRemediationState, HostSystemResourceInfo, HostSystemSwapConfiguration, HostTpmAttestationReport, Network, VirtualMachine, VirtualMachineConfigInfo
Since: 2.0

Managed 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 DisallowedOperationOnFailoverHost fault. See ClusterFailoverHostAdmissionControlPolicy.

Properties

Name	Type	Description
answerFileValidationResult*	AnswerFileStatusResult	Host answer file validation result. *Since* vSphere API 6.7
answerFileValidationState*	AnswerFileStatusResult	Host answer file validation state. *Since* vSphere API 6.7
capability*	HostCapability	Host capabilities. This might not be available for a disconnected host.
complianceCheckResult*	ComplianceResult	The host profile compliance check result. *Since* vSphere API 6.7
complianceCheckState*	HostSystemComplianceCheckState	The host profile compliance check state. *Since* vSphere API 6.7
config*	HostConfigInfo	Host configuration information. This might not be available for a disconnected host.
configManager	HostConfigManager	Host configuration systems. In releases after vSphere API 5.0, vSphere Servers might not generate property collector update notifications for this property. To obtain the latest value of the property, you can use PropertyCollector methods RetrievePropertiesEx or WaitForUpdatesEx. If you use the PropertyCollector.WaitForUpdatesEx method, specify an empty string for the version parameter. Any other version value will not produce any property values as no updates are generated.
datastore* P	ManagedObjectReference[] to a Datastore[]	A collection of references to the subset of datastore objects in the datacenter that are available in this HostSystem.
datastoreBrowser P	ManagedObjectReference to a HostDatastoreBrowser	DatastoreBrowser to browse datastores for this host.
hardware*	HostHardwareInfo	Hardware configuration of the host. This might not be available for a disconnected host.
licensableResource	HostLicensableResourceInfo	Information about all licensable resources, currently present on this host. This information is used mostly by the modules, manipulating information in the LicenseManager. Developers of such modules should use this property instead of Hardware. NOTE: The values in this property may not be accurate for pre-5.0 hosts when returned by vCenter 5.0 *Since* vSphere API 5.0
network* P	ManagedObjectReference[] to a Network[]	A collection of references to the subset of network objects in the datacenter that are available in this HostSystem.
precheckRemediationResult*	ApplyHostProfileConfigurationSpec	The host profile precheck-remediation result. *Since* vSphere API 6.7
remediationResult*	ApplyHostProfileConfigurationResult	The host profile remediation result. *Since* vSphere API 6.7
remediationState*	HostSystemRemediationState	The host profile remediation state. *Since* vSphere API 6.7
runtime	HostRuntimeInfo	Runtime state information about the host such as connection state.
summary	HostListSummary	Basic information about the host, including connection state.
systemResources*	HostSystemResourceInfo	Reference for the system resource hierarchy, used for configuring the set of resources reserved to the system and unavailable to virtual machines.
vm*	ManagedObjectReference[] to a VirtualMachine[]	List of virtual machines associated with this host.
Properties inherited from ManagedEntity
alarmActionsEnabled, configIssue, configStatus, customValue, declaredAlarmState, disabledMethod, effectiveRole, name, overallStatus, parent, permission, recentTask, tag, triggeredAlarmState
Properties inherited from ExtensibleManagedObject
availableField, value

*May not be presentP Required privilege: System.View

Methods

Methods defined in this Managed Object
AcquireCimServicesTicket, ConfigureCryptoKey, DisconnectHost_Task, EnableCrypto, EnterLockdownMode, EnterMaintenanceMode_Task, ExitLockdownMode, ExitMaintenanceMode_Task, PowerDownHostToStandBy_Task, PowerUpHostFromStandBy_Task, PrepareCrypto, QueryHostConnectionInfo, QueryMemoryOverhead, QueryMemoryOverheadEx, QueryProductLockerLocation, QueryTpmAttestationReport, RebootHost_Task, ReconfigureHostForDAS_Task, ReconnectHost_Task, RetrieveFreeEpcMemory, RetrieveHardwareUptime, ShutdownHost_Task, UpdateFlags, UpdateIpmi, UpdateProductLockerLocation_Task, UpdateSystemResources, UpdateSystemSwapConfiguration
Methods inherited from ManagedEntity
Destroy_Task, Reload, Rename_Task
Methods inherited from ExtensibleManagedObject
setCustomValue

AcquireCimServicesTicket(acquireCimServicesTicket)

Creates and returns a credential used to establish a remote connection to a Web Based Management (CIM) interface. Valid only when ESXi wbem authentication mode is set to password. The ticket provides the port for the service and sslThumbprint should be used by client to validate ssl connection. This ticket is valid for 2 minutes then will expire and is non-renewable.

Required Privileges: Host.Cim.CimInteraction
Since: VI API 2.5

Parameters

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

Return Value

Type	Description
HostServiceTicket

Faults

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

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="AcquireCimServicesTicket" type="vim25:AcquireCimServicesTicketRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="AcquireCimServicesTicketResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:HostServiceTicket"/>
                     </sequence>
                  </complexType>
               </element>

ConfigureCryptoKey(configureCryptoKey)

Sets/changes the key to be used for coredump encryption and puts the host in vim.HostSystem.CryptoState#safe state. This function will make the host crypto safe and unlock all encrypted VMs on the host. When the encryption on the host is enabled for the first time after adding it to vCenter Server, this method will start sending asynchronously all the encryption keys for VMs on the host and cluster to unlock encrypted VMs. This API behaves differently on the ESXi host vs. the vCenter server. Before vSphere 7.0, it is not supported on host, and invoking directly on a host will throw NotSupported fault. Since vSphere 7.0, calling the API on host will make the host crypto safe, but the parameter should not be blank and should only be a key id from a trusted key provider.

Required Privileges: Cryptographer.RegisterHost
Since: vSphere API 6.5

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the HostSystem used to make the method call.

keyId* P

CryptoKeyId

The key to be used for coredump encryption. If unset, uses existing host or cluster key or new key is generated from the default KMIP server.

Since vSphere API 6.5

*Need not be set P Required privilege: keyId

Return Value

Type	Description
None

Faults

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

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ConfigureCryptoKey" type="vim25:ConfigureCryptoKeyRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ConfigureCryptoKeyResponse">
                  <complexType/>
               </element>

DisconnectHost_Task(disconnect)

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

Required Privileges: Host.Config.Connection

Parameters

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

Return Value

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

Faults

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

Events

Type
None

EnableCrypto(enableCrypto)

Sets/changes the key to be used for coredump encryption and puts the host in vim.HostSystem.CryptoState#safe state Note: PrepareCrypto must be called first

Required Privileges: Cryptographer.RegisterHost
Since: vSphere API 6.5

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the HostSystem used to make the method call.

keyPlain P

CryptoKeyPlain

The key to be used for coredump encryption

Since vSphere API 6.5

P Required privilege: keyPlain

Return Value

Type	Description
None

Faults

Type	Description
InvalidState	Thrown if the host is in vim.HostSystem.CryptoState#incapable state
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="EnableCrypto" type="vim25:EnableCryptoRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="EnableCryptoResponse">
                  <complexType/>
               </element>

EnterLockdownMode(enterLockdownMode)

Deprecated. As of vSphere API 6.0, use ChangeLockdownMode.

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, adminDisabled 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 AuthorizationManager

Required Privileges: Host.Config.Settings
Since: vSphere API 4.1

Parameters

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

Return Value

Type	Description
None

Faults

Type	Description
AdminDisabled	Thrown if the host's Administrator permission has been disabled. See AuthorizationManager
DisableAdminNotSupported	Thrown if invoked directly on the host or the host doesn't support this operation. See AuthorizationManager
HostConfigFault	See AuthorizationManager
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="EnterLockdownMode" type="vim25:EnterLockdownModeRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="EnterLockdownModeResponse">
                  <complexType/>
               </element>

EnterMaintenanceMode_Task(enterMaintenanceMode)

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, vCenter Server will automatically evacuate powered-off virtual machines.

If this API is called directly on the ESXi host, then the user is responsible for powering off, suspending or evacuating all powered-on virtual machines. The task is cancellable.

Required Privileges: Host.Config.Maintenance

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostSystem used to make the method call.
timeout P	xsd:int	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. *Since* 2.0
evacuatePoweredOffVms* P	xsd: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. *Since* 2.0
maintenanceSpec* P	HostMaintenanceSpec	Any additional actions to be taken by the host upon entering maintenance mode. If omitted, default actions will be taken as documented in the HostMaintenanceSpec. *Since* 2.0

*Need not be set PRequired privilege - see tooltip for details

Return Value

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

Faults

Type	Description
InvalidState	Thrown if the host is already in maintenance mode.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
Timedout	Thrown if the operation timed out.

Events

Type
None

ExitLockdownMode(exitLockdownMode)

Deprecated. As of vSphere API 6.0, use ChangeLockdownMode.

Restores Administrator permission for the local administrative account for the host that was removed by prior call to EnterLockdownMode. If the operation is successful, adminDisabled 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 AuthorizationManager

Required Privileges: Host.Config.Settings
Since: vSphere API 4.1

Parameters

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

Return Value

Type	Description
None

Faults

Type	Description
AdminNotDisabled	Thrown if the host's Administrator permission is not disabled. See AuthorizationManager
DisableAdminNotSupported	Thrown if invoked directly on the host or the host doesn't support this operation. See AuthorizationManager
HostConfigFault	See AuthorizationManager
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ExitLockdownMode" type="vim25:ExitLockdownModeRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ExitLockdownModeResponse">
                  <complexType/>
               </element>

ExitMaintenanceMode_Task(exitMaintenanceMode)

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.

Required Privileges: Host.Config.Maintenance

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the HostSystem used to make the method call.

timeout P

xsd:int

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.

Since 2.0

P Required privilege: timeout

Return Value

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

Faults

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

Events

Type
None

PowerDownHostToStandBy_Task(enterStandbyMode)

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, vCenter Server will automatically evacuate powered-off virtual machines.

The task is cancellable.

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

Required Privileges: Host.Config.Maintenance
Since: VI API 2.5

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the HostSystem used to make the method call.

timeoutSec P

xsd:int

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.

Since VI API 2.5

evacuatePoweredOffVms* P

xsd: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.

Since VI API 2.5

*Need not be set PRequired privilege - see tooltip for details

Return Value

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

Faults

Type	Description
HostPowerOpFailed	Thrown if the standby operation fails.
InvalidState	Thrown if the host is already in standby mode, or disconnected.
NotSupported	Thrown if the host does not support standby mode.
RequestCanceled	Thrown if the operation is canceled.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
Timedout

Events

Type
None

PowerUpHostFromStandBy_Task(exitStandbyMode)

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.

Required Privileges: Host.Config.Maintenance
Since: VI API 2.5

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the HostSystem used to make the method call.

timeoutSec P

xsd:int

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.

Since VI API 2.5

P Required privilege: timeoutSec

Return Value

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

Faults

Type	Description
HostPowerOpFailed	Thrown if the standby operation fails.
InvalidState	Thrown if the host is in a state from which it cannot be woken up (e.g., disconnected, poweredOff)
NotSupported	Thrown if the host does not support standby mode.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
Timedout

Events

Type
None

PrepareCrypto(prepareCrypto)

Prepare the host for receiving sensitive information and puts the host in vim.HostSystem.CryptoState#prepared mode Note: Must be invoked before EnableCrypto

Required Privileges: Cryptographer.RegisterHost
Since: vSphere API 6.5

Parameters

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

Return Value

Type	Description
None

Faults

Type	Description
InvalidState	Thrown if the host is not in vim.HostSystem.CryptoState#incapable state
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="PrepareCrypto" type="vim25:PrepareCryptoRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="PrepareCryptoResponse">
                  <complexType/>
               </element>

QueryHostConnectionInfo(queryConnectionInfo)

Connection-oriented information about a host.

Required Privileges: System.Read

Parameters

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

Return Value

Type	Description
HostConnectInfo

Faults

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

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryHostConnectionInfo" type="vim25:QueryHostConnectionInfoRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryHostConnectionInfoResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:HostConnectInfo"/>
                     </sequence>
                  </complexType>
               </element>

QueryMemoryOverhead(queryOverhead)

Deprecated. As of VI API 2.5, use QueryMemoryOverheadEx.

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

Required Privileges: System.Read

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostSystem used to make the method call.
memorySize P	xsd:long	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 VirtualHardware. *Since* 2.0
videoRamSize* P	xsd:int	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 VirtualMachineVideoCard. If this parameter is left unset, the default video RAM size for virtual machines on this host is assumed. *Since* 2.0
numVcpus P	xsd:int	The number of virtual CPUs. For an existing virtual machine, this value can be found as the numCPU property of the VirtualHardware. *Since* 2.0

*Need not be set PRequired privilege - see tooltip for details

Return Value

Type	Description
xsd:long	The amount of overhead memory required to power on such a virtual machine, in bytes.

Faults

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

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryMemoryOverhead" type="vim25:QueryMemoryOverheadRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryMemoryOverheadResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="xsd:long"/>
                     </sequence>
                  </complexType>
               </element>

QueryMemoryOverheadEx(queryOverheadEx)

Deprecated. As of VI API 6.0, use initialOverhead.

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

Required Privileges: System.Read
Since: VI API 2.5

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the HostSystem used to make the method call.

vmConfigInfo P

VirtualMachineConfigInfo

The configuration of the virtual machine.

Since VI API 2.5

P Required privilege: vmConfigInfo

Return Value

Type	Description
xsd:long	The amount of overhead memory required to power on such a virtual machine, in bytes.

Faults

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

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryMemoryOverheadEx" type="vim25:QueryMemoryOverheadExRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryMemoryOverheadExResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="xsd:long"/>
                     </sequence>
                  </complexType>
               </element>

QueryProductLockerLocation(queryProductLockerLocation)

Query the path to VMware Tools repository configured on the host. The host should be powered on.

Required Privileges: System.Read
Since: vSphere API 6.7.1

Parameters

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

Return Value

Type	Description
xsd:string	The absolute path currently set for the VMware Tools repository on the host.

Faults

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

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryProductLockerLocation" type="vim25:QueryProductLockerLocationRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryProductLockerLocationResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="xsd:string"/>
                     </sequence>
                  </complexType>
               </element>

QueryTpmAttestationReport(queryTpmAttestationReport)

Basic information about TPM attestation state of the host.

Required Privileges: System.Read
Since: vSphere API 5.1

Parameters

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

Return Value

Type	Description
HostTpmAttestationReport

Faults

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

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryTpmAttestationReport" type="vim25:QueryTpmAttestationReportRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryTpmAttestationReportResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:HostTpmAttestationReport" minOccurs="0"/>
                     </sequence>
                  </complexType>
               </element>

RebootHost_Task(reboot)

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 rebootSupported. If QuickBoot is enabled on the host, additional setup steps are performed.

Required Privileges: Host.Config.Maintenance

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the HostSystem used to make the method call.

force P

xsd:boolean

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.

Since 2.0

P Required privilege: force

Return Value

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

Faults

Type	Description
InvalidState	Thrown if "force" is false and the host is not in maintenance mode.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

ReconfigureHostForDAS_Task(reconfigureDAS)

Reconfigures the host for vSphere 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.

Required Privileges: Host.Config.Connection

Parameters

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

Return Value

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

Faults

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

Events

Type
None

ReconnectHost_Task(reconnect)

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.

Any changes made to the resource hierarchy on the host when the host was disconnected are overriden by VirtualCenter settings on reconnect.

This method is only supported through VirtualCenter.

Required Privileges: Host.Config.Connection

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the HostSystem used to make the method call.

cnxSpec* P

HostConnectSpec

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.

Since 2.0

reconnectSpec* P

HostSystemReconnectSpec

Includes connection parameters specific to reconnect. This will mainly be used to indicate how to handle divergence between the host settings and vCenter Server settings when the host was disconnected.

Since 2.0

*Need not be set PRequired privilege - see tooltip for details

Return Value

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

Faults

Type	Description
AlreadyBeingManaged	Thrown if host is already being managed by another VirtualCenter server
GatewayConnectFault	Thrown if the host is managed via host gateway and any error occurred during the communication with the gateway
GatewayHostNotReachable	Thrown if the host is managed via host gateway and the gateway server cannot connect to the host
GatewayNotFound	Thrown if the host is managed via host gateway and no available gateway server is found for the given parameters
GatewayNotReachable	Thrown if the host is managed via host gateway and vCenter Server cannot establish a network connection to the gateway server, or verify the gateway server's identity
GatewayOperationRefused	Thrown if the gateway server cannot accept more host connections
GatewayToHostAuthFault	Thrown if the host is managed via host gateway and the gateway server needs additional information to authenticate before the host
GatewayToHostTrustVerifyFault	Thrown if the host is managed via host gateway and the gateway server cannot verify that the host is trusted
HostConnectFault	Thrown if an error occurred when attempting to reconnect to a host. Typically, a more specific subclass, such as AlreadyBeingManaged, is thrown.
InvalidLogin	Thrown if the method fails to authenticate with the host.
InvalidName	Thrown if the host name is invalid.
InvalidState	Thrown if the host is not disconnected.
NoHost	Thrown if the method is unable to contact the server.
NotSupportedHost	Thrown if the host is running a software version that is not supported.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
SSLVerifyFault	Thrown if the host certificate could not be authenticated.

Events

Type
None

RetrieveFreeEpcMemory(retrieveFreeEpcMemory)

Return the amount of free EPC memory on the host in bytes.

Required Privileges: System.Read
Since: vSphere API 7.0

Parameters

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

Return Value

Type	Description
xsd:long

Faults

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

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RetrieveFreeEpcMemory" type="vim25:RetrieveFreeEpcMemoryRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RetrieveFreeEpcMemoryResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="xsd:long"/>
                     </sequence>
                  </complexType>
               </element>

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

Required Privileges: System.Read
Since: vSphere API 4.1

Parameters

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

Return Value

Type	Description
xsd:long

Faults

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

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RetrieveHardwareUptime" type="vim25:RetrieveHardwareUptimeRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RetrieveHardwareUptimeResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="xsd:long"/>
                     </sequence>
                  </complexType>
               </element>

ShutdownHost_Task(shutdown)

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

Required Privileges: Host.Config.Maintenance

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the HostSystem used to make the method call.

force P

xsd:boolean

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.

Since 2.0

P Required privilege: force

Return Value

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

Faults

Type	Description
InvalidState	Thrown if "force" is false and the host is not in maintenance mode.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

UpdateFlags(updateFlags)

Update flags that are part of the HostFlagInfo object.

Required Privileges: Host.Config.Settings
Since: VI API 2.5

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the HostSystem used to make the method call.

flagInfo P

HostFlagInfo

Since VI API 2.5

P Required privilege: flagInfo

Return Value

Type	Description
None

Faults

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

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateFlags" type="vim25:UpdateFlagsRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateFlagsResponse">
                  <complexType/>
               </element>

UpdateIpmi(updateIpmi)

Update fields that are part of the HostIpmiInfo object.

Required Privileges: Host.Config.Settings
Since: vSphere API 4.0

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the HostSystem used to make the method call.

ipmiInfo P

HostIpmiInfo

Since vSphere API 4.0

P Required privilege: ipmiInfo

Return Value

Type	Description
None

Faults

Type	Description
InvalidIpmiLoginInfo	Thrown if the supplied user ID and/or password is invalid.
InvalidIpmiMacAddress	Thrown if the supplied MAC address is invalid.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateIpmi" type="vim25:UpdateIpmiRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateIpmiResponse">
                  <complexType/>
               </element>

UpdateProductLockerLocation_Task(updateProductLockerLocation)

Change and reconfigure the VMware Tools repository on the host. If the new path is the same as the path already configured on the host, no changes will be made to the host. The host should be powered on.

This task is not cancellable and cannot be reverted once started.

Required Privileges: Host.Config.ProductLocker
Since: vSphere API 6.7.1

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the HostSystem used to make the method call.

path P

xsd:string

The absolute path for the VMware Tools repository on the host. It should have "/vmfs/volumes/" prefix and it should be a valid existing path, or it could be empty to restore to default value.

Since vSphere API 6.7.1

P Required privilege: path

Return Value

Type	Description
ManagedObjectReference to a Task	This method returns a Task object with which to monitor the operation. The result property in the Task contains the stable vmfs path of the VMware Tools repository upon success. A stable vmfs path is of the form: /vmfs/volumes/[datastore-uuid]/[path/inside/datastore] or empty to indicate restoring to default value.

Faults

Type	Description
FileNotFound	Thrown if the path does not exist.
HostConfigFault	Thrown if the configuration could not be written.
InvalidArgument	Thrown if the path does not have "/vmfs/volumes/" prefix and is not empty.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if there is another task configuring the VMware Tools repository on the host.

Events

Type
None

UpdateSystemResources(updateSystemResources)

Deprecated. as of Vsphere API 6.0. Please, contact VMware Support to get instructions on how to configure system ESX resource pools.

Update the configuration of the system resource hierarchy.

Required Privileges: Host.Config.Resources

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the HostSystem used to make the method call.

resourceInfo P

HostSystemResourceInfo

Since 2.0

P Required privilege: resourceInfo

Return Value

Type	Description
None

Faults

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

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateSystemResources" type="vim25:UpdateSystemResourcesRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateSystemResourcesResponse">
                  <complexType/>
               </element>

UpdateSystemSwapConfiguration(updateSystemSwapConfiguration)

Update the System Swap Configuration.
See HostSystemSwapConfiguration

Required Privileges: Host.Config.Settings
Since: vSphere API 5.1

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the HostSystem used to make the method call.

sysSwapConfig P

HostSystemSwapConfiguration

Contains a list of system swap options that configure the system swap functionality.
See HostSystemSwapConfiguration

Since vSphere API 5.1

P Required privilege: sysSwapConfig

Return Value

Type	Description
None

Faults

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

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateSystemSwapConfiguration" type="vim25:UpdateSystemSwapConfigurationRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateSystemSwapConfigurationResponse">
                  <complexType/>
               </element>