How to configure a bridge network over a bonded interface for Virtualizor

Virtualizor expects a Linux bridge to attach guest VMs to the host's network — viifbr0 is its default name. On a dedicated server (Hivelocity, OVH, Hetzner robot, etc.) the uplink is usually a bond of two physical NICs (bond0 over eno1 + eno2), and the host's public IPv4/IPv6 lives directly on the bond. To run Virtualizor, the bridge has to sit on top of that bond: the IP configuration moves from bond0 to viifbr0, and bond0 becomes a slave port of the bridge so traffic still ingresses through the physical NICs.

The trap is that NetworkManager refuses to slave an interface that still holds a manual IP — so the migration has to be done in two stages, with the IP cleared from the bond before it's enslaved. Get the order wrong and the activation step fails halfway through; get a typo wrong on the new IP and you lose SSH the instant the bridge comes up. This guide is the careful version: gather, stage, verify, activate, then update Virtualizor.

Read this before you start. You are reconfiguring the server's primary network over an active SSH session. A wrong IP, gateway, or CIDR will lock you out the moment you activate the bridge. Do not proceed without IPMI / KVM / remote-console access already open and authenticated to the server — that is your only way back in if the swap fails.

Gather your current network information

Before changing anything, write down the exact values you'll reuse on the bridge: connection name, IPv4/IPv6 addresses, CIDR prefixes, and gateways.

nmcli con show

The bond connection is usually called bond0 — confirm the exact name from the output, since nmcli con modify <name> is case- and string-sensitive.

ip -4 addr show bond0
ip -6 addr show bond0
ip route
ip -6 route

You should leave this step with the following written down:

IPv4 address + CIDR (e.g. 203.0.113.42/29)
IPv4 default gateway (e.g. 203.0.113.41)
IPv6 address + CIDR (e.g. 2001:db8::42/64) — if assigned
IPv6 default gateway (e.g. 2001:db8::1) — if assigned
The exact bond connection name (e.g. bond0)

Create the bridge interface (viifbr0)

Create the bridge with the name Virtualizor expects, and disable Spanning Tree Protocol — STP isn't useful on a single-uplink host bridge and the default forwarding delay slows guest network bring-up.

nmcli con add type bridge ifname viifbr0 con-name viifbr0
nmcli con modify viifbr0 bridge.stp no bridge.forward-delay 15

The bridge exists in NetworkManager now, but has no IPs and no slave ports yet — it's safe to keep configuring without affecting the live network.

Move the IP configuration onto the bridge

Apply the host's IPv4 (and IPv6, if applicable) configuration to the new bridge. Replace each YOUR_* placeholder with the values you noted in step 1.

IPv4:

nmcli con modify viifbr0 \
  ipv4.addresses YOUR_IPV4/CIDR \
  ipv4.gateway   YOUR_IPV4_GATEWAY \
  ipv4.method    manual

IPv6 (if applicable):

nmcli con modify viifbr0 \
  ipv6.addresses YOUR_IPV6/CIDR \
  ipv6.gateway   YOUR_IPV6_GATEWAY \
  ipv6.method    manual

The bridge now holds the configuration but is not yet active — the activation happens in step 6, after the bond has been re-parented.

Reattach the bond as a slave of the bridge

This is the step where the order matters. NetworkManager refuses to convert an interface into a bridge slave while that interface still holds manual IP settings (connection.master and ipv4.method=manual are mutually exclusive on the same connection). So the change happens in two distinct sub-steps.

Stage A — strip the IP configuration from the bond:

nmcli con modify bond0 \
  ipv4.addresses "" ipv4.gateway "" ipv4.method disabled \
  ipv6.addresses "" ipv6.gateway "" ipv6.method disabled

Stage B — enslave the bond to the bridge:

nmcli con modify bond0 \
  connection.master    viifbr0 \
  connection.slave-type bridge

bond0 is now a port of viifbr0 in the saved configuration — the running interface still has the live IP until you activate the change in step 6.

Verify the staged configuration

Always inspect the saved settings before activating. A typo here is a typo on the only path back to your server.

Bridge:

nmcli con show viifbr0 | grep -E 'ipv4.addresses:|ipv4.gateway:|ipv6.addresses:|ipv6.gateway:'

