From 8c0190a6cc9b7ae2b0d2f26205ab3601b35fe0b7 Mon Sep 17 00:00:00 2001 From: LiudmylaNad Date: Tue, 23 Dec 2025 14:37:59 +0100 Subject: DOC: Proofreading bonding.rst (#1721) --- docs/configuration/interfaces/bonding.rst | 660 +++++++++++++++++------------- 1 file changed, 371 insertions(+), 289 deletions(-) (limited to 'docs/configuration/interfaces') diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/bonding.rst index 27f1bbed..e0a374c3 100644 --- a/docs/configuration/interfaces/bonding.rst +++ b/docs/configuration/interfaces/bonding.rst @@ -1,16 +1,20 @@ -:lastproofread: 2021-06-30 +:lastproofread: 2025-12-09 .. _bond-interface: ####################### -Bond / Link Aggregation +Bond / link aggregation ####################### -The bonding interface provides a method for aggregating multiple network -interfaces into a single logical "bonded" interface, or LAG, or ether-channel, -or port-channel. The behavior of the bonded interfaces depends upon the mode; -generally speaking, modes provide either hot standby or load balancing services. -Additionally, link integrity monitoring may be performed. +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 @@ -23,318 +27,394 @@ Common interface configuration :var0: bonding :var1: bond0 -Member Interfaces +Member interfaces ================= .. cfgcmd:: set interfaces bonding member interface - Enslave `` interface to bond ``. + **Add an interface to the bonding group.** + + **Example:** + + To configure eth0 and eth1 as members of the bonding interface bond0, execute + the following commands: + +.. code-block:: none + + set interfaces bonding bond0 member interface eth0 + set interfaces bonding bond0 member interface eth1 -Bond options +Bond modes ============ .. cfgcmd:: set interfaces bonding mode <802.3ad | active-backup | broadcast | round-robin | transmit-load-balance | adaptive-load-balance | xor-hash> - Specifies one of the bonding policies. The default is 802.3ad. Possible - values are: - - * ``802.3ad`` - IEEE 802.3ad Dynamic link aggregation. Creates aggregation - groups that share the same speed and duplex settings. Utilizes all slaves - in the active aggregator according to the 802.3ad specification. - - Slave selection for outgoing traffic is done according to the transmit - hash policy, which may be changed from the default simple XOR policy via - the :cfgcmd:`hash-policy` option, documented below. - - .. note:: Not all transmit policies may be 802.3ad compliant, particularly - in regards to the packet misordering requirements of section 43.2.4 - of the 802.3ad standard. - - * ``active-backup`` - Active-backup policy: Only one slave in the bond is - active. A different slave becomes active if, and only if, the active slave - fails. The bond's MAC address is externally visible on only one port - (network adapter) to avoid confusing the switch. - - When a failover occurs in active-backup mode, bonding will issue one or - more gratuitous ARPs on the newly active slave. One gratuitous ARP is - issued for the bonding master interface and each VLAN interfaces - configured above it, provided that the interface has at least one IP - address configured. Gratuitous ARPs issued for VLAN interfaces are tagged - with the appropriate VLAN id. - - This mode provides fault tolerance. The :cfgcmd:`primary` option, - documented below, affects the behavior of this mode. - - * ``broadcast`` - Broadcast policy: transmits everything on all slave - interfaces. - - This mode provides fault tolerance. - - * ``round-robin`` - Round-robin policy: Transmit packets in sequential - order from the first available slave through the last. - - This mode provides load balancing and fault tolerance. - - * ``transmit-load-balance`` - Adaptive transmit load balancing: channel - bonding that does not require any special switch support. - - Incoming traffic is received by the current slave. If the receiving slave - fails, another slave takes over the MAC address of the failed receiving - slave. - - * ``adaptive-load-balance`` - Adaptive load balancing: includes - transmit-load-balance plus receive load balancing for IPV4 traffic, and - does not require any special switch support. The receive load balancing - is achieved by ARP negotiation. The bonding driver intercepts the ARP - Replies sent by the local system on their way out and overwrites the - source hardware address with the unique hardware address of one of the - slaves in the bond such that different peers use different hardware - addresses for the server. - - Receive traffic from connections created by the server is also balanced. - When the local system sends an ARP Request the bonding driver copies and - saves the peer's IP information from the ARP packet. When the ARP Reply - arrives from the peer, its hardware address is retrieved and the bonding - driver initiates an ARP reply to this peer assigning it to one of the - slaves in the bond. A problematic outcome of using ARP negotiation for - balancing is that each time that an ARP request is broadcast it uses the - hardware address of the bond. Hence, peers learn the hardware address - of the bond and the balancing of receive traffic collapses to the current - slave. This is handled by sending updates (ARP Replies) to all the peers - with their individually assigned hardware address such that the traffic - is redistributed. Receive traffic is also redistributed when a new slave - is added to the bond and when an inactive slave is re-activated. The - receive load is distributed sequentially (round robin) among the group - of highest speed slaves in the bond. - - When a link is reconnected or a new slave joins the bond the receive - traffic is redistributed among all active slaves in the bond by initiating - ARP Replies with the selected MAC address to each of the clients. The - updelay parameter (detailed below) must be set to a value equal or greater - than the switch's forwarding delay so that the ARP Replies sent to the - peers will not be blocked by the switch. - - * ``xor-hash`` - XOR policy: Transmit based on the selected transmit - hash policy. The default policy is a simple [(source MAC address XOR'd - with destination MAC address XOR packet type ID) modulo slave count]. - Alternate transmit policies may be selected via the :cfgcmd:`hash-policy` - option, described below. - - This mode provides load balancing and fault tolerance. + **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 min-links <0-16> - Specifies the minimum number of links that must be active before asserting - carrier. It is similar to the Cisco EtherChannel min-links feature. This - allows setting the minimum number of member ports that must be up (link-up - state) before marking the bond device as up (carrier on). This is useful for - situations where higher level services such as clustering want to ensure a - minimum number of low bandwidth links are active before switchover. + **Configure how many member interfaces must be active (in the link-up state) to + mark the bonding interface UP (carrier asserted).** - This option only affects 802.3ad mode. + 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 will cause the carrier to be asserted - (for 802.3ad mode) whenever there is an active aggregator, - regardless of the number of available links in that aggregator. + 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:: Because an aggregator cannot be active without at least one - available link, setting this option to 0 or to 1 has the exact same - effect. + .. 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 lacp-rate - Option specifying the rate in which we'll ask our link partner to transmit - LACPDU packets in 802.3ad mode. - - This option only affects 802.3ad mode. - - * slow: Request partner to transmit LACPDUs every 30 seconds - - * fast: Request partner to transmit LACPDUs every 1 second - - The default value is slow. - -.. cfgcmd:: set interfaces bonding system-mac - - This option allow to specifies the 802.3ad system MAC address.You can set a - random mac-address that can be used for these LACPDU exchanges. - -.. cfgcmd:: set interfaces bonding hash-policy - - * **layer2** - Uses XOR of hardware MAC addresses and packet type ID field - to generate the hash. The formula is - - .. code-block:: none - - hash = source MAC XOR destination MAC XOR packet type ID - slave number = hash modulo slave count - - This algorithm will place all traffic to a particular network peer on - the same slave. - - This algorithm is 802.3ad compliant. + **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.** - * **layer2+3** - This policy uses a combination of layer2 and layer3 - protocol information to generate the hash. Uses XOR of hardware MAC - addresses and IP addresses to generate the hash. The formula is: + This command applies only when the bonding interface is configured in + 802.3ad mode. - .. code-block:: none + The following options are available: - hash = source MAC XOR destination MAC XOR packet type ID - hash = hash XOR source IP XOR destination IP - hash = hash XOR (hash RSHIFT 16) - hash = hash XOR (hash RSHIFT 8) + * **slow (default):** Requests the link partner to transmit LACPDUs every 30 seconds. - And then hash is reduced modulo slave count. + * **fast:** Requests the link partner to transmit LACPDUs every 1 second. - If the protocol is IPv6 then the source and destination addresses are - first hashed using ipv6_addr_hash. - This algorithm will place all traffic to a particular network peer on the - same slave. For non-IP traffic, the formula is the same as for the layer2 - transmit hash policy. - - This policy is intended to provide a more balanced distribution of traffic - than layer2 alone, especially in environments where a layer3 gateway - device is required to reach most destinations. - - This algorithm is 802.3ad compliant. - - * **layer3+4** - This policy uses upper layer protocol information, when - available, to generate the hash. This allows for traffic to a particular - network peer to span multiple slaves, although a single connection will - not span multiple slaves. - - The formula for unfragmented TCP and UDP packets is +.. cfgcmd:: set interfaces bonding system-mac - .. code-block:: none + **Configure a specific MAC address for the bonding interface.** - hash = source port, destination port (as in the header) - hash = hash XOR source IP XOR destination IP - hash = hash XOR (hash RSHIFT 16) - hash = hash XOR (hash RSHIFT 8) + 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. - And then hash is reduced modulo slave count. - If the protocol is IPv6 then the source and destination addresses are - first hashed using ipv6_addr_hash. +.. cfgcmd:: set interfaces bonding hash-policy - For fragmented TCP or UDP packets and all other IPv4 and IPv6 protocol - traffic, the source and destination port information is omitted. For - non-IP traffic, the formula is the same as for the layer2 transmit hash - policy. + **Configure which transmit hash policy to use for distributing traffic across + member interfaces.** + + The following policies are available: + + * ``layer2`` + + .. list-table:: + :widths: 20 80 + + * - **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`` + + .. list-table:: + :widths: 20 80 + + * - **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`` + + .. list-table:: + :widths: 20 80 + + * - **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 primary - This algorithm is not fully 802.3ad compliant. A single TCP or UDP - conversation containing both fragmented and unfragmented packets will see - packets striped across two interfaces. This may result in out of order - delivery. Most traffic types will not meet these criteria, as TCP rarely - fragments traffic, and most UDP traffic is not involved in extended - conversations. Other implementations of 802.3ad may or may not tolerate - this noncompliance. + **Configure the primary member interface in the bond.** -.. cfgcmd:: set interfaces bonding primary + The primary member interface remains active as long as it is operational; + alternative member interfaces are used only if it fails. - An `` specifying which slave is the primary device. The specified - device will always be the active slave while it is available. Only when the - primary is off-line will alternate devices be used. This is useful when one - slave is preferred over another, e.g., when one slave has higher throughput - than another. + Use this configuration when a specific member interface is preferred, + such as one with higher throughput. - The primary option is only valid for active-backup, transmit-load-balance, - and adaptive-load-balance mode. + This command applies only to ``active-backup``, ``transmit-load-balance``, and + ``adaptive-load-balance`` modes. .. cfgcmd:: set interfaces bonding arp-monitor interval