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.
- 1 Before you begin
- 2 Open a terminal window
- 3 Installing prerequisites
- 4 Getting OpenWrt source code
- 5 Updating package list
- 6 Preparing our image
- 7 Compile the image
- 8 Boot our image in QEMU
- 9 Using the console (optional)
- 10 Shutting down your OpenWrt VM
- 11 Summary
Before you begin
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
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.
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
The OpenWrt source code is stored in a Git repository. Getting OpenWrt consists of a single command:
git clone git://git.openwrt.org/openwrt.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:
Updating package list
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
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:
After a few seconds, the following screen should pop up in your terminal window:
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
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.
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)"
Space to select this. You should be back at the main configuration screen now with the proper target system selected.
Setting Subtarget (optional)
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)
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.
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)
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.
Enter to go to the Target Images submenu.
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
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.
Next, we press
Enter which takes us to the Advanced configuration options sub menu.
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.
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.
Now that we've changes this option, we'll press
Enter twice to get back to our main menu.
Looking at packages (optional)
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.
Saving our .config file
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.
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
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
After our build is complete, we're going to go to the directory containing our image:
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-mipselis the QEMU command to start a new emulated MIPS system in little endian mode.
-kernel openwrt-malta-le-vmlinux-initramfs.elfis an option telling QEMU that our kernel image for our operating system is in the
-nographicis 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)
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
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 ----------------------------------------------------- root@(none):/#
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
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.