Proxmox Networking Setup: From a Simple Bridge to LACP Bonds

A good network layout on a bare-metal Proxmox node does three things. It keeps the management network private, it keeps guest traffic on its own VLANs, and it survives a cable or switch port failure. In this guide, you will learn to build that layout step by step. We use one Proxmox VLAN bridge as the base, add active-backup or LACP bonds, and move the management IP to its own network.

This guide is tested for Proxmox VE 9.2. The steps also work on Proxmox VE 8.x, because the network file format is the same. You will learn these parts:

• How vmbr bridges work, and how Proxmox uses /etc/network/interfaces.
• How to make a VLAN-aware bridge, and how to use tagged and untagged VM networks.
• How to build an active-backup bond and an LACP bond.
• How to move the management IP to its own VLAN or its own network card.
• How to change the network remotely and roll back automatically if something breaks.

We use this plan for all examples. Change the numbers to match your network:

Interface names such as eno1 and eno2 are examples. Run ip -br link on your server to see your real names.

Before you start Proxmox networking setup, check these items:

• A bare-metal Proxmox VE node with root access.
• At least one network card. Two or more cards are needed for bonding.
• Out-of-band access: IPMI, iDRAC, iLO, or the KVM console from your provider.
• A switch or provider network that supports VLAN tags (802.1Q) if you want VLANs.
• A switch that supports LACP (802.3ad) if you want an LACP bond.

Use the following command to check your version and your network tool:

Proxmox uses ifupdown2, so you can apply network changes live without a reboot. If ifupdown2 is missing, install it with the command below:

Warning: Do not use ifdown vmbr0 and ifup vmbr0 on a running node. ifdown on a bridge cuts all guest traffic, and ifup does not reconnect those guests later. Use ifreload -a instead.

If you want to host this setup on a server with full network control, you can use a dedicated server with a private network port from PerLod.

Proxmox keeps all its network settings in the /etc/network/interfaces file. When you change the network in the web UI, Proxmox does not write to this file at once. It writes to a staging file named /etc/network/interfaces.new. When you click Apply Configuration, Proxmox moves the changes into the real file and applies them live. If you edit the real file manually, you must apply your changes with:

Proxmox uses these names:

• Physical cards: eno1, enp3s0f1, and similar.
• Bridges: vmbr0, vmbr1, and so on.
• Bonds: bond0, bond1, and so on.
• VLAN on a device: the device name plus a dot and the VLAN ID, such as bond0.10 or vmbr0.10.

A big upgrade or a new kernel can change the name of a network card. For example, enp3s0 can become enp4s0. Your bridge or bond then points to a card that no longer exists, and the server loses its network.

Proxmox has a tool that locks the names, so they stay the same after upgrades. Do this before you build bridges and bonds:

This creates .link files in /usr/local/lib/systemd/network and updates /etc/network/interfaces to use the new names. Also, it writes .new files first, so you can compare them:

A reboot is needed for the new names to work. Do this only when you can reach the console.

A wrong network change can lock you out of a remote server in seconds. This step protects you from that. You must save a copy of the network file, create a rollback script, and start a timer that restores the old setup by itself. Do it before every network change.

First, you can run your work inside tmux. If your SSH session drops, your commands keep running, and you can log in again and continue:

If you lose the connection, log in again and run tmux attach -t net.

Before you change anything, you must save a copy of your working network file. If something breaks, this is the file you will restore:

This small script puts your saved network file back and reloads the network. The safety timer in the next step runs it for you, and you can also run it manually from the console.

Before you apply a network change, you must start a timer. If you lose access, the server runs the rollback script by itself after 5 minutes. If the change works, you cancel the timer.

You must use these steps for every network change in this guide:

1. Save the copy.
2. Edit /etc/network/interfaces.
3. Check the syntax without applying it: ifreload -s -a
4. Start the safety timer: systemd-run --unit=net-rollback --on-active=5m /root/net-rollback.sh
5. Apply the change: ifreload -a
6. Open a new SSH session to the new address and test the web UI on port 8006.
7. If it works, cancel the timer and save the new file as the good copy:

If it does not work, do nothing. Wait for the timer, or run /root/net-rollback.sh from the console.

If a change breaks the network so much that the timer cannot run, use the IPMI or KVM console and restore the file manually:

If nothing else works, reboot the server. It will start with the file you restored.

This is the default Proxmox layout. One card connects to one bridge, and the VMs act like they are plugged into the same switch as the host. It is the simplest setup, and a good starting point for a new server. Open the file with:

