path: root/docs/configuration/interfaces/bonding.md

---
lastproofread: '2025-12-09'
---

(bond-interface)=

# Bond / link aggregation

A **bonding interface** aggregates multiple network interfaces into a single
logical interface (referred to as a bond, {abbr}`LAG (Link Aggregation Group)`,
EtherChannel, or port-channel).

The behavior of a bonding interface depends on the selected mode. Modes provide
either fault tolerance or a combination of load balancing and fault tolerance.
Additionally, the bonding interface can be configured for link integrity
monitoring.

## Configuration

### Common interface configuration

```{cmdincludemd} /_include/interface-common-with-dhcp.txt
:var0: bonding
:var1: bond0
```

### Member interfaces

```{cfgcmd} set interfaces bonding \<interface\> member interface \<member\>

**Add an interface to the bonding group.**

**Example:**

To configure eth0 and eth1 as members of the bonding interface bond0, execute
the following commands:
```

```none
set interfaces bonding bond0 member interface eth0
set interfaces bonding bond0 member interface eth1
```

### Bond modes

````{cfgcmd} set interfaces bonding \<interface\> mode \<802.3ad | active-backup | broadcast | round-robin | transmit-load-balance | adaptive-load-balance | xor-hash\>

```{eval-rst}
**Configure the bonding mode on the interface. The default mode is**
``802.3ad``.

The available modes are:

* ``802.3ad``

.. list-table::
   :widths: 20 80

   * - **Description:**
     - IEEE 802.3ad Dynamic Link Aggregation. Groups only member
       interfaces with the same speed (e.g., 1 Gbps) and duplex
       settings. Member interfaces with different speed and duplex
       settings are not included in the active bond.

       Provides load balancing and fault tolerance. Uses the
       :abbr:`LACP (Link Aggregation Control Protocol)` to
       negotiate the bond with the switch.
   * - **Traffic distribution:**
     - Traffic is distributed according to the **transmit hash
       policy** (default: XOR).

       The bonding driver applies an XOR operation to specific
       packet header fields, generating a hash value that maps to
       a particular member interface. This ensures the same network
       flow is consistently transmitted over the same member
       interface.

       The transmit hash policy is configured via the ``hash-policy`` option.
   * - **Failover:**
     - If a member interface fails, the hash is recalculated to distribute
       traffic among the remaining active member interfaces.

.. note:: Not all transmit hash policies comply with 802.3ad, particularly
   section 43.2.4. Using a non-compliant policy may result in out-of-order
   packet delivery.

* ``active-backup``

.. list-table::
   :widths: 20 80

   * - **Description:**
     - Provides fault tolerance. Only one member interface is active
       at a time. Other member interfaces remain in a standby mode.
   * - **Traffic distribution:**
     - All traffic (incoming and outgoing) is routed via one active
       member interface.
   * - **Failover:**
     - If the designated member interface fails, all traffic is
       routed to another member interface. The bonding driver sends
       a Gratuitous ARP to update the peer's MAC address table,
       linking the bond's MAC address to another physical port.

* ``broadcast``

.. list-table::
   :widths: 20 80

   * - **Description:**
     - Provides maximum fault tolerance by duplicating traffic.
   * - **Traffic distribution:**
     - Every packet is duplicated and transmitted on **all** member
       interfaces.
   * - **Failover:**
     - Traffic flow is not interrupted as long as at least one
       member interface remains active.

* ``round-robin``

.. list-table::
   :widths: 20 80

   * - **Description:**
     - Provides load balancing and fault tolerance.
   * - **Traffic distribution:**
     - Packets are transmitted in sequential order across the member
       interfaces (e.g., packet 1 > interface A, packet 2 >
       interface B, etc.).
   * - **Failover:**
     - If a member interface fails, the sequence skips the failed
       interface and continues with the remaining active members.

* ``transmit-load-balance``

.. list-table::
   :widths: 20 80

   * - **Description:**
     - Provides adaptive transmit load balancing and fault tolerance.
   * - **Traffic distribution:**
     - **Outgoing:** Distributed across all active member interfaces
       based on the current load.

       **Incoming:** Received by a designated member interface
       (active receiver).
   * - **Failover:**
     - If the active receiver fails, another member interface takes
       over as the new active receiver.

* ``adaptive-load-balance``

.. list-table::
   :widths: 20 80

   * - **Description:**
     - Provides adaptive transmit load balancing identical to
       ``transmit-load-balance``, receive load balancing for IPv4
       traffic, and fault tolerance for both incoming and outgoing
       traffic.
   * - **Traffic distribution:**
     - **Outgoing:** Identical to ``transmit-load-balance``.

       **Incoming:** Distributed based on ARP manipulation. For
       both local and remote connections, the bonding driver
       intercepts ARP traffic and changes the source MAC address
       to the MAC address of the least loaded member interface.

       All traffic from that peer is then routed to the chosen
       member interface.
   * - **Failover:**
     - If a member interface's state changes (fails, recovers, is
       added, or excluded), the traffic is redistributed among all
       active member interfaces.

* ``xor-hash``: Provides load balancing and fault tolerance
  based on a hash formula. Distributes traffic and handles
  failover identically to ``802.3ad``, but operates without
  the :abbr:`LACP (Link Aggregation Control Protocol)`.
```

