Most OpenWrt on Proxmox trouble comes from treating firmware, virtual hardware, and VLANs as one setting. They are three separate decisions. Boot the guest with OVMF UEFI firmware plus its own EFI variables disk, attach the raw OpenWrt combined EFI image, and set every network card to the virtio model. Then decide whether OpenWrt or Proxmox owns each VLAN tag, and make the physical switch agree with that choice.

Last updated: 2026-08-03

The VM architecture keeps the packet path visible

Use a full Kernel-based Virtual Machine, not an LXC container. OpenWrt needs its own kernel, firewall state, modules, and network devices. A privileged container can be made to work, but then the host kernel becomes part of every router problem.

The clean layout has separate virtual paths:

• A WAN bridge connects OpenWrt to the modem or upstream router.
• A LAN bridge connects OpenWrt to your local switch or internal virtual network.
• A management bridge keeps the Proxmox interface away from the WAN.
• Virtio network cards connect the VM to those bridges.

This design suits a home lab, branch router, test gateway, or virtual network where brief host downtime is acceptable. It also gives you snapshots and console access.

However, the router now depends on the Proxmox host. A host reboot takes the network with it. If that failure model is unacceptable, buy a dedicated router and keep the VM as a lab target.

How should you set up OpenWrt on Proxmox with OVMF, virtio, and VLANs?

Use OVMF with an EFI image, attach the raw OpenWrt disk through VirtIO SCSI, and select virtio for every network card. Then decide who owns each VLAN tag before configuring the bridge.

Do not troubleshoot all six layers at once. If OpenWrt reaches its login prompt, OVMF has done its job. If the virtio interfaces appear, the virtual hardware has done its job. Everything after that is bridges, tags, firewall policy, or the switch.

The reliable OpenWrt install sequence

Download the combined EFI ext4 image from the official OpenWrt x86/64 download target. For the documented 24.10.5 release, the filename is openwrt-24.10.5-x86-64-generic-ext4-combined-efi.img.gz. Future releases change the version, so check the live download directory rather than copying an old URL.

The important suffix is generic-ext4-combined-efi.img.gz. Use the EFI variant with OVMF. Ext4 also gives the VM a writable root filesystem without the overlay arrangement used by squashfs images.

Then prepare the image on the Proxmox host:

gzip -dk openwrt-24.10.5-x86-64-generic-ext4-combined-efi.img.gz
qemu-img info openwrt-24.10.5-x86-64-generic-ext4-combined-efi.img

The first command decompresses the image while keeping the download. The second confirms that Proxmox is about to import a raw disk rather than the compressed archive. Importing the .gz file is a common way to build a VM that goes straight to the firmware shell.

Create the VM without an operating system disk or installation ISO. Select OVMF, add an EFI variables disk, and leave Secure Boot disabled unless you have built a signed boot chain.

Next, import the raw image:

VMID='<vm-id>'
IMAGE='/path/to/openwrt-x86-64-generic-ext4-combined-efi.img'
STORAGE='<proxmox-storage>'

qm importdisk "$VMID" "$IMAGE" "$STORAGE"

Check the command output. It tells you the volume name and shows the imported disk as unused hardware on the VM.

Open the VM Hardware page, attach that unused disk through SCSI, and select the VirtIO SCSI controller. Set the imported disk first in the boot order. Do not add another empty boot disk and then wonder why OpenWrt never appears.

If you enlarge the virtual disk, remember that this changes only the outer disk size. The OpenWrt partition and filesystem still need to be extended from inside the guest. qemu-img resize does not grow a filesystem by goodwill.

OVMF is firmware, not a networking fix

Use OVMF for a VM you plan to keep. Proxmox selects it with the ovmf BIOS setting, while the EFI variables disk is configured separately as efidisk0.

OVMF gives the guest modern Unified Extensible Firmware Interface, or UEFI, boot. It also keeps the configuration aligned with the combined EFI OpenWrt image. Legacy BIOS remains valid for an older non-EFI image. Mixing firmware and image types sends you into the wrong debugging branch.

An OVMF EFI variables disk can use efitype=2m or efitype=4m. The smaller type is the default, while the larger one is required for Secure Boot. Pre-enrolled keys are disabled by default and enable Secure Boot only when used with the larger EFI type.

