media: tegra: add supporting for RAW8/RAW10 input and output
[linux-2.6.git] / Documentation / networking / bonding.txt
index 8e6b8d3..91df678 100644 (file)
@@ -1,7 +1,7 @@
 
                Linux Ethernet Bonding Driver HOWTO
 
-               Latest update: 12 November 2007
+               Latest update: 27 April 2011
 
 Initial release : Thomas Davis <tadavis at lbl.gov>
 Corrections, HA extensions : 2000/10/03-15 :
@@ -49,6 +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    Configuration with Interfaces Support
+3.6    Overriding Configuration for Special Cases
 
 4. Querying Bonding Configuration
 4.1    Bonding Configuration
@@ -160,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
 =========================
@@ -194,6 +196,60 @@ or, for backwards compatibility, the option value.  E.g.,
 
        The parameters are as follows:
 
+ad_select
+
+       Specifies the 802.3ad aggregation selection logic to use.  The
+       possible values and their effects are:
+
+       stable or 0
+
+               The active aggregator is chosen by largest aggregate
+               bandwidth.
+
+               Reselection of the active aggregator occurs only when all
+               slaves of the active aggregator are down or the active
+               aggregator has no slaves.
+
+               This is the default value.
+
+       bandwidth or 1
+
+               The active aggregator is chosen by largest aggregate
+               bandwidth.  Reselection occurs if:
+
+               - A slave is added to or removed from the bond
+
+               - Any slave's link state changes
+
+               - Any slave's 802.3ad association state changes
+
+               - The bond's administrative state changes to up
+
+       count or 2
+
+               The active aggregator is chosen by the largest number of
+               ports (slaves).  Reselection occurs as described under the
+               "bandwidth" setting, above.
+
+       The bandwidth and count selection policies permit failover of
+       802.3ad aggregations when partial failure of the active aggregator
+       occurs.  This keeps the aggregator with the highest availability
+       (either in bandwidth or in number of ports) active at all times.
+
+       This option was added in bonding version 3.4.0.
+
+all_slaves_active
+
+       Specifies that duplicate frames (received on inactive ports) should be
+       dropped (0) or delivered (1).
+
+       Normally, bonding will drop duplicate frames (received on inactive
+       ports), which is desirable for most users. But there are some times
+       it is nice to allow duplicate frames to be delivered.
+
+       The default value is 0 (drop duplicate frames received on inactive
+       ports).
+
 arp_interval
 
        Specifies the ARP link monitoring frequency in milliseconds.
@@ -324,10 +380,10 @@ 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
-               susecptible to loss of the gratuitous ARP, and an
+               susceptible to loss of the gratuitous ARP, and an
                appropriate updelay setting may be required.
 
        follow or 2
@@ -376,7 +432,8 @@ max_bonds
        Specifies the number of bonding devices to create for this
        instance of the bonding driver.  E.g., if max_bonds is 3, and
        the bonding driver is not already loaded, then bond0, bond1
-       and bond2 will be created.  The default value is 1.
+       and bond2 will be created.  The default value is 1.  Specifying
+       a value of 0 will load bonding, but will not create any devices.
 
 miimon
 
@@ -388,6 +445,23 @@ miimon
        determined.  See the High Availability section for additional
        information.  The default value is 0.
 
+min_links
+
+       Specifies the minimum number of links that must be active before
+       asserting carrier. It is similar to the Cisco EtherChannel min-links
+       feature. This allows setting the minimum number of member ports that
+       must be up (link-up state) before marking the bond device as up
+       (carrier on). This is useful for situations where higher level services
+       such as clustering want to ensure a minimum number of low bandwidth
+       links are active before switchover. This option only affect 802.3ad
+       mode.
+
+       The default value is 0. This will cause carrier to be asserted (for
+       802.3ad mode) whenever there is an active aggregator, regardless of the
+       number of available links in that aggregator. Note that, because an
+       aggregator cannot be active without at least one available link,
+       setting this option to 0 or to 1 has the exact same effect.
+
 mode
 
        Specifies one of the bonding policies. The default is
@@ -539,6 +613,25 @@ mode
                swapped with the new curr_active_slave that was
                chosen.
 
+num_grat_arp
+num_unsol_na
+
+       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.  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 3.0 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
 
        A string (eth0, eth2, etc) specifying which slave is the
