The following guide will walk you through the downloading, configuring, and compilation of OpenWRT. The guide makes no assumption about the reader’s previous experience with OpenWRT, or even building from source, so as long as you follow along you should be fine. That said, experience with compiling software and general troubleshooting skills would help make sure the process goes smoothly.
Disclaimer: The final part of this guide will have you install your self-built firmware image onto your router. While the ability to compile and configure your own router firmware is an incredible achievement for the open source community, it’s also somewhat risky. Make sure to familiarize yourself with the firmware recovery options that are specific to your device by visiting the OpenWRT “Table of Hardware”, located at:
What is OpenWRT?
It’s easy to assume that OpenWRT is “just another router firmware”, like the well known DD-WRT or Tomato firmwares. In fact, up until just a few months ago, that’s what I thought myself. But whereas DD-WRT aims at being a feature-rich router firmware that will give you an out of the box experience closer to what you would see on a high-end enterprise router, OpenWRT aims to give you a full Linux system that just happens to be running on a router. With OpenWRT installed on your router, you’ll have something that’s much closer to a minimal Linux install on your PC than what you would expect from a router. Out of the box there’s no friendly web UI to set up the router, just the prospect of logging in over SSH and editing text files by hand.
The possibilities for such a system are endless. With a large package repository, an OpenWRT device has access to software you may never have even considered running on a router. You can setup an OpenWRT device to run as a file server, a media extender, a security auditing toolbox, or anything else you could do with a normal Linux system. The only limitation is the processing capability of the specific hardware OpenWRT runs on, which can be anywhere from a cheap router that barely has enough RAM to boot the system to devices which could give some smartphones a run for their money. The individual hardware you chose will depend on many factors (probably not least of which, your budget), but the process described here works the same on any device OpenWRT can or will support.
Why Build from Source?
While the OpenWRT project makes firmware images available for all of the various devices they support, these aren’t always ideal depending on what your goals are. The stock images from OpenWRT are setup with the assumption that you want to end up with a more or less standard consumer router when you are done with the installation, which may be far from the case. Due to the limited storage space available on these devices, you can’t afford to have your flash storage taken up by things like firewalls and web configuration pages if you are looking to turn an OpenWRT-capable router into a robot controller or a dedicated file server on your network.
From personal experience, the router I use for OpenWRT development has so little storage space left after installation of the stock OpenWRT firmware image that I couldn’t install even a single additional package. For me, I had to build from source just to get any use out of my device.
Even if you have the storage space to burn, learning the ins and outs of OpenWRT by compiling it from source is an excellent way to learn how the system works. If you plan on doing any kind of modification to OpenWRT, it’s definitely in your best interests to dive right in and see how the whole build process functions.
Before we begin, I should make clear that there are some hardware requirements for building a project of this size. While you’ll only need about 300 MB to download the OpenWRT source, the size of the final compiled code can easily get up to few gigabytes, so keep that in mind if your are on a size constrained setup.
You’ll also need a rather powerful machine to work through this build. For my own development I use a 6 core AMD machine with 4 GB of RAM, and it takes around 20 minutes to build a minimal OpenWRT firmware image. On a dual or even single core machine, the build times will likely be into the hours, especially if you are including a lot of software in the image.
Setting up the Build Environment
To start, you’ll need to prepare your system for building packages from source if it isn’t already, and install Subversion which is used by the OpenWRT developers to distribute the code. On an APT-based system (Ubuntu, Mint, etc), the following command should cover all the bases:
bash$ sudo apt-get install subversion build-essential libncurses5-dev zlib1g-dev gawk flex quilt git-core
With those packages installed, you’ll be able to get the latest source code from the OpenWRT developers and begin the process of turning that into an installable image.
At this point you’ll need to make a determination on which version of OpenWRT you want to run. There are currently two branches, the stable branch called “Backfire”, and the development branch which is referred to as “trunk”. While some devices are well supported via Backfire, newer devices will require you use trunk as support for them hasn’t always hit the point where the developers are ready to call it stable. For the purposes of this guide we will be going along with trunk as it has the most hardware support, but the steps will be the same if you chose to download Backfire instead.
To begin the download of OpenWRT, first decide where you want to store and build the source. Some like to do this out of /usr/src, but any directory will work. For simplicities sake, let’s build it out of our /home directory. Run the following commands to download OpenWRT and get yourself into the source tree:
bash$ mkdir ~/OpenWRT bash$ cd OpenWRT bash$ svn co svn://svn.openwrt.org/openwrt/trunk/ bash$ cd trunk
The previous commands got the core of OpenWRT downloaded, and you now have everything you need to build a minimal firmware image for your router. But depending on what you want to do, there might be additional software outside of the stock OpenWRT tree that you want to include in your final firmware image. OpenWRT includes a tool called “feeds” which helps find, update, and install these additional packages, which you should run before going any farther if you wish to include any of them. To start using the “feeds” tool, you first need to tell it which repositories you want to include. This is done through a file in the root of the OpenWRT source called “feeds.conf.default”. Opening it up in your text editor of choice should present you with the following:
src-svn packages svn://svn.openwrt.org/openwrt/packages src-svn xwrt http://x-wrt.googlecode.com/svn/trunk/package src-svn luci http://svn.luci.subsignal.org/luci/trunk/contrib/package #src-svn phone svn://svn.openwrt.org/openwrt/feeds/phone #src-svn efl svn://svn.openwrt.org/openwrt/feeds/efl #src-svn xorg svn://svn.openwrt.org/openwrt/feeds/xorg #src-svn desktop svn://svn.openwrt.org/openwrt/feeds/desktop #src-svn xfce svn://svn.openwrt.org/openwrt/feeds/xfce #src-svn lxde svn://svn.openwrt.org/openwrt/feeds/lxde #src-link custom /usr/src/openwrt/custom-feed
Here we can see that only the first three repositories are enabled, as everything else is commented out with the “#” character. For most tasks the first three repositories should be sufficient, but if you are looking to get into the more advanced territories, like installing X and using graphical tools on it, you’ll need to enable the appropriate repositories in this file by removing the “#” signs before each line.
Now that we’ve enabled the repositories we want to use, the next step is to download the list of available packages by running the following command from within the OpenWRT source tree:
bash$ scripts/feeds update -a
You’ll then see a very long list of packages being downloaded and updated, after which you’ll be dropped back to the shell. With the updated list of packages in hand, you can now search for any install anything you may want which isn’t included in OpenWRT. For example, if you were looking for Bluetooth related packages you could run the following:
bash$ scripts/feeds search Bluetooth Search results in feed 'packages': anyremote A bluetooth remote control app bemusedlinuxserver Bemused linux server bluez-hcidump Bluetooth packet analyzer bluez-libs Bluetooth library bluez-utils Bluetooth utilities miax A console iax (asterisk) client python-bluez Python wrapper for the BlueZ Bluetooth stack
Let’s say you then wanted to install bluez-utils and bluez-libs, you could run the following command:
bash$ scripts/feeds install bluez-libs bluez-utils Collecting package info: done Collecting target info: done Installing package 'bluez-libs' Installing package 'gettext' Installing package 'libiconv' Installing package 'bluez-utils' Installing package 'dbus' Installing package 'expat' Installing package 'gettext-full' Installing package 'libiconv-full'
Note that “feeds” is smart enough to resolve dependencies for those two packages, and has therefore installed quite a few other packages which will be required to use Bluetooth on your final OpenWRT firmware.