Chapter 12. Hosts

The hosts collection provides information about the hosts in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="hosts" link obtained from the entry point URI (see Chapter 4, Entry Point).
The following table shows specific elements contained in a host resource representation.

Note

The icons used in the properties column of this table are described in Table 7.1, “Element property icons”

Table 12.1. Host elements

Element Type Description Properties
link rel="storage" relationship A link to the storage sub-collection for host storage.
link rel="nics" relationship A link to the nics sub-collection for host network interfaces.
link rel="tags" relationship A link to the tags sub-collection for host tags.
link rel="permissions" relationship A link to the permissions sub-collection for host permissions. See Section 7.3.7, “ Permissions ”.
link rel="statistics" relationship A link to the statistics sub-collection for host statistics.
type One of rhel or rhev-h The host type.
address string The IP address or hostname of the host.
status See below The host status.
cluster id= GUID A reference to the cluster that includes this host.
port integer The listen port of the VDSM daemon running on this host.
storage_manager Boolean: true or false true if the host is the storage pool manager (SPM).
power_management complex Configuration options for host power management. See Section 12.1, “Power Management”.
ksm Boolean: true or false true if Kernel SamePage Merging (KSM) is enabled.
transparent_hugepages Boolean: true or false true if Transparent Hugepages is enabled.
iscsi complex The SCSI initiator for the host.
cpu complex Statistics for the host CPU. Includes sub-elements for the CPU's name, topology cores=, topology sockets= and speed. The topology cores= aggregates the total cores while the topology sockets= aggregates the total physical CPUs.
summary complex Summary statistics of the virtual machines on the host. Includes sub-elements for numbers of active, migrating and total VMs.
version major= minor= complex The compatibility level of the host See Chapter 5, Compatibility Level Versions.
root_password string The root password of this host, by convention only included in the client-provided host representation on creation.

The status contains one of the following enumerative values: down, error, initializing, installing, install_failed, maintenance, non_operational, non_responsive, pending_approval, preparing_for_maintenance, connecting, reboot, unassigned and up. These states are listed in host_states under capabilities (See Section 6.1.21, “Resource Status States”).

Example 12.1. An XML representation of a host

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
    <name>host1</name>
    <actions>
        <link rel="install"
          href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/install"/>
        <link rel="activate"
          href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/activate"/>
        <link rel="fence"
          href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/fence"/>
        <link rel="deactivate"
          href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/deactivate"/>
        <link rel="approve"
          href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/approve"/>
        <link rel="iscsilogin"
          href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/iscsilogin"/>
        <link rel="iscsidiscover"
          href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/iscsidiscover"/>
        <link rel="commitnetconfig"
          href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/commitnetconfig"/>
    </actions>
    <link rel="storage"
      href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/storage"/>
    <link rel="nics"
      href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics"/>
    <link rel="tags"
      href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/tags"/>
    <link rel="permissions"
      href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/permissions"/>
    <link rel="statistics"
      href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/statistics"/>
    <type>rhev-h</type>
    <address>host1.example.com</address>
    <status>
        <state>up</state>
    </status>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <port>54321</port>
    <storage_manager>true</storage_manager>
    <power_management>
        <enabled>false</enabled>
        <options/>
    </power_management>
    <ksm>
        <enabled>true</enabled>
    </ksm>
    <transparent_hugepages>
        <enabled>true</enabled>
    </transparent_hugepages>
    <iscsi>
        <initiator>iqn.2001-04.com.example:diskarrays-sn-a8675309</initiator>
    </iscsi>
    <cpu>
        <topology cores="2" sockets="1"/>
        <name>Intel(R) Core(TM)2 Duo CPU E8400 @ 3.00GHz</name>
        <speed>2993</speed>
    </cpu>
    <summary>
        <active>2</active>
        <migrating>0</migrating>
        <total>3</total>
    </summary>
    <version major="3" minor="0"/>
</host>

Creation of a new host requires the name, address and root_password elements. See Section 7.2.4, “ Creating a Resource in a Collection ” for more information.

Example 12.2. Creating a host

POST /api/hosts HTTP/1.1
Accept: application/xml
Content-type: application/xml

<host>
  <name>host2</name>
  <address>host2.example.com</address>
  <root_password>p@55w0Rd!</root_password>
</host>

New host creation applies only to the addition of Red Hat Enterprise Linux hosts. Red Hat Enterprise Virtualization Manager detects hypervisor hosts automatically and requires approval for their use.
The root_password element is only included in the client-provided initial representation and is not exposed in the representations returned from subsequent requests.
The name, name, cluster, power_management, transparent_hugepages and ksm elements are updatable post-creation. See Section 7.3.2, “ Updating a Resource ” for more information.

Example 12.3. Updating a host

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<host>
  <name>host3</name>
</host>

Removal of a host requires a DELETE request.

Example 12.4. Removing a host

DELETE /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3 HTTP/1.1

HTTP/1.1 204 No Content

12.1. Power Management

The power_management element provides users with the ability to set a power management configuration, which is required for host fencing. Certain sub-elements are required when configuring power_management.

Table 12.2. Power management options

Element Type Description Properties
type= fencing device code A list of valid fencing device codes are available in the capabilities collection. See Section 6.1.4, “Power Managers”.
enabled Boolean: true or false Indicates whether power management configuration is enabled or disabled.
address string The host name or IP address of the host.
username string A valid user name for power management.
password string A valid, robust password for power management.
options complex Fencing options for the selected type=.

The options element requires a list of option sub-elements. Each option requires a name and type attributes. Certain options are only available for specific fencing types as defined in the capabilities collection (see Section 6.1.4, “Power Managers”).
A new host includes an optional power_management configuration when POSTing to the host resource. The power_management configuration is updatable using a PUT request.

Example 12.5. An XML representation of a host's power management configuration

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
    <name>host1</name>
    ...
    <power_management type="ilo">
        <enabled>true</enabled>
        <address>192.168.1.107</address>
        <username>admin</username>
        <password>p@55w0Rd!</password>
        <options>
            <option name="secure" value="true"/>
            <option name="port" value="54345"/>
            <option name="slot" value="3"/>
        </options>
    </power_management>
    ...
</host>