HotBond - Linux Hotpluggable Network Interface Bonding

HotBond is a flexible network interface bonding solution for Linux, designed primarily for laptops that need to seamlessly bond Wi-Fi and Ethernet connections across different locations (home, office, etc.).

Key Features & Rationale

HotBond addresses a critical limitation of traditional Linux kernel bonding: with kernel bonding, to add an interface to a bond, the interface must be brought down first. This is problematic for Wi-Fi interfaces because:

• Bringing down a Wi-Fi interface breaks its network association
• You need the interface to stay up to maintain its connection and to determine if you want to bond it (e.g., based on which network it's connected to)

HotBond solves this by:

• Allowing interfaces to be added to the bond while they remain up and connected
• Supporting location-aware bonding where different Wi-Fi networks can be bonded with different Ethernet interfaces
• Providing dynamic rule-based configuration for interface selection

Configuration

HotBond reads configuration from /etc/hotbond/<bond_name>.toml files. Each file configures a single bond interface:

# /etc/hotbond/home.toml
bond_mac = "02:00:00:00:00:01"
[[interfaces]]
name = "eth0"
priority = 1
[[interfaces]]
name = "wlan0"
priority = 2
ssid = "HomeNet"

Configuration Options

• bond_mac: MAC address for the virtual bond interface (required)
• interfaces: List of match rules determining which physical interfaces should be added to this bond. All criteria all optional but you should specify at least one. All the specified criteria must match the interface (there is an implicit AND between them).
  • name: Interface name
  • mac: Interface MAC address
  • ssid: ESSID (network name) of the connected wireless network
  • bssid: BSSID (access point MAC) of the connected wireless network
  • priority: Priority the interface will have in the bond (lower number = higher priority)

MAC Address Configuration

For bonding to work correctly, the MAC addresses must match between the bond interface and all the physical interfaces within it.

Wired interface MAC handling

If you have only one wired interface in the bond, you can simply reuse its native MAC as the bond MAC. Or you can set the interface's MAC using e.g. systemd-networkd or udev rules.

Wireless MAC address handling

For Wi-Fi interfaces, you can configure MAC addresses per network in wpa_supplicant:

# /etc/wpa_supplicant/wpa_supplicant.conf
network={
 ssid="HomeNet"
 # ... other network settings ...
 mac_addr=3 # Use custom MAC
 mac_value=02:00:00:00:00:01 # Must match bond_mac
}
network={
 ssid="OfficeNet"
 # ... other network settings ...
 mac_addr=3
 mac_value=02:00:00:00:00:02 # Different bond's MAC
}

Use Case Example

A laptop that connects to both home and office networks:

# /etc/hotbond/home.toml
bond_mac = "02:00:00:00:00:01"
[[interfaces]]
name = "eth0" # Home ethernet
priority = 1
[[interfaces]]
name = "wlan0" # Home Wi-Fi
priority = 2
ssid = "HomeNet" # Only use when on home network

# /etc/hotbond/office.toml
bond_mac = "02:00:00:00:00:02"
[[interfaces]]
name = "eth0"
priority = 1
mac = "00:11:22:33:44:55" # Match office dock's ethernet
[[interfaces]]
name = "wlan0"
priority = 2
ssid = "OfficeNet" # Only use when on office network

In this setup:

• Each location has its own bond configuration file
• The same physical interfaces can be used in different bonds
• Wi-Fi interfaces remain connected while being added/removed from bonds
• Interface selection happens automatically based on location (network)

Technical Implementation

HotBond works by creating a virtual network interface for each bond using a veth pair, and then using tc (traffic control) rules to redirect traffic between the virtual interface and the currently active physical interface. This approach allows for seamless interface switching without bringing down the physical interfaces.

Core Components

1. Virtual Interface Setup

   • Creates a veth pair for each bond: <bond_name> and <bond_name>-peer
   • The bond interface gets the configured MAC address
   • The peer interface is used to control carrier state (up/down)

2. Traffic Control Rules

   • Uses tc mirred actions to redirect traffic in both directions
   • For ingress (incoming) traffic:

     tc qdisc add dev <physical_if> ingress
     tc filter add dev <physical_if> parent ffff: protocol all prio 1 u32 \
      match u32 0 0 action mirred ingress redirect dev <bond_if>
     

   • For egress (outgoing) traffic:

     tc qdisc add dev <bond_if> root handle 1: prio
     tc filter add dev <bond_if> parent 1: protocol all prio 1 u32 \
      match u32 0 0 action mirred egress redirect dev <physical_if>
     

Interface Switching Process

1. When a state change is detected (interface up/down or WiFi connection):

   • Cleans up existing tc rules on both interfaces
   • Evaluates all interface rules in priority order
   • Selects the highest priority interface that matches all criteria (name, MAC, SSID, BSSID)

2. For the selected interface:

   • Verifies the interface's MAC matches the bond's MAC
   • Sets up new tc rules for bidirectional traffic redirection
   • Brings up the peer interface to indicate carrier presence

3. If no interface is selected:

   • Brings down the peer interface to indicate no-carrier state
   • Bond interface remains up but without connectivity

Requirements

• Linux with tc support
• Python 3.7+
• iproute2 tools
• Root privileges

Installation

1. Install dependencies:

sudo apt install python3 python3-trio iproute2 # Debian/Ubuntu

(or analogously for other Linux distros)

2. Install HotBond:

sudo mkdir /usr/local/lib/hotbond
sudo cp *.py /usr/local/lib/hotbond/
sudo cp hotbond.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now hotbond