Building OpenWrt

(Redirected from Building prplwrt)
Jump to: navigation, search

Based upon the then-latest development version of OpenWrt, Chaos Calmer

The first step to developing on OpenWrt is understanding how to build it. OpenWrt's build system is complex but getting started with it is pretty straightforward. While not vital to know, OpenWrt uses the BuildRoot system. This tutorial will walk you through setting up your system to build OpenWrt, getting the OpenWrt source and compiling the source and running your new OpenWrt image in a QEMU virtual machine.

Before you begin[edit]

Before you begin, you're going to need to be using Linux, Mac or other Unix operating system. Unfortunately, Windows is not supported for building OpenWrt but you can run a Linux distribution in a virtual machine on Windows.

For this tutorial, I'll use the the commands necessary for building on Ubuntu Linux 14.04 - 64-bit. The instructions likely work for Debian, however Fedora and MacOS will be different and not be covered in this tutorial.

Open a terminal window[edit]

The commands for building OpenWrt are run in the terminal window. To get to a terminal on Ubuntu, click on the Ubuntu logo near the top left corner. Type the phrase Terminal and then click on the icon named Terminal.

Installing prerequisites[edit]

OpenWrt requires a number of packages installed on your Ubuntu system before you can compile it. Let's install all those packages now:

sudo apt-get install build-essential subversion libncurses5-dev zlib1g-dev gawk gcc-multilib flex git-core gettext qemu-system-mips

You'll be asked to enter the root password since you are modifying the system state. This will take a few minutes to download all the packages and install them so just relax and watch the lines of text flow by.

One quick thing to note is that qemu-system-mips is not a prerequisite for building OpenWrt. Instead it's the program we use for testing our finished version of OpenWrt.

Getting OpenWrt source code[edit]

The OpenWrt source code is stored in a Git repository. Getting OpenWrt consists of a single command:

git clone git://

This gets you a copy of the OpenWrt code base on your local system.

If you want to use the exact revision of the OpenWrt code base that I used, run the following command:

git checkout 2d8e941ca54c57db1476b8c4a1888321d511a654

This makes sure you'd building with the exact same version of the code base as I am.

The next commands will happen from the inside this local copy of OpenWrt so we'll change our subdirectory to OpenWrt:

cd openwrt

Updating package list[edit]

Most distributions of Linux includes a package management system. For example, we used the APT package management system built into Ubuntu and Debian to install the prerequisites for building OpenWrt. OpenWrt has a similar package management system for managing the software you can include in your OpenWrt image. To get started we need to update the internal list of software packages OpenWrt can include:

./scripts/feeds update -a

Preparing our image[edit]

The Linux kernel and the set of software that runs on a router or, in our case, QEMU gets combined into a file called an image. If you're familiar with the concept of an ISO file, an image is a little bit like that. We need to set up what software and features are included in our image. Fortunately OpenWrt has a tool for this called menuconfig.

To get started run we need to start the menuconfig tool in our terminal by running:

make menuconfig

After a few seconds, the following screen should pop up in your terminal window:

Make Menu.png

This is the main configuration screen for setting up your OpenWrt image. OpenWrt includes options for thousands of different system configurations; we won't address many of them in this tutorial but suffice it to say, there's lots of opportunities to do creative things if you want to.

Setting Target System[edit]

The first thing we need to do is to set our target system. The target system option corresponds to a processor type or family. In most cases, routers will not function if they have an image from an incorrect target system type. To do that, we press Enter to go to the target system submenu.

Target system menu.png

By default, the target system is Atheros AR7xxx/AR9xxx. We want to use the "MIPS Malta CoreLV board (qemu)" instead. Simply press your down arrow key repeatedly until you're highlighting "MIPS Malta CoreLV board (qemu)"

MIPS Malta select.png

Press Space to select this. You should be back at the main configuration screen now with the proper target system selected.

Setting Subtarget (optional)[edit]

In some cases, a target system has additional configuration option sets called subtargets. Subtargets often correspond to a particular version of the architecture for the target system. Let's use down arrow key to highlight the Subtarget menu item.


We can got to the subtarget submenu by pressing Enter. In this submenu, you can see a list of subtargets. In our case we want our subtarget to stay as "Little Endian" so we press Enter to get back to the main menu.

Setting Target Profile (optional)[edit]

A number of targets and subtargets have one more set of additional configuration options called a "profile". These profiles usually correspond to adding packages and configuration options needed to build an image for popular router models. Let's use down arrow key to highlight the Target Profile menu item.

Target profile.png

Normally, we'd use the Enter key to visit change the Target Profile. In this case, the selected target/subtarget combination of "MIPS Malta CoreLV board (qemu)" and "Little Endian" only has a "Default" profile so we won't do anything here.

Setting Target Images (optional)[edit]

OpenWrt allows you to create a variety of different image types. These types vary on the method of packing the software into the image as well as the specific method of loading the software at boot-time. For this tutorial, we need to load our image from a ramdisk. Let's use the down arrow key to select the Target Images menu item.

Target images highlight.png

Press Enter to go to the Target Images submenu.

Ramdisk highlight.png

The Target Images submenu allows you to compile and organize your image in a number of different ways. In our case, we want to have ramdisk selected. Since it already is, we press Enter to confirm our selection and go back to the main menu.

