Files
2026-04-04 10:52:45 +02:00

6.9 KiB
Raw Permalink Blame History

Network Guide — Proxmox VE 9.1

This guide covers network configuration for a homelab Proxmox setup: bridges, VLANs, trunk ports, and an optional pfSense VM as the network gateway.


Table of Contents

  1. How Proxmox Networking Works
  2. Linux Bridges
  3. VLAN Overview
  4. VLAN-Aware Bridge Setup
  5. Trunk Port to a Managed Switch
  6. Assigning VMs to VLANs
  7. pfSense as a VM Gateway
  8. Bonding and Link Aggregation
  9. Useful Network Commands

1. How Proxmox Networking Works

Proxmox uses standard Linux networking. There is no proprietary abstraction. The main file is:

/etc/network/interfaces

Changes made in the web UI (Node > Network) write to this file. Changes are applied with ifreload -a or on reboot.

Key concepts:

  • Physical NIC (eno1, enp3s0, etc.): the real hardware interface. Set to manual — Proxmox bridges own the IP.
  • Linux bridge (vmbr0, vmbr1, etc.): virtual switch. VMs plug into bridges, not directly into NICs.
  • VLAN interface (vmbr0.10, eno1.10): tagged sub-interface for a specific VLAN.
  • Bond (bond0): aggregates 2+ physical NICs into one logical link.

2. Linux Bridges

Default bridge (vmbr0)

Created during installation. Carries the Proxmox management IP.

auto vmbr0
iface vmbr0 inet static
    address 192.168.1.10/24
    gateway 192.168.1.1
    bridge-ports eno1
    bridge-stp off
    bridge-fd 0

bridge-stp off and bridge-fd 0 are important: they prevent the 15-second STP forwarding delay on startup.

Adding a second bridge (isolated internal network)

auto vmbr1
iface vmbr1 inet manual
    bridge-ports none
    bridge-stp off
    bridge-fd 0
    # No physical port: internal-only traffic between VMs

Apply:

ifreload -a

3. VLAN Overview

VLANs let you segment traffic on a single physical link. Each VLAN has an ID (1–4094). Traffic is tagged with an 802.1Q header.

Common homelab VLAN layout:

VLAN ID Name Purpose
1 Native/Mgmt Proxmox management, hypervisor
10 LAN Trusted devices, desktops
20 IoT Smart home devices
30 DMZ Public-facing services
40 Lab Experimental VMs

4. VLAN-Aware Bridge Setup

Proxmox supports VLAN-aware bridges natively since PVE 4.x. This is the recommended approach.

Manual edit of /etc/network/interfaces

auto vmbr0
iface vmbr0 inet static
    address 192.168.1.10/24
    gateway 192.168.1.1
    bridge-ports eno1
    bridge-stp off
    bridge-fd 0
    bridge-vlan-aware yes
    bridge-vids 2-4094

bridge-vlan-aware yes enables 802.1Q tagging on this bridge. bridge-vids 2-4094 declares all VLANs as allowed. You can restrict to specific IDs if needed.

Apply:

ifreload -a

Verify:

bridge vlan show

For automated setup, use the provided script:

bash network/vlan-setup.sh --bridge vmbr0 --vlans 10,20,30,40 --dry-run

Remove --dry-run to apply.


5. Trunk Port to a Managed Switch

For VLANs to reach other devices on your network, your managed switch must have the Proxmox port configured as a trunk (carries all tagged VLANs).

Cisco-style configuration (example)

interface GigabitEthernet0/1
  description Proxmox-PVE01
  switchport mode trunk
  switchport trunk allowed vlan 1,10,20,30,40
  spanning-tree portfast trunk

Set the port connecting to Proxmox as Tagged for all VLANs you want to pass through.

The Proxmox management VLAN (VLAN 1 by default) should be the native VLAN (untagged) on the trunk port so the Proxmox host itself remains accessible.


6. Assigning VMs to VLANs

With a VLAN-aware bridge, you tag VMs individually. No extra bridge per VLAN needed.

In the web UI

When creating or editing a VM: Hardware > Network Device > set VLAN Tag to the desired VLAN ID.

Via CLI (qm set)

# Assign VM 201 to VLAN 10
qm set 201 --net0 virtio,bridge=vmbr0,tag=10

# Assign LXC 200 to VLAN 20
pct set 200 --net0 name=eth0,bridge=vmbr0,tag=20,ip=dhcp

The VM sees an untagged interface (the hypervisor handles the tagging). No changes needed inside the VM.


7. pfSense as a VM Gateway

pfSense or OPNsense running as a VM provides routing and firewall between VLANs.

Architecture

Internet (WAN)
    |
[Physical NIC eno2] -- vmbr-wan (bridge, no IP)
    |
[pfSense VM]
    |
[vmbr0, VLAN-aware] -- internal VLANs (LAN, IoT, DMZ, Lab)

pfSense gets:

  • A WAN interface: plugged into vmbr-wan (connected to your router or modem)
  • A LAN interface: plugged into vmbr0 with a VLAN trunk

pfSense then handles inter-VLAN routing and firewall rules.

Create the WAN bridge

auto vmbr-wan
iface vmbr-wan inet manual
    bridge-ports eno2
    bridge-stp off
    bridge-fd 0

pfSense VM configuration

qm create 300 \
  --name pfsense \
  --memory 2048 \
  --cores 2 \
  --net0 virtio,bridge=vmbr-wan \
  --net1 virtio,bridge=vmbr0 \
  --ostype other \
  --scsihw virtio-scsi-pci \
  --scsi0 local-lvm:16

Inside pfSense, configure net1 as a VLAN trunk and create VLAN interfaces for each VLAN ID.


If your server has 2+ NICs, you can bond them for redundancy or increased throughput.

Active-backup bond (redundancy)

auto bond0
iface bond0 inet manual
    bond-slaves eno1 eno2
    bond-miimon 100
    bond-mode active-backup
    bond-primary eno1

auto vmbr0
iface vmbr0 inet static
    address 192.168.1.10/24
    gateway 192.168.1.1
    bridge-ports bond0
    bridge-stp off
    bridge-fd 0
    bridge-vlan-aware yes
    bridge-vids 2-4094

bond-miimon 100 checks link state every 100ms. If eno1 fails, traffic switches to eno2 automatically.

LACP / 802.3ad (requires managed switch support)

auto bond0
iface bond0 inet manual
    bond-slaves eno1 eno2
    bond-miimon 100
    bond-mode 802.3ad
    bond-lacp-rate fast
    bond-xmit-hash-policy layer2+3

Configure the corresponding port-channel on your switch.


9. Useful Network Commands

# Show all interfaces and their state
ip link show

# Show IP addresses
ip addr show

# Show bridge details (ports, VLANs)
bridge link show
bridge vlan show

# Reload network config without full reboot
ifreload -a

# Show the current routing table
ip route show

# Test connectivity between VMs on different VLANs
ping -c 3 -I vmbr0.10 192.168.10.1

# Show bond status (if bonding is configured)
cat /proc/net/bonding/bond0

# Capture traffic on a bridge port (tcpdump)
tcpdump -i vmbr0 -n -v 'vlan 10'