man: add supported bonding options

Co-authored-by: Marius Tomaschewski <mt@suse.com>

man/ifcfg-bonding.5.in

@@ -1,99 +1,321 @@
 .\" Automatically generated by Pandoc 3.1.11.1
 .\"
-.TH "IFCFG\-BONDING" "5" "May 6, 2024" "Wicked User Manual" ""
+.TH "IFCFG\-BONDING" "5" "May 30, 2024" "wicked" "Wicked User Manual"
 .SH NAME
 ifcfg\-bonding \- Bonding interface configuration
 .SH SYNOPSIS
 \f[CR]/etc/sysconfig/network/ifcfg\-*\f[R]
 .SH Bonding Interfaces
-To setup a bonding interface you need a configuration file ifcfg\-bond
-with the usual network settings.
-But you must add additional variables
+To setup a bonding interface you need an configuration file ifcfg\- with
+the following bond specific variables:
 .TP
 \f[CR]BONDING_MASTER\f[R]
-Must be set to `yes' to identify this interface as a bonding interface.
+Must be set to `yes' to identify the configuration as for a bonding
+interface.
 .TP
 \f[CR]BONDING_SLAVE_<X>\f[R]
-Here you specify the interface name representing the slave network
+Here you specify the interface name representing the port network
 interfaces.
-Note also: Bonding slave interfaces are reserved for the bonding and are
-not usable for any another purposes (unlike e.g.\ interfaces used for
-VLANs) and the bonding master manages the slaves itself, e.g.\ it sets
-the MAC address on the slaves by default.
-To configure this accordingly, set BOOTPROTO=none in the ifcfg file of
-each slave interfaces to avoid any IP or link\-layer setup on these
-interfaces.
-Wicked will apply the link settings (e.g.\ for fail_over_mode=active) at
-enslave time.
+Supported are Ethernet \f[B]or\f[R] Infiniband(\-Child) interfaces.
+.RS
+.PP
+The Bonding master takes over the control of these port interfaces,
+which are not usable for another purposes, especially not for an L3 (IP)
+setup.
+It propagates several settings to the ports, e.g.\ it sets the MAC
+address (not on Infiniband) and MTU.
+Also if there is a vlan on top of the bond, it offloads the vlan setup
+to the ports.
+.PP
+Without a dedicated \f[CR]ifcfg\-<port>\f[R] configuration file, the
+auto generated port configuration is:
+.IP
+.EX
+ STARTMODE=hotplug
+ BOOTPROTO=none
+.EE
+.PP
+The use of \f[CR]STARTMODE=hotplug\f[R] for the ports ensures, that
+wicked does not wait for the ports while setup, but only for the bonding
+master, which calculates it\[cq]s own carrier state from the carrier on
+the ports using own (configurable) logic and signals it\[cq]s carrier
+when a sufficient number of ports is available (default: min_links=1).
+.PP
+\f[B]Note\f[R]: It\[cq]s strongly recommended to change the udev rule to
+match the ports by Bus\-ID (\f[CR]KERNELS==\[dq]\&...\[dq]\f[R]) in
+order to assign a persistent name via
+\f[CR]/etc/udev/rules.d/70\-persistent\-net.rules\f[R] (can be done in
+YaST2) as the bonding master usually sets the same MAC address on all
+it\[cq]s ports.
+.PP
+The use of \f[CR]BOOTPROTO=none\f[R] disables IPv6 on the port
+interfaces via sysctl (and IPv4 in wicked) to ensures that no L3 / IP
+setup (from \f[CR]ifcfg\-<port>\f[R] config) is applied to the ports.
+.RE
 .TP
 \f[CR]BONDING_MODULE_OPTS\f[R]