Setting Advanced Configuration Options[edit]

Occasionally, developers need to be able to modify the build process of OpenWrt slightly. OpenWrt places these options in the "Advanced configuration options (for developers)" menu. Due to a bug in the version of QEMU included with Ubuntu 14.04, we need to modify ones of these options. If you're not using Ubuntu 14.04, it's possible you won't need to perform this step.

To get started, we use the down arrow key to highlight the Advanced configuration options (for developers) menu item. Then we press Space to tell OpenWrt that we'll be using one of these options.

Advanced config selected.png

Next, we press Enter which takes us to the Advanced configuration options sub menu.

Advanced config options.png

There are loads of choices in this menu for modifying all kinds of things of settings affecting the OpenWrt build process. In our case we're going to need to modify one of the "Target Options" settings. To do that, we use the down arrow key to highlight the Target Options menu item. Next we press Space to tell OpenWrt that we want to modify one of the Target Options.

Target options selected.png

To go to the Target Options submenu, we press Enter. There will be a few options that might not mean much to you right now; that's okay. We need to turn the "Build packages with MIPS16 instructions" off. We'll do that by using the down arrow key to highlight the "Build packages with MIPS16 instructions" menu item and then pressing Space to deselect this option.

MIPS16 deselected.png

Now that we've changes this option, we'll press Enter twice to get back to our main menu.

Looking at packages (optional)[edit]

While most of the settings we've looked at so far deal with configuration, OpenWrt's build system also let's you select software packages you'd like to include and build along with your image. Starting at the "Base System" menu item are a set of software categories containing all the supported pieces of software OpenWrt supports. While we won't modify any of these in this tutorial, feel free to look around in the menus if you'd like.

Software and configuration choices.png

Saving our .config file[edit]

We've configured the creation of our OpenWrt images so all we have left to do before building is to save our configuration file, .config. We press the right arrow key once to select "Exit" at the bottom of the menu screen and press Enter. You'll be asked if you want to save your new configuration.

Do you want to save.png

Press Enter to confirm that you do want to save your .config file. You'll be sent back to the terminal after the .config file is saved.

Compile the image[edit]

Compiling the image is pretty simple, all you have to do is run:


This command will take a pretty long time to finish, possibly hours. Don't worry; that's normal!

Boot our image in QEMU[edit]

After our build is complete, we're going to go to the directory containing our image:

cd bin/malta

This directory contains all of the images we created as well as the packages that were built. You can see this by listing the directory contents:


In our case, we only care about the ramdisk image for running in QEMU, the file named "openwrt-malta-le-vmlinux-initramfs.elf"

We're going to boot our image in QEMU using the following command:

qemu-system-mipsel -kernel openwrt-malta-le-vmlinux-initramfs.elf -nographic

Let's break down each part of this command:

  • qemu-system-mipsel is the QEMU command to start a new emulated MIPS system in little endian mode.
  • -kernel openwrt-malta-le-vmlinux-initramfs.elf is an option telling QEMU that our kernel image for our operating system is in the openwrt-malta-le-vmlinux-initramfs.elf image.
  • -nographic is an option telling QEMU to turn off the normal graphical output and send all of the command line input and output to the terminal.

You should see lines of text show up on your screen. Everything that's happening is the normal boot mechanism for OpenWrt.

Using the console (optional)[edit]

Towards the end of this boot mechanism, you'll see the following line of output:

Please press Enter to activate this console.

OpenWrt has a console that you can use to modify and work with the operating system, just like the terminal we're using in Linux. Let's get to the terminal by pressing Enter.

The console should display something like the following (some of the details will vary based upon the latest version of OpenWrt and when you built your image):

BusyBox v1.22.1 (2014-10-16 13:00:11 CDT) built-in shell (ash)
Enter 'help' for a list of built-in commands.

  _______                     ________        __
 |       |.-----.-----.-----.|  |  |  |.----.|  |_
 |   -   ||  _  |  -__|     ||  |  |  ||   _||   _|
 |_______||   __|_____|__|__||________||__|  |____|
          |__| W I R E L E S S   F R E E D O M
 CHAOS CALMER (Bleeding Edge, r42923)
  * 1 1/2 oz Gin            Shake with a glassful
  * 1/4 oz Triple Sec       of broken ice and pour
  * 3/4 oz Lime Juice       unstrained into a goblet.
  * 1 1/2 oz Orange Juice
  * 1 tsp. Grenadine Syrup

It's possible some more lines of text jump on the screen after you press Enter. OpenWrt is running a number of things in the background and they can notify you at the console. These lines that come up have no effect on the commands you run.

The command line and set of tools that OpenWrt runs is called BusyBox. You can explore the system and run any command that BusyBox includes as well as commands that are unique to OpenWrt.

Shutting down your OpenWrt VM[edit]

When you're done exploring your OpenWrt image, you're going to want to turn it off just like you would a real machine. We can do this in QEMU by pressing Ctrl-a followed by c. This gets us to a console for controlling QEMU virtual machines. From here, we run the command q. This sends us back to our main command line and and shuts down our virtual machine.


In this tutorial, we learned how to get the OpenWrt source code, configure and run the image build process and run an OpenWrt image in a QEMU virtual machine.