Hack 46 AirPort Linux

Turn your Graphite AirPort (or other KarlNet based AP) into a full-fledged Linux router.

Lurking underneath the shiny "War of the Worlds" clam shell of the Graphite Apple AirPort (http://www.apple.com/airport/) is a complete computer. Originally designed by KarlNet (http://karlnet.com/), the guts of the Apple AirPort essentially are the same as the Proxim RG1000, RG1100, and a few other access points. To network hackers, this presents an enormous opportunity and challenge: if a more capable OS (such as Linux) can be made to run on AirPort hardware, then it should be possible to build a "Super AP" that can perform much more complicated tasks than a standard AP. For example, a Linux AirPort could handle dynamic routing, firewalling, and even manage Internet tunnels, such as IPIP [Hack #54] or GRE [Hack #55].

A number of people have made quite a bit of headway on this project. The single greatest obstacle has been trying to shoehorn a usable system onto the system itself. The AirPort is a very tiny computer with meager hardware resources. It is essentially a 486 CPU (without floating point) with only 4 MB of RAM and 512 KB of flash storage. By today's PC standards, it isn't much more than a pocket calculator.

These severe physical restrictions have led to a number of trade-offs:

• The system needs a lightweight kernel. The kernel of choice at the moment is from the Linux 2.2 series to save on RAM.

• There isn't nearly enough room to store a usable Linux system on the flash, so the root filesystem is kept on an NFS share. This share is mountable over the Ethernet or over wireless.

• With only 4 MB of RAM, application space is very limited. Lightweight applications like telnetd are still usable, but running sshd is virtually impossible.

• Since the card inside the AirPort is a Hermes-based radio, Host AP [Hack #57] won't work with it. To date, no one (to my knowledge) has gotten Hermes AP [Hack #61] working with AirPort Linux, although it can be done. This means that the wireless must be used in Ad-Hoc mode, and Ethernet bridging isn't possible.

AirPort Linux works by uploading a custom firmware to the AirPort that instructs it to boot from the network. If you decide later that you would like to turn your AirPort back into a traditional AP, you can simply flash the firmware with Apple's original version. To get AirPort Linux running, you need a server capable of providing DHCP, TFTP, and NFS services. Any old Linux or BSD server will do.

Installation

AirPort Linux was pioneered by Till Straumann. His original project is well documented online at http://www-hft.ee.tu-berlin.de/~strauman/airport/airport.html; however, the quickest way to get started is to go to http://www.seattlewireless.net/index.cgi/AirportLinux and download the AirportLinux-0.01.tar.gz package. This is just a collection of all of the software you need to get things going with a bit of documentation.

First, set up the necessary services on your Linux or BSD server. Extract the AirPortLinux-0.01.tar.gz archive, and cd into it. For simplicity, I will install the software in directories under /remote/, but you can put them wherever you like:

~/AirportLinux-0.01# mvserver/tftpboot / ~/AirportLinux-0.01# mkdir /remote; mvairport /remote

The /tftpboot/ directory contains the tiny kernel that the AirPort will boot, and /remote/airport/ contains the root filesystem. Now that the data is in place, configure tftpd and NFS. Put a line like this in your /etc/inetd.conf, and restart inetd:

tftp      dgram      udp      wait      root      in.tftpd

Add the following to /etc/exports and restart rpc.nfsd. Make sure that portmap is also running.

/remote/airport       airport(ro)

We now need to configure dhcpd to serve a static IP to the AirPort, and to give it additional boot parameters. To do this, you need the hardware MAC address of your AirPort. The MAC addresses of the Ethernet and wireless cards are listed on the bottom of the unit. If you are booting from the Ethernet (most likely), use the Ethernet ID. If you plan on booting from the AirPort card, use the AirPort ID. Note that wireless booting can be tricky to configure, and is definitely slower than booting from the wire. I recommend using the Ethernet for booting whenever possible.

Now that you have the proper MAC address, create a stanza like the following in /etc/dhcpd.conf, and restart dhcpd:

host airport {                 hardware ethernet  00:30:65:FF:AA:BB;                 filename "/tftpboot/vmlinubz.nbi";                 option host-name "airport";                 option option-130 "eth0";                 option root-path "/remote/airport";         }

Naturally, substitute the real MAC address for 00:30:65:FF:AA:BB. Finally, pick an unused IP address on your local network and add an appropriate entry to your /etc/hosts file:

10.15.6.20 airport

Now that your server is ready to serve AirPort Linux, you are ready to flash your AirPort hardware.

Flashing the AirPort

The simplest way to flash the AirPort is to use the Java Configurator [Hack #47]. A copy is included in the AirportLinux-0.01.tar.gz archive for convenience, in the etherboot/ directory. Boot the AirPort as you normally would, and make a note of the IP address it is using. Fire up the Configurator, enter the IP address and password for your AirPort, and select File Upload new base station firmware.... When prompted for a file, select the etherboot/etherboot-airport.bin file from the archive. Wait a few moments, and your AirPort will reboot. After it resets, it is very important to hard boot the AirPort by removing and reapplying the power. It's a good idea to do this any time you flash the firmware on a device, just to be sure you are starting with a fresh boot.

In a few moments, you should be able to ping the AirPort at the IP address you specified; and when it has finished booting, you can telnet to it. Log in as root with no password, and you should have a shell on your very own AirPort:

$ telnet 10.15.6.20 Trying 10.15.6.20... Connected to 10.15.6.20. Escape character is '^]'. airport login: root BusyBox v0.60.2 (2002.08.30-19:59+0000) Built-in shell (msh) Enter 'help' for a list of built-in commands. #

Change the root password with the usual passwd command, and your system is ready to use. Configure the interfaces with ifconfig and iwconfig as you normally would. If you are unable to get to the AirPort after it has rebooted, look closely at the DHCP, TFTP, and NFS logs on your server (many times, they all end up in /var/log/messages). You should see the AirPort request a DHCP lease, request vmlinubz.nbi from in.tftpd, and eventually mount /remote/airport once the kernel has booted.

Putting It Back

If you ever need to turn your AirPort back into a plain vanilla AP, it is as simple as flashing the firmware again. Reboot the AirPort without the Ethernet cable connected. It will create a network called "AirPort xxxxxxxx." Associate your Mac with this network, and run Apple's AirPort configuration utility. It will automatically find the AirPort. Double-click on the AirPort, and enter the AirPort's hardware password. The AirPort Configuration utility will tell you that there is updated firmware available. Click "Yes" to update the firmware, and when the AirPort reboots, it will be back to its old self.

AirPort Linux isn't for everybody, but it can allow some very tricky things to happen with the AirPort hardware. If this still doesn't provide enough flexibility for your wireless project, you might try building your own AP from scratch [Hack #51].