Update documentation. Default BONDMODE to balance-rr. Update rc.inet1.conf.

1 files changed, 179 insertions, 0 deletions

diff --git a/README.bonding b/README.bonding
new file mode 100644
index 0000000..e81b7c9
--- /dev/null
+++ b/README.bonding
@@ -0,0 +1,179 @@
+Bonding (link aggrigation)
+==========================
+
+Features
+--------
+* Full support of features offered by the bonding kernel module.
+* Selectable bonding mode using a single parameter in rc.inet1.conf.
+* Easy addition of interfaces to the bond using a parameter in rc.inet1.conf.
+* Custom bonding module options can be proided using the generic parameter
+  IFOPTS[x] in the configuration file.
+
+  
+Implementation
+--------------
+[This section can be removed from the final README.bonding as it relates to
+ implimentation by Pat rather than user level configuration]
+
+Pat should add a /lib/modprobe.d/bonding.conf (preferred) or
+/etc/modprobe.d/bonding.conf file to a package (probably network-scripts), with
+content:
+    options bonding max_bonds=0
+    options rtnl-link-bond max_bonds=0
+in order to disable the automatic creation of a bond0 interface when the kernel
+module is loaded.
+
+Rationale: Even though the bond0 interface may be scheduled for creation
+because it's configured in rc.inet1.conf, having the interface in an up state
+before configuration will prevent it from being configured due to rc.inet1's
+checking of interface state before going through the process of setting up the
+interface.
+
+This check is necessary in rc.inet1 because rc.inet1 has no way of knowing
+whether the interface has been brought up by itself or by some other means -
+there is no state information stored by rc.inet1, which prevents it from
+knowing.  It is also not possible to rely on the interface being configured
+with an IP address to determine if it has been configured or not - a bond
+interface may be used as part of a bridge, and would thus not have an IP
+configured to validate against.
+
+Effects: Previous versions of Slackware followed the default behaviour when
+loading the bonding module, and would automatically create a bond0 interface
+for the user to configure.  This behaviour would now change to prevent a bond0
+interface being created at load time in order for rc.inet1 to be able to
+configure a user defined bond0 interface in rc.inet1.conf at a later time.
+
+Since Slackware has never had support for bond interfaces in previous versions,
+the automatic creation of a bond interface has never been a defined behaviour -
+users should not have relied on that behaviour.
+
+Effects if not used: In its present form, rc.inet1 checks whether an interface
+is up before it tries to configure it based on the interfaces present in
+rc.inet1.conf - rc.inet1 will not try to reconfigure an interface which is up
+and running, instead issuing an debug message that the interface is already up
+when being run with any of the 'start' options.
+
+Without the inclusing of the bonding.conf options file, rc.inet1 would be
+unable to work with a bond0 interface in it's present form.  It is also highly
+unlikely that rc.inet1 could be coded to *not* check whether an interface is up
+before trying to configure it - this check is fundamental to the way it works.
+
+ 
+Configuration
+-------------
+Bonding interfaces can be configured via two new bond specific parameters in
+rc.inet1.conf, plus use of the generic IFOPTS[x] parameter.  New parameters
+are:
+  BONDNICS[x]=""	The space delimited list of interfaces to add to this
+			bond.  The interfaces will be brought up and configured
+			while bringing up the interface, so do not need to be
+			previously defined in rc.inet1.conf.  A bond can be
+			created with only 1 interface, but does not become
+			useful until at least 2 interfaces are configured.
+
+  BONDMODE[x]=""	This parameter sets the bonding mode for this
+			interface.  If not specified when BONDNICS[x] has been
+			used, the default is 'balance-rr'.  See below for a
+			list of all bonding modes available.
+
+The following bond modes are available:
+  balance-rr		This mode is also known as round-robin mode.  Packets
+			are sequentially transmitted and received through each
+			interface one by one.  This mode provides load 
+			balancing functionality along with fault tolerance.
+  active-backup		When in this mode only one interface set to active,
+			while all other interfaces are in the backup state.  If
+			the active interface fails, a backup interface replaces 
+			it as the only active interface in the bond.  This mode
+			only provides fault tolerance, no load balancing.
+			This mode requires that the 'primary <interface>'
+			option be configured with the IFOPTS[x] parameter.
+  balance-xor		The source MAC address uses exclusive or (XOR) logic 
+			with the destination MAC address.  This	calculation 
+			ensures that the same slave interface is selected for 
+			each destination MAC address.  This mode provides fault
+			tolerance and load balancing.
+  broadcast		All packets are sent to all the slaved interfaces. This
+			mode provides fault tolerance, but may result in
+			duplicate packets arriving at the destination.
+  802.3ad		Also known as LACP.  This mode creates aggregation
+			groups that share the same speed and duplex settings, 
+			and it requires a switch that supports an IEEE 802.3ad.
+			This mode uses all interfaces to form the aggregation
+			group and provides fault tolerance and load balancing.
+  balance-tlb		This mode ensures that the outgoing traffic 
+			distribution is set according to the load on each
+			interface and that the current interface receives all
+			the incoming traffic.  If the assigned interface fails
+			to receive traffic, another interface is assigned to
+			the receiving role.  This provides fault tolerance and
+			load balancing.
+  balance-alb		The receiving packets are load balanced through Address
+			Resolution Protocol (ARP) negotiation.  This mode
+			provides fault tolerance and load balancing.
+
+Module specific interface options can be set using the the IFOPTS[x] paramter,
+which takes a pipe (|) delimited list of options for the interface.  The
+following are the most useful options which can be set with IFOPTS[x]:
+  miimon	Specifies the MII link monitoring frequency in milliseconds.
+		This determines how often the link state of each slaved
+		interface is checked for link failures.  A value of zero
+		disables MII link monitoring, but this is NOT advised.  A value
+		of 100 is a good starting point.  The default value is 0, so be
+		sure to set this option with ALL modes.
+  lacp_rate	This option specifies the rate at which the host will ask the
+		link partner to transmit LACPDU packets in 802.3ad mode.
+		Possible values are:
+		  slow		Transmit LACPDUs every 30 seconds.
+		  fast		Transmit LACPDUs every 1 second.
+		The default is slow, but fast is recommended.
+  primary	The interface (eth0, eth2, ...) selecting which slave is the
+		primary device.  The specified interface will always be the
+		active slave while it is available.  Only when the primary is
+		off-line will alternate interfaces be used.  This is useful
+		when one interface is preferred over another (eg, when one
+		interface has higher throughput than another).  This option
+		is only valid for active-backup, balance-tlb and balance-alb
+		modes.
+  xmit_hash_policy
+		Selects the transmit hash policy to use for interface selection
+		in balance-xor, 802.3ad, and balance-tlb modes.  Possible 
+		values are:
+		  layer2	Use XOR of source/dest hardware MAC addresses
+				and packet type ID fields to generate the hash.
+				This algorithm will place all traffic to a 
+				particular network peer on the same slave.
+		  layer2+3	Use a combination of layer2 and layer3 protocol
+				information (hardware MAC addresses and IP
+				addresses) to generate the hash.
+				This algorithm will place all traffic to a
+				particular network peer on the same slave.
+				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.
+		  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 slave interfaces,
+				although a single connection will not span 
+				multiple slaves.
+		The default value is layer2.  Additional (lesser used) policies
+		are available, and documented in kernel source documentation:
+		/usr/src/linux/Documentation/networking/bonding.txt
+
+The IFOPTS[x] option should always include the 'miimon' option - not using this
+option will result in network degradation.
+In 'active-backup' mode, the 'primary' option should also be supplied.
+When using '802.3ad mode', set "lacp_rate fast" for faster recovery from an
+interface failure.
+In other modes, the 'xmit_hash_policy' should be set.
+
+Full documentation of the bonding layer is available in the kernel source
+documentation: /usr/src/linux/Documentation/networking/bonding.txt.
+
+
+--
+Darren 'Tadgy' Austin.
+<darren (at) afterdark.org.uk>