My OpenWrt firmware image build guide

This method is NOT OFFICIALLY supported. A native GNU/Linux environment is recommended.

Build guide mainly based on an old revision of OpenWrt document "Quick Image Building Guide".

1. Prerequisites

A suitable case-sensitive file system.
Last tested on WSL2 (Windows Version 10.0.19044.1586) with Debian GNU/Linux 11 (bullseye).

Click to display more info

Click to hide the extra info

See Windows version information with cmd.exe command: 

ver

See Debian version information with Debian command: 

cat /etc/os-release

:!: Mind issue with path!

1.1 Download package information

Debian terminal command: 

sudo apt update

Click to display more info

Click to hide the extra info

After downloading package information (update), optional install available upgrades (upgrade) with Debian terminal commands: 

sudo apt update
sudo apt upgrade

Or with one Debian terminal command: 

sudo apt update && sudo apt upgrade

Other commands (e.g. upgrade) operate on package information (update).

Optional, remove obsolete packages with Debian terminal command: 

sudo apt autoremove


Description see Debian apt manpage.
:?: What about “sudo apt dist-upgrade”?

1.2 Install required dependencies

See examples of package installations.
:!: Verify link and required packages!

Click to display more info

Click to hide the extra info

If package list information is not downloaded (step 1.1), message can be:
E: Unable to locate package

1.3 Leave privileged mode

Debian terminal command: 

exit

2. Get OpenWrt source code

2.1 Clone repository

For OpenWrt 19.07 Debian terminal command: 

git clone -b openwrt-19.07 --single-branch https://git.openwrt.org/openwrt/openwrt.git openwrt_19.07

For OpenWrt 21.02 Debian terminal command: 

git clone -b openwrt-21.02 --single-branch https://git.openwrt.org/openwrt/openwrt.git openwrt_21.02

Click to display more info

Click to hide the extra info

This is to clone an specific OpenWrt branch/head (-b openwrt-19.07 --single-branch or -b openwrt-21.02 --single-branch) in a new directory (openwrt_19.07 or openwrt_21.02).
See Debian git clone manpage, the OpenWrt source code repositories and difference snapshots, releases and branches.

If dependency is not installed (step 1.2), message can be:
-bash: git: command not found
If trying Debian terminal command second time, message can be one of these:
fatal: destination path 'openwrt_19.07' already exists and is not an empty directory.
fatal: destination path 'openwrt_21.02' already exists and is not an empty directory.

2.2 Change working directory

For OpenWrt 19.07 Debian terminal command: 

cd openwrt_19.07

For OpenWrt 21.02 Debian terminal command: 

cd openwrt_21.02

Click to display more info

Click to hide the extra info

See Debian cd manpage.

If repository is not cloned (step 2.1), message can be one of these:
-bash: cd: openwrt_19.07: No such file or directory
-bash: cd: openwrt_21.02: No such file or directory

2.3 Update local branch

If there is a new release in the branch, update local branch repository with Debian terminal command: 

git pull

Click to display more info

Click to hide the extra info

See Debian git pull manpage.

2.4 Select version

For OpenWrt 19.07 Debian terminal command: 

git checkout v19.07.8

For OpenWrt 21.02 Debian terminal command: 

git checkout v21.02.3

Click to display more info

Click to hide the extra info

See Debian git checkout manpage.

List branches (tags) with Debian terminal command: 

git tag -l

See Debian git tag manpage.

Show current branch (highlighted in green and marked with an asterisk) with Debian terminal command: 

git branch

See Debian git branch manpage.
Or show working tree status with Debian terminal command: 

git status

See Debian git status manpage.

2.5 Update and install feeds

Debian terminal command: 

./scripts/feeds update -a && ./scripts/feeds install -a

Click to display more info

Click to hide the extra info

If dependencies are not installed (step 1.2), messages can be:
Can't exec “make”: No such file or directory at ./scripts/feeds line 22.
Unsupported version of make found: make
Checking 'gcc'... failed.
Checking 'working-gcc'... failed.
Checking 'g++'... failed.
Checking 'working-g++'... failed.
Checking 'ncurses'... failed.
Checking 'awk'... failed.
Checking 'unzip'... failed.
Checking 'bzip2'... failed.
Checking 'wget'... failed.
Checking 'python'... failed.
Checking 'python3'... failed.
Checking 'file'... failed.
If directory is wrong (step 2.2), message can be:
-bash: ./scripts/feeds: No such file or directory

3. OpenWrt Configuration

Debian terminal command: 

make menuconfig

:?: What about “make defconfig”?

3.1 Configure target system

For router hardware select corresponding values in menu (:!: link to router hardware table):

  • “Target System” ⇒ “Select” ⇒ <target system> ⇒ “Select”
  • “Subtarget” ⇒ “Select” ⇒ <subtarget> ⇒ “Select”
  • “Target Profile” ⇒ “Select” ⇒ <target profile> ⇒ “Select”

Click to display more info about tested router hardware and relevant firmware image build information.

Click to hide table with tested router hardware and relevant build information.

