Introduction: Why Bond Your Network Interfaces?

If you have upgraded your Raspberry Pi 5 with a 2.5Gbps USB LAN adapter, you might be wondering what to do with the built-in 1Gbps Ethernet port. Instead of leaving it unused, you can configure Network Bonding to increase reliability.

In this guide, I will show you how to set up Active-Backup Bonding using Netplan. This configuration prioritizes your fast 2.5GbE connection but automatically switches to the built-in LAN if the USB adapter fails or gets disconnected.

Since many of us run Raspberry Pi in a headless environment, messing with network settings can be scary. This guide includes specific steps to prevent SSH lockouts.

Hardware Used

Device: Raspberry Pi 5

OS: Ubuntu / Raspberry Pi OS (Netplan based)

Adapter: UGREEN 2.5Gbps USB LAN Adapter


Step 1: Check and Backup Current Configuration

Before making any changes, it is crucial to backup your existing Netplan configuration to ensure you can revert if needed.

Check Existing Config Files

First, list the files in your Netplan directory.

ls /etc/netplan/

Create a Backup

Move the existing configuration file to a backup folder. This prevents conflicts between the old and new settings.

sudo mkdir /etc/netplan/backup
# The filename may vary (e.g., 50-cloud-init.yaml or 90-NM-....yaml)
sudo mv /etc/netplan/90-NM-....yaml /etc/netplan/backup/

Step 2: Create the Configuration File

Create the Bonding Configuration File

We will create a new configuration file for the bonding interface.

sudo nano /etc/netplan/99-bonding.yaml

Paste the following configuration. Important: Be sure to replace the macaddress value with the actual MAC address of your USB LAN adapter.

network:
  version: 2
  renderer: NetworkManager
  ethernets:
    eth0:
      dhcp4: false
      dhcp6: false
      optional: true
    eth1:
      dhcp4: false
      dhcp6: false
      optional: true
  bonds:
    bond0:
      interfaces:
        - eth1
        - eth0
      dhcp4: true
      dhcp6: false
      macaddress: 6C:1F:F7:73:A8:4B
      parameters:
        mode: active-backup
        primary: eth1
        mii-monitor-interval: 100

Explanation of Settings

  • eth0 / eth1: DHCP is disabled here so the bonding interface (bond0) can handle IP assignment.
  • bond0: DHCP is enabled here.
  • mode: active-backup: Uses one link at a time. If the primary link fails, it switches to the backup. No special switch configuration (LACP) is required.
  • primary: eth1: Forces the system to prefer the faster USB LAN (2.5GbE) when available.

Fix Permissions

Secure the file so only root can read/write it.

sudo chmod 600 /etc/netplan/99-bonding.yaml

Step 3: Test for Syntax Errors and Conflicts

Always test your configuration before applying it.

sudo netplan generate

If there is no output, the syntax is correct. If you see an error, check your indentation (YAML is sensitive to spaces).

Check for Conflicts

Ensure no other files defining eth0 or eth1 exist in the folder.

ls /etc/netplan/

Safe to keep: Your new 99-bonding.yaml and any Wi-Fi configs (wlan0).

Must remove: Any old ethernet config files (like the one we moved to backup).

Step 4: Verify MAC Address and Emergency Access

This is the most critical step to avoid losing SSH access.

Double-Check the MAC Address

Verify that the MAC address in your config file matches your physical USB device exactly. A single typo will cause the router to assign a different IP address, dropping your connection.

◆ Check the config file:

grep macaddress /etc/netplan/99-bonding.yaml

◆Check the actual device:

ip link show eth1 | grep ether

Ensure these two outputs match perfectly.

Emergency “Backdoor” via Wi-Fi

If the wired connection fails, you can recover via Wi-Fi. Check your Wi-Fi IP address now:

ip a show wlan0

Note down this IP address (e.g., 192.168.x.x). If SSH via Ethernet fails, use this IP to log in and fix the configuration.

Step 5: Apply Settings and Verify

全ての確認が完了したら、設定を適用します。

sudo netplan apply
Note: Your SSH session may freeze for about 10 seconds while the network restarts. If it doesn't recover, open a new terminal or connect via the Wi-Fi IP you noted earlier.

Verify Status

Check IP and Interface:

ip a

Confirm that bond0 exists and has an IP address.

Check Bonding Status:

cat /proc/net/bonding/bond0

You should see:

  • Bonding Mode: fault-tolerance (active-backup)
  • Primary Slave: eth1
  • Currently Active Slave: eth1

Success! You now have a redundant network setup that automatically prioritizes your 2.5GbE connection.いました。

Bonding Raspberry Pi