Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 9. Hosts

The hosts collection provides information about the hosts in a Red Hat Storage environment. An API user accesses this information through the rel="hosts" link obtained from the entry point URI (see Chapter 5, Entry Point).
The following table shows specific elements contained in a hosts resource representation.
Expand
Table 9.1. Host elements
Element Type Description Properties
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 Chapter 7, Common Features.
link rel="statistics" relationship A link to the statistics sub-collection for host statistics.
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.
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.
version major= minor= complex The compatibility level of the host.
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.

Example 9.1. An XML representation of a host

<hosts>
        <host href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56" id="eaf4af64-e51c-4e72-a2cf-bdb6076a9e56">
            <actions>
                <link href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/forceselectspm" rel="forceselectspm"/>
                <link href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/iscsilogin" rel="iscsilogin"/>
                <link href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/iscsidiscover" rel="iscsidiscover"/>
                <link href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/commitnetconfig" rel="commitnetconfig"/>
                <link href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/approve" rel="approve"/>
                <link href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/fence" rel="fence"/>
                <link href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/install" rel="install"/>
                <link href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/activate" rel="activate"/>
                <link href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/deactivate" rel="deactivate"/>
            </actions>
            <name>host1</name>
            <comment></comment>
            <link href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/storage" rel="storage"/>
            <link href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/nics" rel="nics"/>
            <link href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/tags" rel="tags"/>
            <link href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/permissions" rel="permissions"/>
            <link href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/statistics" rel="statistics"/>
            <link href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/hooks" rel="hooks"/>
            <address>10.70.43.145</address>
            <certificate>
                <organization>Test</organization>
                <subject>O=Test,CN=10.70.43.145</subject>
            </certificate>
            <status>
                <state>up</state>
            </status>
            <cluster href="/api/clusters/419590b8-5aa0-473b-9651-aa41f1372c59" id="419590b8-5aa0-473b-9651-aa41f1372c59"/>
            <port>54321</port>
            <type>rhel</type>
             <storage_manager priority="5">false</storage_manager>
            <version major="4" minor="14" build="7" revision="2" full_version="vdsm-4.14.7.2-1.el6rhs"/>
            <hardware_information>
                <manufacturer>Red Hat</manufacturer>
                <version>6Server-6.4.0.4.el6</version>
                <serial_number>4C4C4544-004E-5A10-8031-B1C04F4E5631_bc:30:5b:f2:bc:60</serial_number>
                <product_name>RHEV Hypervisor</product_name>
                <uuid>f70d244f-5fd9-4106-965d-a3d1bb1f0b3b</uuid>
                <family>Red Hat Enterprise Linux</family>
            </hardware_information>
            <power_management>
                <enabled>false</enabled>
                <options/>
            </power_management>
            <ksm>
                <enabled>false</enabled>
            </ksm>
            <transparent_hugepages>
                <enabled>true</enabled>
            </transparent_hugepages>
            <iscsi>
                <initiator>iqn.1994-05.com.redhat:4c5810adce86</initiator>
             </iscsi>
            <ssh>
                <port>22</port>
                <fingerprint>7b:e5:04:1f:df:b4:73:ed:4f:c2:7a:97:a7:5a:93:98</fingerprint>
            </ssh>
            <cpu>
                <topology sockets="1" cores="1" threads="1"/>
                <name>Intel Xeon E312xx (Sandy Bridge)</name>
                <speed>2200</speed>
            </cpu>
            <memory>2103443456</memory>
            <max_scheduling_memory>1698693120</max_scheduling_memory>
            <summary>
                <active>0</active>
                <migrating>0</migrating>
                <total>0</total>
            </summary>
            <os type="RHEL">
                <version full_version="6Server - 6.5.0.1.el6"/>
            </os>
            <libvirt_version major="0" minor="10" build="2" revision="0" full_version="libvirt-0.10.2-18.el6_4.15"/>
        </host>