Hardware Branch Target System Subtarget Target Profile Target directory
Belkin F5D8235-4 v1 21.02.0 MediaTek Ralink MIPS RT288x based boards Belkin F5D8235 V1 ramips\rt288x
D-Link DIR-615 rev D3 19.07.8 MediaTek Ralink MIPS RT3x5x/RT5350 based boards D-Link DIR-615 D ramips\rt305x
21.02.0 “bin is too big: 3932975 > 3866624”
TP-Link Archer MR200 v1.0 ? ? ? ? ?
TP-Link TL-WA730RE v1 19.07.8 Atheros ATH79 (DTS) Devices with small flash TP-LINK TL-WA730RE v1 ath79\tiny
21.02.0 “images are too big by 306444 bytes”
Ubiquiti UniFi AP-LR 21.02.2 Atheros ATH79 Generic Ubiquiti UniFi ath79\generic
Ubiquiti UniFi AP AC Pro 21.02.3 Atheros ATH79 Generic Ubiquiti UniFi AC Pro ath79\generic

3.2 Options

Maybe add “LuCI”:

  • “LuCI” ⇒ “Select” ⇒ “Collections” ⇒ “Select” ⇒ on “luci” press <Y> to include (= “*” built-in) ⇒ “Exit” ⇒ “Exit”

Maybe remove some packages to save space.
- remove “PPP daemon”:

  • “Network” ⇒ “Select” ⇒ on “ppp” press <N> to exclude (= “ ” excluded) ⇒ “Exit”

- remove “IPv6 support”:

  • “Global build settings” ⇒ “Select” ⇒ on “Enable IPv6 support in packages” press <N> to exclude (= “ ” excluded) ⇒ “Exit”

Maybe make WPA2 Enterprise with wpa_supplicant available by:
- remove “wpad-mini”:

For OpenWrt 19.07:

  • “Network” ⇒ “Select” ⇒ on “wpad-mini” press <N> to exclude (= “ ” excluded) ⇒ “Exit”

For OpenWrt 21.02:

  • “Network” ⇒ “Select” ⇒ “WirelessAPD” ⇒ “Select” ⇒ on “wpad-basic-wolfssl” press <N> to exclude (= “ ” excluded) ⇒ “Exit” ⇒ “Exit”

- add “wpad”:

For OpenWrt 19.07:

  • “Network” ⇒ “Select” ⇒ on “wpad” press <Y> to include (= “*” built-in) ⇒ “Exit”

For OpenWrt 21.02:

  • “Network” ⇒ “Select” ⇒ “WirelessAPD” ⇒ “Select” ⇒ on “wpad” press <Y> to include (= “*” built-in) ⇒ “Exit” ⇒ “Exit”

Maybe add load balancing/failover with multiple WAN interfaces.
- add “MAC-VLAN support”:

  • “Kernel modules” ⇒ “Select” ⇒ “Network Devices” ⇒ “Select” ⇒ on “kmod-macvlan” press <Y> to include (= “*” built-in) ⇒ “Exit” ⇒ “Exit”

- add “LuCI support for the MWAN3 multiwan hotplug script”:

  • “LuCI” ⇒ “Select” ⇒ “3. Applications” ⇒ “Select” ⇒ on “luci-app-mwan3” press <Y> to include (= “*” built-in) ⇒ “Exit” ⇒ “Exit”

- or without LuCI, add “Multiwan hotplug script with connection tracking support”:

  • “Network” ⇒ “Select” ⇒ “Routing and Redirection” ⇒ “Select” ⇒ on “mwan3” press <Y> to include (= “*” built-in) ⇒ “Exit” ⇒ “Exit”

Maybe add network watchdog utility.
- add “LuCI Support for Watchcat”:

  • “LuCI” ⇒ “Select” ⇒ “3. Applications” ⇒ “Select” ⇒ on “luci-app-watchcat” press <Y> to include (= “*” built-in) ⇒ “Exit” ⇒ “Exit”

- or without LuCI, add “Watchcat”:

  • “Utilities” ⇒ “Select” ⇒ on “Watchcat” press <Y> to include (= “*” built-in) ⇒ “Exit”

3.3 Exit configuration

To exit OpenWrt Configuration and save target with options settings do following:

  • “Exit” ⇒ “Yes”

4. Build image

Debian terminal command: 

make V=s 2>&1 | tee build.log

Completion can take time. If successful, the images are in the directory ./bin/targets/<target directory>

  • The *-factory.bin image file is for the first installation of OpenWrt on the target.
  • The *-sysupgrade.bin image file is for updating an existing OpenWrt installation.

To recompile the images, remove files from directory ./bin/targets/<target directory> and build image (step 4) again.
:?: What about cleaning up “make clean”, “make dirclean”, “make distclean”?

For faster compiling, use make -j N, where N is the number of CPU cores + 1. Be aware that this method is prone to errors during compiling. In case you encounter compile errors, your very first step is to compile again without -j N. Use of make download prior to parallel compilation is recommended to prevent some of these errors (-jN is generally safe for the download step for those with faster Internet connectivity.)

To build an OpenWrt firmware image for other hardware or with other options, use the OpenWrt Configuration (step 3) and then build image (step 4) again.

Also more hardware info on wikidevi.

Other OpenWrt pages:

This website uses cookies. By using the website, you agree with storing cookies on your computer. Also you acknowledge that you have read and understand our Privacy Policy. If you do not agree leave the website.More information about cookies
  • Last modified: 2022/07/15 05:20
  • by ja