⁠14.6. Sub-Collections

⁠14.6.1. Host Network Interface Sub-Collection

⁠14.6.1.1. Host Network Interface Sub-Collection

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:
⁠

Table 14.3. 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= mtu= complex The IP level configuration of the interface.  
mtu complex The maximum transmission unit for 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]
bridged Boolean Defines the bridged network status. Set to true for a bridged network and true for a bridgeless network.  
[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 14.8. An XML representation of a network interface on a host

<host_nic id="e8f02fdf-3d7b-4135-86e1-1bf185570cd8"
  href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
  e8f02fdf-3d7b-4135-86e1-1bf185570cd8">
    <name>bond0</name>
    <link rel="statistics"
      href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
      e8f02fdf-3d7b-4135-86e1-1bf185570cd8/statistics"/>      
    <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
      href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
    <network id="e657d631-657d-42bb-a536-73501a085d85"
      href="/api/networks/e657d631-657d-42bb-a536-73501a085d85"/>
    <mac address="D6:76:F1:3A:AF:74"/>
    <ip address="192.168.0.128" netmask="255.255.255.0" gateway="192.168.0.1"/>
    <mtu>1500</mtu>
    <boot_protocol>dhcp</boot_protocol>
    <speed>1000000000</speed>
    <status>
        <state>up</state>
    </status>
    <bonding>
        <options>
            ...
        </options>
        <slaves>
            <host_nic id="eb14e154-5e73-4f7f-bf6b-7f52609d94ec"/>
            <host_nic id="6aede5ca-4c54-4b37-a81b-c0d6b53558ea"/>
        </slaves>
    </bonding>
    <actions>
        <link rel="attach"
          href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
          e8f02fdf-3d7b-4135-86e1-1bf185570cd8/attach"/>
        <link rel="detach"
          href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
          e8f02fdf-3d7b-4135-86e1-1bf185570cd8/detach"/>
    </actions>
    <bridged>true</bridged>
</host_nic>
An API user creates only 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. 
POST /api/hosts HTTP/1.1
Accept: application/xml
Content-type: application/xml

<host_nic>
    <name>MyNIC</name>
    <network id="e657d631-657d-42bb-a536-73501a085d85">
        <name>MyNetwork</name>
    </network>
</host_nic>
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

<host_nic>
    <ip address="192.168.0.129" netmask="255.255.255.0" gateway="192.168.0.1"/>
</host_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

Important

The API as documented in this section is experimental and subject to change. It is not covered by the backwards compatibility statement.
Report a bug

⁠14.6.1.2. Bonded Interfaces

A bonded interface is represented as a host_nic resource containing a bonding element.
⁠

Table 14.4. 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 creating a new host_nic (POST) or updating a host_nic (PUT). Use either the id or name elements identify the slave host_nic elements.
⁠

Example 14.9. 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.
Use a DELETE request to a bonded interface URI to delete it.

Important

Changes to bonded interface configuration must be explicitly committed.
Report a bug

⁠14.6.1.3. Network Interface Statistics

Each host's network interface exposes a statistics sub-collection for a host's network interface statistics. Each statistic contains the following elements:
⁠

Table 14.5. 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.
⁠

Table 14.6. 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 14.10. An XML representation of a host's network interface statistics sub-collection

<statistics>
    <statistic id="ecd0559f-e88f-3330-94b4-1f091b0ffdf7"
      href="/api/hosts/25fcdd2e-d452-11e0-bb4d-525400d75548/nics/
      c34728e8-4338-4540-ac9b-86b8582e602e/statistics/
      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 id="c34728e8-4338-4540-ac9b-86b8582e602e"
          href="/api/hosts/25fcdd2e-d452-11e0-bb4d-525400d75548/nics/
          c34728e8-4338-4540-ac9b-86b8582e602e"/>
    </statistic>
    ...
</statistics>

Note

This statistics sub-collection is read-only.
Report a bug

⁠14.6.1.4. Actions

⁠14.6.1.4.1. Attach Network Interface Card to Host Action
A host network interface card is attached to a network, indicating the given network is accessible over that network interface card. Either the id or name elements identify the network to which the network interface card will be attached.
⁠

Example 14.11. Action to attach a host network interface card 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.
Report a bug
⁠14.6.1.4.2. Detach Network Interface Card from Host Action
Detach a network interface card from a network. Either the id or name elements identify the network from which the network interface card will be detached.
⁠

Example 14.12. Action to detach a host network interface card from 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.
Report a bug
⁠14.6.1.4.3. Multiple Network Setup Action
A host's nics collection contains an action to perform setup of multiple network interfaces. Perform a POST request on the setupnetworks action.
⁠

Example 14.13. Action to setup multiple host network interfaces

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

<action>
    <host_nics>
        <host_nic id="41561e1c-c653-4b45-b9c9-126630e8e3b9">
            <name>em1</name>
            <network id="00000000-0000-0000-0000-000000000009"/>
            <boot_protocol>dhcp</boot_protocol>
        </host_nic<
        <host_nic id="3c3f442f-948b-4cdc-9a48-89bb0593cfbd">
            <name>em2</name>
            <network id="00000000-0000-0000-0000-000000000010"/>
            <ip address="10.35.1.247" netmask="255.255.254.0"
              gateway="10.35.1.254"/>
            <boot_protocol>static</boot_protocol>
        </host_nic>
        <checkConnectivity>true</checkConnectivity>
        <connectivityTimeout>60</connectivityTimeout>
        <force>false</false>
    </host_nics>
</action>
This action updates all specified network interface resources with standard NIC elements. The request includes additional elements specified in the following table.
⁠

Table 14.7. Additional elements for multiple host network interface setup

Element Type Description Properties
checkConnectivity Boolean Set to true to verify connectivity between the host and the Red Hat Enterprise Virtualization Manager. If the connectivity is lost, Red Hat Enterprise Virtualization Manager reverts the settings.  
connectivityTimeout integer Defines the timeout for loss of connectivity.  
force Boolean Set to true to force changes even if connectivity is lost.  
Report a bug