What the main lines mean:

• bridge-ports eno1 connects the physical card to the bridge.
• bridge-stp off turns off spanning tree on the bridge. It is not needed on a simple host.
• bridge-fd 0 removes the forwarding delay, so ports come up fast.
• The host IP and gateway are on vmbr0, not on eno1.

Note: Many hosting providers block extra MAC addresses on one port. If your VMs get no network with this layout, use the routed layout below.

You can use this layout if your provider gives you one main IP and an extra IP block for VMs, and it blocks bridged traffic. Packets from VMs go through the host, so the provider only sees one MAC address.

Here, the host owns 198.51.100.5, and your VMs use addresses from 203.0.113.16/28 with 203.0.113.17 as their gateway. Replace both blocks with the real addresses your provider gave you. 

In this layout, one network card carries many VLANs. The host management IP sits on VLAN 10, and your VMs use VLAN 20, 30, and 40. The bridge itself has no IP, so the host talks only on the management VLAN. Your switch port must allow all four VLANs.

Note: Before you apply it, make sure your current SSH session can survive. If your switch does not carry VLAN 10 yet, the node goes offline. Use the rollback timer from Step 1, and test with the safe change routine.

After you apply the change, check it with the commands below:

You should see the IP 172.16.10.2/24 on vmbr0.10, and VLAN 10 listed on eno1 and vmbr0.

If you change the management IP, also update /etc/hosts so the node name points to the new IP. Open the file and fix the line for your hostname:

The second command should show the new management IP. Do not change the IP of a node that is already in a cluster without a plan, because the cluster files also use it.

With a VLAN-aware bridge, you must set the VLAN tag on the VM network card. Then, the VM joins that VLAN, with no extra bridge needed. You can set the tag in the web UI or CLI.

In the Web UI:

1. Select the VM, and open Hardware.
2. Select the Network Device, and click Edit.
3. Set Bridge to vmbr0.
4. Set VLAN Tag to 20.
5. Click OK.

From the Command Line:

First, check the current setting so you keep the same MAC address:

Then, you can set the tag. Use the same MAC address from the output above:

For a container, use pct instead of qm. The tag works the same way:

Some VMs, such as a router or firewall VM, need many VLANs on one network card. You can use trunks and handle the tags inside the VM:

Remember to put the value in quotes, because the semicolon has a special meaning in the shell.

If you do not set a VLAN tag, the VM uses the default VLAN of the bridge. This is VLAN 1 by default. Your switch port must use the same default VLAN:

Use untagged networks only when you have a clear reason, for example, when your provider gives you one public network without tags. For all other guests, set a tag. It makes the network easy to see in the VM config and stops mix-ups.

If the host IP is on vmbr0 and you turn on VLAN awareness, the host stays on the default VLAN. This works, but the management network is shared with every untagged guest. The next sections show a better way.

A bond joins two or more network cards into one logical card. It protects you from a cable, card, or switch port failure. It can also add speed. The most used modes include:

If your switch supports LACP, use 802.3ad. If not, use active-backup. Other modes, such as balance-rr or balance-xor, can cause problems and are not the best choice for a production node.

You can use this layout when you want failover, but your switch has no LACP, or when you connect the two cables to two different switches.

• bond-slaves eno1 eno2 lists the cards in the bond.
• bond-miimon 100 checks the link every 100 ms.
• bond-mode active-backup uses one card at a time. The other waits.
• bond-primary eno1 sets the preferred card. Traffic goes back to it when it recovers.

Both switch ports must carry the same VLANs. No LACP setup is needed on the switch. Check the bond with:

Look for Bonding Mode: fault-tolerance (active-backup), Currently Active Slave: eno1, and MII Status: up for both cards.

LACP uses both cards at the same time and fails over if one stops. The switch must be set up as a port-channel with LACP on. If the switch side is not ready, the bond will not work as expected.

• bond-mode 802.3ad is LACP.
• bond-xmit-hash-policy layer3+4 picks the card for each flow using IP addresses and ports. This spreads traffic better than layer2.
• bond-lacp-rate fast sends LACP messages every second instead of every 30 seconds, so a failed link is found faster.

LACP works only when both sides are set up. Your server and your switch must both use LACP. Use this checklist on the switch side, with your switch's own commands. If you rent a dedicated server, ask your provider to do these steps.

