Guides
OpenWRT
Building and Emulating OpenWRT with QEMU

Building and Emulating OpenWRT with QEMU

June 25, 2025·Niranjan V Ram
Niranjan V Ram

1. Set Up the OpenWRT Build Environment

Install Required Dependencies (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install build-essential clang flex bison g++ gawk gcc-multilib g++-multilib gettext git libncurses5-dev libssl-dev python3-setuptools rsync swig unzip zlib1g-dev file wget

Install QEMU:

sudo apt-get install qemu-system

2. Download and Prepare OpenWRT Source

Clone the OpenWRT Repository:

git clone git@github.com:openwrt/openwrt.git
git clone https://github.com/openwrt/openwrt.git

Update and Install Feeds:

cd openwrt
./scripts/feeds update -a
./scripts/feeds install -a

3. Configure and Build the Image

Launch configuration menu:

make menuconfig

Set the following:

  • Target System: x86
  • Subtarget: x86_64
  • Target Profile: Generic x86/64

Exit and save. This generates the .config file.

Build the image:

make -j4 V=s

Replace 4 with the number of available CPU cores.
V=s enables verbose output.

4. Run the OpenWRT Image in QEMU

  1. Unpack the Image
cd openwrt/bin/targets/x86/64
gunzip openwrt-x86-64-generic-ext4-combined-efi.img.gz
  1. Launch OpenWRT in QEMU
qemu-system-x86_64 -machine q35 -drive file=openwrt-x86-64-generic-ext4-combined-efi.img,format=raw
qemu-system-x86_64 -machine q35 -drive file=openwrt-x86-64-generic-ext4-combined-efi.img,format=raw \
-device virtio-net,netdev=net0 -netdev user,id=net0,net=192.168.1.0/24,hostfwd=tcp:127.0.0.1:1122-192.168.1.1:22
qemu-system-x86_64 -machine q35 -drive file=openwrt-x86-64-generic-ext4-combined-efi.img,format=raw \
-device virtio-net,netdev=net0 -netdev user,id=net0,net=192.168.1.0/24,hostfwd=tcp:127.0.0.1:1122-192.168.1.1:22 \
-device virtio-net,netdev=net1 -netdev user,id=net1,net=192.168.2.0/24
  1. To enable Internet access in the QEMU instance, add the following content to the /etc/config/network file:
/etc/config/network
config interface 'wan'
  option device 'eth1'
  option proto 'dhcp'
  1. Then reboot the VM:
reboot

5. Optional: Shell Script to Launch QEMU

launch_qemu.sh
#!/bin/bash
QEMU_BIN=$(which qemu-system-x86_64)
CURR_DIR=$(pwd)

# Define location of launch image
OPENWRT_BIN="~/Desktop/openwrt/bin/targets/x86/64"

# Move to location of OpenWRT's bin
# cd $OPENWRT_BIN

# Define location of image
OPENWRT_IMG="$OPENWRT_BIN/openwrt-x86-64-generic-ext4-combined-efi.img"

# Extract image file from compressed file
# gunzip "$OPENWRT_IMG.gz"
# cd "$CURR_DIR"/

# Add QEMU's binary file location
# QEMU_CMD="$QEMU_BIN"

# Add QEMU command
QEMU_CMD="qemu-system-x86_64"

# Allocate memory to the QEMU system
QEMU_CMD+=" -m 512"

# To launch the instance in same terminal
QEMU_CMD+=" -nographic"

# Speify number of CPUs to be used
# QEMU_CMD+=" -smp 1"

# Specify image file to be launched
QEMU_CMD+=" -drive file=$OPENWRT_IMG,format=raw"

# QEMU_CMD+=" -nic user"
# QEMU_CMD+=" -device e1000,netdev=net0 -netdev user,id=net0,hostfwd=tcp::5555-:22"
# QEMU_CMD+=" -nic hostfwd=tcp::1122-:22"
# QEMU_CMD+=" -netdev user,id=network0 -device e1000,netdev=network0,mac=52:54:00:12:34:56"

# For LUCI
QEMU_CMD+=" -device virtio-net,netdev=net0 -netdev user,id=net0,net=192.168.1.0/24,hostfwd=tcp:127.0.0.1:1122-192.168.1.1:22,hostfwd=tcp:127.0.0.1:8080-192.168.1.1:80"
QEMU_CMD+=" -device virtio-net,netdev=net1 -netdev user,id=net1,net=192.168.2.0/24"

# For normal use case, comment everything below this line

# For having SSH and SCP only
# QEMU_CMD+=" -device virtio-net,netdev=net0 -netdev user,id=net0,net=192.168.1.0/24,hostfwd=tcp:127.0.0.1:1122-192.168.1.1:22"

# For having internet access
# QEMU_CMD+=" -device virtio-net,netdev=net0 -netdev user,id=net0,net=192.168.1.0/24,hostfwd=tcp:127.0.0.1:1122-192.168.1.1:22"
# QEMU_CMD+=" -device virtio-net,netdev=net1 -netdev user,id=net1,net=192.168.2.0/24"

# Launch QEMU instance in same terminal
# QEMU_CMD+=" -nographic"

# QEMU_CMD+=" -drive file=overlay.qcow2,if=virtio,format=qcow2"
 
eval $QEMU_CMD
ℹ️

Notes:

  • Use this to SSH into the instance:
    ssh -p 1122 root@localhost
  • Use this to copy a file via SCP:
    scp -P 1122 -O ~/Desktop/sample.txt root@localhost:~
Creating a Custom RPCD Service in OpenWRTSet Up an Init Program for OpenWrt in QEMU