1 files changed, 121 insertions, 39 deletions

diff --git a/Documentation/networking/bonding.txt b/Documentation/networking/bonding.txt
index d2b62b71b617..675612ff41ae 100644
--- a/Documentation/networking/bonding.txt
+++ b/Documentation/networking/bonding.txt
@@ -1,7 +1,7 @@
 
                 Linux Ethernet Bonding Driver HOWTO
 
-                Latest update: 23 September 2009
+                Latest update: 27 April 2011
 
 Initial release : Thomas Davis <tadavis at lbl.gov>
 Corrections, HA extensions : 2000/10/03-15 :
@@ -49,7 +49,8 @@ Table of Contents
 3.3     Configuring Bonding Manually with Ifenslave
 3.3.1           Configuring Multiple Bonds Manually
 3.4     Configuring Bonding Manually via Sysfs
-3.5     Overriding Configuration for Special Cases
+3.5     Configuration with Interfaces Support
+3.6     Overriding Configuration for Special Cases
 
 4. Querying Bonding Configuration
 4.1     Bonding Configuration
@@ -161,8 +162,8 @@ onwards) do not have /usr/include/linux symbolically linked to the
 default kernel source include directory.
 
 SECOND IMPORTANT NOTE:
-        If you plan to configure bonding using sysfs, you do not need
-to use ifenslave.
+        If you plan to configure bonding using sysfs or using the
+/etc/network/interfaces file, you do not need to use ifenslave.
 
 2. Bonding Driver Options
 =========================
@@ -367,7 +368,7 @@ fail_over_mac
                 gratuitous ARP is lost, communication may be
                 disrupted.
 
-                When this policy is used in conjuction with the mii
+                When this policy is used in conjunction with the mii
                 monitor, devices which assert link up prior to being
                 able to actually transmit and receive are particularly
                 susceptible to loss of the gratuitous ARP, and an
@@ -584,25 +585,23 @@ mode
                 chosen.
 
 num_grat_arp
-
-        Specifies the number of gratuitous ARPs to be issued after a
-        failover event.  One gratuitous ARP is issued immediately after
-        the failover, subsequent ARPs are sent at a rate of one per link
-        monitor interval (arp_interval or miimon, whichever is active).
-
-        The valid range is 0 - 255; the default value is 1.  This option
-        affects only the active-backup mode.  This option was added for
-        bonding version 3.3.0.
-
 num_unsol_na
 
-        Specifies the number of unsolicited IPv6 Neighbor Advertisements
-        to be issued after a failover event.  One unsolicited NA is issued
-        immediately after the failover.
+        Specify the number of peer notifications (gratuitous ARPs and
+        unsolicited IPv6 Neighbor Advertisements) to be issued after a
+        failover event.  As soon as the link is up on the new slave
+        (possibly immediately) a peer notification is sent on the
+        bonding device and each VLAN sub-device.  This is repeated at
+        each link monitor interval (arp_interval or miimon, whichever
+        is active) if the number is greater than 1.
 
-        The valid range is 0 - 255; the default value is 1.  This option
-        affects only the active-backup mode.  This option was added for
-        bonding version 3.4.0.
+        The valid range is 0 - 255; the default value is 1.  These options
+        affect only the active-backup mode.  These options were added for
+        bonding versions 3.3.0 and 3.4.0 respectively.
+
+        From Linux 2.6.40 and bonding version 3.7.1, these notifications
+        are generated by the ipv4 and ipv6 code and the numbers of
+        repetitions cannot be set independently.
 
 primary
 
@@ -765,28 +764,49 @@ xmit_hash_policy
         does not exist, and the layer2 policy is the only policy.  The
         layer2+3 value was added for bonding version 3.2.2.
 
+resend_igmp
+
+        Specifies the number of IGMP membership reports to be issued after
+        a failover event. One membership report is issued immediately after
+        the failover, subsequent packets are sent in each 200ms interval.
+
+        The valid range is 0 - 255; the default value is 1. A value of 0
+        prevents the IGMP membership report from being issued in response
+        to the failover event.
+
+        This option is useful for bonding modes balance-rr (0), active-backup
+        (1), balance-tlb (5) and balance-alb (6), in which a failover can
+        switch the IGMP traffic from one slave to another.  Therefore a fresh
+        IGMP report must be issued to cause the switch to forward the incoming
+        IGMP traffic over the newly selected slave.
+
+        This option was added for bonding version 3.7.0.
 
 3. Configuring Bonding Devices
 ==============================
 
         You can configure bonding using either your distro's network
 initialization scripts, or manually using either ifenslave or the
-sysfs interface.  Distros generally use one of two packages for the
-network initialization scripts: initscripts or sysconfig.  Recent
-versions of these packages have support for bonding, while older
+sysfs interface.  Distros generally use one of three packages for the
+network initialization scripts: initscripts, sysconfig or interfaces.
+Recent versions of these packages have support for bonding, while older
 versions do not.
 
         We will first describe the options for configuring bonding for
