Skip to content

How to turn your OpenWRT router into a PXE server for hardware installations from your couch

So I have a custom made NAS at home which was running with debian and ZFS. I wanted to switch the OS to Ubuntu for reasons that are not important for this post. The NAS is buried in a closet, it has no out of band management/ipmi and I didn't want to hassle with USB-Sticks/ISOs anymore.

I have some experience with provisioning VMs and Baremetal via Foreman. I won't go into too much detail: In principal you give Foreman some control over a subnet by providing a dhcp and tftp server with hosts (MACs and IPs) you want to provision and what kind of OS you want to install. Foreman will then put the right files on the tftp server and setup a lease that boots an pxe image. Further more Foreman provides preseeds, kickstart or cloud-init configuration so you don't have to do anything.

Foreman does a good job at unattended installations but Foreman is no option for my home environment. It's a heavy application with so many configurations to do before hand, so a total overkill. Besides that there is no suitable host to install it, I have my OpenWRT router, PC and a laptop.

So the idea is to use my router for pxe boot and do an attended installation for now. This requires a USB-Stick for storing the pxe images, tftp for serving them and dnsmasq to provide them to PXE network booting hosts.

USB Stick preparation

I used a spare USB-Stick that I formated with ext4 and lableing the partition tftp.

mkfs.ext4 -L tftp /dev/sdXX

Replace /dev/sdXX with your partition path. ie /dev/sdc1

OpenWRT preparation

This was done on OpenWRT Version 19.07

opkg update
opkg install usbutils kmod-usb-storage block-mount kmod-fs-ext4 wget
mkdir -p /mnt/usb/

wget package is needed because the dropbear version does not support SSL

Mount USB-Stick reboot persistent

uci set fstab.@mount[0].label=tftp
uci set fstab.@mount[0].target=/mnt/usb
uci set fstab.@mount[0].options=noatime,nodiratime
uci commit

block mount

Get PXE images

Instead of pulling each OS image individually I use is basically a menu wrapper for all kinds of operating systems.

cd /mnt/usb/
# Legacy (PCBIOS) iPXE Bootloaders
wget --no-check-certificate
# UEFI iPXE Bootloaders
wget --no-check-certificate

Configure dnsmasq

Unfortunately I was only able to set one bootfile.

The documentation states that multiple entries should be possible. This didn't work for me =(

uci set dhcp.@dnsmasq[0].enable_tftp=1
uci set dhcp.@dnsmasq[0].tftp_root=/mnt/usb/
uci set dhcp.@dnsmasq[0]
uci commit
/etc/init.d/dnsmasq restart


After booting via my NAS' network interface I was greeted by the installer menu. This was much easier than expected. Even tho many documentations seems outdated.

Next thing will be unattended installations. Ubuntu switched from preseed to autoinstall which is basically cloud-init which looks promissing.

The OpenWRT tftp pxe user guide seems outdated

Last update: March 26, 2021