Translation(s): English - italiano


Bonding

This article will show how to "bond" two Ethernet connections together to create an auto failover interface.

Installation

First install the ifenslave package, necessary to enable bonding:

# apt-get install ifenslave

Shutdown / Unconfigure Existing Interfaces

# ifdown eth0 (Repeat for all interfaces included in the bond)
# /etc/init.d/networking stop

{i} Sometimes, ifdown doesn't work, in that case use ifconfig eth0 down.

Configuration - Example 1

Modify the /etc/network/interfaces file:

auto bond0

iface bond0 inet static
    address 10.31.1.5
    netmask 255.255.255.0
    network 10.31.1.0
    gateway 10.31.1.254
    slaves eth0 eth1
    bond-mode active-backup
    bond-miimon 100
    bond-downdelay 200
    bond-updelay 200

For more detail, see /usr/share/doc/ifenslave/README.Debian and /usr/src/linux/Documentation/networking/bonding.txt.

Configuration - Example 2 ("Laptop-Mode")

Tie cable and wireless network interfaces (RJ45/WLAN) together to define a single, virtual (i.e. bonding) network interface (e.g. bond0).

As long as the network cable is connected, its interface (e.g. eth0) is used for the network traffic. If you pull the RJ45-plug, ifenslave switches over to the wireless interface (e.g. wlan0) transparently, without any loss of network packages.

After reconnecting the network cable, ifenslave switches back to eth0 ("failover mode").

From the outside (=network) view it doesn't matter which interface is active. The bonding device presents its own software-defined (i.e. virtual) MAC address, different from the hardware defined MACs of eth0 or wlan0.

The dhcp server will use this MAC to assign an ip address to the bond0 device. So the computer has one unique ip address under which it can be identified. Without bonding each interface would have its own ip address.

Modify the /etc/network/interfaces file:

# Define slaves   
auto eth0
iface eth0 inet manual
    bond-master bond0
    bond-primary eth0
    bond-mode active-backup
   
auto wlan0
iface wlan0 inet manual
    wpa-conf /etc/network/wpa.conf
    bond-master bond0
    bond-primary eth0
    bond-mode active-backup

# Define master
auto bond0
iface bond0 inet dhcp
    bond-slaves none
    bond-primary eth0
    bond-mode active-backup
    bond-miimon 100

Note: The configuration above has been found working on Debian 6 and 7.1. It is somewhat contrary to the documentation of interfaces, ifup and ifenslave and the examples under /usr/share/doc/ifenslave/examples/.

Theoretically only the bond0 interface should have the auto attribute. ifup bond0 will bring up the slaves automatically (as documentation says). This is partially true but obviously the configuration options of the slaves are ignored. E.g. wlan0 is brought up without starting wpa_supplicant and the bond-primary setting of eth0 is ignored. (TODO: Is this a bug in ifenslave?)

It seems the slaves must be brought up before bond0 to include their configuration options. To do so via the /etc/init.d/networking script, their definitions must be before the bond0 definition and the auto attributes have to be set.

Of course, they must not be started again when bond0 starts. The option bond-slaves none disables this.

The options bond-master, bond-primary and bond-mode have to be repeated consistently for each slave.

There will be warnings "ifup: interface xyz already configured", but at least it works.

Tip

In order to get some insight what is happening behind the scenes while experimenting a small script to show some information about the bonding device may be helpful.

#! /bin/sh

echo "Slaves = $(cat /sys/class/net/bond0/bonding/slaves)"
echo "Primary = $(cat /sys/class/net/bond0/bonding/primary)"
echo "Active Slave = $(cat /sys/class/net/bond0/bonding/active_slave)"

r=$(pidof dhclient)
test -n "$r" && ps $r

r=$(pidof wpa_supplicant)
test -n "$r" && ps $r

Debugging ifenslave