````

```{cfgcmd} set interfaces bonding \<interface\> min-links \<0-16\>

**Configure how many member interfaces must be active (in the
link-up state) to mark the bonding interface UP (carrier
asserted).**

This command applies only when the bonding interface is configured
in 802.3ad mode and functions like the Cisco EtherChannel min-links
feature. It ensures that a bonding interface is marked UP (carrier
asserted) only when a specified number of member interfaces are
active (in the link-up state). This helps guarantee a minimum level
of bandwidth for higher-level services (such as clustering) relying
on the bonding interface.

The default value is 0. This marks the bonding interface UP
(carrier asserted) whenever an active LACP aggregator exists,
regardless of the number of member interfaces in that aggregator.

:::{note}
In 802.3ad mode, a bond cannot be active without at least one active
member interface. Therefore, setting min-links to 0 or 1 has the same result:
the bonding interface is marked UP (carrier asserted).
:::
```

```{cfgcmd} set interfaces bonding \<interface\> lacp-rate \<slow|fast\>

**Configure the rate at which the bonding interface requests its link
partner to send** {abbr}`LACPDUs (Link Aggregation Control Protocol Data
Units)` **in 802.3ad mode.**

This command applies only when the bonding interface is configured in
802.3ad mode.

The following options are available:

* **slow (default):** Requests the link partner to transmit LACPDUs every 30 seconds.

* **fast:** Requests the link partner to transmit LACPDUs every 1 second.
```
```{cfgcmd} set interfaces bonding \<interface\> system-mac \<mac address\>

**Configure a specific MAC address for the bonding interface.**

This sets the 802.3ad system MAC address, which is used for {abbr}`LACPDU (Link
Aggregation Control Protocol Data Unit)` exchanges with the link partner.
You can assign a fixed MAC address or generate a random one for these
{abbr}`LACPDU (Link Aggregation Control Protocol Data Unit)` exchanges.
```
```{cfgcmd} set interfaces bonding \<interface\> hash-policy \<policy\>

**Configure which transmit hash policy to use for distributing traffic across
member interfaces.**

The following policies are available:

* ``layer2``

**Description:** Routes all traffic destined for a specific network peer through
the same member interface. The policy is 802.3ad-compliant.

**Hash inputs:** Source MAC address, destination MAC address, and Ethernet packet
type ID.

**Formula:**

:::{code-block} none
hash = source MAC address XOR destination MAC address XOR packet type ID
member interface number = hash modulo member interface count
:::

* ``layer2+3``

**Description:** Similar to ``layer2``, routes all traffic destined for a specific
network peer through the same member interface and is IEEE 802.3ad-compliant. Uses
both Layer 2 and Layer 3 information to provide a more balanced traffic distribution.

**Hash inputs:**
* Source MAC address, destination MAC address, and Ethernet packet type ID.
* Source IP address, destination IP address. IPv6 addresses are first hashed
  using ``IPv6_addr_hash``.

**Formula:**

:::{code-block} none
hash = source MAC address XOR destination MAC address XOR packet type ID
hash = hash XOR source IP address XOR destination IP address
hash = hash XOR (hash RSHIFT 16)
hash = hash XOR (hash RSHIFT 8)
member interface number = hash modulo member interface count
:::

For non-IP traffic, the formula is the same as for ``layer2``.

* ``layer3+4``

**Description:** Routes different connections (flows) destined for a specific
network peer through multiple member interfaces, but ensures each individual
flow is routed through only one member interface.

:::{note}
This policy is not fully 802.3ad-compliant. When a single TCP or UDP flow
contains both fragmented and unfragmented packets, the algorithm may distribute
them across different member interfaces. This may result in out-of-order packet
delivery, violating the 802.3ad standard.
:::

**Hash inputs:**
* Source port, destination port (if available).
* Source IP address, destination IP address. IPv6 addresses are first hashed
  using ``IPv6_addr_hash``.

**Formula:**

:::{code-block} none
hash = source port, destination port (as in the header)
hash = hash XOR source IP address XOR destination IP address
hash = hash XOR (hash RSHIFT 16)
hash = hash XOR (hash RSHIFT 8)
member interface number = hash modulo member interface count
:::

For fragmented TCP or UDP packets and all other IPv4 and IPv6 traffic, the
source and destination port information is omitted.

For non-IP traffic, the formula is the same as for ``layer2``.
```