Confirm every IP and gateway matches what you wrote down. If the bridge is missing an address or gateway, fix it now with another nmcli con modify viifbr0 ... — not after activation.

Bond:

nmcli con show bond0 | grep -E 'connection.master:|connection.slave-type:|ipv4.method:|ipv6.method:'

Expected:

connection.master: viifbr0
connection.slave-type: bridge
ipv4.method: disabled
ipv6.method: disabled

If ipv4.method or ipv6.method still says manual, stage A didn't take — re-run it before going on.

Activate the new configuration

To minimise the time the host is unreachable, bring both connections up in a single chained command. Bringing the bridge up first activates the new IP; bringing the bond up second moves the physical NICs under the bridge.

nmcli con up viifbr0 && nmcli con up bond0

Expect a 5–15 second freeze on your SSH session while the kernel re-parents the bond and traffic switches to the bridge. If the session does not reconnect within ~60 seconds, log in via your IPMI / remote console and run nmcli con show --active to see what came up.

Once SSH is back, confirm the bridge holds the IPs and the bond is one of its ports:

ip a show viifbr0
bridge link

ip a show viifbr0 should list your IPv4 and IPv6 addresses on the bridge. bridge link should show bond0 with master viifbr0 state forwarding.

Update Virtualizor to use viifbr0

The host is now correctly bridged. Tell Virtualizor to use the bridge for guests:

Log in to the Virtualizor Admin Panel.
Navigate to Nodes → List Nodes.
Click the Edit (pencil) icon next to the server.
Under network settings, set Bridge Name to exactly viifbr0.
Save the configuration.
Restart the Virtualizor service from SSH so the change takes effect:
```
systemctl restart virtualizor
```

New VMs created on this node will now attach to viifbr0 and route their traffic out through bond0.

Troubleshooting

nmcli con up viifbr0 fails with "connection activation failed". The bridge's ipv4.addresses is wrong (typo, conflicting subnet, or missing CIDR). Re-check with nmcli con show viifbr0 | grep ipv4. Fix and reactivate — the bond is unaffected because it has no IP at this point.
SSH never reconnects. The host is unreachable on the new IP. Use IPMI to log in. The fastest recovery is to put the IP back on the bond and tear down the bridge: nmcli con modify bond0 ipv4.addresses YOUR_IPV4/CIDR ipv4.gateway YOUR_IPV4_GATEWAY ipv4.method manual && nmcli con modify bond0 connection.master "" connection.slave-type "" && nmcli con up bond0. Then start over from step 1 with the typo fixed.
bridge link does not list bond0. Stage B didn't take. Re-run nmcli con modify bond0 connection.master viifbr0 connection.slave-type bridge followed by nmcli con up bond0.
Guests have no network after Virtualizor restart. Confirm viifbr0 is up (ip link show viifbr0) and that the guest's vNIC is attached as a port (bridge link should show vifN.0 style interfaces alongside bond0). Also confirm the Bridge Name field in the Virtualizor node settings matches exactly — viifbr0, not viif-br0 or virbr0.
IPv6 default route is missing on the bridge. Some providers deliver IPv6 via SLAAC / Router Advertisements rather than a static gateway. If ipv6.method manual doesn't work for you, try ipv6.method auto on the bridge instead and omit ipv6.gateway.

Summary

To migrate a Virtualizor host from a bonded interface to a bridge over the bond:

Gather the bond's connection name, IPv4/IPv6 addresses, CIDRs, and gateways before changing anything.
Open IPMI before running any nmcli command — it is the only way back in if the activation fails.
Create viifbr0 with nmcli con add type bridge, disable STP.
Move IPs onto the bridge with nmcli con modify viifbr0 ipv4.addresses ... ipv4.gateway ... ipv4.method manual (and the same for IPv6).
Strip then enslave the bond in two steps — clear ipv4.method/ipv6.method to disabled first, then set connection.master viifbr0 connection.slave-type bridge.
Verify with nmcli con show <name> | grep ... before activating — a typo here costs you SSH.
Activate both connections in one chained command: nmcli con up viifbr0 && nmcli con up bond0. Expect a brief freeze.
Update Virtualizor to use viifbr0 as the bridge name and restart the service.

Done correctly, the swap is a 30-second blip in connectivity. The careful order — gather, stage, verify, activate — is what keeps a five-step nmcli change from turning into an IPMI-rescue evening.