Managed Object - HostSystem

Property of: ClusterDrsMigration, ClusterHostRecommendation, ComputeResource, DatastoreHostMount, DatastoreNotWritableOnHost, DiagnosticManagerBundleInfo, HostConfigInfo, HostEventArgument, HostListSummary, HostVMotionCompatibility, Network, VirtualMachineConfigOptionDescriptor, VirtualMachineRelocateSpec, VirtualMachineRuntimeInfo
Parameter to: BrowseDiagnosticLog, CheckLicenseFeature, ConfigureLicenseSource, CreateVM_Task, DisableFeature, EnableFeature, GenerateLogBundles_Task, MarkAsVirtualMachine, MigrateVM_Task, MoveHostInto_Task, MoveInto_Task, PowerOnVM_Task, QueryConfigOption, QueryConfigTarget, QueryDescriptions, QueryLicenseSourceAvailability, QueryLicenseUsage, QueryVMotionCompatibility, RegisterVM_Task, RevertToCurrentSnapshot_Task, RevertToSnapshot_Task, SetLicenseEdition, ValidateMigration
Returned by: AddHost_Task
Extends: ManagedEntity
See also: Datastore, HostCapability, HostConfigInfo, HostConfigManager, HostConnectInfo, HostConnectSpec, HostDatastoreBrowser, HostHardwareInfo, HostListSummary, HostRuntimeInfo, HostSystemResourceInfo, Network, VirtualMachine

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.

Properties

Name	Type	Description
capability*	HostCapability	Host capabilities. This might not be available for a disconnected host.
config*	HostConfigInfo	Host configuration information. This might not be available for a disconnected host.
configManager	HostConfigManager	Host configuration systems.
datastore*	ManagedObjectReference[] to a Datastore[]	A collection of references to the subset of datastore objects in the datacenter that are available in this HostSystem.
datastoreBrowser	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.
network*	ManagedObjectReference[] to a Network[]	A collection of references to the subset of network objects in the datacenter that are available in this HostSystem.
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
configIssue, configStatus, customValue, declaredAlarmState, disabledMethod, effectiveRole, name, overallStatus, parent, permission, recentTask, triggeredAlarmState

*May not be present

Methods

Methods defined in this Managed Object
DisconnectHost_Task, EnterMaintenanceMode_Task, ExitMaintenanceMode_Task, QueryHostConnectionInfo, QueryMemoryOverhead, RebootHost_Task, ReconfigureHostForDAS_Task, ReconnectHost_Task, ShutdownHost_Task, UpdateSystemResources
Methods inherited from ManagedEntity
Destroy_Task, Reload, Rename_Task

DisconnectHost_Task

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
NotSupported	Thrown if run directly on an ESX Server host.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="DisconnectHost_Task">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="DisconnectHost_TaskResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim2:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

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 virtual machines. However, if the host is part of a cluster with VMware DRS enabled, DRS provides migration recommendations to evacuate the virtual machines. If DRS is in fully-automatic mode, these are automatically scheduled.

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

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.
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	Thrown if the operation timed out.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="EnterMaintenanceMode_Task">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="timeout" type="xsd:int"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="EnterMaintenanceMode_TaskResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim2:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

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.

Required Privileges: Host.Config.Maintenance

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostSystem used to make the method call.
timeout	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.

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

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="ExitMaintenanceMode_Task">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="timeout" type="xsd:int"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="ExitMaintenanceMode_TaskResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim2:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

QueryHostConnectionInfo

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.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="QueryHostConnectionInfo">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="QueryHostConnectionInfoResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim2:HostConnectInfo"/>
               </sequence>
            </complexType>
         </element>

QueryMemoryOverhead

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	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.
videoRamSize*	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.
numVcpus	xsd:int	The number of virtual CPUs. For an existing virtual machine, this value can be found as the numCPU property of the VirtualHardware.

*Need not be set

Return Value

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

Faults

Type	Description
NotSupported	Thrown if the host does not have memory resource allocation features.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="QueryMemoryOverhead">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="memorySize" type="xsd:long"/>
                  <element name="videoRamSize" type="xsd:int" minOccurs="0"/>
                  <element name="numVcpus" type="xsd:int"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="QueryMemoryOverheadResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="xsd:long"/>
               </sequence>
            </complexType>
         </element>

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 vim.host.Capability.rebootSupported.

Required Privileges: Host.Config.Maintenance

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostSystem used to make the method call.
force	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.

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.
NotSupported	Thrown if the host does not support the reboot operation.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="RebootHost_Task">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="force" type="xsd:boolean"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="RebootHost_TaskResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim2:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

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.

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.
NotSupported	Thrown if run directly on an ESX Server host.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="ReconfigureHostForDAS_Task">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="ReconfigureHostForDAS_TaskResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim2:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

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

*Need not be set

Return Value

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

Faults

Type	Description
AlreadyBeingManaged	Thrown if host is already being managed by another VirtualCenter server
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.
NotEnoughLicenses	Thrown if there are not enough licenses to add this host.
NotSupported	Thrown if no host can be added to this group. This is the case if the ComputeResource is a standalone type.
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.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="ReconnectHost_Task">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="cnxSpec" type="vim2:HostConnectSpec" minOccurs="0"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="ReconnectHost_TaskResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim2:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

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

Required Privileges: Host.Config.Maintenance

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostSystem used to make the method call.
force	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.

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.
NotSupported	Thrown if the host does not support shutdown.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="ShutdownHost_Task">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="force" type="xsd:boolean"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="ShutdownHost_TaskResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim2:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

UpdateSystemResources

Update the configruration 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	HostSystemResourceInfo

Return Value

Type	Description
None

Faults

Type	Description
InvalidArgument	Thrown if the resource specification 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.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="UpdateSystemResources">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="resourceInfo" type="vim2:HostSystemResourceInfo"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="UpdateSystemResourcesResponse">
            <complexType/>
         </element>