Bridge analysis & guided repair

Audits every vmbrX bridge declared in /etc/network/interfaces, verifies that its physical ports actually exist, and offers a step-by-step repair when they don't. The analysis is read-only; the repair is gated, previewed and backed up.

What this does

Reads each bridge in /etc/network/interfaces, looks at its bridge-ports line and checks whether each declared port (e.g. enp3s0) actually exists on the host. If a port is missing, proposes a substitute and — with explicit consent — applies the change with a backup, preview, apply, verify flow.

When you need this

Linux assigns predictable interface names from PCI topology and slot order. Several events shuffle them and leave /etc/network/interfaces referring to names that no longer exist:

Adding or removing a PCIe card (a NIC, a GPU, a HBA, an NVMe carrier).
Moving an existing card to a different PCIe slot.
BIOS / UEFI updates that re-enumerate PCI devices.
Migrating the boot disk to different hardware.

After the next boot, the bridge tries to attach to a port that no longer exists, fails to come up, and the host loses its network. Persistent interface names prevents this from happening again — but if you are already locked out, this page is the recovery path.

The big picture

/etc/network/interfaces

auto vmbr0 iface vmbr0 inet static bridge-ports enp3s0

step 1

Analyze (read-only)

ip link show enp3s0 → does not exist

step 1

Report + suggestion

❌ enp3s0: NOT FOUND Replace with: eno1 (no changes yet)

Guided repair

1. Backup 2. Show current 3. Preview changes 4. Apply 5. Verify

apply with backup

/etc/network/interfaces (new)

auto vmbr0 iface vmbr0 inet static bridge-ports eno1

Step 1: analysis (read-only)

Selecting Analyze Bridge Configuration aborts immediately if the host is not on the classic Debian/Proxmox stack. Otherwise it walks every bridge and reports:

Bridge name, current status (UP / DOWN), assigned IP.
Each declared port and whether it currently exists (ip link show <port>).
For each invalid port: a proposed replacement (the first available physical interface) plus the exact sed command to apply it manually.
Bridges with no bridge-ports at all and orphan auto entries (no matching iface block).

🔍 BRIDGE CONFIGURATION ANALYSIS
==================================================

🌉 Bridge: vmbr0
   📍 Status: DOWN
   🌐 IP: No IP assigned
   🔌 Configured Ports: enp3s0
   ❌ Port enp3s0: NOT FOUND

🔧 SUGGESTION FOR vmbr0:
   Replace invalid port(s) 'enp3s0' with: eno1
   Command: sed -i 's/bridge-ports.*/bridge-ports eno1/' /etc/network/interfaces

📊 ANALYSIS SUMMARY
=========================
Bridges analyzed: 1
Issues found: 1
Physical interfaces available: 2

⚠️  IMPORTANT: No changes have been made to your system
Use the Guided Repair option to fix issues safely

Read-only guarantee

Up to this point the script has not run a single modifying command. You can leave the analysis open, copy the suggested sed commands and apply them manually if you prefer — or accept the next prompt to enter the guided repair.

Step 2: guided repair (5 steps)

Only entered if you accept the prompt at the end of the analysis. Each step shows what will happen and asks for confirmation before continuing.

1. Safety backup

Copies /etc/network/interfaces to /var/backups/proxmenux/interfaces_backup_<TIMESTAMP>. The exact backup path is shown before the copy and again after, with the rollback command.

2. Review current configuration

Opens the live /etc/network/interfaces in a scrollable dialog so you can see exactly what is about to be changed.

3. Preview proposed changes

Lists exactly which bridges will be touched and which port substitutions will happen. If the analysis decides nothing actually needs fixing (race condition: the port came back), the flow exits cleanly with "No changes needed."

4. Apply changes

For each affected bridge, runs sed -i "/iface $bridge/,/bridge-ports/ s/bridge-ports.*/bridge-ports $new_ports/" against /etc/network/interfaces. If a bridge had no valid replacement available, the substitution is skipped and reported in step 5.

5. Verification

Re-reads the file and confirms each bridge's new port now exists. Prints the rollback command (cp <backup> /etc/network/interfaces). Finally offers a Restart networking prompt — accept only if you have console fallback.

Restarting networking ≠ a free undo

The repair is written to disk regardless of whether you restart the service. systemctl restart networking applies the change now, which can drop your SSH session if the new port is wrong. If you decline the restart, the change still takes effect on the next reboot — confirm the new config first or roll back from the printed command.

What gets edited (exactly)

Only the bridge-ports line of each affected bridge. Other directives (address, netmask, gateway, bridge-stp, …) are left untouched. The script never creates new iface blocks and never removes existing ones in this flow — that is the job of Config analysis & cleanup.

Troubleshooting

Analysis aborts with "Unsupported Network Stack"

The host runs netplan, systemd-networkd or NetworkManager. The tool only supports /etc/network/interfaces. Switch the host to the classic stack first, or edit the configuration with the manager's native tooling (e.g. netplan apply).

No suggestion is printed for an invalid port

The host has zero free physical interfaces (everything is either already in another bridge or doesn't exist). The analysis falls back to suggesting bridge-ports none so the bridge can at least come up without a port. Add a NIC or migrate ports between bridges manually before re-running.

The repair completes but the bridge is still DOWN

sed updated the file but systemctl restart networking was declined. Run it manually once the new config is verified, or reboot. If the restart was accepted and the bridge is still DOWN, run ip link show to confirm the new port exists, then check journalctl -u networking for the actual error (cable unplugged, link not negotiated, port already a member of another bridge).

I lost SSH access right after restarting networking

Use console / IPMI / iKVM to reach the host. Restore the backup:

cp /var/backups/proxmenux/interfaces_backup_<TIMESTAMP> /etc/network/interfaces
systemctl restart networking

Then re-run the analysis from the console to figure out why the suggestion did not work (typically: the replacement port is not actually plugged in).

Persistent interface names — pin names to MAC addresses so this scenario stops happening.
Config analysis & guided cleanup — for orphaned iface blocks (the other half of the same problem).
Interfaces backup & restart — manual snapshots and the restore browser.

ProxMenux Scripts: Previous

Live monitoring tools

ProxMenux Scripts: Next

Config analysis & cleanup