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

4 files changed, 238 insertions, 16 deletions

diff --git a/README.VLANs b/README.VLANs
index 22e6866..f5f9aec 100644
--- a/README.VLANs
+++ b/README.VLANs
@@ -1,20 +1,52 @@
-VLAN support
-============
+VLANs (aka, 802.1q)
+===================
 
-Slackware's rc.inet1 is now VLAN aware, and can be used to bring up interfaces
-bound to specific VLAN IDs.  The interfaces support IPv4 and IPv6 IP addressing,
-and can be configured on top of a bonded interface.
+Features
+--------
+* Simple configuration of VLAN interfaces using standard rc.inet1.conf
+  variables.
+* Utilises the new IFOPTS[x]="" paramter, which allows VLAN interface
+  specific configuration, supporting the use of any option.
+* VLAN interfaces can be built on top of bonds and virtual or physical
+  interfaces.
+
+
+Configuration
+-------------
+Configuring VLAN bound interfaces utilises the standard Slackware networking
+configuration syntax in rc.inet1.conf, with setting up an interface as simple
+as changing the IFNAME[x].
 
 VLAN interfaces can be configured quite simply in rc.inet1.conf, in the standard
 Slackware way of defining an interface.  The key to the configuration is to use
 the correct IFNAME[x]="" setting for the underlying ethernet (or bond) interface
-and the tagged VLAN ID that should be exposed.
+and the tagged VLAN ID that should be exposed.  For example:
+  IFNAME[0]="eth0.10"
+  IFOPTS[0]=""
+  IPADDR[0]="192.168.10.1"
+  NETMASK[0]="24"
+
+The VLAN ID is taken from the full interface name, which is comprised of the
+underlying interface name, a period (.) and then the VLAN ID to expose.
+The above example would use the physical interface 'eth0', and expose the VLAN
+with ID '10'.
+
+It is also possible to use a bond as the underlying interface, which allows
+link aggrigated VLAN interfaces to be created for network redundancy.
+
+The interfaces support IPv4 and IPv6 IP addressing, configured in the Slackware
+way in rc.inet1.conf.
+
+IFOPTS[x] is a pipe (|) delimited list of VLAN kernel module specific settings
+to be applied to the interface.  The ip-link(8) man page contains details of
+exactly what settings can be used with this option (search for "VLAN Type
+Support").  For example:
+  VLANOPTS[x]="protocol 802.1ad | reorder_hdr off"
+
+Under normal circumstances, where a standard VLAN interface is required, no
+options should be supplied.
 
-Here are the basic settings for a VLAN with ID 100 on the eth0 interface,
-configured with a static IPv4 address:
-    IFNAME[0]="eth0.100"
-    IPADDR[0]="192.168.100.10"
-    NETMASK[0]="24"
 
-As you can see, the IFNAME of the interface contains the underlying ethernet
-device name (eth0), a period (.), and the VLAN ID to be exposed.
+--
+Darren 'Tadgy' Austin.
+<darren (at) afterdark.org.uk>
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>
diff --git a/rc.inet1 b/rc.inet1
index 55ac726..60116d0 100644
--- a/rc.inet1
+++ b/rc.inet1
@@ -189,8 +189,8 @@ bond_create() {
   info_log "${IFNAME[$1]}: creating bond"
   debug_log "/sbin/ip link add name ${IFNAME[$1]} type bond"
   /sbin/ip link add name ${IFNAME[$1]} type bond
-  debug_log "/sbin/ip link set dev ${IFNAME[$1]} type bond mode ${BONDMODE[$1]}"
-  /sbin/ip link set dev ${IFNAME[$1]} type bond mode ${BONDMODE[$1]}
+  debug_log "/sbin/ip link set dev ${IFNAME[$1]} type bond mode ${BONDMODE[$1]:-balance-rr}"
+  /sbin/ip link set dev ${IFNAME[$1]} type bond mode ${BONDMODE[$1]:-balance-rr}
   for BONDIF in ${BONDNICS[$1]}; do
     debug_log "/sbin/ip address flush dev $BONDIF"
     /sbin/ip address flush dev $BONDIF
diff --git a/rc.inet1.conf b/rc.inet1.conf
index 8ac6c8d..af8a091 100644
--- a/rc.inet1.conf
+++ b/rc.inet1.conf
@@ -69,7 +69,18 @@ GATEWAY6=""
 # =============================================================================
 
 # Example of how to configure a bond (link aggrigation) interface.
-
+# Note the addition of the BONDNICS and BONDMODE parameters.
+# BONDNICS is a 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.
+# BONDMODE sets the bonding mode for this interface.  If not specified when 
+# BONDNICS has been used, the default is 'balance-rr'.
+# The IFOPTS[x] option should always include the 'miimon' option when
+# configuring bonding - 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.
 #IFNAME[0]="bond0"
 #BONDNICS[0]="eth0 eth1"
 #BONDMODE[0]="balance-rr"