Translation(s): English


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
    bond-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 later versions. The last verified version is Debian 9.8 (*). The configuration 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.

(*) With newer Debian versions the names of the network devices (may) have changed, depending on the upgrade path. Installations from scratch now use "predictable network interface names" (https://wiki.debian.org/NetworkConfiguration#Predictable_Network_Interface_Names). To find the names of your interfaces you will want to look here: $ ls /sys/class/net/ 

This document still uses the traditional names.

Configuration - Example 3 ("Laptop mode", mostly as per documentation - Debian 9 "stretch")

This is a way to bring up a laptop mode with automatic failover between wired and wireless, with wired preferred if both are available, based on the documentation. However, the documentation example is not complete and not fully correct. Specificly, the changes to the example (usr/share/doc/ifenslave/examples/ethernet+wifi) are:

So here is the /etc/network/interfaces marvel:

auto bond0
iface bond0 inet static
    bond-slaves wlan0 eth0
    bond-mode active-backup
    bond-primary eth0
    bond-miimon 100
    address <ipv4address>/<maskbits>
    gateway <ipv4address>

allow-bond0 eth0
iface eth0 inet manual

allow-bond0 wlan0
iface wlan0 inet manual
#    bond-give-a-chance 10
    wpa-bridge bond0
    wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf

If you use DHCP or some other service, you need to change the "bond0" stanza accordingly, but the other interfaces must remain "manual", as they aren't supposed to get an IP address.

Configuration - Example 4 - (very complex server setup) with LACP Bonded trunk and VLANs split out of the trunk, different MTU's on the VLANs

Example is Debian 11 with lots of hard-to-derive-from-man-pages syntax. You are NOT going to want this config on a desktop computer, this is likely only going to be used in a datacenter with a properly configured (802.3ad or LACP bonding) upstream network switch Example /etc/network/interfaces file:

#
# LACP bonded mode - and the bond is provisioned as a TRUNK (NOT an ACCESS port)
# Required for bonding:
#aptitude install vlan ifenslave
# echo "8021q" >> /etc/modules
# 
#cat /etc/modprobe.d/bonding.conf 
#alias bond0 bonding
#options bonding mode=4  miimon=100 downdelay=200 updelay=200
#


###### Bonded 10Gig setup - LACP Aggregation #######
## View status in:    /proc/net/bonding


auto bond0
iface bond0 inet manual
        bond-slaves eno1 eno2
# bond-mode 4 = 802.3ad AKA LACP
        bond-mode 4
        bond-miimon 100
        bond-downdelay 200
        bond-updelay 200
        bond-lacp-rate 1
        bond-xmit-hash-policy layer2+3
        up ifconfig bond0 0.0.0.0 up

### trunked interface (configured as an 802.3ad AKA LACP bond on upstream switch)
# split out vlan 123 and vlan 456 from this bond on seperate interfaces

auto bond0.123
iface bond0.123 inet static

        address 10.123.0.3
        netmask 255.255.255.0
        mtu 1500
        gateway 10.123.0.1
        vlan-raw-device bond0
        post-up ifconfig bond0.123 mtu 1500


# note this VLAN has a different MTU value
auto bond0.456
iface bond0.456 inet static

        address 192.168.456.4
        netmask 255.255.255.0
        mtu 9000
        vlan-raw-device bond0
        post-up ifconfig vlan456 mtu 9000
        post-up ifconfig eno1 mtu 9000 && ifconfig eno2 mtu 9000 && ifconfig bond0 mtu 9000 && ifconfig bond0.456 9000

# Note: upstream bond and member interfaces must have MTU9000, then lower level VLANS can use MTU1500 or MTU9000

bridging the bond

If you want to use the bond in a bridge, simply add the bridge lines as per normal to your /etc/network/interfaces file. Change the bond interface to manual and use it as the bridge interface. Here's a sample bridged bond interfaces file:

# onboard network interface
auto enp4s0
iface enp4s0 inet manual
# PCIe nic
auto enp8s0
iface enp8s0 inet manual
# bond inteface
auto bond0
iface bond0 inet manual
        bond-slaves enp4s0 enp8s0
        bond-mode 802.3ad
# bridge interface
auto br0
iface br0 inet static
        address 192.168.1.17
        netmask 255.255.255.0
        network 192.168.1.0
        broadcast 192.168.1.255
        gateway 192.168.1.1
        bridge_ports bond0
        bridge_stp off
        bridge_fd 0
        bridge_maxwait 0

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. bond1.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=bond1
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. bond1.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=bond1

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=bond1

or

[Match]
Name=enp0s01
Name=enp5s10

[Network]
Bond=bond1

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=bond1

[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=bond1

[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 link list

You should see 4 devices, lo, your two physical network interfaces (marked as "SLAVE"), and the bond1 device. Only the bond1 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

enabling bridging for virtual machines

I've added this section because it's not immediately obvious that your existing network bridge configuration probably won't work with systemd-networkd. Prior to setting up my network bond, I was using the bridge utils to create a br0 device using /etc/network/interfaces. Since I've removed that file, I needed a new way to set up the bridge.

Fortunately systemd-networkd is multi-talented and quite adept at handling network bridges. All you need to do is define the bridge and give it the appropriate characteristics.

Like the bond0 device, you need to create a .netdev file to define the device. I created br0.netdev as follows:

[NetDev]
Name=br0
Kind=bridge

Then I link it to the network bond I'd defined earlier using br0.network:

[Match]
Name=bond1

[Network]
Bridge=br0

Finally, I change the management .network file to refer to br0 instead of bond1. Because the previous definitions have made bond1 a slave to br0, this results in the bridge being brought up properly.

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.

Testing / Debugging

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

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


CategoryNetwork CategoryNetwork CategoryNetwork