Leave those Secure Boot controls alone unless you know which keys sign the guest boot path. Selecting OVMF does not require Secure Boot.

More importantly, OVMF cannot repair a missing VLAN, a bad bridge, or swapped WAN and LAN interfaces. Once the kernel boots, stop changing firmware.

Virtio is the right virtual hardware

Choose virtio for each network card. Proxmox documents virtio as its highest-performing virtual network model with very low CPU overhead. Emulated E1000 or Realtek cards add work without solving a real compatibility problem here.

Attach one virtio NIC to each bridge the router needs:

qm set "$VMID" --net0 virtio,bridge=vmbr-wan
qm set "$VMID" --net1 virtio,bridge=vmbr-lan
qm config "$VMID"

The first two commands attach virtio NICs to the WAN and LAN bridges. The final command prints the resulting VM configuration, including each MAC address. Save those addresses before assigning OpenWrt interfaces.

Inside OpenWrt, run:

ip -br link
ip -br addr

The first command lists the interfaces and their state. The second shows which addresses OpenWrt assigned. Match interfaces to the Proxmox MAC addresses instead of assuming the first Ethernet name must be LAN.

That mapping matters after you remove, reorder, or recreate virtual hardware. Interface names are labels. MAC addresses tell you which virtual cable you actually connected.

WAN and LAN bridges stay separate

Give the WAN its own Proxmox bridge. Attach one physical port facing the modem or upstream network, then attach only the OpenWrt WAN NIC to that bridge.

Do not assign the Proxmox host an address on the WAN bridge. The hypervisor does not need to answer there, and its management interface certainly does not belong beside an untrusted uplink.

A minimal bridge shape looks like this:

auto vmbr-wan
iface vmbr-wan inet manual
 bridge-ports <wan-physical-port>

auto vmbr-lan
iface vmbr-lan inet manual
 bridge-ports <lan-physical-uplink>

The WAN bridge passes frames between the physical port and the router VM. The LAN bridge reaches your switch, other guests, or both.

Meanwhile, keep Proxmox management on a separate bridge or a deliberately isolated management VLAN. Reusing one bridge for everything saves a few lines of configuration and removes the boundary you built the router to enforce.

If the WAN connects directly to a modem, avoid placing other guests on that bridge. Some upstream networks hand an address to whichever MAC asks first. The winner may not be your router.

A VLAN-aware bridge passes trunks without guessing

Enable VLAN awareness only on a bridge that must carry tagged traffic. In /etc/network/interfaces, the key setting is bridge-vlan-aware yes.

A trunk bridge can use this shape:

auto vmbr-lan
iface vmbr-lan inet manual
 bridge-ports <lan-physical-uplink>
 bridge-vlan-aware yes
 bridge-vids <allowed-vlan-list>

The VLAN-aware setting turns on Linux bridge filtering. The allowed list limits which tags the bridge will carry. Check the Proxmox VE virtual machine documentation for the syntax supported by your installed release.

Do not enable VLAN awareness across every bridge because a screenshot showed the checkbox. A plain WAN bridge connected to an untagged modem does not gain anything from it.

After applying the bridge configuration, run:

bridge vlan show
bridge link
ip -s link show dev vmbr-lan

bridge vlan show prints membership, port VLAN identifiers, and untagged egress rules. bridge link shows the bridge ports. The final command gives you packet and error counters for the bridge.

One layer owns each VLAN tag

Pick one tagging model and keep it consistent. OpenWrt can own a trunk, or Proxmox can present access ports. Mixing those models produces packets with the wrong tag or an extra tag.

OpenWrt owns the trunk

Use this model when OpenWrt should route several VLANs over one virtio NIC.

• Make the Proxmox bridge VLAN-aware.
• Leave the VM NIC tag field empty.
• Pass the trunk unchanged to OpenWrt.
• Create the VLAN devices inside OpenWrt.
• Configure the physical switch uplink as a matching trunk.

This is the usual choice for a router VM. OpenWrt sees the tags, owns the VLAN interfaces, and applies firewall and Dynamic Host Configuration Protocol, or DHCP, policy to each network.

Proxmox owns the access VLAN

Use this model when the guest should receive untagged traffic from one VLAN.