-Contains bonding options.
-Here you can set interface timeouts or working modes
-(`mode=active\-backup' for backup mode).
-For additional information take a look into the documentation mentioned
-at the bottom.
+Contains bonding options to configure the aggregation mode, port link
+monitoring and another options.
+.RS
+.PP
 Note, that this options are not passed as parameters to the bonding
-kernel module any more, but set via sysfs interface.
-This variable will be renamed in the feature.
+kernel module any more, but configured by wicked via the
+\f[CR]rtnetlink\f[R] interface.
+.PP
+Bonding of Infiniband(\-Child) port interfaces requires
+\f[CR]mode=active\-backup\f[R] mode along with the
+\f[CR]fail_over_mac=active\f[R] option.
+.PP
+The following options are currently implemented in wicked.
+.IP \[bu] 2
+Link aggregation operation mode:
+.RS 2
+.IP \[bu] 2
+\f[B]mode\f[R]=[\f[CR]balance\-rr\f[R](0) | \f[CR]active\-backup\f[R](1)
+| \f[CR]balance\-xor\f[R](2) | \f[CR]broadcast\f[R](3) |
+\f[CR]802.3ad\f[R](4) | \f[CR]balance\-tlb\f[R](5) |
+\f[CR]balance\-alb\f[R](6)]
+.RS 2
+.PP
+The \f[CR]active\-backup\f[R], \f[CR]balance\-tlb\f[R] and
+\f[CR]balance\-alb\f[R] modes do not require any special switch support.
+The \f[CR]802.3ad\f[R] mode requires dynamic (lacp) and the
+\f[CR]balance\-xor\f[R], \f[CR]balance\-rr\f[R], \f[CR]broadcast\f[R] a
+static link aggregation group/LAG switch configuration.
+.RE
+.RE
+.IP \[bu] 2
+Port monitoring:
+.RS 2
+.PP
+It is critical to configure link monitoring by specifying either the
+\f[B]miimon\f[R] or the \f[B]arp_interval\f[R] and
+\f[B]arp_ip_target\f[R] options.
+ARP monitoring should not be used in conjunction with miimon.
+Otherwise serious network degradation will occur during link failures
+and wicked rejects such configuration as insufficient and unsupported.
+.IP \[bu] 2
+Netif Carrier/MII link monitoring (\f[I]all modes\f[R]):
+.RS 2
+.IP \[bu] 2
+\f[B]miimon\f[R]=[msec]: enables the monitoring using specified interval
+.PD 0
+.P
+.PD
+.RS 2
+.IP \[bu] 2
+\f[B]use_carrier\f[R]=[\f[B]1\f[R]|0]: 0 reverts from netif\-carrier to
+MII/ethtool
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]updelay\f[R]=[msec]: link\-up detection delay
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]downdelay\f[R]=[msec]: link\-down detection delay
+.RE
+.RE
+.IP \[bu] 2
+ARP link monitoring (\f[I]active\-backup\f[R], \f[I]balance\-rr\f[R],
+\f[I]balance\-xor\f[R], \f[I]broadcast\f[R]):
+.RS 2
+.IP \[bu] 2
+\f[B]arp_interval\f[R]=[msec]: enables the monitoring using specified
+interval
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]arp_ip_target\f[R]=[x.x.x.x[,\&...]]: comma\-separated IPv4 address
+to monitor
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]arp_validate\f[R]=[\f[B]\f[CB]none\f[B]\f[R] | \f[CR]active\f[R] |
+\f[CR]backup\f[R] | \f[CR]all\f[R] | \f[CR]filter\f[R] |
+\f[CR]filter_active\f[R] | \f[CR]filter_backup\f[R]]: reply validation
+and filtering (\f[I]active\-backup\f[R])
+.PD 0
+.P
+.PD
+.RS 2
+.IP \[bu] 2
+\f[B]arp_all_targets\f[R]=[\f[CR]any\f[R] | \f[CR]all\f[R]] link\-up
+consideration (\f[I]active\-backup\f[R])
+.RE
+.RE
+.RE
+.IP \[bu] 2
+Primary port configuration (\f[I]active\-backup\f[R],
+\f[I]balance\-alb\f[R], \f[I]balance\-tlb\f[R]):
+.RS 2
+.IP \[bu] 2
+\f[B]primary\f[R]=[ifname]: interface name of the primary/preferred port
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]primary_reselect\f[R]=[\f[B]\f[CB]always\f[B]\f[R]|\f[CR]better\f[R]|\f[CR]failure\f[R]]:
+primary reselection policy
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]active_slave\f[R]=[ifname]: volatile runtime option enforcing
+active port change
+.RE
+.IP \[bu] 2
+\f[I]active\-backup\f[R] mode specific settings:
+.RS 2
+.IP \[bu] 2
+\f[B]fail_over_mac\f[R]=[\f[B]\f[CB]none\f[B]\f[R] | \f[CR]active\f[R] |
+\f[CR]follow\f[R]]: MAC address on failover
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]num_grat_arp\f[R],\f[B]num_unsol_na\f[R]=[0..255]: peer
+notification count
+.RE
+.IP \[bu] 2
+Transmit balancing settings:
+.RS 2
+.IP \[bu] 2
+\f[B]xmit_hash_policy\f[R]=[\f[B]\f[CB]layer2\f[B]\f[R] |
+\f[CR]layer2+3\f[R] | \f[CR]layer3+4\f[R] | \f[CR]encap2+3\f[R] |
+\f[CR]encap3+4\f[R]]: XOR hash type (\f[I]802.3ad\f[R],
+\f[I]balance\-xor\f[R], \f[I]balance\-tlb\f[R], \f[I]balance\-alb\f[R])
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]tlb_dynamic_lb\f[R]=[\f[CR]0\f[R]|\f[B]\f[CB]1\f[B]\f[R]]: enable
+flow shuffling in favor of hash distribution
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]lp_interval\f[R]=[sec]: learning packets to port peer switch
+sending interval
+.RE
+.IP \[bu] 2
+\f[I]802.3ad\f[R] mode specific settings:
+.RS 2
+.IP \[bu] 2
+\f[B]lacp_rate\f[R]=[\f[B]\f[CB]slow\f[B]\f[R]|fast]: LACPDU packet
+transmission rate
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]ad_select\f[R]=[\f[B]\f[CB]stable\f[B]\f[R] | \f[CR]bandwidth\f[R]
+| \f[CR]count\f[R]]: aggregation selection logic
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]ad_user_port_key\f[R]=[1..1023]: custom port\-key
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]ad_actor_sys_prio\f[R]=[1..65535]: custom system priority
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]ad_actor_system\f[R]=[hwaddr]: actor mac address for LACPDU
+exchanges.
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]min_links\f[R]=[uint]: number of required port links
+.RE
+.IP \[bu] 2
+Other options:
+.RS 2
+.IP \[bu] 2
+\f[B]resend_igmp\f[R]=[0..255]: membership reports after failover,
+default 1 (\f[I]balance\-rr\f[R], \f[I]active\-backup\f[R],
+\f[I]balance\-tlb\f[R] and \f[I]balance\-alb\f[R])
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]packets_per_slave\f[R]=[0..65535]: packets to transmit before move
+(\f[I]balance\-rr\f[R])
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]all_slaves_active\f[R]=[\f[B]\f[CB]0\f[B]\f[R]|\f[CR]1\f[R]]:
+deliver duplicate frames on inactive ports (\f[I]all modes\f[R])
+.RE
+.RE
+.SH Additional Information
+For additional and more general information take a look into the kernel
+documentation at
+.PD 0
+.P
+.PD
+\f[CR]https://www.kernel.org/doc/Documentation/networking/bonding.rst\f[R].
 .SH EXAMPLE
-Example for a bonding interface on eth0 and eth1 using the backup mode
+Example for a bonding configuration on eth0 and eth1 ports using the
+\f[CR]active\-backup\f[R] mode:
 .PP
-\f[I]ifcfg\-bond0\f[R]
+\f[B]ifcfg\-bond0\f[R]
+.PD 0
+.P
+.PD
 .IP
 .EX
-STARTMODE=\[aq]onboot\[aq]
+STARTMODE=\[aq]auto\[aq]
 BOOTPROTO=\[aq]static\[aq]
 IPADDR=\[aq]192.168.0.1/24\[aq]
 BONDING_MASTER=\[aq]yes\[aq]
 BONDING_SLAVE_0=\[aq]eth0\[aq]
 BONDING_SLAVE_1=\[aq]eth1\[aq]
 BONDING_MODULE_OPTS=\[aq]mode=active\-backup miimon=100\[aq]
+#MTU=\[aq]9000\[aq]
+#LLADDR=\[aq]7a:b9:14:00:d6:ed\[aq]
 .EE
 .PP
-\f[I]ifcfg\-eth0\f[R]
+The optional port configurations \f[I]may\f[R] set e.g.\ ethtool
+options:
+.PP
+\f[B]ifcfg\-eth0\f[R]
+.PD 0
+.P
+.PD
 .IP
 .EX
 STARTMODE=\[aq]hotplug\[aq]
 BOOTPROTO=\[aq]none\[aq]
-#ETHTOOL_OPTIONS=\[aq]wol g\[aq]
+ETHTOOL_OPTIONS=\[aq]wol g\[aq]
 .EE
 .PP
-\f[I]ifcfg\-eth1\f[R]
+\f[B]ifcfg\-eth1\f[R]
+.PD 0
+.P
+.PD
 .IP
 .EX
 STARTMODE=\[aq]hotplug\[aq]
 BOOTPROTO=\[aq]none\[aq]
-#ETHTOOL_OPTIONS=\[aq]wol g\[aq]
+ETHTOOL_OPTIONS=\[aq]wol g\[aq]
 .EE
-.PP
-\f[B]Note\f[R], that the slaves are configured with BOOTPROTO=`none',
-what avoids link set UP and IP configuration of the slaves.
-Further also \f[CR]STARTMODE=\[aq]hotplug\[aq]\f[R], allowing that some
-(all) of the slaves are allowed to be missed at boot time.
-The hotplug slaves will be added to the bond as soon as are become
-available (udev BUS based persistent name rule or manual ifup bond0 is
-required).
-Wicked waits for the slaves, but when there is no slave available at
-bonding start time (boot time), the bonding creation will fail and also
-wicked will report an error.
-.SH Additional Information
-For additional and more general information take a look into
-http://www.linuxfoundation.org/collaborate/workgroups/networking/bonding
-or /usr/src/linux/Documentation/networking/bonding.txt.
-Maybe you need to install the kernel sources to get this additional
-documentation.
-.PP
-The configuration of routes for this kind of interface does not differ
-from ordinary interfaces.
-See \f[CR]man routes\f[R] for details.
 .SH COPYRIGHT
 Copyright (C) 2014\-2024 SUSE LLC
 .SH BUGS
-Please report bugs at \c
-.UR http://bugs.opensuse.org
-.UE \c
+Please report bugs at @PACKAGE_BUGREPORT@
 .SH SEE ALSO
 \f[B]\f[CB]routes\f[B]\f[R] (5), \f[B]\f[CB]ifcfg\f[B]\f[R] (5),
 \f[B]\f[CB]wicked\f[B]\f[R] (8)
 .SH AUTHORS
-Wilken Gottwalt \[en] original bonding man page.
+Wilken Gottwalt (original bonding man page); Pawel
+Wieczorkiewicz; Marius Tomaschewski; Clemens Famulla\-Conrad.