</hosts>
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 9.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>
  <cluster>cluster_name</cluster>
</host>
New host creation applies only to the addition of Red Hat Enterprise Linux hosts.
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 and cluster elements are updatable post-creation. See Section 7.3.2, “Updating a Resource” for more information.

Example 9.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 9.4. Removing a host

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

HTTP/1.1 204 No Content
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug

9.1. Network Interface Sub-Collection
Copy link

The nics sub-collection represents a host's physical network interfaces. Each host_nic element in the representation acts as a network interface and contains the following elements:

Note

The icons used in the properties column of this table are described in Table 7.1, “Element property icons”
Expand
Table 9.2. Elements for a host's network interfaces
Element Type Description Properties
name string The name of the host network interface, e.g. eth0 [a]
link rel="statistics" relationship A link to the statistics sub-collection for a host's network interface statistics.
link rel="master" relationship A reference to the master bonded interface, if this is a slave interface.
host id= GUID A reference to the host.
network id= GUID A reference to the network, if any, that the interface is attached. [b]
mac address= string The MAC address of the interface.
ip address= netmask= gateway= complex The IP level configuration of the interface.
boot_protocol enumerated The protocol for IP address assignment when the host is booting. A list of enumerated values is available in capabilities.
speed integer The network interface speed in bits per second.
status enumerated The link status for the network interface. These states are listed in host_nic_states under capabilities.
vlan id integer The VLAN which this interface represents.
bonding complex A list of options and slave NICs for bonded interfaces. [c]
[a] Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added.
[b] Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added.
[c] Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added.

Example 9.5. An XML representation of a network interface on a host

<host_nic href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/nics/4800fa31-08f0-40bb-9964-ea6045702b2a" id="4800fa31-08f0-40bb-9964-ea6045702b2a">
    <actions>
        <link href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/nics/4800fa31-08f0-40bb-9964-ea6045702b2a/attach" rel="attach"/>
        <link href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/nics/4800fa31-08f0-40bb-9964-ea6045702b2a/detach" rel="detach"/>
    </actions>
    <name>eth0</name>
    <link href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/nics/4800fa31-08f0-40bb-9964-ea6045702b2a/statistics" rel="statistics"/>
    <host href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56" id="eaf4af64-e51c-4e72-a2cf-bdb6076a9e56"/>
    <network href="/api/networks/00000000-0000-0000-0000-000000000009" id="00000000-0000-0000-0000-000000000009"/>
    <mac address="00:15:1e:00:9d:4c"/>
    <ip address="10.70.43.145" netmask="255.255.252.0" gateway="10.70.43.254"/>
    <boot_protocol>dhcp</boot_protocol>
    <status>
        <state>up</state>
    </status>
    <mtu>1500</mtu>
    <bridged>true</bridged>
    <custom_configuration>false</custom_configuration>
</host_nic>
An API user creates only bonded interfaces (see Section 9.1.1, “Bonded Interfaces”). All other network interfaces contain updatable network, ip and boot_protocol elements using a PUT request.
When adding a new network interface, the name and network elements are required. Identify the network element with the id attribute or name element.
An API user modifies a network interface with a PUT request. 
PUT /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
e8f02fdf-3d7b-4135-86e1-1bf185570cd8 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<nic>
    <ip address="192.168.0.129" netmask="255.255.255.0" gateway="192.168.0.1"/>
</nic>
An API user removes a network interface with a DELETE request. 
DELETE /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
e8f02fdf-3d7b-4135-86e1-1bf185570cd8 HTTP/1.1

HTTP/1.1 204 No Content
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug

9.1.1. Bonded Interfaces
Copy link

A bonded interface is represented as a host_nic resource containing a bonding element.
Expand
Table 9.3. Bonded interface properties
Element Type Description Properties
options complex A list of option elements for a bonded interface. Each option contains property name and value attributes. [a]
slaves complex A list of slave host_nic id= elements for a bonded interface. [b]
[a] Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added.
[b] Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added.
An API user creates a new bond when POSTing to a host_nic with bonding options and slave interfaces. The name, network and bonded elements are required when creating a new bonded interface. Either the id or name elements identify the network and slave host_nics.

