VMware vSphere SDKs and Tools 8.0

8.0 7.0 6.7 6.5

ESXi
 Hosts

Use the
vSphere Automation
 APIs to run general operations on the
ESXi
 hosts in your vSphere environment.
You can retrieve information about the hosts, create a standalone host, disconnect, and reconnect an
ESXi
 host to a
vCenter Server
 system.

How to Retrieve Information About
ESXi
 Hosts

You retrieve information about the
ESXi
 hosts running in a
vCenter Server
 instance by listing only the
ESXi
 hosts that you are interested in.
To filter the
ESXi
 hosts on a
vCenter Server
 instance and get only the ones you want,
call the
list
 function and pass your criteria with a
HostTypes.FilterSpec
 instance.
 Combine several filter criteria by including one or more of the following parameters:
  • The name or unique identifier of the host.
  • Clusters, data centers, or folders that contain the host.
  • Connection state of the host which can be one of the following:
    CONNECTED
    ,
    DISCONNECTED
    , or
    NOT_RESPONDING
    .
  • Power state of the host which can be one of the following:
    POWERED_OFF
    ,
    POWERED_ON
    , or
    STANDBY
    .
The function returns a list of
com.vmware.vcenter.HostTypes.Summary
 objects that contain information about up to 2500 hosts that match all specified criteria. You can use the list to retrieve information about the returned
ESXi
 hosts.

How to Add a Standalone
ESXi
 Host to
vCenter Server

You can use the
vSphere Automation
APIs to add a standalone host to a
vCenter Server
 instance.
Add a single
ESXi
 host to a
vCenter Server
 instance by calling the
create
 function and passing a
com.vmware.vcenter.HostTypes.CreateSpec
 instance as parameter. When you create the host specification, make sure that you set the IP address or the DNS resolvable host name and the administrator credentials.

How to Disconnect and Reconnect
ESXi
 Hosts

You can use the
vSphere Automation
 APIs to connect
ESXi
 hosts to a
vCenter Server
 instance and make the hosts managed. You can temporarily disconnect a managed host from a
vCenter Server
 instance and reconnect the host, for example, to refresh the ESX agents on the host.
When you add a host to a
vCenter Server
 instance, the host is connected to
vCenter Server
 and becomes a managed host. To disconnect a managed host from a
vCenter Server
 instance,
call the
disconnect
 function and pass the host identifier as a parameter
. The managed host and its associated virtual machines remain in the inventory but
vCenter Server
 temporarily stops managing and monitoring them.
To reconnect a managed host to a
vCenter Server
 instance,
call the
connect
 function and pass the host identifier as a parameter
. As a result, the connection status of the host changes, and
vCenter Server
 resumes managing the host and its associated virtual machines.
If you want to delete a host and all its associated virtual machines from the inventory, you can remove the host from the
vCenter Server
 instance. To delete a disconnected host from a
vCenter Server
 instance,
call the
delete
 function and pass the host identifier as a parameter
.

How to Configure
ESXi
 Entropy

You can use the
vSphere Automation
 API to feed external entropy data to an
ESXi
 host in your inventory. You can also query the current entropy levels on the host and add external entropy data when needed.
Entropy is a measure of the randomness or diversity of a data-generating function. In releases prior to vSphere 8.0 Update 1,
ESXi
 supported only CPU-based entropy data generated from interrupts or manufacturer provided interfaces, such as RDSEED and RDRAND. High-quality entropy is important for the proper functioning of security-related operations such as generating encryption keys for secure communication over the network. Starting with vSphere 8.0 Update 1, you can add external entropy sources to an
ESXi
 host and in this way ensure the high quality of the entropy data on that host. You provide external entropy data by using devices such as hardware security modules (HSMs) which are FIPS 140-3 and EAL4 certified.
You can configure the
ESXi
 entropy sources by using the VMkernel boot options. To use external entropy sources, set the
entropySources
 value to more than or equal to
8
. For more information about how to set the desired entropy sources by using the VMkernel boot options, see Controlling ESXi Entropy in the
vSphere Security
 documentation.
You can also configure external entropy sources in the kickstart file for the
ESXi
 scripted installation. See Configuring External Entropy Sources During Scripted Installation.
If a host is configured to use only external entropy sources, that is,
entropySources
 is set to
8
, you must keep supplying the external entropy data through the
vSphere Automation
 API. In case the entropy in the host gets exhausted, the host becomes unresponsive and might require a hard reboot or re-installation to recover the host from this situation.

Querying Entropy Data on a Host

To retrieve details about the external entropy available on an
ESXi
 host, use the
ExternalPool
 service. You must have the
Host.Entropy.Read
 privilege.
You can check whether an external entropy source is added to a host by
calling the
get(host_id)
 method of the
com.vmware.vcenter.host.entropy.ExternalPool
 interface and passing the host ID as parameter. The method returns an
ExternalPool.Info
 instance that contains detailed information about the external entropy data on the host
.
Details for the External Entropy Data on a Host
External Entropy Data Detail
Description
getStatus()
Indicates whether an external entropy source is added for a host.
getCapacity()
Shows the maximum capacity of external entropy data in bytes that a host can store in the VMkernel entropy pool. When you feed the host with additional external entropy data, make sure that you do not exceed this maximum capacity. Otherwise, all extra entropy data is discarded.
getCurrentlyAvailable()
Indicates the current amount of entropy data in bytes available in the VMkernel entropy pool on the host.
getInactiveSourceTimeout()
Indicates the amount of time in seconds that can elapse without any activity between the host and the external entropy source. Your application must check periodically the levels of entropy data on the host and send entropy data from the external source when required. When this timeout exceeds an
esx.audit.entropy.external.source.disconnected
 VMkernel Observation (VOB) is logged. This system event suggests possible loss of connection to the external entropy source. For the full list of available entropy VOBs in vSphere 8.0, see the VMware knowledge base article at https://kb.vmware.com/s/article/89074.
getLowWatermark()
Indicates the threshold in bits sufficient for the in-memory cache to operate successfully. When the in-memory entropy cache is running low and the threshold is reached, an
esx.audit.entropy.available.low
 VOB is logged. For more information about the entropy VOBs, see the VMware knowledge base article at https://kb.vmware.com/s/article/89074.

Adding External Entropy Data to a Host

To add entropy data from an external entropy source to a host, you must have the
Host.Entropy.Write
 privilege. Use the
ExternalPool
 service and call the
add(host_id, add_spec)
 method. Pass the host ID and an
ExternalPool.AddSpec
 instance as method parameters. The
ExternalPool.AddSpec
 instance contains the Base64 encoded external entropy data. You must convert the binary data coming from the external entropy source to Base64 format so that the host can consume it. As a result, the method returns an instance of the
ExternalPool.AddResult
 class.
When the external entropy data reaches the host, the entropy daemon stores it first in the in-memory cache and the storage cache. Then the external entropy data is pushed to the VMkernel entropy pool from which it is fed to the applications in need.
The entropy data in the storage cache persists on the host disk and is only consumed during the
ESXi
 booting. The default storage file size is 4MiB and can be configured through the ESXCLI commands. See the
ESXCLI Command Reference
 documentation.

Content feedback and comments