```{cfgcmd} set interfaces bonding \<interface\> primary \<interface\>

**Configure the primary member interface in the bond.**

The primary member interface remains active as long as it is operational;
alternative member interfaces are used only if it fails.

Use this configuration when a specific member interface is preferred,
such as one with higher throughput.

This command applies only to ``active-backup``, ``transmit-load-balance``, and
``adaptive-load-balance`` modes.
```


```{cfgcmd} set interfaces bonding \<interface\> arp-monitor interval \<time\>

**Configure the ARP monitoring interval, in seconds, for the bonding interface.**

ARP monitoring periodically assesses the health of each member interface by
checking whether it has recently sent or received traffic (this criterion
varies depending on the bonding mode and the member interface’s state). ARP
probes are sent to the IP addresses specified with the arp-monitor target option.

When ARP monitoring is used with EtherChannel-compatible modes (such as
``round-robin`` or ``xor-hash``), the switch should be configured to distribute
traffic across all member interfaces. If the switch distributes traffic using
an XOR-based policy, all ARP replies will be received on one member interface,
causing other member interfaces to be incorrectly marked as failed.

Setting this value to 0 disables ARP monitoring.

The default value is 0.
```


```{cfgcmd} set interfaces bonding \<interface\> arp-monitor target \<address\>

**Configure the IP addresses for ARP monitoring requests.**

The bonding driver sends ARP requests to these IP addresses to check the
state of member interfaces.

To enable ARP monitoring, configure at least one IP address (up to 16 per
bonding interface).

By default, no IP addresses are configured.
```

### {abbr}`VLAN (Virtual Local Area Network)`

```{cmdincludemd} /_include/interface-vlan-8021q.txt
:var0: bonding
:var1: bond0
```

### SPAN port mirroring

```{cmdincludemd} ../../_include/interface-mirror.txt
:var0: bonding
:var1: bond1
:var2: eth3
```

#### EVPN multihoming


EVPN multihoming (EVPN-MH) is a standards-based solution (RFC 7432, RFC 8365)
that enables Customer Edge (CE) devices, such as servers, to connect to two
or more Provider Edge (PE) devices for redundancy and load balancing.


EVPN-MH is often used as a modern, standards-based alternative to
{abbr}`MLAG (Multi-Chassis Link Aggregation)` and {abbr}`VTEPs (Virtual
Tunnel Endpoints)`.


**Ethernet Segment (ES) and Ethernet Segment Identifier (ESI)**


Physical links that connect a CE device to PE devices are bundled using link
aggregation. This logical bundle is called an Ethernet Segment (ES) and is
uniquely identified by an Ethernet Segment Identifier (ESI) within the
EVPN domain.


To enable EVPN-MH, configure the same ESI on the bonding interfaces of all
PE devices connected to a single CE device.


An ESI is configured by specifying either a system MAC address and a local
discriminator, or an Ethernet Segment Identifier Name (ESINAME).


The following two commands generate a 10-byte Type-3 ESI by combining the
system MAC and local discriminator:

```{cfgcmd} set interfaces bonding \<interface\> evpn es-id \<1-16777215|10-byte ID\>

```
```{cfgcmd} set interfaces bonding \<interface\> evpn es-sys-mac \<xx:xx:xx:xx:xx:xx\>

Alternatively, assign an ESINAME directly as a 10-byte Type-0 ESI using the
following format: 00:AA:BB:CC:DD:EE:FF:GG:HH:II.

**BGP-EVPN route usage**

EVPN-MH uses BGP-EVPN route types 1 and 2 for ES discovery and MAC-IP
synchronization:

* **Type 1 (EAD-per-ES and EAD-per-EVI)** routes advertise the locally
attached ESs and discover remote ESs in the network.
* **Type 2 (MAC-IP advertisement)** routes are advertised with a
destination ESI, enabling MAC-IP synchronization between ES peers.
```