@@ -550,6 +643,46 @@ primary
 
        The primary option is only valid for active-backup mode.
 
+primary_reselect
+
+       Specifies the reselection policy for the primary slave.  This
+       affects how the primary slave is chosen to become the active slave
+       when failure of the active slave or recovery of the primary slave
+       occurs.  This option is designed to prevent flip-flopping between
+       the primary slave and other slaves.  Possible values are:
+
+       always or 0 (default)
+
+               The primary slave becomes the active slave whenever it
+               comes back up.
+
+       better or 1
+
+               The primary slave becomes the active slave when it comes
+               back up, if the speed and duplex of the primary slave is
+               better than the speed and duplex of the current active
+               slave.
+
+       failure or 2
+
+               The primary slave becomes the active slave only if the
+               current active slave fails and the primary slave is up.
+
+       The primary_reselect setting is ignored in two cases:
+
+               If no slaves are active, the first slave to recover is
+               made the active slave.
+
+               When initially enslaved, the primary slave is always made
+               the active slave.
+
+       Changing the primary_reselect policy via sysfs will cause an
+       immediate selection of the best active slave according to the new
+       policy.  This may or may not result in a change of the active
+       slave, depending upon the circumstances.
+
+       This option was added for bonding version 3.6.0.
+
 updelay
 
        Specifies the time, in milliseconds, to wait before enabling a
@@ -619,7 +752,7 @@ xmit_hash_policy
                in environments where a layer3 gateway device is
                required to reach most destinations.
 
-               This algorithm is 802.3ad complient.
+               This algorithm is 802.3ad compliant.
 
        layer3+4
 
@@ -660,28 +793,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
 
@@ -910,17 +1064,19 @@ USERCTL=no
 NETMASK, NETWORK and BROADCAST) to match your network configuration.
 
        For later versions of initscripts, such as that found with Fedora
-7 and Red Hat Enterprise Linux version 5 (or later), it is possible, and,
-indeed, preferable, to specify the bonding options in the ifcfg-bond0
+7 (or later) and Red Hat Enterprise Linux version 5 (or later), it is possible,
+and, indeed, preferable, to specify the bonding options in the ifcfg-bond0
 file, e.g. a line of the format:
 
-BONDING_OPTS="mode=active-backup arp_interval=60 arp_ip_target=+192.168.1.254"
+BONDING_OPTS="mode=active-backup arp_interval=60 arp_ip_target=192.168.1.254"
 
        will configure the bond with the specified options.  The options
 specified in BONDING_OPTS are identical to the bonding module parameters
-except for the arp_ip_target field.  Each target should be included as a
-separate option and should be preceded by a '+' to indicate it should be
-added to the list of queried targets, e.g.,
+except for the arp_ip_target field when using versions of initscripts older
+than and 8.57 (Fedora 8) and 8.45.19 (Red Hat Enterprise Linux 5.2).  When
+using older versions each target should be included as a separate option and
+should be preceded by a '+' to indicate it should be added to the list of
+queried targets, e.g.,
 
        arp_ip_target=+192.168.1.1 arp_ip_target=+192.168.1.2
 
@@ -928,7 +1084,7 @@ added to the list of queried targets, e.g.,
 options via BONDING_OPTS, it is not necessary to edit /etc/modules.conf or
 /etc/modprobe.conf.
 
-       For older versions of initscripts that do not support
+       For even older versions of initscripts that do not support
 BONDING_OPTS, it is necessary to edit /etc/modules.conf (or
 /etc/modprobe.conf, depending upon your distro) to load the bonding module
 with your desired options when the bond0 interface is brought up.  The
@@ -1176,7 +1332,7 @@ monitoring is enabled, and vice-versa.
 To add ARP targets:
 # echo +192.168.0.100 > /sys/class/net/bond0/bonding/arp_ip_target
 # echo +192.168.0.101 > /sys/class/net/bond0/bonding/arp_ip_target
-       NOTE:  up to 10 target addresses may be specified.
+       NOTE:  up to 16 target addresses may be specified.
 
 To remove an ARP target:
 # echo -192.168.0.100 > /sys/class/net/bond0/bonding/arp_ip_target
@@ -1212,8 +1368,141 @@ 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 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
+----------------------
 
