diff options
| author | Daniil Baturin <daniil@vyos.io> | 2026-05-06 14:08:24 +0100 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-05-06 14:08:24 +0100 |
| commit | dfea790b36ddab4c6661436c8eed3cea7af5bd3a (patch) | |
| tree | c1a9a432839a7ce7aecc4072750d476ae6186248 /docs/configuration/interfaces/md-bonding.md | |
| parent | 4b36114e053ee11d0cb264a1e4cfe4692d78f194 (diff) | |
| download | vyos-documentation-dfea790b36ddab4c6661436c8eed3cea7af5bd3a.tar.gz vyos-documentation-dfea790b36ddab4c6661436c8eed3cea7af5bd3a.zip | |
Revert "Add incremental RST-to-MyST swap mechanism (#1857)" (#1892)
This reverts commit 4b36114e053ee11d0cb264a1e4cfe4692d78f194.
Diffstat (limited to 'docs/configuration/interfaces/md-bonding.md')
| -rw-r--r-- | docs/configuration/interfaces/md-bonding.md | 764 |
1 files changed, 0 insertions, 764 deletions
diff --git a/docs/configuration/interfaces/md-bonding.md b/docs/configuration/interfaces/md-bonding.md deleted file mode 100644 index 7a07a27c..00000000 --- a/docs/configuration/interfaces/md-bonding.md +++ /dev/null @@ -1,764 +0,0 @@ ---- -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 |