```{cfgcmd} set interfaces bonding \<interface\> evpn es-df-pref \<1-65535\>

**Configure the** {abbr}`DF (Designated Forwarder)` **preference (1-65535) for
the interface. A higher value indicates a higher preference to become the**
{abbr}`DF (Designated Forwarder)`. **The** {abbr}`DF (Designated Forwarder)`
**preference is configured per-ES.**

The DF election process determines which interface in a specific ES forwards
{abbr}`BUM (Broadcast, Unknown Unicast, and Multicast)` traffic from the EVPN
overlay to the connected CE device. EVPN Type-4 (Ethernet Segment) routes are
used to elect the DF, implementing the preference-based election method defined
in RFC 9785.

Interfaces not elected as the DF drop any BUM traffic from the EVPN overlay
using non-DF filters. Similarly, traffic received from ES peers via the EVPN
overlay is blocked from forwarding to the CE device to maintain split-horizon
filtering with local bias.
```

```{cmdincludemd} /_include/interface-evpn-uplink.txt
:var0: bonding
:var1: bond0
```

## Example


The following configuration example applies to all listed third-party vendors.
It creates a bonding interface with two member interfaces, defines VLANs 10
and 100 on the bonding interface, and assigns an IPv4 address to each VLAN
subinterface.

```none
# Create the bonding interface bond0 with 802.3ad LACP
set interfaces bonding bond0 hash-policy 'layer2'
set interfaces bonding bond0 mode '802.3ad'

# Add the required VLANs and IPv4 addresses on them
set interfaces bonding bond0 vif 10 address 192.168.0.1/24
set interfaces bonding bond0 vif 100 address 10.10.10.1/24

# Add the member interfaces to the bonding interface
set interfaces bonding bond0 member interface eth1
set interfaces bonding bond0 member interface eth2
```
:::{note}
If you are running this configuration in a virtual environment like
EVE-NG, ensure the e1000 driver is chosen for your VyOS NIC. The default
drivers, such as ``virtio-net-pci`` or ``vmxnet3``, are incompatible with
this configuration. Specifically, ICMP messages will not be processed
correctly.

To check your NIC driver, use the following command:
``show interfaces ethernet eth0 physical | grep -i driver``
:::


### Cisco Catalyst configuration


Configure a Cisco Catalyst switch to integrate with a two-member VyOS bonding
interface.


Assign member interfaces to PortChannel:

```none
interface GigabitEthernet1/0/23
 description VyOS eth1
 channel-group 1 mode active
!
interface GigabitEthernet1/0/24
 description VyOS eth2
 channel-group 1 mode active
!
```

A new interface, `Port-channel1`, becomes available; all configuration,
such as allowed VLAN interfaces and STP, is applied here.

```none
interface Port-channel1
 description LACP Channel for VyOS
 switchport trunk encapsulation dot1q
 switchport trunk allowed vlan 10,100
 switchport mode trunk
 spanning-tree portfast trunk
!
```

### Juniper EX Switch configuration


Configure a Juniper EX Series switch to integrate with a two-member VyOS bonding
interface.

```none
# Create aggregated ethernet device with 802.3ad LACP and port speeds of 10gbit/s
set interfaces ae0 aggregated-ether-options link-speed 10g
set interfaces ae0 aggregated-ether-options lacp active

# Create layer 2 on the aggregated ethernet device with trunking for our VLANs
set interfaces ae0 unit 0 family ethernet-switching port-mode trunk

# Add the required vlans to the device
set interfaces ae0 unit 0 family ethernet-switching vlan members 10
set interfaces ae0 unit 0 family ethernet-switching vlan members 100

# Add the two interfaces to the aggregated ethernet device, in this setup both
# ports are on the same switch (switch 0, module 1, port 0 and 1)
set interfaces xe-0/1/0 ether-options 802.3ad ae0
set interfaces xe-0/1/1 ether-options 802.3ad ae0

# But this can also be done with multiple switches in a stack, a virtual
# chassis on Juniper (switch 0 and switch 1, module 1, port 0 on both switches)
set interfaces xe-0/1/0 ether-options 802.3ad ae0
set interfaces xe-1/1/0 ether-options 802.3ad ae0
```

### Aruba/HP configuration


Configure an Aruba/HP 2510G switch to integrate with a two-member VyOS bonding
interface.

```none
# Create trunk with 2 member interfaces (interface 1 and 2) and LACP
trunk 1-2 Trk1 LACP

# Add the required VLANs to the trunk
vlan 10 tagged Trk1
vlan 100 tagged Trk1
```

### Arista EOS configuration


When deploying VyOS in environments with Arista switches, use the following
blueprint as an initial setup to configure an operational LACP port-channel
between the two devices.