1. Create a port-channel (LAG) with the two ports.
2. Set the mode to LACP (active).
3. Make the port-channel a trunk and allow VLANs 10, 20, 30, and 40.
4. Set the native VLAN to match your plan.
5. Use fast LACP rate on the switch too.

After you apply the bond, check that LACP really works with the command below:

Look for these signs of a healthy bond:

• Bonding Mode: IEEE 802.3ad Dynamic link aggregation
• Both cards show MII Status: up.
• The Partner Mac Address is not 00:00:00:00:00:00.
• Both cards show the same Aggregator ID.

If the partner MAC is all zeros, the switch is not sending LACP messages. Check the switch port-channel.

One limit to remember: LACP does not give one single connection more than one card of speed. It spreads many different flows across the cards.

Management traffic is the web UI (port 8006), SSH (port 22), and cluster traffic. You must keep it away from your guest network, so a VM can never reach it. There are three levels of isolation, including a separate VLAN, a separate network card, and firewall rules. Pick the one that fits your server.

This is what Topology 3, 4, and 5 do. The host IP sits on vmbr0.10, and guests use other VLANs. It is simple and needs no extra card.

The limit is that a Proxmox VLAN bridge lets a VM use any tag you give it. A user who can edit a VM network card could set tag 10 and land in the management network. So limit who has rights to change VM network devices, and never give VLAN 10 to a guest.

This is the strongest layout. One card carries only management. A bond carries all guest traffic. No guest port touches the management network.

The host has an IP only on vmbr1. The guest bridge vmbr0 has no host IP at all, so the host does not answer on the guest network. Never attach a VM to vmbr1, unless it is a management tool such as a jump host.

Firewall rules add a second lock to your management network. With them, only trusted IPs can reach the web UI and SSH, even if the network is shared. Keep one SSH session open while you set this up, so you can undo a mistake.

First, open the cluster firewall file with the command below:

Add the management network and your admin IP to the special management IP set. Then, turn on the firewall:

Replace 203.0.113.50 with your own admin or VPN IP. Hosts in the management set can reach the web UI, VNC, SPICE, and SSH. When the firewall is on, other traffic to the host is blocked by default, with some exceptions for the local network and cluster traffic. Check the status with:

Start the rollback timer before you turn the firewall on. If the firewall locks you out, you can stop it from the console:

For a cluster, keep Corosync on its own network, ideally with a separate network card. It can switch between networks itself, so a bond is not needed.

If you use LACP, set bond-lacp-rate fast on the node and enable fast LACP on the switch. The slow setting can take about 90 seconds to detect a failure, which is too long for HA services. Avoid balance-rr, balance-xor, balance-tlb, and balance-alb for Corosync.

At this point, you can use the safe change routine from Step 1 to apply your settings, then open a new SSH session. Check the host connection, VLANs, and bond before you cancel the rollback timer.

Open a new SSH session. Then, run these checks:

Then, you can start a VM on VLAN 20 and ping its gateway. To test failover, keep the ping running and unplug one bond cable or disable its switch port. The connection should recover with only a few lost packets.

When all tests pass, cancel the timer and save the file:

If the host or a VM loses its connection, you can use these checks to find the problem. Start with the VLAN settings, switch ports, and bond status.

• No network after applying: Wait for the rollback timer, or run /root/net-rollback.sh from the console.
• VM on a VLAN has no network: Check that the switch trunk allows this VLAN, and run bridge vlan show to see if the bridge and port carry it.
• Host unreachable after adding vmbr0.10: The switch port may not carry VLAN 10, or the native VLAN is wrong.
• LACP shows one active link: The switch port-channel is missing or not in LACP mode. Check the partner MAC in /proc/net/bonding/bond0.
• Provider cuts the port after using bridges: The provider blocks extra MACs. Use the routed layout.
• Card names changed after an upgrade: Fix the names in /etc/network/interfaces, and pin the names as shown earlier.
• Web UI works but cluster is unstable: Move Corosync to its own network.

Everything in this guide is for one node and one site. A VLAN-aware bridge is the best tool for that job.

If you need to link guests across several nodes or data centers, you need an overlay network. For that, you can read the multi-site Proxmox SDN guide with WireGuard fabric. You can keep the host management network from this guide on its own VLAN or card, and build SDN on top of it.

A clear Proxmox network setup keeps management and guest traffic separate. You must choose the right bridge and bond for your server, check the switch settings, and test before moving workloads.

Always back up your network file and use a rollback timer when making remote changes.

We hope you enjoy this guide. For more information, you can check the Official Proxmox VE Network Configuration.