• Set a VLAN tag on the Proxmox VM NIC.
• Treat the interface inside OpenWrt as untagged.
• Add more virtual NICs if OpenWrt needs more access VLANs.
• Keep the bridge VLAN-aware and allow the selected VLAN.

The Proxmox net[n] configuration supports a virtio model, bridge assignment, firewall control, and a VLAN tag. In this mode, that tag makes the VM-facing NIC act like an access port.

The recurring mistake is setting a Proxmox VM tag and then creating the same tagged subinterface inside OpenWrt. That is not extra isolation. It is two different layers modifying the same frame.

For the packet-level reasoning, read the VLAN tagging guide for homelabs.

Segmentation belongs in OpenWrt firewall zones

When OpenWrt owns the trunk, create one VLAN device and one logical interface for each network role. Common roles include trusted LAN, guests, Internet of Things devices, and management.

OpenWrt stores network device configuration in /etc/config/network. A generic x86 VM usually sees plain virtio Ethernet devices. So do not copy a Distributed Switch Architecture, or DSA, switch-port tutorial without checking the device model first. DSA uses bridge VLAN configuration to create VLANs on supported switch hardware.

A generic tagged device can follow this template:

config device 'guest_vlan'
 option type '8021q'
 option ifname '<lan-virtio-device>'
 option vid '<guest-vlan-id>'
 option name '<lan-virtio-device>.<guest-vlan-id>'

config interface 'guest'
 option device '<lan-virtio-device>.<guest-vlan-id>'
 option proto 'static'

Replace every placeholder with your actual interface and VLAN identifier. Then assign an address, create a DHCP scope in /etc/config/dhcp, and place the interface in its own zone in /etc/config/firewall.

Keep the policy explicit:

• Trusted LAN may reach selected internal services and the internet.
• Guest clients should reach the internet without reaching trusted systems.
• IoT devices should reach only the services they need.
• Management should reach Proxmox and OpenWrt administration, with no reverse access from untrusted zones.

Do not place several interfaces in the LAN firewall zone and call them segmented. Different subnets are not a security boundary when the firewall permits forwarding between them.

The physical switch must match the virtual design

The switch port facing the Proxmox LAN uplink must carry the same VLANs allowed by the Proxmox bridge. If OpenWrt owns the tags, configure that port as a trunk and leave the VM NIC untagged at the Proxmox level.

Ports facing ordinary clients are access ports. The switch removes the VLAN tag on egress and adds it on ingress based on the port's VLAN membership.

Native or untagged traffic needs special care. Both ends must agree on which VLAN, if any, crosses the trunk without a tag. If the switch treats untagged frames as one network while OpenWrt expects another, DHCP requests disappear into the wrong broadcast domain.

I prefer tagged traffic for routed user networks and a separate recovery path for management. An untagged management network can work, but document it. Six months later, "native VLAN" is usually the line nobody remembers changing.

The WAN switch port is different. A normal modem-facing port is untagged unless the provider requires a specific VLAN. Do not copy your LAN trunk settings onto the WAN side.

Passthrough only earns its cost for a concrete reason

Use bridged virtio networking unless you can name the feature that requires direct hardware. It keeps the VM portable, lets other guests share selected bridges, and leaves the Proxmox host in control of the physical NIC.

PCI passthrough gives the NIC directly to OpenWrt. The host loses that device, and the VM becomes tied to the machine's Input-Output Memory Management Unit, or IOMMU, layout and hardware.

Passthrough can make sense when:

• A required hardware feature is unavailable through a Linux bridge.
• You need stronger separation between the WAN NIC and the host network stack.
• A physical driver behaves badly on the Proxmox host but works in OpenWrt.
• You have measured a bridge bottleneck and traced it to the host path.

"Passthrough sounds faster" is not a requirement. First check interface counters, CPU use, packet steering, and offload behavior. The OpenWrt packet steering guide covers the guest-side tuning that matters after you have evidence.

Also, OVMF does not make passthrough work by itself. You still need IOMMU support, usable device groups, and a NIC the host can surrender.

Diagnose failures from the packet path

Start with the VM state, then move outward. Random changes across OpenWrt, Proxmox, and the switch destroy the evidence.

First, confirm firmware and virtual hardware:

qm config <vm-id>

Check the output for OVMF, the imported boot disk, the virtio NICs, their bridge assignments, and any Proxmox VLAN tag. If OpenWrt reaches a shell, firmware is no longer the suspect.