The bonding mechanism is based on a kernel module named bonding which exposes its interface via the virtual /sys filesystem (e.g. /sys/class/net/bond0/*).

Setup and configuration is done in userland with shell-scripts:

These scripts are called on system initialization and shutdown (actually it is ifup which calls them). Their intention is to feed the kernel module with the appropriate parameters and settings.

If something with bonding fails at all (and the tip above doesn't help) you may have a look what the scripts do step by step.

To enable verbose output, invoke ifup -a -v directly (instead of invoking /etc/init.d/networking). The -v option enables a log of all commands the scripts are executing. This gives at least a trace what is happening when.

Unfortunately this will not show the reactions of the kernel module (like possible error messages), because kernel (module) messages are reported via the syslog utility.

To get a real insight what is going on you have to do what is called invasive debugging. This means to add lines to the scripts at critical points to send a message to syslog.

Example:

Function sysfs_change_down in file /etc/network/if-pre-up.d/ifenslave

        logger -t sysfs_change_down sysfs "$1" "$2"
                sysfs "$1" "$2"
        logger -t sysfs_change_down $(cat /sys/class/net/bond0/bonding/mode)

Additional Note For Debian Lenny On Sparc

(may be applicable on other architectures as well)

# cd /etc/modprobe.d

# cat > aliases-bond.conf
alias bond0 bonding
  options bonding mode=1 arp_interval=2000 arp_ip_target=192.168.3.1
<CTRL-D>

Without this file, you will get a warning when starting up the bonded interface similar to this:

bonding: Warning: either miimon or arp_interval and arp_ip_target module parameters must be specified, otherwise bonding will not detect link failures! see bonding.txt for details.

Startup / Configure New Interfaces

# ifup bond0
# /etc/init.d/networking start

And more, if you use a Lenny environment which has been upgraded from Etch, it is strongly recommended to check the result of the following command to check the bonding device mode, because configuration files for Etch and older versions do not work for Lenny and later releases.

cat /sys/class/net/bond0/bonding/mode

Testing

1. Ping to other system in a terminal

# ping X.X.X.X

2. Disconnect the active network cable and watch the ping result, the network should be resumed in few seconds

3. Reconnect the disconnected network cable, wait for 30 seconds to let the ARP table being updated

4. Disconnect another network cable and watch the ping result, the network should be resumed in few seconds

Change active slave

1. Use ifenslave to change the active slave. Below example will set eth0 as active slave

# ifenslave -c bond0 eth0 eth1

Using systemd-networkd

This method does not use the package ifenslave which is mentioned above. If your computer is using systemd, and your network cards are currently working, you don't need anything else.

Note that as is common on unix-type operating systems, case matters - "Bond" is different from "bond" and "Name" is not the same as "name".

Enabling systemd-networkd

If you are not currently using systemd-networkd, you need to enable it.

systemctl enable systemd-networkd

Configuring the bond device

Create a file ending in .netdev in /etc/systemd/network. Name this after the bonded interface name you want to use (e.g. bond0.netdev).

This example assumes 802.3ad or LACP bonding, for more information see the systemd.netdev manpage and/or the kernel documentation.

Most systems should work with 802.3ad and this is probably the mode you want as it has both network cards working together to give you double the throughput. However, if it doesn't work in your case, you can try another mode, such as active-backup (used in the ifenslave example above).

[NetDev]
Name=bond0
Description=LAG/Bond to a switch
Kind=bond

[Bond]
Mode=802.3ad

Add interfaces to the bond/lag

There are two ways you can do this. One is to create a .network file for each network interface plus one for the bonded network. The other is to describe the network interfaces in the bonded network's file. Here we'll use the latter method.

Create a file ending in .network in /etc/systemd/network using the same name as previously (e.g. bond0.network).

systemd-networkd uses a matching system to decide which interface to use. You could use name-based matching here if you like, but do not use mac-based matching as this could cause confusion with the bond changing mac addresses.

This example uses pci-id based matching. To find the addresses for your network cards, use:

lspci -d | grep Ether

then use that information to create the .network file.

[Match]
Path=pci-0000:00:01.0
Path=pci-0000:05:10.0

[Network]
Bond=bond0

Another option is to simply use the names of the network interfaces by replacing the Path= line with Name=<network interface name>. You can also use wildcards, and you can specify both/all devices in a single file:

[Match]
Name=enp*

[Network]
Bond=bond0

or

[Match]
Name=enp0s01
Name=enp5s10

[Network]
Bond=bond0

Giving the bond an IP

Create a file ending in .network in /etc/systemd/network. The name (obviously) should not already be used. This tell systemd how to bring up the bonded network. For a static IP address, you could use:

[Match]
Name=bond0

[Network]
Address=10.31.1.5
Gateway=10.31.1.1
DNS=10.31.1.1

For DHCP (e.g. for a laptop where you could use wireless and/or wired connections) try:

[Match]
Name=bond0

[Network]
DHCP=yes

Actualise the settings

If your network was using /etc/network/interfaces before setting up the bonding, rename the file to stop it from being used:

mv /etc/network/interfaces /etc/network/interfaces.save

At this point I recommend rebooting the system. This is the easiest way to clear out any previous network configurations and it tests that systemd-networkd starts as expected. The network should come up with bonding active. You can verify this with:

ip address

You should see 4 devices, lo, your two physical network interfaces (marked as "SLAVE"), and the bond0 device. Only the bond0 device should have an ip address. It should also be marked as "MASTER".

If you need to make further changes later, or fix problems with your current setup, from now on you can simply restart systemd-networkd after updating the /etc/systemd/network files.

systemctl restart systemd-networkd

udev renaming issue

You will likely only see UDEV rules for your network devices if you have upgraded from previous versions of Debian. New installations name the network cards after their pci addresses. The rules are used to preserve the legacy names for devices (e.g. eth0) in case they are being used elsewhere.

If you are confident that you are not using the legacy names, you can simply remove the file described below.

"udev" assign network adapter names as per

/etc/udev/rules.d/70-persistent-net.rules

where rule typically looks like this:

# PCI device 0x10ec:0x8168 (r8169)
SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="xx:xx:xx:xx:xx:xx", ATTR{dev_id}=="0x0", ATTR{type}=="1", KERNEL=="eth*", NAME="eth0"

The problem with bonding is that two or more NICs may have the very same MAC address which confuses udev when it tries to (re)name adapters as per their MACs and fails because another card with this MAC already exists. When it happens NIC may be left named like "rename2" instead of "eth0" etc.

Possible solution is to change udev rule to assign network interface names as per NICs PCI IDs instead of MAC addresses. This can be done by replacing

ATTR{address}=="xx:xx:xx:xx:xx:xx"

with something like

KERNELS=="0000:04:00.0"

in the file "70-persistent-net.rules".

Corresponding PCI IDs can be found in dmesg:

sudo dmesg | grep eth

Where one can look for line fragment like this:

r8169 0000:04:00.0 eth0: RTL8168e/8111e
#     ^^^^^^^^^^^^

But this is not recommended as it will not find, for example, wireless devices or devices not using legacy names.

The preferred alternative is to find PCI IDs using "lspci -D | grep Ether":

0000:04:00.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8111/8168/8411 PCI Express Gigabit Ethernet Controller (rev 06)

Note that on modern systems, you can translate the PCI address to the network name by using the two middle numbers expressed in base10. In the above example, the controller 0000:04:00.0 would be enp4s00.


CategoryNetwork CategoryNetwork