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.