Next, inspect the Proxmox host:

ip -br link
bridge link
bridge vlan show
journalctl -b -u networking

That tells you whether the physical NICs, bridges, and VM tap interfaces exist and are up. The VLAN output shows whether the expected tag is allowed on each port.

Then inspect OpenWrt:

ip -br link
ip -d link show
ip -s link
logread -e netifd
ubus call network.interface dump
dmesg | grep -i virtio

ip -d link show exposes VLAN details. Interface counters show whether packets arrive but fail higher in the stack. netifd logs explain interface setup failures, while the kernel messages confirm that the virtio devices loaded.

Finally, capture on both sides of the bridge:

tcpdump -eni <physical-uplink>
tcpdump -eni <vm-tap-interface>

If the frame appears on the physical uplink but not the VM tap, blame the Proxmox bridge or VLAN filter. If it reaches the tap but not the OpenWrt VLAN interface, blame the guest VLAN setup. If it never reaches the physical uplink, check the switch.

Older OpenWrt releases install packet capture tools with opkg:

opkg update
opkg install tcpdump

OpenWrt 25.12.0 replaced the opkg package manager with apk, so a newer build uses:

apk update
apk add tcpdump

Do not swap one command for the other blindly. Check which release the VM runs first, then use the matching package tool. The official OpenWrt migration notes list the command changes.

The same configuration mistakes keep returning

A broken OpenWrt on Proxmox setup is usually one wrong assumption repeated across three devices.

WAN and LAN share a bridge. This leaks broadcast traffic across the boundary and can expose internal systems upstream. Give them separate bridges.

The VM NIC has a Proxmox tag and OpenWrt tags the same traffic. Pick access mode or trunk mode. Do not combine them on one NIC.

The bridge is not VLAN-aware. Tagged frames reach the host, then disappear at bridge filtering. Check bridge vlan show.

The switch native VLAN does not match. Untagged DHCP traffic lands in a different network from the one OpenWrt serves. Compare the switch port configuration with the bridge and guest.

WAN and LAN interfaces were identified by name. Match MAC addresses from qm config against ip -br link.

The Proxmox management address sits on the WAN bridge. Move management to its own bridge or controlled VLAN before exposing the uplink.

A copied DSA configuration is applied to x86 virtio devices. Read /etc/config/network and identify the actual device type first.

Firmware gets blamed after Linux has booted. Once the OpenWrt kernel sees its disk and NICs, OVMF is finished. Follow the frame instead.

A clean OpenWrt on Proxmox build is reproducible because every packet has one documented path. The bridge, guest, and switch either agree on that path or the counters show where it stopped.

FAQ

Does an OpenWrt VM need the Q35 machine type?

No, not for ordinary bridged routing. Use the default machine type unless a passthrough device or firmware requirement gives you a reason to choose Q35. Changing machine type during a network fault adds another variable and tells you nothing about the missing frame.

Can OpenWrt start automatically after a Proxmox reboot?

Yes. Enable automatic startup for the VM and place it after any storage or infrastructure guests it needs. Then confirm that the physical bridges exist before the VM starts and that OpenWrt retries its WAN connection when the upstream device returns.

Keep console access available. A router that starts automatically with a bad LAN configuration is still unreachable automatically.

Should I snapshot OpenWrt before an upgrade?

Take a disk snapshot or backup before changing packages, firewall rules, or the system image. However, do not treat a snapshot as the only copy of your configuration. Export /etc/config as well, because that remains useful if you rebuild the VM on different storage.

After restoring, check MAC addresses and interface assignments. A restored router with different virtual NICs may boot cleanly while routing through the wrong side.

Can one physical NIC carry both WAN and LAN?

It can if a managed switch keeps the WAN and LAN VLANs separate all the way to the host. I would not use that layout for a main household gateway unless hardware leaves no alternative.

One bad trunk or native VLAN change can join the untrusted uplink to the internal switch fabric. Separate physical WAN and LAN ports make the failure easier to see and harder to create.

Related on this blog

• Enable eBPF on OpenWrt: Kernel Config Guide

Related: Build OpenWrt Access Points Without Wireless Mesh

Related: Build a Linux Bridge Safely With Ip or NetworkManager