High-Wire Engineering: Building an Active-Backup Network Bond with nmcli via SSH

There is a specific brand of adrenaline known only to systems administrators: modifying the primary network interface configuration of a remote server over an active SSH session. One wrong keystroke, one premature service restart, and you instantly cut your own lifeline, locking yourself out of a headless machine that might be miles away.

This was the exact challenge faced during a recent infrastructure upgrade on a Raspberry Pi server running a modern Linux distribution managed by NetworkManager. The goal: combine the physical onboard Ethernet (eth0) and the wireless network (wlan0) into a single, resilient, active-failover bonded interface (bond0) pinned to a static IP address. If the physical network cable gets yanked out, the system should instantly failover to Wi-Fi without dropping a single packet. And it all had to be executed completely headless over the network.

The Invisible Safety Net: Laptop to Pi via tmux

Before touching a single network configuration utility, you need an insurance policy. When you tell a web server or a network stack to cycle its connections, the underlying routing table tears down and rebuilds. If your terminal connection flickers for even a microsecond during this transition, a standard SSH session dies instantly, leaving the server in an indeterminate, broken state.

The secret weapon here is running a double layer of tmux (Terminal Multiplexer): one session managed locally on the laptop to maintain workspace persistence, and crucially, a persistent tmux session running directly on the Raspberry Pi. By executing the network changes inside a remote tmux session, the commands keep running to completion in the background even when the SSH socket momentarily disconnects. You simply let the network catch its breath, reconnect, re-attach to your tmux session, and pick up exactly where you left off.

The Automation Blueprint: Using NetworkManager

To ensure the transition happened cleanly and bypassed any conflicting profiles generated by Netplan during the OS installation, the entire process was driven by a custom automation script utilizing nmcli (NetworkManager Command Line Interface). Managing a bond this way is incredibly elegant because NetworkManager handles the complex background Wi-Fi security handshakes natively as a slave component.

Here is the exact implementation script used to build the pipeline:

#!/bin/bash
echo Run this with sudo
read ans
1. Delete the old netplan-generated profiles to avoid configuration conflicts
nmcli connection delete “netplan-eth0”
nmcli connection delete “netplan-wlan0-Brightspeed_013450E3”
2. Create the master bond interface
nmcli connection add type bond con-name bond0 ifname bond0 mode active-backup +bond.options “miimon=100”
3. Add eth0 as a slave to bond0
nmcli connection add type ethernet con-name bond-eth slave-type bond master bond0 ifname eth0
4. Add wlan0 as a slave to bond0
nmcli connection add type wifi con-name bond-wifi slave-type bond master bond0 ifname wlan0 ssid “Brightspeed_013450E3”
nmcli connection modify bond-wifi wifi-sec.key-mgmt wpa-psk wifi-sec.psk “royaltrain445”
5. Assign your target static IP (.64) to the bond master
nmcli connection modify bond0 ipv4.addresses “192.168.1.64/24” ipv4.gateway “192.168.1.1” ipv4.dns “8.8.8.8” ipv4.method manual
6. Make the bond an active failover (Crucial for mixed wire/wireless bonds)
nmcli connection modify bond0 +bond.options “fail_over_mac=active”
7. Cycle the connections to apply the changes
This will sever your SSH session, which is relatively safe inside tmux!
nmcli connection up bond0

Anatomy of a Bulletproof Bond

Reviewing the architecture of this script highlights a few critical engineering decisions that keep a headless server from bricking its own network connectivity:

• Clearing the Ground: Deleting the netplan- profiles at the start is vital. Netplan and NetworkManager like to compete for hardware control. Purging the old profiles ensures NetworkManager has exclusive, unhindered control over the physical ports.
• The MAC Address Conundrum (fail_over_mac=active): This is the absolute golden rule of bridging Ethernet and Wi-Fi. A standard network bond tries to force all slave interfaces to share a single MAC address. However, most modern Wi-Fi access points will reject wireless packets if the Wi-Fi card attempts to spoof the Ethernet card's MAC address. Setting fail_over_mac=active forces the kernel to dynamically change the MAC address of the virtual bond0 interface to match whichever physical card is actively routing data at that moment.
• The MII Link Monitor: The miimon=100 option instructs the Linux kernel network driver to inspect the physical link health of the active interface every 100 milliseconds. If you pull the physical LAN cable, the failure is detected in a tenth of a second, and traffic instantly switches to the wireless radio.

The Payoff

When the final line of the script executes and brings the new bond0 master online, your terminal window will freeze. That is completely normal—the network stack is pivoting. Because the script was insulated inside a remote tmux wrapper, the command completed perfectly in the background.

After a few seconds, typing a fresh SSH command logs you straight back into the exact same static IP space, now backed by an incredibly resilient, failover-protected network pipeline. Good systems engineering isn't just about making things work; it's about deploying the safety nets that give you the confidence to refactor critical infrastructure from a distance.

• ← Previous Post
• Next Post →