OpenWrt Training

Day 1
Training agenda - Day 1
● What is OpenWrt?
● OpenWrt build system basics
● OpenWrt feeds
● Build process and packages selection
● OpenWrt build debugging
What is OpenWrt?
What is OpenWrt?
● OpenWrt stands for "Open Wireless RouTer"
● highly extensible GNU/Linux distribution for embedded devices
● stable, secure, flexible and customizable
● build system and many components are licensed under the GNU General Public License
Version 2 (packages licences can be different)
● 2000+ devices supported (detailed database and technical reference)
● collection more than 27000 packages (extensible through package feeds)
● large community of users and developers who contribute to the project
● wiki, forums, mailing lists, documentation
Why OpenWrt?
● Typical routers - vendor lock-in
● Not designed as an out-of-the-box distribution
○ Allows tailoring your own system
● Small footprint
○ System architecture optimized in size
○ Lightweight components
● Portability
○ Wide hardware platform support
● Customizability
○ Huge number of packages ready to be selected
○ Easy way of adding custom packages and system modifications
OpenWrt history
● started in 2004 as a fork of the Linux-based firmware for the Linksys WRT54G wireless
router
● initiated by a group of developers who wanted to create an open source firmware
● many forks through the past:
○ LEDE (Linux Embedded Development Environment) - merged with OpenWrt in 2018
○ DD-WRT
○ Gargoyle
○ Tomato
OpenWrt releases
● OpenWrt 18.06.x (2018-2020) ● White Russian (2007)
● OpenWrt 19.07.x (2020-2022) ● Kamikaze (2008)
● OpenWrt 21.02.x (2021-2022) ● Backfire (2010-2011)
● OpenWrt 22.03.x (2022-) ● Attitude Adjustment (2013)
● OpenWrt 23.05.x (2023-) ● Barrier Breaker (2014)
● OpenWrt 24.10 still RC (2024-) ● Chaos Calmer (2015-2016)
● OpenWrt master branch ● LEDE 17.01 (2017-2018)
Choosing the right release
● Depends on the target device and level of stability/support present in each release
○ Latest and greatest - use OpenWrt master
○ Stable - use latest OpenWrt release (23.05.x, soon 24.10.x)
○ Obsolete devices - check Table of Hardware for the latest OpenWrt supported
● Build your own image
○ provides all the flexibility and allows various customizations
● Prebuilt images
○ https://downloads.openwrt.org/
○ https://firmware-selector.openwrt.org/
■ configure and build your own image
○ download and flash to the device
○ allows installation of additional software and kernel modules using OpenWrt package manager opkg
OpenWrt build system basics
OpenWrt build system
● builds OpenWrt firmware from source code
● set of Makefiles, patches and scripts
● based on buildroot
● requires a GNU/Linux environment with a case-sensitive file system
○ can work on macOS and WSL
● hardware resources hungry
○ 10 - 15 GB of disk space for a single target device
○ 2 GB RAM or more
● creates a cross-compilation toolchain, C standard library, Linux kernel and user space
programs
○ alternative: Image builder (limited customization)
Directory structure
● tools/
○ utilities for building cross compile toolchain
● toolchain/
○ compiler, C libraries, kernel headers
● target/
○ configs and Makefiles for all target platforms
● scripts/
○ helper scripts for preparing OpenWrt packages
● include/
○ build system include files (Makefiles)
● dl/
○ all source code downloaded during the build
● package/
○ collection of built in OpenWrt packages (.ipk)
Directory structure
● bin/
○ stores the OpenWrt firmware images once the build process is finished
● tmp/
○ stores build system metafiles used by make menuconfig
● feeds/
○ stores Makefiles and feed indexes for package feeds
● target/linux/generic/patches-*/
○ Linux kernel patches that need to be applied for every OpenWrt target
● feeds.conf.default
○ default feeds config file
Directory structure - build_dir
● all source code for selected target firmware image is extracted and compiled under
build_dir
● build_dir has 4 main subdirectories:
○ build_dir/host
■ used for compiling all the tools that will run on the host computer during firmware build
○ build_dir/toolchain-<...>
■ per target, used for compiling cross compile tools, C library and tools which will run on the host
computer
○ build_dir/target-<...>
■ per target, used for compiling the Linux kernel and all selected packages
○ build_dir/target-<...>/linux-<...>/linux-<version>
■ per target, directory where the Linux kernel source is built into the kernel image
Directory structure - staging_dir
● all compiled programs are installed under staging_dir and used later for building further
packages, or preparing firmware image
● staging_dir has 4 main subdirectories:
○ staging_dir/host
■ mini Linux root filesystem with all host tools used during the build (added to PATH)
○ staging_dir/toolchain-<...>
■ mini Linux root filesystem with cross compiler tools used for building the target firmware
○ staging_dir/target-<...>/root-<...>
■ per target, contains installed versions of selected packages which will become the target firmware
○ staging_dir/packages/<..>
■ per target, collection of all compiled packages (.ipk) for selected target
Build system setup
● Fedora / CentOS
○ sudo dnf --setopt install_weak_deps=False --skip-broken install bash-completion bzip2 gcc gcc-c++ git make
ncurses-devel patch rsync tar unzip wget which diffutils python2 python3 perl-base perl-Data-Dumper
perl-File-Compare perl-File-Copy perl-FindBin perl-Thread-Queue
● Debian / Ubuntu
○ sudo apt install build-essential clang flex bison g++ gawk gcc-multilib g++-multilib gettext git libncurses5-dev
libssl-dev python3-distutils rsync unzip zlib1g-dev file wget
● Arch Linux
○ sudo pacman -S --needed base-devel autoconf automake bash binutils bison bzip2 fakeroot file findutils flex
gawk gcc gettext git grep groff gzip libelf libtool libxslt m4 make ncurses openssl patch pkgconf python rsync
sed texinfo time unzip util-linux wget which zlib
○ sudo pacman -S --needed asciidoc help2man intltool perl-extutils-makemaker swig
Build system preparation
● Clone OpenWrt build system
○ git clone https://git.openwrt.org/openwrt/openwrt.git
○ cd openwrt
● Select desired release revision (tag):
○ git tag
○ git checkout v22.03.5
● or select desired branch:
○ git branch -a
○ git checkout openwrt-23.05
● or stay on master:
○ git checkout master
Build system basic usage
● make package/symlinks
○ update and install all configured feeds
● make menuconfig
○ configure build for a target device
● make
○ build firmware based on selected target and packages
● make -j$(nproc)
○ build firmware based on selected target and packages with all available CPU cores
● make clean
○ clean up build artifacts
OpenWrt feeds
● feed is additional collection of packages for OpenWrt build system
● can be on remote version control system or local filesystem
● configured in feeds.conf if it exists, otherwise feeds.conf.default