-distros using versions of initscripts and sysconfig with full or
-partial support for bonding, then provide information on enabling
+distros using versions of initscripts, sysconfig and interfaces with full
+or partial support for bonding, then provide information on enabling
 bonding without support from the network initialization scripts (i.e.,
 older versions of initscripts or sysconfig).
 
-        If you're unsure whether your distro uses sysconfig or
-initscripts, or don't know if it's new enough, have no fear.
+        If you're unsure whether your distro uses sysconfig,
+initscripts or interfaces, or don't know if it's new enough, have no fear.
 Determining this is fairly straightforward.
 
-        First, issue the command:
+        First, look for a file called interfaces in /etc/network directory.
+If this file is present in your system, then your system use interfaces. See
+Configuration with Interfaces Support.
+
+        Else, issue the command:
 
 $ rpm -qf /sbin/ifup
 
@@ -1319,8 +1339,62 @@ echo 2000 > /sys/class/net/bond1/bonding/arp_interval
 echo +eth2 > /sys/class/net/bond1/bonding/slaves
 echo +eth3 > /sys/class/net/bond1/bonding/slaves
 
-3.5 Overriding Configuration for Special Cases
+3.5 Configuration with Interfaces Support
+-----------------------------------------
+
+        This section applies to distros which use /etc/network/interfaces file
+to describe network interface configuration, most notably Debian and it's
+derivatives.
+
+        The ifup and ifdown commands on Debian don't support bonding out of
+the box. The ifenslave-2.6 package should be installed to provide bonding
+support.  Once installed, this package will provide bond-* options to be used
+into /etc/network/interfaces.
+
+        Note that ifenslave-2.6 package will load the bonding module and use
+the ifenslave command when appropriate.
+
+Example Configurations
+----------------------
+
+In /etc/network/interfaces, the following stanza will configure bond0, in
+active-backup mode, with eth0 and eth1 as slaves.
+
+auto bond0
+iface bond0 inet dhcp
+        bond-slaves eth0 eth1
+        bond-mode active-backup
+        bond-miimon 100
+        bond-primary eth0 eth1
+
+If the above configuration doesn't work, you might have a system using
+upstart for system startup. This is most notably true for recent
+Ubuntu versions. The following stanza in /etc/network/interfaces will
+produce the same result on those systems.
+
+auto bond0
+iface bond0 inet dhcp
+        bond-slaves none
+        bond-mode active-backup
+        bond-miimon 100
+
+auto eth0
+iface eth0 inet manual
+        bond-master bond0
+        bond-primary eth0 eth1
+
+auto eth1
+iface eth1 inet manual
+        bond-master bond0
+        bond-primary eth0 eth1
+
+For a full list of bond-* supported options in /etc/network/interfaces and some
+more advanced examples tailored to you particular distros, see the files in
+/usr/share/doc/ifenslave-2.6.
+
+3.6 Overriding Configuration for Special Cases
 ----------------------------------------------
+
 When using the bonding driver, the physical port which transmits a frame is
 typically selected by the bonding driver, and is not relevant to the user or
 system administrator.  The output port is simply selected using the policies of
@@ -2491,18 +2565,15 @@ enslaved.
 16. Resources and Links
 =======================
 
-The latest version of the bonding driver can be found in the latest
+        The latest version of the bonding driver can be found in the latest
 version of the linux kernel, found on http://kernel.org
 
-The latest version of this document can be found in either the latest
-kernel source (named Documentation/networking/bonding.txt), or on the
-bonding sourceforge site:
-
-http://www.sourceforge.net/projects/bonding
+        The latest version of this document can be found in the latest kernel
+source (named Documentation/networking/bonding.txt).
 
-Discussions regarding the bonding driver take place primarily on the
-bonding-devel mailing list, hosted at sourceforge.net.  If you have
-questions or problems, post them to the list.  The list address is:
+        Discussions regarding the usage of the bonding driver take place on the
+bonding-devel mailing list, hosted at sourceforge.net. If you have questions or
+problems, post them to the list.  The list address is:
 
 bonding-devel@lists.sourceforge.net
 
@@ -2511,6 +2582,17 @@ be found at:
 
 https://lists.sourceforge.net/lists/listinfo/bonding-devel
 
+        Discussions regarding the developpement of the bonding driver take place
+on the main Linux network mailing list, hosted at vger.kernel.org. The list
+address is:
+
+netdev@vger.kernel.org
+
+        The administrative interface (to subscribe or unsubscribe) can
+be found at:
+
+http://vger.kernel.org/vger-lists.html#netdev
+
 Donald Becker's Ethernet Drivers and diag programs may be found at :
  - http://web.archive.org/web/*/http://www.scyld.com/network/