diff options
| author | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-02 17:25:47 +0300 |
|---|---|---|
| committer | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-06 16:18:03 +0300 |
| commit | fa54a080fac977157454beb0853daf0ac0e6af66 (patch) | |
| tree | 82b112cde06437b80515450d63eb793bee198ec6 /docs/configuration/interfaces/bonding.md | |
| parent | 746195618941d8be8ed132f4b0be539763ec352d (diff) | |
| download | vyos-documentation-fa54a080fac977157454beb0853daf0ac0e6af66.tar.gz vyos-documentation-fa54a080fac977157454beb0853daf0ac0e6af66.zip | |
feat(swap): import .md files and webp transition from myst/current
Selective import from origin/myst/current (cf9c9b34):
- Add/update 255 .md files (full MyST conversion plus webp ref updates)
- Delete 175 PNG/JPG from docs/_static/images (webp twins already present)
- Delete 5 autotest topology.png (webp twins already present)
Preserved on swap (untouched):
- All .rst files (incremental swap pattern)
- conf.py, _ext/, _include/*.txt, .gitignore
- 115 canary md-*.md files
- 7 superpowers/specs/*.md design docs
- Logos vyos-logo.png / vyos-logo-icon.png (referenced by conf.py)
🤖 Generated by [robots](https://vyos.io)
Diffstat (limited to 'docs/configuration/interfaces/bonding.md')
| -rw-r--r-- | docs/configuration/interfaces/bonding.md | 764 |
1 files changed, 764 insertions, 0 deletions
diff --git a/docs/configuration/interfaces/bonding.md b/docs/configuration/interfaces/bonding.md new file mode 100644 index 00000000..7a07a27c --- /dev/null +++ b/docs/configuration/interfaces/bonding.md @@ -0,0 +1,764 @@ +--- +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 +::: +```
\ No newline at end of file |