src-git packages https://git.openwrt.org/feed/packages.git

src-git luci https://git.openwrt.org/project/luci.git
src-git routing https://git.openwrt.org/feed/routing.git
src-git telephony https://git.openwrt.org/feed/telephony.git
src-link custom /usr/src/openwrt/custom-feed
OpenWrt feeds
OpenWrt feed locations
Method Function

src-bzr Data is downloaded from the source path/URL using bzr

Data is copied from the source path. The path can be specified as either relative to OpenWrt repository
src-cpy
root or absolute.

src-darcs Data is downloaded from the source path/URL using darcs

src-git Data is downloaded from the source path/URL using git as a shallow (depth of 1) clone

src-git-full Data is downloaded from the source path/URL using git as a full clone

src-gitsvn Bidirectional operation between a Subversion repository and git

src-hg Data is downloaded from the source path/URL using hg

src-link A symlink to the source path is created. The path must be absolute.

src-svn Data is downloaded from the source path/URL using svn

Working with feeds
● ./scripts/feeds
○ script to work with feeds (update, install, uninstall, clean, search)
● ./scripts/feeds update -a
○ update packages from all configured feeds, usually after modifying feeds.conf file
● ./scripts/feeds update luci
○ update packages from "luci" feed, usually if packages are updated in the feed
● ./scripts/feeds install -a
○ install all packages from all feeds, which are then available in "make menuconfig"
● ./scripts/feeds install luci
○ install "luci" package, which is then available in "make menuconfig"
● ./scripts/feeds install -a -p luci
○ install all packages from "luci" feed, which are then available in "make menuconfig"
● make package/symlinks
○ make target which will run "feeds update -a" and feeds install -a"
Build process and packages selection
Build process overview
1. clone OpenWrt repository
2. checkout desired branch/tag
3. adapt feeds.conf
4. update and install packages from feeds (./scripts/feeds)
5. select target and desired packages (make menuconfig)
6. start build process (make)
Target and packages selection
● make menuconfig
○ configure build target:
■ chipset architecture target system
■ subtarget (if applicable)
■ target profile
○ select desired packages and features
● pressing y sets the <*> built-in label
○ this package will be compiled and included in the firmware
image file
● pressing m sets the <M> package label
○ this package will be compiled, but not included in the
firmware image file, e.g. to be installed with opkg after flashing
the firmware image file to the device
● pressing n sets the < > excluded label
○ the source code will not be processed
● Once saved, the build system config is stored in .config
file
Starting the building process
● make
○ starts the complete firmware build
● make -j8
○ starts the complete firmware build using 8 CPU cores
● make -j$(nproc)
○ starts the complete firmware build using all available CPU cores (as returned by nproc)
● make download
○ only download source codes for all selected software
● make package/tcpdump/compile
○ build single package, in this example "tcpdump" package

● once build finishes, target firmware is located under bin/targets/<...>

Make targets
● OpenWrt build system offers a number of high level make targets for standard package workflows
● Targets are in the format component/name/action, for example:
○ toolchain/gdb/compile
○ package/mtd/install

● make package/mtd/prepare
○ Prepare the "mtd" package source tree
● make package/mtd/compile
○ Compile the "mtd" package
● make package/mtd/clean
○ Clean the "mtd" package
● make package/mtd/{clean,compile}
○ Clean and compile the "mtd" package
Build sequence
1. tools - automake, autoconf, sed, cmake
2. toolchain/binutils - as, ld, ...
3. toolchain/gcc - gcc, g++, cpp, ...
4. target/linux - kernel modules
5. package - core and feed packages
6. target/linux - kernel image
7. target/linux/image - firmware image file generation
Build system clean up
● make clean
○ deletes contents of bin/ and build_dir/ for the selected target
● make targetclean
○ deletes contents of bin/, build_dir/, build_dir/toolchain* and staging_dir/toolchain* for the selected target
(introduced in 22.03 release)
● make dirclean
○ deletes contents of bin/, build_dir/, staging_dir/, tmp/ and logs/
● make distclean
○ full clean of the build system, including .config file
● make package/tcpdump/clean
○ clean single package from build_dir/, in this example "tcpdump" package
OpenWrt build debugging
OpenWrt build debugging
● if build fails, repeat it with more verbose log output
● make -j1 V=s
○ rebuild the firmware with single core and verbose output
● make package/tcpdump/{clean,compile} V=s
○ build single package, in this example "tcpdump" package, with verbose output
● parameter V= can be set to:
○ s - Show both stdout and stderr
○ c - Print only commands
○ w - Show only warnings and errors
● Verbosity levels can be combined, e.g.
○ make V=sc
○ make V=sw