IEEE 802.11 Wireless AP using a Soekris SBC

After having tossed several plug-and-play solutions to get IEEE 802.11 wireless connectivity at home, at chat with the folks of the Wireless Leiden initiative (hi Rudi!) drew my attention to the Soekris Engineering Single Board Computers (SBC). These SBC's are compact (easy to fit almost anywhere), low-power, low-cost and can be expanded using a MiniPCI type III board and up to two PC-Card adaptors. My pick: the net4521.

FRONT
 BACK

With the hardware picture now clear, I decided to also throw out the big, old, noisy, power-consuming PC that manages my ADSL line, in favour of the Soekris SBC (the latter comes with two built-in 10/100 Mbps Ethernet RJ-45 UTP ports). Fortunately, the entry point of the ADSL cable is also the best location to fit a small omni-directional antenna to cover most part of the house and the backyard.

The advantage of this do-it-yourself project over a turn-key solution, is that you can get a finer grain of control ranging from wireless interface and/or radio settings to the ability to run IPsec or IPv6, which you usually don't find in the low-cost SOHO market products. And... it's way more fun!

Installing FreeBSD on the Soekris "net4521" SBC

One of the best things of the Soekris "net4521" SBC is that it is designed for FreeBSD :-) Well, that's fine, but how do you get a FreeBSD installation on a box that had neither CD-ROM nor floppy drive and whose storage is a Compact Flash card... The answer: via the network!
The "net4521" (and other models) contain a smart boot ROM that contains Intel's Preboot eXecution Environment (PXE). FreeBSD supports this with pxeboot, a modified version of the system third-stage bootstrap. After DHCP configuration, pxeboot retrieves the kernel, modules, and other files either via NFS or TFTP, selectable through compile-time options.

