August 18, 2005

Linux wireless freedom with OpenWrt

Author: "American" Dave Kline

You can turn your blue Linksys router into a Linux box with OpenWrt, an embedded Linux distribution for Linksys WRT54G and WRT54GS routers. This tiny distribution exceeds the default firmware functionality in many useful ways. Instead of having only a Web-controlled wireless access point, OpenWrt provides you with a fully interactive Linux system. Some notable features are the ability to telnet/SSH to your router, install software such as Snort, Mini-Sendmail, and Asterisk, and create and control VLANs for every Ethernet port on the device.

Though OpenWrt runs on Linksys routers, it can also run on a plethora of similar routers from other vendors. Keep in mind, however, that you void your router vendor's warranty by installing OpenWrt. OpenWrt, like the original Linksys firmware, is distributed under the GPL.

Installing OpenWrt is easy, but in addition to the aforementioned warranty-voiding, be aware of the potential for locking yourself out of your router in the event that the installation process fails or you make configuration changes that your hardware doesn't like. Putting OpenWrt on a router takes time and preparation. Be familiar with and its instructions, especially the notes about specific hardware. You will need the following:

  • A compliant revision of a WRT54G or WRT54GS series router, or another vendor's supported router
  • An OpenWrt firmware file specific to your router type
  • A Linux box with a tftp (Trivial File Transfer Protocol) client

Our example will use a Linksys WRT54GS version 2.0 router. You can find the revision number on the bottom of your router, but unfortunately
not on the outside of the retail box. (Don't buy one of these boxes to use for OpenWrt if you can't verify what revision the device is.) We'll use atftp (Advanced TFTP) as our tftp client.

First, download OpenWrt. There are two ways to obtain OpenWrt firmware: compile the source or
grab a binary. For simplicity, we'll download a binary. You then have a choice
of filesystems for your firmware to use -- either JFFS2 or SquashFS. We
used JFFS2, as it enables a fully writable filesystem and it's simpler than the SquashFS filesystems. The firmware file for
our router is called openwrt-wrt54gs-jffs2.bin. I suggest using a download utility, such as Wget, to obtain this file; I corrupted a few firmware downloads when using a Web browser, and needless to say, I wasn't happy when I finally figured out why.

Choose your path

You don't need a tftp client for your first OpenWrt installation. You can install OpenWrt via the Linksys Web interface provided with the router. Simply point a Web browser at the router's default IP address (or whatever IP address you changed it to) and upload the OpenWrt binary as the firmware upgrade. Although this method is fast and easy, there is less of a chance of recovering than a tftp install if things go awry. Use web interface method only if you're impatient and brave.

The preferred installation method is to coax the router into enabling a special variable called boot_wait, which toggles a special behavior that delays the router's boot process for a few seconds. This pause enables you to upload new firmware images via tftp. The official OpenWrt installation instructions walk you through a process of enabling boot_wait via the official Linksys Web interface. Enabling boot_wait for the first time is tricky, and the procedure changes depending on your router revision.

Once you've enabled boot_wait, you can proceed to transmit the firmware through atftp. To do so, plug an Ethernet cable from your Linux box to your router's port 1. Ensure your Linux box can ping If you can't reach this IP address, run the following command as root:

	linuxbox:~# route add eth0

After verifying connectivity to your router, unplug the router's power cable. Next, run atftp from your Linux box and issue the following commands:

	user@linuxbox:~$ atftp
	tftp> connect
	tftp> mode octet
	tftp> trace
	Trace mode on.
	tftp> put openwrt-wrt54gs-jffs2.bin

Quickly plug in your router's power cord after running the put command from atftp. You should see a lot of text scroll by. Wait five minutes after sending the firmware. Be sure to familiarize yourself with the tftp error messages at in case your firmware upload gives errors. Remember that since you enabled boot_wait, you can simply retry a firmware upload if things go awry.

Using OpenWrt

After successfully sending the firmware, you can telnet to your router. Issue telnet and notice that you don't need a username or password. You may have a read-only filesystem upon logging in. If this is the case, type reboot at your router's shell. You should now have a basic yet powerful Linux system on your router.

By default, OpenWrt's installation emulates the normal Linksys firmware functionality. This means that although you installed OpenWrt, your router still acts as a wireless access point and switch. Included in OpenWrt is a robust iptables-based firewall. The router stores configuration information in non-volatile RAM. In other words, though you can still use utilities like route and ifconfig, you have to store such configuration information in NVRAM, or your changes will not survive a reboot. Use normal Linux tools first and commit configuration information to NVRAM only after you've verified good settings. To get an idea of what NVRAM holds, issue the command:

	nvram show | more

Visit the documentation at to list these variables and see their meaning. The commands nvram get variable_name and nvram set variable_name show and set a variable's value. Use nvram commit to finalize your changes. If you mess up your variables, simply reboot without committing your changes. If you installed OpenWrt via the Web interface, boot_wait will not be set. Your first order of business is to ensure that boot_wait is enabled. While logged onto your router, type the following:

	nvram show | grep boot_wait
	nvram set boot_wait=on
	nvram commit

OpenWrt obeys common networking conventions, taking advantage of route, ifconfig, and /etc/resolv.conf, while also having a unique network arrangement. OpenWrt sets up our version 2.0 WRT54GS arrangement like this:

  • LAN is configured as vlan0
  • WAN is configured as vlan1
  • WIFI is configured as eth1

LAN is for locally connected Ethernet clients. An IP address assigned to the LAN interface would be reachable from the Ethernet ports. WAN is your "upstream" interface, meaning it acts like the stock firmware's interface to connect to a device, such as a DSL router. WIFI is the IP address of the wireless interface, which is reachable by wireless clients. By default, LAN and WAN are bridged, meaning both are reachable from either wireless or wired clients. If you want to change your LAN IP address, type the command:

	ifconfig vlan0

Remember, such changes will not survive a reboot unless you change the appropriate NVRAM variable. Also remember that changing the IP address of the interface you're logged into will kick you off the machine.

One of the great things about OpenWrt is its use of iPKG, a tiny package management system inspired by Debian's APT. With iPKG, installing packages, such as tcpdump, is simple as running a command like ipkg install tcpdump. Use ipkg update and ipkg list to see what add-on software is available.

If you damage your router

It's all fun and games until someone gets hurt, or in this case, you can't log into your router. With all the fun and exciting new functionality you gain, you also gain new ways to break your router. For instance, you can have a bad tftp upload, you can commit bad changes to NVRAM variables, or you can make iptables changes that lock you out. If you do something wrong, but you have boot_wait enabled, you can simply retry a firmware upload through your tftp client. If this fails, there are more complex methods described at's troubleshooting pages.


With OpenWrt, friendly and helpful volunteers have created a powerful and fun Linux system that replaces the default Linksys firmware. You can use OpenWrt to implement everything from programmable VLANs to intrusion detection on a compact, fan-less box. With OpenWrt, you will be amazed at what free software is up to these days.


  • Networking
Click Here!