12.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 elements:

Note

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

Table 12.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= 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. See Section 6.1.18, “Boot Protocols”.
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 (See Section 6.1.21, “Resource Status States”).
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 12.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"/>
    <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>
</host_nic>

An API user creates only bonded interfaces (see Section 12.3.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

Important

The API as documented in this section is experimental and subject to change. It is not covered by the backwards compatibility statement in Section 6, “Backwards Compatibility Statement”.

12.3.1. Bonded Interfaces

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

Table 12.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 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 12.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.
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 12.6.8, “ Commit Network Configuration Action ”.