Running Linux on your Linksys WRT54GS v7 Router

DISCLAIMER: This worked for me, but I can't guarantee success. Replacing your router firmware definitely voids the warranty. Please don't return your router to the store if you break it, because that just encourages hardware designers to make it harder to replace the firmware!

I finally got tired of the extremely limiting firewall settings and random crashes I got with stock router firmware and decided to try my luck with a Linux-based one. So I went to the store and picked up a new Linksys WRT54GS, which I knew is supported by Linux. It turned out to be a v7 (16 megs RAM, 2 megs flash), which most Linux router distros can't do... bummer.

Luckily, a special "micro" version of "dd-wrt" works great. I followed the special WRT54GS v7 instructions from their site to install dd-wrt.v24_micro_wrt54gv8.bin (note how this one was made for v8 hardware, but also works fine with v7).

Before I found this (eventually successful) process, I accidentally tried upgrading to the wrong version of dd-wrt, which seemed to "brick" my router. I recovered thanks to Unbrick your Linksys WRT54GS v7 by "Valiant."

None of the instructions I found really explain why you're doing anything. As a computer engineer, I find this a little frustrating, because when the instructions don't work verbatim, I have no idea where to begin troubleshooting. I'm sure that information is around somewhere, but apparently not in the official docs. So here you go:

What really happens when you replace your WRT54GS firmware

Here's what's really going on:

• The original system (hardware models starting with v5) is based on VxWorks, not Linux. It includes a web UI that will check the checksum of anything you upload.

• Step 1 is to deliberately break the VxWorks installation so that the bootloader will fail at startup time and accept other kinds of images. This is the purpose of the "vxworks-killer.bin" referred to in the official instructions.

• When the bootloader has a heart attack, it will reset back to listening on 192.168.1.1 for tftp. You can use any tftp client to send it an image that you want it to try loading; it reboots automatically after the transfer is complete. Despite rumours, it takes only a few seconds to save a new image to flash, so you don't have to wait 2 minutes or anything ridiculous.

• If your new image is "valid" but fails to boot (eg. if it's for the wrong hardware model), the system won't answer pings anymore and there's no way to tftp to it. This is the state you're normally in when you need the "how to unbrick your router" instructions linked above.

• The "unbrick" instructions are a very long and unclear way of explaining this simple fact: if you reboot the router while holding the RESET button, the bootloader will sit for 10 seconds in its tftp-receptive state (192.168.1.1, accepting tftp connections) before starting to load the real OS. If you hardcode your workstation to 192.168.1.x and continuously ping 192.168.1.1 while rebooting with the RESET button pressed, you'll see that about 10 pings get through.

• So the trick is to tftp the file during that 10 seconds. Basically, run a ping in one window, and be ready to hit "enter" to launch the tftp command in another window. Reset your router. When you see the first pings start to come back, launch the tftp right away.

Once you understand all these steps, you can understand something important: it's very hard to break your router through experimentation! The worst you can do is load a totally invalid image via tftp... and if that happens, you just do the RESET-ping-tftp trick to replace it with a different one.

This is a nice design. Congratulations, Linksys and/or Broadcom, for putting a safe bootloader into your routers.

Update 2008/02/18: I forgot to mention one important thing: the "micro" version of dd-wrt is surprisingly full-featured. It wasn't missing a single thing that I expected my router to be able to do; I'm not even really sure what's supposed to go into the non-micro versions. So I wholeheartedly recommend it and encourage you not to think of it as "stripped down" or "low-end" like I thought it would be.