OpenWrt on Proxmox VE: a virtual router on a mini PC — install, networking and upgrades

This guide shows how to install OpenWrt on Proxmox VE and turn a mini PC running Proxmox into a full home router: OpenWrt runs in a virtual machine, provides internet access and DHCP, and the same hardware still has room for other VMs and containers, such as Home Assistant on Proxmox. Proxmox must already be installed — see the official documentation.

Script card in the catalog: OpenWrt VM · all Proxmox scripts (RU mirrors / GitFlic).

The guide is updated for Proxmox VE 9.2 and OpenWrt 25.12.5. Screenshots were taken on Proxmox 7.4 and OpenWrt 22.03, but the relevant menus have barely changed. My hardware is an N5105 mini PC with four network ports; for heavier workloads a mini PC with an Intel i5–i7 is a good choice. Everything here also applies to a regular x86 (Intel/AMD) PC or server.

The main change from the first version of this guide is the network layout. Previously Proxmox was moved to an internal bridge with no physical ports, so if OpenWrt failed to boot you lost access to Proxmox. Now Proxmox stays reachable through the LAN ports even when the router VM is down.

What you need

• an x86 mini PC or server with two or more network ports (or one port plus a USB Ethernet adapter);
• Proxmox VE 8 or 9 already installed;
• for the OpenWrt VM — 1–2 cores, 512 MB of RAM and 2 GB of disk;
• a laptop with an Ethernet port for the initial setup;
• 30–40 minutes if you follow the steps in order.

Network layout and order of steps

• vmbr0 — the WAN bridge with port enp2s0, where the ISP cable goes. Proxmox has no IP address on this bridge, so it is not reachable from the internet.
• vmbr1 — the LAN bridge with the remaining ports (enp3s0 enp4s0 enp5s0). It acts as a switch connecting the OpenWrt LAN, Proxmox itself and other VMs and containers — for example a Jellyfin LXC where you can mount an SMB network share.
• OpenWrt: the VM’s first NIC (eth0) is attached to vmbr1 and becomes LAN, the second (eth1) to vmbr0 and becomes WAN. This is the default interface assignment of OpenWrt for x86, so nothing needs remapping.

Your port names may differ — check them in pve → System → Network. The order of steps matters:

1. While the mini PC is still connected to your old router via enp2s0, create the vmbr1 bridge and the OpenWrt VM. Proxmox keeps its current address.
2. Connect a laptop to a LAN port of the mini PC and configure OpenWrt: password, disk, language.
3. Move the Proxmox address to vmbr1.
4. Only then plug the ISP cable into enp2s0 and switch the old router to access point mode.

The OpenWrt subnet must differ from the old router’s subnet. OpenWrt defaults to 192.168.1.1 — if your old router uses the same address, change the OpenWrt LAN to e.g. 192.168.2.1 (see the first boot section). The examples below use 192.168.1.1 for OpenWrt and 192.168.1.2 for Proxmox.

The vmbr1 LAN bridge

Open pve → System → Network. Proxmox created vmbr0 with the first port during installation — leave it alone for now.

Click Create → Linux Bridge. Name — vmbr1, leave IPv4 and gateway empty, and in Bridge ports list all remaining ports separated by spaces: enp3s0 enp4s0 enp5s0. The screenshot shows a single port — you will have several.

Click Apply Configuration. Before that, back up the network config in pve → Shell — you will need it if something goes wrong:

cp /etc/network/interfaces /etc/network/interfaces.bak

Creating the OpenWrt virtual machine on Proxmox

Pick one of three ways. The fastest is a single command in the Proxmox shell; the web UI takes longer but shows every step.

Option 1: commands in the Proxmox shell

Open pve → Shell or SSH into Proxmox and download the image. You need the generic-ext4-combined.img.gz file from targets/x86/64 on downloads.openwrt.org:

# Check the current release on downloads.openwrt.org
VER=25.12.5
cd /root
wget https://downloads.openwrt.org/releases/$VER/targets/x86/64/openwrt-$VER-x86-64-generic-ext4-combined.img.gz
# The "trailing garbage ignored" warning is expected
gunzip -f openwrt-$VER-x86-64-generic-ext4-combined.img.gz
mv openwrt-$VER-x86-64-generic-ext4-combined.img openwrt.img

Create the VM: the command imports the image as a disk, attaches the NICs in the right order and enables a serial console. Unlike the regular noVNC console, pasting text works there.

# VM ID — any free number
VMID=100
qm create $VMID --name openwrt --ostype l26 
  --cpu host --cores 2 --memory 512 
  --scsihw virtio-scsi-single 
  --scsi0 local-lvm:0,import-from=/root/openwrt.img 
  --boot order=scsi0 
  --net0 virtio,bridge=vmbr1 
  --net1 virtio,bridge=vmbr0 
  --serial0 socket --vga serial0 
  --onboot 0
# 2 GB disk: room for packages and upgrades
qm disk resize $VMID scsi0 2G
qm start $VMID

