==========
Interfaces
==========

An interface represents either a physical interface (Ethernet) or a logical interface (VLAN) on the bonder.

Interfaces are required to create interface legs and connected IPs.

Adding, editing, & deleting interfaces
------------------------------------------------------------------------------------------------------------------------

Interfaces are displayed in a table on the bond details page.

To add an interface, click the |node-object-add| button to the upper-left of the interfaces table. This will open the "add interface" modal.

To edit an interface, click the |node-object-edit| button. This will open the "edit interface" modal.

To delete an interface, click the |node-object-delete| button. This will ask for confirmation, and is permanent.

Interface status
-----------------------------------------------------------------------------------------------------------------

To get comprehensive details on a particular interface's running state, click the caret |node-object-caret| beside its ID.

This will open the status information dropdown. Here, interface details detected by the bonder at runtime can be found (e.g., if the interface detects carrier, or the detected MTU).

Configuring an interface
--------------------------

Interface configuration options are accessed through the interface add and edit modals.

Type
^^^^

Bonders can have four different types of interfaces:

#. Ethernet
#. VLAN
#. VXLAN
#. Bridge

Ethernet interfaces must exist on the host (they will not be created by bonding).
Conversely, VLAN, VXLAN, and bridge interfaces will be created on the device
if they do not exist already, and they will be recreated if they already exist
when bonding starts.

VLAN interfaces require an existing Ethernet interface to be defined for use as a trunk device.

VXLAN interfaces can be used on bonders to implement layer-2 EVPN
functionality. For integration with local networks, a VXLAN can be attached to
a bridge that also has an ethernet or VLAN interface attached. Also, if a
VXLAN-aware switch is connected to an ethernet interface, the VXLAN can be set
to communicate directly using multicast.


Ethernet interface options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

These options are specific to Ethernet interfaces.

Interface name
++++++++++++++

The name of the interface on the bonder. Can't be changed after creation.

Interface mode
++++++++++++++

This setting controls the interface speed and whether it uses full-duplex or half-duplex communication. Set to auto negotiation by default.


VLAN interface options
^^^^^^^^^^^^^^^^^^^^^^^^^

These options are specific to VLAN interfaces.

Ethernet interface
++++++++++++++++++

The Ethernet interface to use as the trunk device. Can't be changed after creation.

VLAN tag
++++++++

The tag ID of this VLAN.


VXLAN interface options
^^^^^^^^^^^^^^^^^^^^^^^

These options are specific to VXLAN interfaces.

VXLANs are like VLANs but much more powerful. See here_ for an introduction to the technology.

.. _here: https://vincent.bernat.ch/en/blog/2017-vxlan-linux

Interface name
++++++++++++++

The name to give the VXLAN interface on the bonder. Can't be changed after creation.

VNI
++++++++++++++

The *VXLAN Network Identifier* (analogous to a VLAN tag ID).

Ethernet interface
++++++++++++++++++

The name of the base interface to use on the bonder.

Unlike VLANs, a base device is not required for VXLANs, and can be changed after creation.

Having a base Ethernet interface allows the VXLAN device to join a multicast
group and perform neighbor discovery, instead of requiring peers to be
manually added. This can be used to peer with a local VXLAN-aware switch.

Multicast group
++++++++++++++++++

The multicast group for the interface to participate in.

A base Ethernet device is required to use multicast.
If no multicast group is explicitly set and a base Ethernet device is configured, the 240.0.0.0 group is used.

Source address
++++++++++++++++++

The source address to use for this interface.

Must belong to the same IP family (IPv4 or IPv6) as the source address of peer VXLAN devices.


TTL
++++++++++++++++++

The TTL to set on packets leaving the interface.

ToS
++++++++++++++++++

The ToS to set on packets leaving the interface.

Add endpoint
+++++++++++++++++++++++++++++

Configure a peer VXLAN device by VNI, address, and port.


Bridge interface options
^^^^^^^^^^^^^^^^^^^^^^^^

These options are specific to bridge interfaces.

Bridges allow multiple interfaces to be combined into a single layer-2 bridge
that operates as a virtual switch.

They can be used to avoid the need for a local switch when connecting multiple
devices to a bonder that need to be in the same network. They can also be used
in conjunction with VXLAN interfaces to implement a layer-2 EVPN.

When using bridges it is important to note that any IP addressing must be
attached to the bridge itself and not any of the interfaces attached to the
bridge.


Ageing Time
+++++++++++

The maximum time a MAC address is held in the forwarding database since the
last time it sent a frame.

STP
+++

Enables Spanning Tree Protocol, which protects networks from bridging loops
that can cause network failures.

This should be enabled when multiple switches and bridges are connected
together. When plugging in a new device there will be a short delay before it
will forward layer-2 traffic while it attempts to detect a loop.

For simple bridges, this can be disabled to eliminate the forwarding delay.

For more information, see https://en.wikipedia.org/wiki/Spanning_Tree_Protocol

Hello Time
++++++++++

When STP is enabled, and this bridge is determined to be a designated or root
bridge, this is the interval in seconds between the transmission of hello
messages.

Forward Delay
+++++++++++++

When STP is enabled, this sets the delay in seconds after a device is plugged
before it will forward traffic. This delay is used to detect loops.

Priority
++++++++

When STP is enabled, this defines the priority of this bridge when electing
the root bridge. Lower priority values are preferred over higher ones.


Common interface options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

These options can be set for all interface types.

Bridge
++++++

Attaches the interface to a bridge interface. This can be set for any
interface types except for bridge.

When an interface is attached to a bridge, it can no longer be used with
connected IPs or services. Connected IPs and services must be assigned to the
bridge interface instead.

Interface MAC
++++++++++++++

The MAC address for the interface. This is required when using VLAN
interfaces that connect to the same ISP to keep the connection from
constantly flapping up and down.

Interface MTU
++++++++++++++

The MTU for the interface, in bytes. If MTU detection is enabled, this
represents the upper bound of possible MTU values that are checked when
detecting the path MTU. Reducing this value will speed up detection if
the path MTU is less than 1500. If MTU detection is disabled, this field
should be provided when the path MTU is less than 1500 and the modem
cannot report its MTU to the bonder correctly.

If the bond MTU detection option is disabled, the interface MTU should
be set manually in these scenarios:

#. When connected to a DSL modem in non-bridged mode, where the modem is providing a DHCP address to the bonder

#. When connected to a mobile broadband leg over Ethernet

#. Any other environment where the path MTU between the bonder and aggregator is less than 1500 bytes, but the leg is connected via Ethernet with a 1500 byte MTU

We strongly recommend that the bond's MTU detection option is not
disabled, as it handles all these scenarios automatically.

Note
++++

A free-form field for any relevant information.

Backwards compatibility
-----------------------

As of 6.4, interface mode is only configurable on Ethernet interfaces.
This changes the behaviour of the v3 API in the context of attempting to change the interface mode of a leg with a VLAN interface
(i.e. any such request will be ignored).

.. |node-object-add| image:: /attachments/bonds/node-object-add.png
.. |node-object-edit| image:: /attachments/bonds/node-object-edit.png
.. |node-object-delete| image:: /attachments/bonds/node-object-delete.png
.. |node-object-caret| image:: /attachments/bonds/node-object-caret.png
