How to Configure Network Bonding or Teaming in Ubuntu

Table of Contents#

1. Prerequisites
2. Bonding vs. Teaming: Key Differences
3. Understanding Bonding Modes
4. Configuring Network Bonding with Netplan
5. Verifying Your Setup
6. Troubleshooting Common Issues
7. Conclusion
8. References

Prerequisites#

Before you start, ensure you have:

• Ubuntu 20.04 LTS or newer: Netplan is default since Ubuntu 17.10, but 20.04+ is recommended for stable bonding support.
• 2+ Wired NICs: Use ip link show or lshw -class network to list interfaces (e.g., enp0s3, enp0s8).
• Sudo Access: To modify system configurations.
• Basic CLI Knowledge: Comfort with editing files (nano/vim) and running commands.
• Switch Configuration (for LACP): If using 802.3ad (LACP) mode, your switch must support LACP.

Bonding vs. Teaming: Key Differences#

Historically, Linux offered two approaches to link aggregation: bonding (kernel-space) and teaming (user-space via teamd). However, teaming has been deprecated in Red Hat Enterprise Linux 9 and removed in RHEL 10, and Ubuntu's Netplan never supported teaming as a configuration type. Bonding is the recommended and widely supported approach.

Recommendation: Use bonding for all link aggregation setups. It is the standard, well-supported option across all major Linux distributions and works seamlessly with Netplan.

Understanding Bonding Modes#

The bonding driver supports several modes to define how traffic is handled across slave interfaces. Below are the most common:

Bonding Modes#

Configuring Network Bonding with Netplan#

Bonding is managed by the Linux kernel. We’ll use Netplan to configure it (replace enp0s3/enp0s8 with your NICs).

Step 1: Create a Netplan Configuration File#

Netplan files are stored in /etc/netplan/. Create a new file:

sudo nano /etc/netplan/01-bonding-config.yaml

Step 2: Define the Bond Interface#

Paste this YAML (adjust IPs, modes, and interfaces):

network:
  version: 2
  renderer: networkd
  ethernets:
    enp0s3:
      dhcp4: false
    enp0s8:
      dhcp4: false
  bonds:
    bond0:
      interfaces: [enp0s3, enp0s8]
      addresses: [192.168.1.100/24]
      routes:
        - to: default
          via: 192.168.1.1
      nameservers:
        addresses: [8.8.8.8, 1.1.1.1]
      parameters:
        mode: active-backup
        primary: enp0s3
        mii-monitor-interval: 100

Note: The gateway4 key is deprecated in modern Netplan. Use routes with - to: default and via: instead.

Step 3: Apply the Configuration#

Test the config (rolls back if it fails):

sudo netplan try

If successful, apply it permanently:

sudo netplan apply

Step 4: Verify Bond Status#

Check the bond’s state and slaves:

# Show bond0 details (IP, link status)
ip a show bond0
 
# Show bonding statistics (slaves, mode, failover)
cat /proc/net/bonding/bond0

Sample output for active-backup mode:

Bonding Mode: fault-tolerance (active-backup)
Primary Slave: enp0s3 (active)
Slave Interfaces: enp0s3, enp0s8
MII Status: up
MII Polling Interval (ms): 100

A Note on Network Teaming#

Network teaming (via the teamd daemon) was an alternative to bonding that provided a user-space implementation with extensible runners and plugins. However, teaming is now deprecated:

• Red Hat deprecated teaming in RHEL 9 and removed it in RHEL 10.
• Netplan (Ubuntu's network configuration tool) never supported teaming as a device type—the teams: key does not exist in Netplan YAML.
• Bonding covers all common use cases that teaming addressed and is the standard, well-supported approach.

If you are migrating from an older system that used teaming, convert your configuration to bonding using the equivalent modes:

Verifying Your Setup#

Test redundancy and load balancing to ensure your config works.

Redundancy Test (Failover)#

1. Ping a remote server (e.g., 8.8.8.8):

   ping 8.8.8.8

2. Unplug one of the slave NICs (e.g., enp0s3).
3. The ping should not drop—traffic fails over to the standby slave.

Load Balancing Test#

Use iperf3 to test bandwidth across slaves:

1. Install iperf3 on both client (your Ubuntu machine) and server:

   sudo apt install iperf3

2. Run the server (on a remote machine):

   iperf3 -s

3. Run the client with 4 parallel streams (simulates multiple flows):

   iperf3 -c server_ip -P 4

Sample output (load balanced across 2 NICs):

[  5]   0.00-10.00  sec  1.10 GBytes   943 Mbits/sec  0.000 ms  0/80342 (0%)
[  7]   0.00-10.00  sec  1.09 GBytes   935 Mbits/sec  0.000 ms  0/80342 (0%)

Troubleshooting Common Issues#

1. Netplan Syntax Errors#

• Symptom: netplan apply fails with "Error in network definition".
• Fix: Use netplan try to catch errors. Check indentation (YAML uses spaces, not tabs). Validate with:

  yamllint /etc/netplan/01-bonding-config.yaml

2. Slave Interfaces Not Added#

• Symptom: cat /proc/net/bonding/bond0 shows no slaves.
• Fix: Ensure the slave interfaces are listed in the interfaces section of the bond config. Verify interface names with ip link show.

3. LACP Mode Not Working#

• Symptom: Bond is in 802.3ad mode but not aggregating.
• Fix:
  1. Confirm the switch port is configured for LACP (dynamic trunking).
  2. Match the lacp-rate with the switch (use fast for most setups).
  3. Verify aggregation:

     cat /proc/net/bonding/bond0 | grep Aggregator

4. Failover Not Triggering#

• Symptom: Unplugging a slave causes connection loss.
• Fix:
  1. Check link monitoring: Ensure mii-monitor-interval is set (e.g., mii-monitor-interval: 100).
  2. Verify the slave is up: ip link show enp0s3 should show "UP".

Conclusion#

Network bonding is a powerful tool for improving network reliability and performance. Key takeaways:

• Bonding provides both redundancy and load balancing in a single, well-supported framework.
• Use active-backup mode for simple failover, or 802.3ad (LACP) for maximum throughput with switch support.
• Use Netplan for modern, YAML-based configuration.
• Always test redundancy (unplug a NIC) and load balancing (iperf3) after setup.

References#

1. Ubuntu Netplan Documentation: netplan.io
2. Netplan YAML Configuration Reference: Netplan Docs
3. Linux Kernel Bonding Guide: Kernel.org
4. Iperf3 User Guide: iperf.fr
5. Ubuntu Server Network Guide: Ubuntu.com

Let me know if you have questions—happy to help! 🚀