--onboot 0 keeps autostart off for now. If something is wrong with the VM (for example after PCI passthrough), autostart can hang the whole server. Enable it once you are sure everything works: qm set 100 --onboot 1. If your storage is not called local-lvm, change the name in --scsi0.

Option 2: the Proxmox web UI

Click Create VM in the top right corner. Enter a name and a free VM ID, and tick Advanced. Leave “Start at boot” off for now (it is ticked on the screenshot), for the same reason as in option 1.

On the OS tab choose Do not use any media, leave the System tab as is. On the Disks tab set the minimum size — we will replace this disk with the OpenWrt image.

CPU: type host (performance is noticeably lower without it), 1–2 cores. Memory: 512 MB is enough, 1024 MB if you plan many packages.

Network: choose bridge vmbr1 (this will be LAN) and untick Firewall — the OpenWrt firewall handles filtering. The screenshot from the first version of this guide shows vmbr0.

Finish the wizard. In the VM’s Hardware section detach the empty hard disk, then remove the resulting “Unused Disk 0”.

Download and unpack the image with the commands from option 1 (the wget block), then import it into the VM — replace 100 with your VM ID:

qm disk import 100 /root/openwrt.img local-lvm

“Unused Disk 0” appears in Hardware. Open it and click Add, bus — SCSI.

Add a second NIC: Add → Network Device, bridge vmbr0 (this will be WAN), firewall off.

In Options → Boot Order enable the imported disk and drag it to the top.

For a console where pasting works, add Add → Serial Port (number 0) and set Display to “Serial terminal 0”. Grow the disk to 2 GB: Hard Disk → Disk Action → Resize, add 2 GB.

Start the VM with the Start button.

Option 3: the community-scripts helper

The OpenWrt VM script from the Proxmox VE Helper-Scripts project automates almost all of the above. It is what I use myself now — when the first version of this guide was written it did not work. Run it in the Proxmox shell (pve → Shell):

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/vm/openwrt-vm.sh)"

What the script does:

• detects the current stable OpenWrt release and downloads the official generic-ext4-combined image;
• creates the VM, imports the image and makes it the boot disk;
• boots the VM and types the network setup commands into its console: eth0 as LAN with a static address, eth1 as WAN via DHCP;
• attaches the first NIC to the LAN bridge and the second to the WAN bridge — the same as in our layout.

Choose Advanced — the defaults do not fit our layout:

• WAN Bridge = vmbr0, LAN Bridge = vmbr1. By default both are vmbr0, which puts the OpenWrt LAN and its DHCP server into your old router’s network;
• Router IP — the OpenWrt LAN address, 192.168.1.1 by default. If your old router uses the same subnet, pick another, e.g. 192.168.2.1;
• Disk Size = 2 (the default 1 GB is too small for owut upgrades with a 1024 MB root partition);
• CPU Cores = 2 and RAM = 512 — the defaults of 1 core and 256 MB are tight for a router with a few packages;
• leave VLAN and MTU empty unless you know you need them.

My notes on the script:

• Autostart is always enabled. Until you have checked that everything works, turn it off: qm set 100 --onboot 0 (use the ID the script chose instead of 100).
• The CPU type is not host. Change it: qm set 100 --cpu host, then restart the VM.
• No root password is set and the root partition is not expanded — the disk grows, but OpenWrt still sees 104 MB. Do these steps manually as described below.
• The script is downloaded from the internet and runs as root. The project is popular and open source, but it is worth reading the source code before running it.
• While the script is typing commands into the VM console, do not open that console or press anything in it — the input will get mixed up.

After the script, continue with the first boot section: the LAN address is already set; the password, disk expansion and language remain.

First boot: LAN address and password

Open the VM Console and press Enter.

If the OpenWrt subnet matches your old router’s subnet, change the LAN address:

# Replace 192.168.2.1 with your address
uci set network.lan.ipaddr='192.168.2.1'
uci set network.lan.netmask='255.255.255.0'
uci commit network
/etc/init.d/network restart

Set the root password — without it anyone can log into the web UI and SSH:

passwd

Connect a laptop to any LAN port of the mini PC (enp3s0–enp5s0): it gets an address via DHCP from OpenWrt. Open http://192.168.1.1 (or the address you set) and log in as root. The OpenWrt WAN currently gets its address from the old router, so the VM already has internet access.

You can also change the password in the web UI: System → Administration → Router Password. The LAN address is changed in Network → Interfaces → lan → Edit — enter it with the prefix, e.g. 192.168.1.1/24.

Expanding the OpenWrt disk

The VM disk is already 2 GB, but the OpenWrt root partition is still about 104 MB — it has to be grown to use the free space. SSH into OpenWrt (e.g. with Tabby: LAN address, port 22, user root) or use the Proxmox serial console where pasting works.

# Packages (OpenWrt 25.12 and newer)
apk update
apk add parted losetup resize2fs