-4. Querying Bonding Configuration 
+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
+the selected bonding mode.  On occasion however, it is helpful to direct certain
+classes of traffic to certain physical interfaces on output to implement
+slightly more complex policies.  For example, to reach a web server over a
+bonded interface in which eth0 connects to a private network, while eth1
+connects via a public network, it may be desirous to bias the bond to send said
+traffic over eth0 first, using eth1 only as a fall back, while all other traffic
+can safely be sent over either interface.  Such configurations may be achieved
+using the traffic control utilities inherent in linux.
+
+By default the bonding driver is multiqueue aware and 16 queues are created
+when the driver initializes (see Documentation/networking/multiqueue.txt
+for details).  If more or less queues are desired the module parameter
+tx_queues can be used to change this value.  There is no sysfs parameter
+available as the allocation is done at module init time.
+
+The output of the file /proc/net/bonding/bondX has changed so the output Queue
+ID is now printed for each slave:
+
+Bonding Mode: fault-tolerance (active-backup)
+Primary Slave: None
+Currently Active Slave: eth0
+MII Status: up
+MII Polling Interval (ms): 0
+Up Delay (ms): 0
+Down Delay (ms): 0
+
+Slave Interface: eth0
+MII Status: up
+Link Failure Count: 0
+Permanent HW addr: 00:1a:a0:12:8f:cb
+Slave queue ID: 0
+
+Slave Interface: eth1
+MII Status: up
+Link Failure Count: 0
+Permanent HW addr: 00:1a:a0:12:8f:cc
+Slave queue ID: 2
+
+The queue_id for a slave can be set using the command:
+
+# echo "eth1:2" > /sys/class/net/bond0/bonding/queue_id
+
+Any interface that needs a queue_id set should set it with multiple calls
+like the one above until proper priorities are set for all interfaces.  On
+distributions that allow configuration via initscripts, multiple 'queue_id'
+arguments can be added to BONDING_OPTS to set all needed slave queues.
+
+These queue id's can be used in conjunction with the tc utility to configure
+a multiqueue qdisc and filters to bias certain traffic to transmit on certain
+slave devices.  For instance, say we wanted, in the above configuration to
+force all traffic bound to 192.168.1.100 to use eth1 in the bond as its output
+device. The following commands would accomplish this:
+
+# tc qdisc add dev bond0 handle 1 root multiq
+
+# tc filter add dev bond0 protocol ip parent 1: prio 1 u32 match ip dst \
+       192.168.1.100 action skbedit queue_mapping 2
+
+These commands tell the kernel to attach a multiqueue queue discipline to the
+bond0 interface and filter traffic enqueued to it, such that packets with a dst
+ip of 192.168.1.100 have their output queue mapping value overwritten to 2.
+This value is then passed into the driver, causing the normal output path
+selection policy to be overridden, selecting instead qid 2, which maps to eth1.
+
+Note that qid values begin at 1.  Qid 0 is reserved to initiate to the driver
+that normal output policy selection should take place.  One benefit to simply
+leaving the qid for a slave to 0 is the multiqueue awareness in the bonding
+driver that is now present.  This awareness allows tc filters to be placed on
+slave devices as well as bond devices and the bonding driver will simply act as
+a pass-through for selecting output queues on the slave device rather than 
+output port selection.
+
+This feature first appeared in bonding driver version 3.7.0 and support for
+output slave selection was limited to round-robin and active-backup modes.
+
+4 Querying Bonding Configuration
 =================================
 
 4.1 Bonding Configuration
@@ -1728,7 +2017,7 @@ target to query.
 generally referred to as "trunk failover."  This is a feature of the
 switch that causes the link state of a particular switch port to be set
 down (or up) when the state of another switch port goes down (or up).
-It's purpose is to propogate link failures from logically "exterior" ports
+Its purpose is to propagate link failures from logically "exterior" ports
 to the logically "interior" ports that bonding is able to monitor via
 miimon.  Availability and configuration for trunk failover varies by
 switch, but this can be a viable alternative to the ARP monitor when using
@@ -2305,18 +2594,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:
+       The latest version of this document can be found in the latest kernel
+source (named Documentation/networking/bonding.txt).
 
-http://www.sourceforge.net/projects/bonding
-
-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
 
@@ -2325,8 +2611,19 @@ 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://www.scyld.com/network/
+ - http://web.archive.org/web/*/http://www.scyld.com/network/ 
 
 You will also find a lot of information regarding Ethernet, NWay, MII,
 etc. at www.scyld.com.