Why setting up my access point was harder than it had to be

One reason I always try to be nice to newbies is that there are two different kinds:  people new to everything, and very experienced people who happen to be new to one area.  Everyone was the first kind at one point, and could find themselves being the second kind at any time.

This last weekend I found myself in the second category.  My wireless router died on me again.  I seem to go through about one per year (I suspect inadequate heat dissipation), and was sick of replacing them, so I decided to incorporate its functions into my desktop computer.

I’m about as qualified as you can get for undertaking such a task.  I’ve been using Linux extensively since the late 90’s, and write embedded software for network equipment for a living.  I knew all the pieces needed in generic terms, it was just a matter of finding, installing, and configuring the specific implementations on Ubuntu.

First step:  purchase new hardware.  I needed a second gigabit ethernet NIC for the wired side of the network, and an 802.11g interface for the wireless side.  Complicating matters, since my wife depends so heavily on wireless for her netbook, Nook, and Roku, I wanted to purchase the parts from my local Best Buy instead of my usual online sources so it could be up and running faster.

The gigabit ethernet NIC I didn’t even bother looking up hardware compatibility.  There may be some incompatible ones out there, but I have never seen one.  The 802.11g interface is more complicated.  There is wide support on the client side, but I knew using it as an access point has specific driver requirements.

I did some research on linuxwireless.org, cross referenced it with the inventory on Best Buy’s website, and came up with one possibility.  Only one?  That threw up a red flag, but Best Buy isn’t exactly known for their stellar Linux support, so I let it go.

I picked it up the next day after work, plugged it in, and it turned out to be v3 of that product, which used a different chipset than I was expecting.  I tried a command I had seen on a few HOWTOs anyway:  iwconfig wlan2 mode master.  Didn’t work.  Made sure I was using the best driver, and did some digging to see if there was a development version I could use, and eventually gave up.

Installing the wired side of the network with DNS, DHCP, NAT, and firewall went smoothly.  At least I knew those pieces would be working when I got the wireless up.

The next day, I returned the wireless interface to Best Buy, did some more research to make absolutely sure I was getting a compatible card, and ordered one online overnight delivery.  Plugged it in the next day, and the “mode master” command still didn’t work.

Now I knew something was up.  After some considerable google-fu, I discovered there is an easy new userspace way of handling all the access point management, but the easiest to find documentation all documented the old, more limited way.  In other words, the “mode master” command doesn’t work on purpose now.  Aside from a short issue with hostapd looking like it starts, but not really because of a setting in /etc/defaults/hostapd, I had it up and running fairly quickly.

So what’s the underlying software engineering principle here?  Outdated documents can sometimes be worse than no documents.  Here is this great new feature that makes it easier to do what I want, but because the docs for it are so obscure, it actually made it harder.

I intend to do more about it than rant on my blog.  Ubuntu will soon be getting some updated documentation courtesy one experienced newbie who just figured it out the hard way.  I consider it my way of “paying” for all the great software I use for free, and encourage all of you who solve similar problems to do the same.