Product SiteDocumentation Site

13.3.  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 properties:

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 The name of the host network interface, e.g. eth0 [a]
host id GUID A reference to the host
network id GUID A reference to the network, if any, that the interface is attached to [b]
mac address string The MAC address of the interface
ip complex The IP level configuration of the interface. Contains address, netmask and gateway attributes.
boot_protocol enumerated The protocol for IP address assignment when the host is booting. A list of enumerated values is available in capabilities. See Section 7.1.17, “Boot Protocols”
speed integer The network interface speed in bits per second
status integer The link status for the network interface
vlan id GUID The VLAN which this interface represents, if any
bonding complex A list of options and slave NICs for bonded interfaces [c]
link rel="master" complex A reference to the master bonded interface, if this is a slave interface
[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 13.9. An XML representation of a network interface on a host
<host_nic id="e8f02fdf-3d7b-4135-86e1-1bf185570cd8"
  href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
  e8f02fdf-3d7b-4135-86e1-1bf185570cd8">
    <name>bond0</name>
    <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
      href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
    <network id="e657d631-657d-42bb-a536-73501a085d85"
      href="/rhevm-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"/>
    <boot_protocol>dhcp</boot_protocol>
    <speed>1000000000</speed>
    <status>UP</status>
    <bonded>
        <options>
            ...
        </options>
        <slaves>
            <host_nic id="eb14e154-5e73-4f7f-bf6b-7f52609d94ec"/>
            <host_nic id="6aede5ca-4c54-4b37-a81b-c0d6b53558ea"/>
        </slaves>
    </bonded>
    <actions>
        <link rel="attach"
          href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
          e8f02fdf-3d7b-4135-86e1-1bf185570cd8/attach"/>
        <link rel="detach"
          href="/rhevm-api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
          e8f02fdf-3d7b-4135-86e1-1bf185570cd8/detach"/>
    </actions>
</host_nic>

An API user creates only bonded interfaces (see Section 13.3.1, “ Bonded Interfaces ”). All other network interfaces contain updatable network, ip and boot_protocol properties using a PUT request.

13.3.1.  Bonded Interfaces

A bonded interface is represented as a host_nic resource containing a bonded element, which contains the following 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 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. The network and slave host_nics may be identified by id or name.
Example 13.10. Creating a bonded interface
POST /rhevm-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"/>
    <bonded>
        <options>
            ...
        </options>
        <slaves>
            <host_nic id="eb14e154-5e73-4f7f-bf6b-7f52609d94ec"/>
            <host_nic id="6aede5ca-4c54-4b37-a81b-c0d6b53558ea"/>
        </slaves>
    </bonded>
</host_nic>

Note

bond0, bond1, bond2, bond3 and bond4 are the only valid names for a bonded interface.
Like other resources, a bonded interface may be deleted by issuing a DELETE request to its URI.

Warning

Changes to bonded interface configuration must be explicitly committed. See Section 13.5.8, “ Commit Network Configuration Action ”.