Let's assume the following topology:


```{eval-rst}
.. figure:: /_static/images/vyos_arista_bond_lacp.webp
   :alt: VyOS Arista EOS setup
```


**R1**

```none
interfaces {
    bonding bond10 {
        hash-policy layer3+4
        member {
            interface eth1
            interface eth2
        }
        mode 802.3ad
        vif 100 {
            address 192.0.2.1/30
            address 2001:db8::1/64
        }
    }
```
**R2**



```none
interfaces {
    bonding bond10 {
        hash-policy layer3+4
        member {
            interface eth1
            interface eth2
        }
        mode 802.3ad
        vif 100 {
            address 192.0.2.2/30
            address 2001:db8::2/64
        }
    }
```
**SW1**

```none
!
vlan 100
   name FOO
!
interface Port-Channel10
   switchport trunk allowed vlan 100
   switchport mode trunk
   spanning-tree portfast
!
interface Port-Channel20
   switchport mode trunk
   no spanning-tree portfast auto
   spanning-tree portfast network
!
interface Ethernet1
   channel-group 10 mode active
!
interface Ethernet2
   channel-group 10 mode active
!
interface Ethernet3
   channel-group 20 mode active
!
interface Ethernet4
   channel-group 20 mode active
!
```
**SW2**



```none
!
vlan 100
   name FOO
!
interface Port-Channel10
   switchport trunk allowed vlan 100
   switchport mode trunk
   spanning-tree portfast
!
interface Port-Channel20
   switchport mode trunk
   no spanning-tree portfast auto
   spanning-tree portfast network
!
interface Ethernet1
   channel-group 10 mode active
!
interface Ethernet2
   channel-group 10 mode active
!
interface Ethernet3
   channel-group 20 mode active
!
interface Ethernet4
   channel-group 20 mode active
!
```
:::{note}
When testing this environment in EVE-NG, ensure the e1000 driver
is chosen for your VyOS network interfaces. If the default virtio driver
is used, VyOS will not transmit LACP PDUs, preventing the port-channel
from ever becoming active.
:::


(operation)=

## Operation

```{opcmd} show interfaces bonding

Show brief interface information.


:::{code-block} none
vyos@vyos:~$ show interfaces bonding
Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
Interface        IP Address                        S/L  Description
---------        ----------                        ---  -----------
bond0            -                                 u/u  my-sw1 int 23 and 24
bond0.10         192.168.0.1/24                    u/u  office-net
bond0.100        10.10.10.1/24                     u/u  management-net
:::
```
```{opcmd} show interfaces bonding \<interface\>

Show detailed interface information.

:::{code-block} none
vyos@vyos:~$ show interfaces bonding bond5
bond5: <NO-CARRIER,BROADCAST,MULTICAST,MASTER,UP> mtu 1500 qdisc noqueue state DOWN group default qlen 1000
    link/ether 00:50:56:bf:ef:aa brd ff:ff:ff:ff:ff:ff
    inet6 fe80::e862:26ff:fe72:2dac/64 scope link tentative
       valid_lft forever preferred_lft forever

    RX:  bytes  packets  errors  dropped  overrun       mcast
             0        0       0        0        0           0
    TX:  bytes  packets  errors  dropped  carrier  collisions
             0        0       0        0        0           0
:::
```
```{opcmd} show interfaces bonding \<interface\> detail

Show detailed information about the underlying physical links on the given
bonding interface.

:::{code-block} none
vyos@vyos:~$ show interfaces bonding bond5 detail
Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011)
Bonding Mode: IEEE 802.3ad Dynamic link aggregation
Transmit Hash Policy: layer2 (0)
MII Status: down
MII Polling Interval (ms): 100
Up Delay (ms): 0
Down Delay (ms): 0
802.3ad info
LACP rate: slow
Min links: 0
Aggregator selection policy (ad_select): stable
Slave Interface: eth1
MII Status: down
Speed: Unknown
Duplex: Unknown
Link Failure Count: 0
Permanent HW addr: 00:50:56:bf:ef:aa
Slave queue ID: 0
Aggregator ID: 1
Actor Churn State: churned
Partner Churn State: churned
Actor Churned Count: 1
Partner Churned Count: 1
Slave Interface: eth2
MII Status: down
Speed: Unknown
Duplex: Unknown
Link Failure Count: 0
Permanent HW addr: 00:50:56:bf:19:26
Slave queue ID: 0
Aggregator ID: 2
Actor Churn State: churned
Partner Churn State: churned
Actor Churned Count: 1
Partner Churned Count: 1
:::
```