diff options
| -rw-r--r-- | docs/interfaces/bond.rst | 317 |
1 files changed, 274 insertions, 43 deletions
diff --git a/docs/interfaces/bond.rst b/docs/interfaces/bond.rst index 880c7580..605af30a 100644 --- a/docs/interfaces/bond.rst +++ b/docs/interfaces/bond.rst @@ -1,72 +1,303 @@ .. _bond-interface: +#### Bond ----- +#### -You can combine (aggregate) 2 or more physical interfaces into a single -logical one. It's called bonding, or LAG, or ether-channel, or port-channel. +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. -Create interface bondX, where X is just a number: +Configuration +############# -.. code-block:: none +Address +------- - set interfaces bonding bond0 description 'my-sw1 int 23 and 24' +.. cfgcmd:: set interfaces bonding <interface> address <address | dhcp | dhcpv6> -You are able to choose a hash policy: + Configure interface `<interface>` with one or more interface addresses. -.. code-block:: none + * **address** can be specified multiple times as IPv4 and/or IPv6 address, + e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + * **dhcp** interface address is received by DHCP from a DHCP server on this + segment. + * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on + this segment. - vyos@vyos# set interfaces bonding bond0 hash-policy - Possible completions: - layer2 use MAC addresses to generate the hash (802.3ad) - layer2+3 combine MAC address and IP address to make hash - layer3+4 combine IP address and port to make hash + Example: -For example: + .. code-block:: none -.. code-block:: none + set interfaces bonding bond0 address 192.0.2.1/24 + set interfaces bonding bond0 address 192.0.2.2/24 + set interfaces bonding bond0 address 2001:db8::ffff/64 + set interfaces bonding bond0 address 2001:db8:100::ffff/64 - set interfaces bonding bond0 hash-policy 'layer2' -You may want to set IEEE 802.3ad Dynamic link aggregation (802.3ad) AKA LACP -(don't forget to setup it on the other end of these links): +.. cfgcmd:: set interfaces bonding <interface> ipv6 address autoconf -.. code-block:: none + :abbr:`SLAAC (Stateless Address Autoconfiguration)` + :rfc:`4862`. IPv6 hosts can configure themselves automatically when connected + to an IPv6 network using the Neighbor Discovery Protocol via :abbr:`ICMPv6 + (Internet Control Message Protocol version 6)` router discovery messages. + When first connected to a network, a host sends a link-local router + solicitation multicast request for its configuration parameters; routers + respond to such a request with a router advertisement packet that contains + Internet Layer configuration parameters. - set interfaces bonding bond0 mode '802.3ad' + .. note:: This method automatically disables IPv6 traffic forwarding on the + interface in question. -or some other modes: -.. code-block:: none +.. cfgcmd:: set interfaces bonding <interface> ipv6 address eui64 <prefix> - vyos@vyos# set interfaces bonding bond0 mode - Possible completions: - 802.3ad IEEE 802.3ad Dynamic link aggregation (Default) - active-backup - Fault tolerant: only one slave in the bond is active - broadcast Fault tolerant: transmits everything on all slave interfaces - round-robin Load balance: transmit packets in sequential order - transmit-load-balance - Load balance: adapts based on transmit load and speed - adaptive-load-balance - Load balance: adapts based on transmit and receive plus ARP - xor-hash Load balance: distribute based on MAC address - -Now bond some physical interfaces into bond0: + :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in + :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address. -.. code-block:: none + .. code-block:: none + + set interfaces bonding bond0 ipv6 address eui64 2001:db8:beef::/64 + + +Link Administration +------------------- + +.. cfgcmd:: set interfaces bonding <interface> description <description> + + Assign given `<description>` to interface. Description will also be passed + to SNMP monitoring systems. + + +.. cfgcmd:: set interfaces bonding <interface> disable + + Disable given `<interface>`. It will be placed in administratively down + (``A/D``) state. + +.. cfgcmd:: set interfaces bonding <interface> mac <mac-address> + + Configure user defined :abbr:`MAC (Media Access Control)` address on given + `<interface>`. + +.. cfgcmd:: set interfaces bonding <interface> mode <mode> + + 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 mis-ordering 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. + +.. cfgcmd:: set interfaces bonding <interface> hash-policy <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. + + * **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: + + .. code-block:: none + + 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) + + 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. + + 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 + + .. code-block:: none + + 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) + + 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. + + 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. + + 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 this 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. + +.. cfgcmd:: set interfaces bonding <interface> primary <interface> + + An `<interface>` 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. + + The primary option is only valid for active-backup, transmit-load-balance, + and adaptive-load-balance mode. + +.. cfgcmd:: set interfaces bonding <interface> arp-monitor interval <time> + + Specifies the ARP link monitoring `<time>` in seconds. + + The ARP monitor works by periodically checking the slave devices to determine + whether they have sent or received traffic recently (the precise criteria + depends upon the bonding mode, and the state of the slave). Regular traffic + is generated via ARP probes issued for the addresses specified by the + :cfgcmd:`arp-monitor target` option. + + If ARP monitoring is used in an etherchannel compatible mode (modes + round-robin and xor-hash), the switch should be configured in a mode that + evenly distributes packets across all links. If the switch is configured to + distribute the packets in an XOR fashion, all replies from the ARP targets + will be received on the same link which could cause the other team members + to fail. + + A value of 0 disables ARP monitoring. The default value is 0. + +.. cfgcmd:: set interfaces bonding <interface> arp-monitor target <address> + + Specifies the IP addresses to use as ARP monitoring peers when + :cfgcmd:`arp-monitor interval` option is > 0. These are the targets of the + ARP request sent to determine the health of the link to the targets. + + Multiple target IP addresses can be specified. At least one IP address must + be given for ARP monitoring to function. + + The maximum number of targets that can be specified is 16. The default value + is no IP addresses. + +Member Interfaces +----------------- - set interfaces bonding bond0 member interface eth0 - set interfaces bonding bond0 member interface eth1 +.. cfgcmd:: set interfaces bridge <interface> member interface <member> -After a commit you may treat bond0 as almost a physical interface (you can't -change its` duplex, for example) and assign IPs or VIFs on it. + Enslave `<member>` interface to bond `<interface>`. -You may check the result: +Operation +######### .. code-block:: none - vyos@vyos# run sh interfaces bonding + vyos@vyos:~$ show interfaces bonding Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down Interface IP Address S/L Description --------- ---------- --- ----------- |