Example 9.6. Creating a bonded interface

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

<host_nic>
    <name>bond4</name>
    <network id="e657d631-657d-42bb-a536-73501a085d85"/>
    <bonding>
        <options>
            ...
        </options>
        <slaves>
            <host_nic id="eb14e154-5e73-4f7f-bf6b-7f52609d94ec"/>
            <host_nic id="6aede5ca-4c54-4b37-a81b-c0d6b53558ea"/>
        </slaves>
    </bonding>
</host_nic>

Important

bond0, bond1, bond2, bond3 and bond4 are the only valid names for a bonded interface.
Like other resources, a DELETE request to a bonded interface URI deletes it.

Important

Changes to bonded interface configuration must be explicitly committed. See Section 9.3.5, “Commit Network Configuration Action”.
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug

9.1.2. Network Interface Statistics
Copy link

Each host's network interface exposes a statistics sub-collection for a host's network interface statistics. Each statistic contains the following elements:
Expand
Table 9.4. Elements for a host's network interface statistics
Element Type Description
name string The unique identifier for the statistic entry.
description string A plain text description of the statistic.
unit string The unit or rate to measure the statistical values.
type One of GAUGE or COUNTER The type of statistic measures.
values type= One of INTEGER or DECIMAL The data type for the statistical values that follow.
value complex A data set that contains datum.
datum see values type An individual piece of data from a value.
host_nic id= relationship A relationship to the containing host_nic resource.
The following table lists the statistic types for network interfaces on hosts.
Expand
Table 9.5. Host NIC statistic types
Name
Description
data.current.rx
The rate in bytes per second of data received.
data.current.tx
The rate in bytes per second of data transmitted.
errors.total.rx
Total errors from receiving data.
errors.total.tx
Total errors from transmitting data.

Example 9.7. An XML representation of a host's network interface statistics sub-collection

<statistics>
    <statistic href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/nics/4800fa31-08f0-40bb-9964-ea6045702b2a/statistics/ecd0559f-e88f-3330-94b4-1f091b0ffdf7" id="ecd0559f-e88f-3330-94b4-1f091b0ffdf7">
        <name>data.current.rx</name>
        <description>Receive data rate</description>
        <values type="DECIMAL">
            <value>
                <datum>0</datum>
            </value>
        </values>
        <type>GAUGE</type>
        <unit>BYTES_PER_SECOND</unit>
        <host_nic href="/api/hosts/eaf4af64-e51c-4e72-a2cf-bdb6076a9e56/nics/4800fa31-08f0-40bb-9964-ea6045702b2a" id="4800fa31-08f0-40bb-9964-ea6045702b2a"/>
    </statistic>
    ...
</statistics>

Note

This statistics sub-collection is read-only.
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug

9.1.3. Attach Action
Copy link

A host network interface is attached to a network, indicating the given network is accessible over the interface. Either the id or name elements identify the network.

Example 9.8. Action to attach a host network interface to a network

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/e8f02fdf-3d7b-4135-86e1-1bf185570cd8/attach HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <network id="e657d631-657d-42bb-a536-73501a085d85"/>
</action>

Important

This networking configuration change must be explicitly committed. See Section 9.3.5, “Commit Network Configuration Action”.
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug

9.1.4. Detach Action
Copy link

Detach an interface from a network. Either the id or name elements identify the network.

Example 9.9. Action to detach a host network interface to a network

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/e8f02fdf-3d7b-4135-86e1-1bf185570cd8/detach HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <network id="e657d631-657d-42bb-a536-73501a085d85"/>
</action>

Important

This networking configuration change must be explicitly committed. See Section 9.3.5, “Commit Network Configuration Action”.
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A3522632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top