bond: rewrite with new cfgcmd/opcmd syntax

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
   ---------        ----------                        ---  -----------