# Grow partition 2 to the whole disk
parted -f -s /dev/sda resizepart 2 100%

# Grow the filesystem
losetup /dev/loop1 /dev/sda2
resize2fs -f /dev/loop1
reboot

On OpenWrt 24.10 replace the first two commands with opkg update and opkg install parted losetup resize2fs: the apk package manager arrived in 25.12. Do not allocate more than 2 GB — shrinking a disk is much harder than growing it.

Web UI language

LuCI is in English by default. Other languages are installed as luci-i18n-base-<lang> packages, for example Russian:

apk update
apk add luci-i18n-base-ru

Or in the web UI: System → Software, Update lists…, type the package name in the filter and click Install. Refresh the page afterwards.

Moving Proxmox into the LAN and switching the ISP cable

Proxmox still gets its address from the old router via vmbr0. Let’s move it to vmbr1, behind OpenWrt. Make sure /etc/network/interfaces.bak exists and your laptop is connected to a LAN port of the mini PC.

In pve → System → Network open vmbr0 and clear IPv4/CIDR and Gateway.

Open vmbr1 and set IPv4/CIDR 192.168.1.2/24 and gateway 192.168.1.1 — the OpenWrt address. The screenshot shows the bridge as vmbr99; in our layout it is vmbr1.

Click Apply Configuration. The connection to the old address drops — open https://192.168.1.2:8006 from the laptop on the LAN port. Then fix two more things: set DNS to 192.168.1.1 in System → DNS, and in System → Hosts replace the old IP on the server name line with 192.168.1.2.

Now switch the cables:

• ISP cable — into enp2s0 (WAN). If your ISP uses PPPoE, choose the PPPoE protocol in Network → Interfaces → wan → Edit and enter the credentials from your contract. If the ISP binds access to a MAC address, set the old MAC on the eth1 device (Network → Interfaces → Devices);
• old router — cable from one of its LAN ports to a LAN port of the mini PC. Disable its DHCP server and give it a free address in the new subnet, e.g. 192.168.1.3. It will then work as a Wi-Fi access point;
• other devices — into the LAN ports of the mini PC or of the old router.

Once everything works, enable OpenWrt autostart: qm set 100 --onboot 1 or the “Start at boot” option in Options.

If you lose access to Proxmox

• OpenWrt is off or does not boot. Proxmox is still reachable through the LAN ports: give your laptop a static address 192.168.1.10, mask 255.255.255.0, plug into a LAN port and open https://192.168.1.2:8006.
• After a network change Proxmox is unreachable at any address. Connect a monitor and keyboard to the mini PC, log in as root and restore the backup with the commands below.
• The server hangs when the VM starts. This is usually PCI passthrough. Disable VM autostart (qm set 100 --onboot 0) and remove the passed-through device.

# Restore the Proxmox network config from the backup
cp /etc/network/interfaces.bak /etc/network/interfaces
ifreload -a

Upgrading OpenWrt on Proxmox

The main advantage of a virtual router is snapshots. Take a VM snapshot before any upgrade: if something breaks, rolling back takes seconds. Also save your settings in System → Backup / Flash Firmware → Generate archive.

The easiest way to upgrade is owut: it builds an image of the new release with your packages and settings. The --rootfs-size 1024 option matters: without it the root partition is back to 104 MB after the upgrade. The image builder service does not support more than 1024 MB.

# On Proxmox: snapshot before upgrading
qm snapshot 100 pre_upgrade

# In OpenWrt: upgrade keeping packages and settings
apk update
apk add owut
owut check
owut upgrade --rootfs-size 1024

# If something goes wrong — roll back on Proxmox
qm rollback 100 pre_upgrade

For major version jumps (e.g. 24.10 to 25.12, where the package manager changed) it is safer to create a new VM from a fresh image and restore your settings archive there, keeping the old VM powered off as a fallback. Details are in the OpenWrt x86 documentation.

Performance

• CPU type host and VirtIO NICs — already set above, and they matter most.
• Multiqueue. In each VM NIC (Hardware → Network Device → Advanced) set Multiqueue to the number of VM cores so all cores handle traffic, not just one.
• NIC passthrough (PCI passthrough). For gigabit and faster links you can hand the WAN port to the VM entirely. It needs IOMMU (VT-d) enabled in BIOS and the port in its own IOMMU group — see the Proxmox documentation. Never pass through the port you use to manage Proxmox, and keep autostart off until you have checked that the VM boots.

Alternative: one bridge per port

In the first version of this guide every physical port got its own bridge (vmbr1, vmbr2, vmbr3), each attached to the VM as a separate NIC and joined inside OpenWrt in the br-lan bridge. This lets OpenWrt control each port individually: you can move a port to a guest network or VLAN. The downside is a more complex setup and a higher risk of losing access: if Proxmox sits on a bridge without a physical port, you cannot reach it while OpenWrt is down. If you choose this layout, keep at least one port in the bridge shared with Proxmox.

FAQ