basforge

Search titles, text and the “If it doesn’t work” cases.

    RU
    OverviewHomelabProxmox

    Networking in Proxmox: the vmbr0 bridge, VLANs, a private network behind NAT and the firewall

    A Proxmox host works like a switch inside the computer: the vmbr0 bridge connects the network card to the guests, and each guest is a separate device on the home network with its own MAC and an address from the router. The config is /etc/network/interfaces, applied with ifreload -a without a reboot. VLANs, a private network behind NAT and the firewall are all built around this bridge, so a mistake in it cuts off both the host and every guest.

    The vmbr0 bridge: how a guest gets on the network

    The installer creates one bridge — vmbr0 — and puts the first network card into it. The host’s address is on the bridge, not on the card. Each guest connects to the bridge with its own virtual port: tap<id>i<n> for a VM, veth<id>i<n> for a container.

    router 10.0.0.1 ── cable ── nic0 ─┐
                                      ├─ vmbr0  10.0.0.2   ← host, web UI :8006
                 VM 101 ── tap101i0 ──┤                    ← guest: own MAC, address from the router
          container 201 ── veth201i0 ─┘

    To the router, guests are devices just like phones: each with its own MAC, an address from the router’s DHCP or one you set. Traffic between guests on one host never reaches the router; the bridge forwards it itself.

    The network file after install:

    auto lo
    iface lo inet loopback
    
    iface nic0 inet manual
    
    auto vmbr0
    iface vmbr0 inet static
            address 10.0.0.2/24
            gateway 10.0.0.1
            bridge-ports nic0
            bridge-stp off
            bridge-fd 0
    • iface nic0 inet manual — the card has no address of its own; it’s just a bridge port.
    • bridge-ports nic0 — which cards are in the bridge. A bridge without cards (bridge-ports none) is a network between the guests and the host only.
    • bridge-stp off, bridge-fd 0 — no STP and no forwarding delay: the bridge has one card, so there are no loops.

    The network is applied by ifupdown2: ifreload -a rereads the file and changes only what changed, without stopping guests. In the UI, edits go through /etc/network/interfaces.new and the Apply Configuration button. Editing /etc/network/interfaces by hand and running ifreload -a is the same thing.

    Network card names

    The kernel names a card by its bus position: eno1, enp3s0, and USB adapters by MAC, enx74d4…. After a kernel update the position may read differently: the 9.1 release notes say new PCIe features in the recent kernel change names. The bridge refers to the old name, and the host is left without network.

    The protection is pinned names:

    • In the installer since 9.1 — an option to pin names. The cards are called nic0, nic1, and the name doesn’t depend on the kernel.
    • On an existing host — pve-network-interface-pinning generate. The tool writes .link files to /usr/local/lib/systemd/network/ and updates the Proxmox configs for the new names; they take effect after a reboot.

    The kernel keeps the old name as an alternative one: ip link shows altname enx74d43519a642 on nic0.

    VLANs

    A VLAN splits one physical network into several: guest, smart home, lab. If the router and switch support VLANs (Wired on MikroTik), the Proxmox bridge hands them out to guests by tag. Add two lines to the bridge:

    auto vmbr0
    iface vmbr0 inet static
            address 10.0.0.2/24
            gateway 10.0.0.1
            bridge-ports nic0
            bridge-stp off
            bridge-fd 0
            bridge-vlan-aware yes
            bridge-vids 2-4094

    Then set a VLAN Tag on the guest’s network card, say 20 — in the guest config that’s net0: virtio=…,bridge=vmbr0,tag=20. The guest doesn’t know about the VLAN: it sees a normal network, and the bridge adds and strips the tag. The switch port the host is plugged into must pass these VLANs tagged (trunk).

    A private network behind NAT

    Sometimes guests need a separate network: a rented server has one public address, the host is on Wi-Fi, or test machines shouldn’t see the home network. Then make a second bridge with no cards and let it out through the host’s NAT — the way a home router lets out the apartment:

    auto vmbr1
    iface vmbr1 inet static
            address 10.10.10.1/24
            bridge-ports none
            bridge-stp off
            bridge-fd 0
            post-up   echo 1 > /proc/sys/net/ipv4/ip_forward
            post-up   iptables -t nat -A POSTROUTING -s '10.10.10.0/24' -o vmbr0 -j MASQUERADE
            post-down iptables -t nat -D POSTROUTING -s '10.10.10.0/24' -o vmbr0 -j MASQUERADE
    • Guests on vmbr1 get 10.10.10.x addresses with gateway 10.10.10.1. There’s no DHCP here: set the address yourself — in a cloud-init template it’s one --ipconfig0 option (VM template with cloud-init).
    • -o vmbr0 is the interface the host uses to reach the outside. If the host’s address is directly on the card rather than a bridge, put the card name here.
    • A guest port to the outside is a DNAT rule: iptables -t nat -A PREROUTING -i vmbr0 -p tcp --dport 2222 -j DNAT --to-destination 10.10.10.11:22. It also goes in as a post-up line and comes off in post-down.
    • If the Proxmox firewall is on, the documentation recommends one more line — conntrack zones for outgoing connections: post-up iptables -t raw -I PREROUTING -i fwbr+ -j CT --zone 1.

    With more than three rules, move them into your own script called by post-up and pre-down: the rules then come off with one command and don’t duplicate when the bridge comes up again.

    The same NAT with DHCP can be put together with the mouse: Datacenter › SDN, a Simple zone with the SNAT and DHCP checkboxes. Proxmox brings up dnsmasq itself and hands out addresses to the guests. DHCP in SDN has been a technology preview since 8.1.

    Two cards: a bond

    Two cards in one bond give a reserve in case a cable or port fails. 802.3ad (LACP) mode adds up their speed across different connections but needs switch support. active-backup works with any switch: one card works, the other waits. The bridge is then built on top of the bond: bridge-ports bond0.

    The Proxmox firewall

    The Proxmox firewall is built in and off by default. Rules live on three levels:

    Level Where in the UI What it closes
    Datacenter Datacenter › Firewall the master switch and rules for all nodes; rule groups, address sets
    Node node › Firewall incoming traffic to the host itself: 8006, 22, 3128 (SPICE proxy)
    Guest VM or container › Firewall traffic to the guest at the bridge level; the guest doesn’t know about it

    The order of turning it on matters. Turn the firewall on at Datacenter, and incoming traffic to the hosts is denied except 8006 and 22 from the local network. For a guest, the firewall applies only if it’s on both for the guest (its Firewall › Options › Firewall) and for its network card (firewall=1; in the UI new cards are created with this checkbox).

    There are two implementations. The main one is pve-firewall on iptables. Since 8.2 there’s proxmox-firewall on nftables — a technology preview, enabled per node: Firewall › Options › nftables. The rules in the UI are the same; only what enforces them changes.

    At home a simpler setup is common: the Proxmox firewall is off, nothing is forwarded to the outside, and the host’s 8006 and SSH are reachable only from the home network (8006 from inside only). Internet-facing guests are closed with their own firewall — ufw on Ubuntu (The ufw firewall).

    If it doesn’t work

    Changed the network in the UI — nothing changed

    Cause
    The UI writes edits to /etc/network/interfaces.new, and they reach the live file only with the Apply Configuration button.
    Fix
    Node › System › Network › Apply Configuration. What exactly will change is shown at the bottom of the same page, under Pending changes.

    After a kernel update the host dropped off the network

    Cause
    The new kernel named the card differently (enp3s0 instead of enp2s0), while vmbr0 has the old name in bridge-ports.
    Fix
    From a monitor: ip -br link shows the new name; fix bridge-ports in /etc/network/interfaces and run ifreload -a. Then pin the names: pve-network-interface-pinning generate and a reboot.

    A laptop host on Wi-Fi works, but guests on the bridge have no network

    Cause
    A Wi-Fi client passes only frames with its own MAC: the access point won’t accept frames from guest MACs, so a bridge over Wi-Fi doesn’t work.
    Fix
    Put the guests on a private network behind NAT (vmbr1 with MASQUERADE, below), or connect the host with a cable.

    Rented server: a guest was added to the bridge with a public address — the provider shut the port or sent a complaint

    Cause
    The provider sees several MACs on the port and treats it as a violation: the Proxmox documentation explicitly warns that many hosting providers do this.
    Fix
    Put the guests on a NAT network on vmbr1 and expose ports through DNAT or a proxy on the host. If the provider issues virtual MACs for extra addresses, set them on the guests’ network cards.

    A VM with a VLAN tag doesn’t get an address

    Cause
    The bridge isn’t VLAN-aware, so the tag has nowhere to go, or the switch and router port doesn’t pass that VLAN tagged.
    Fix
    On vmbr0 — bridge-vlan-aware yes and bridge-vids 2-4094; on the switch, the port to the host is a trunk with the VLAN. Check from the host: bridge vlan show — the tap<id>i0 port has the tag.

    Turned the firewall on at Datacenter — lost access to the UI

    Cause
    With the firewall on, incoming traffic to the host is denied except ports 8006 and 22 from the local network. Coming in from another subnet means falling under the ban.
    Fix
    From the host console: pve-firewall stop, then a rule for your address in Datacenter › Firewall and pve-firewall start. Or enable: 0 in /etc/pve/firewall/cluster.fw.