Product SiteDocumentation Site

Chapter 13. Hosts

13.1. Power Management
13.2. Memory Management
13.3. Network Interface Sub-Collection
13.3.1. Bonded Interfaces
13.3.2. Attach Action
13.3.3. Detach Action
13.4. Storage Sub-Collection
13.5. Actions
13.5.1. Install Action
13.5.2. Activate Action
13.5.3. Fence Action
13.5.4. Deactivate Action
13.5.5. Approve Action
13.5.6. iSCSI Login Action
13.5.7. iSCSI Discover Action
13.5.8. Commit Network Configuration Action
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.

Element property icons

The icons used in the properties column of this table are described in Table 8.1, “Element property icons”
Element Type Description Properties
name string A user-supplied human readable name for the host. The name is unique across all host resources.
link rel="storage" string A link to the sub-collection for host storage.
link rel="nics" string A link to the sub-collection for host network interfaces.
link rel="tags" string A link to the sub-collection for host tags.
link rel="permissions" string A link to the sub-collection for host permissions. See Section 8.3.9, “ Permissions ”
link rel="statistics" string A link to the 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 complex 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 Fencing options for host power management. (see Section 13.1, “Power Management”)
ksm boolean: true or false true if Kernel SamePage Merging (KSM) is enabled. Is disabled if transparent_hugepages is enabled. (see Section 13.2, “Memory Management”)
transparent_hugepages boolean: true or false true if transparent hugepages is enabled. (see Section 13.2, “Memory Management”)
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 and speed
summary complex Summary statistics of the virtual machines on the host. Includes sub-elements for numbers of active, migrating and total VMs
version complex The compatibility level of the host (see Chapter 6, 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, PROBLEMATIC, REBOOT, UNASSIGNED or UP.
Example 13.1. An XML representation of a host
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
    <name>host1</name>
    <actions>
        <link rel="install"
          href="/rhevm-api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/install"/>
        <link rel="activate"
          href="/rhevm-api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/activate"/>
        <link rel="fence"
          href="/rhevm-api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/fence"/>
        <link rel="deactivate"
          href="/rhevm-api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/deactivate"/>
        <link rel="approve"
          href="/rhevm-api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/approve"/>
        <link rel="iscsilogin"
          href="/rhevm-api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/iscsilogin"/>
        <link rel="iscsidiscover"
          href="/rhevm-api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/iscsidiscover"/>
        <link rel="commitnetconfig"
          href="/rhevm-api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/commitnetconfig"/>
    </actions>
    <link rel="storage"
      href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/storage"/>
    <link rel="nics"
      href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics"/>
    <link rel="tags"
      href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/tags"/>
    <link rel="permissions"
      href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/permissions"/>
    <link rel="statistics"
      href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/statistics"/>
    <type>rhev-h</type>
    <address>host1.example.com</address>
    <status>UP</status>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/rhevm-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>false</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"/>
        <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>

When creating a new host, the name, address and root_password elements are required. See Section 8.3.2, “ Creating a Resource ” for more information.
Example 13.2. Creating a host
POST /rhevm-api/hosts HTTP/1.1
Accept: application/xml
Content-type: application/xml

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

The root_password element is only included in the client-provided initial representation and is not exposed in the representations returned from subsequent GETs and UPDATEs.
The name element is updatable post-creation. See Section 8.3.4, “ Updating a Resource ” for more information.
Example 13.3. Updating a host
POST /rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3 HTTP/1.1
Accept: application/xml
Content-type: application/xml

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

13.1. Power Management

A recommended feature of the Red Hat Virtualization platform is the option to fence a host with a power_management configuration. Certain sub-elements are required when configuring power_management.
Element Type Description Properties
type= fencing device code A list of valid fencing device codes are available in the capabilities collection. See Section 7.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 7.1.4, “Power Managers”) but can include options such as:
name= type= Values Description
secure bool boolean: true or false Defines if SSH is enabled for power management device connection
port int integer Defines the port for power management device connection
slot int integer Defines the slot to use, specifically when using a Blade server
A new host can include a power_management configuration when POSTing to the host resource. The power_management configuration can also update using PUT.
Example 13.4. An XML representation of a host's power management configuration
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/rhevm-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>