Before you proceed, make sure you have a fairly recent FreeBSD system with full sources installed. This document is written for RELENG_4_8, the security branch of RELENG_4_8_0_RELEASE, commonly known as "FreeBSD 4.8". Also check that the kernel on your development system contains the vnode driver (the GENERIC kernel doesn't!). When applicable, rebuild your kernel with this option:

  pseudo-device   vn              # Vnode driver (turns a file into a device)

1. Prepare PXEBOOT and the LOADER

The pxeboot program can fetch loader and kernel via TFTP or NFS. If you, like me, want to avoid having to set up NFS on your server, you can re-compile pxeboot to use TFTP only. Additionally, pxeboot and the loader by default try to emulate a cons25 terminal, which causes the usual spinning-characters to spread all over the screen and effectively yields the boot details almost unreadable.
Apply the modifications listed below. Note that pxeboot, the loader and others will be installed in /tftpboot in a later stage when you will be running a make (see chapter 2).

  # vi /etc/make.conf
    LOADER_TFTP_SUPPORT= YES

  # cd /usr/src/sys/boot/i386/libi386
  # vi Makefile
    #dont#CFLAGS+= -DTERM_EMU

  # cd /usr/src/sys/boot
  # make clean depend all install

1.1 Prepare the DHCP and TFTP server

If you don't have a running DHCP server already, build isc-dhcp3 from the ports collection:

  # cd /usr/ports/net/isc-dhcp3
  # make all install clean

PXE needs two additional directives from the DHCP server: the next-server it will query and the root-path of the tree where to find the files it is supposed to retrieve. Here's a sample entry from the DHCP configuration file /usr/local/etc/dhcpd.conf:

  # vi /usr/local/etc/dhcpd.conf
    host soekris {
       hardware ethernet 0:0:24:aa:bb:cc;
       fixed-address soekris.example.net;
       filename "pxeboot";
       next-server 192.168.1.2;
       option root-path "/tftpboot";
    }

To enable the TFTP server: uncomment the tftp line from /etc/inetd.conf to read:

  tftp	dgram	udp	wait	root	/usr/libexec/tftpd	tftpd -s /tftpboot

Don't forget to restart inetd:

  # kill -HUP `cat /var/run/inetd.pid`

2. PBI: PXE Boot Image

In order to be able to do anything useful on the Soekris SBC, aside from staring at the little box, admiring its color, we must find a way to tell it to boot FreeBSD and give us a shell prompt. Basically, there are just a few things we really want to do in the early stages, like:

1. Boot FreeBSD using a minimal kernel so that we can verify that at least the hardware is okay.
2. Provide the tools to initialize the CompactFlash card (fdisk, disklabel, newfs, mount) and to configure the network (ifconfig)
3. Network download of a diskimage to copy to the CompactFlash (tftp, dd)

Our goal is to build both a kernel and a (small) root filesystem in memory: a MFS filesystem mounted as the root filesystem. I call the package that builds both, the PBI (PXE Boot Image).

2.1 PBI: the kernel

A custom kernel build is required to get a small kernel, tailored to the Soekris hardware, although one could probably get away with booting the GENERIC kernel. Have a peek at the kernel config that I use and proceed to the next section.

2.2 PBI: the MFS root filesystem

Creating a MFS root filesystem is a bit more work, but the good news is that it's just a matter of simply running make and you will be ready. The techniques used resemble those used in e.g. PicoBSD, but a bit simplified.

Download the tarball pbi-4.8.tar.gz and unpack it in a directory of your choice. If you prefer, you can browse the PBI tree before downloading the gzipped tarball (which is actually only 6 KB or so).

  # cd /some/where/i/want/it
  # tar zxpvf pbi-4.8.tar.gz

Take a few minutes to walk yourself through the files in the "pbi" directory. You'll see that the Makefile does most of the work. If the home directory of your TFTP server is not /tftpboot, you might want to edit the pbi/Makefile and change the line that reads:

   PXEROOT?=       /tftpboot       # TFTP root directory

The file crunch.conf.in is used by crunchgen to create a build environment for the tools you want to have available in the root filesystem on the Soekris. If you're confident enough to start the build, simply run make (as 'root' !) in the "pbi" directory:

  # cd pbi
  # make

This will do the complete build (kernel + root mfs) and install the results (with the 'pxeboot' modified in chapter 1) in the directory /tftpboot. Here's a transcript of the output from the make command on my system for comparison. Now, inspect the /tftpboot directory; it should look similar to this:

  /tftpboot:
    drwxr-xr-x  3 root  wheel      512 Jan  6 21:52 boot
    -rwxr-xr-x  1 root  wheel   524323 Aug 16 16:54 kernel.gz*
    -rw-r--r--  1 root  wheel  2560000 Aug 16 16:54 mfsimage.bin
    -rw-r--r--  1 root  wheel   157696 Apr 19 10:13 pxeboot

  /tftpboot/boot:
    drwxr-xr-x  2 root  wheel     512 Jan  6 21:52 defaults
    -r-xr-xr-x  1 root  wheel  155648 Aug 16 16:53 loader*
    -r--r--r--  1 root  wheel    9237 Apr  3 10:55 loader.4th
    -rw-r--r--  1 root  wheel      85 Aug 16 16:54 loader.conf
    -rw-r--r--  1 root  wheel      31 Aug 16 16:54 loader.rc
    -r--r--r--  1 root  wheel   25121 Apr  3 10:55 support.4th

  /tftpboot/boot/defaults:
    -r--r--r--  1 root  wheel   11067 Oct 11 21:42 loader.conf

2.3 Boot the Soekris SBC

To connect the serial line of another PC to the serial port of the Soekris, you need a DB-9 female-female null-modem cable. Here's the pinout of the one I made:

   1  /- o          o -\  1      although you might get   1  o          o  1
   2  |  o -------- o  |  3       away with just this :   2  o -------- o  3
   3  |  o -------- o  |  2                               3  o -------- o  2
   4  +- o          o -+  4                               4  o          o  4
   5  |  o -------- o  |  5                               5  o -------- o  5
   6  \- o          o -/  6                               6  o          o  6
   7     o -------- o     8                               7  o          o  8
   8     o -------- o     7                               8  o          o  7
   9     o          o     9                               9  o          o  9

Assuming that you have the serial ports connected, you can power-on the Soekris and watch it start up. Stay awake to Press Ctrl-P for entering Monitor in time and boot from the network (Eth0):

  > boot f0

If DHCP is working on your server and the TFTP server enabled, it should now retrieve the kernel and MFS and start executing it. Here's a transcript of the Soekris boot messages from my system.

At this point, we're running FreeBSD and we can type commands (do a "ls bin" to see what generic FreeBSD commands are available).
Assuming that this is a complete new system, you'll want to initialize the CompactFlash card: the setup script will do it for you (note that this script is still work in progress). The script will create a single root partition (ad0s1a) on the card. I use 32 MB cards, by the way.

  # setup

3 CFFS: Compactflash FreeBSD Filesystem

(todo)

References

• FreeBSD Jumpstart Guide by Alfred Perlstein.
• Booting FreeBSD with PXE by Matt Simerson.
• miniBSD - reducing FreeBSD by Manuel Kasper.