Documentation: Linux vs. FreeBSD – a real-world example

With every operating system there comes the time when you need help with something (if you’re not the absolute Über-guru, that is). If you are in need of help, there are many ways to get it. You can ask an experienced colleague or friend if available. If not, you can search the web. There is a very high possibility of the information that you need being out there, somewhere. If not, you could ask for help and hope that somebody answers. Well, or you could consult the documentation!

In most cases somebody has been right there before and asked for help on the net and somebody else gave an answer. That answer may or may not be correct, of course. And in fact it might even have been correct at some point in time but is no longer valid. This is a very common thing and we have learned to optimize our searches to more or less quickly find the answers that we need. After getting used to that habit, “google it” (replace with $search_engine if you – like me – try to avoid using Google services when possible) is probably the most common way to deal with it once you hit a problem on unfamiliar ground. So while users of Unix-like systems are usually aware of the existence of manpages, I’d say that especially younger people tend to avoid them. And really: You don’t need them. Except for when you do!

Public WLAN

Last week I had two appointments in another city. So I took one day off from work, got up early in the morning and drove about 1.5 hours to the first one. The second one was a few hours later and so I was left with something extremely precious: Free time! To make it even better, neither my children nor my wife were around. The perfect opportunity to get something done!

One of my hobbies aside from computer stuff is writing. In addition to shorter stuff, I also have a fantasy novel (called “Albsturm”) that I’m writing on as time permits (which it hardly ever did during the last two years). And so I figured that it would be a good idea to take a laptop computer with me and spend some hours writing (hint: Like always, I didn’t write a single sentence!). I have two reasonably new laptops that I could choose from, one running Arch Linux, the other one FreeBSD and OpenBSD. The latter is the smaller one and for that simple reason I took that one with me.

It was a warm day and I decided to sit down at a café, have a drink and do my stuff there. When I found one, I saw a sticker which told me that public WLAN was available there. Hm. Other than writing I also had a more or less urgent email to write. Should be a quicky, just a few lines. So I thought that I should probably start with that.

Offline!

The only problem was that I had no idea whatsoever on how to connect to the WLAN using FreeBSD or OpenBSD! In fact I had no idea how to do it on Linux, either. I’m an “all cable guy”. It feels like about two decades ago that I had my first wireless mouse. I really liked it – until the batteries ran out of charge in a very bad moment and I didn’t have any replacement ready. Wireless stuff may be convenient as long as it works, but I prefer reliability over that. And I also like to set up basic things once (which means that I wouldn’t like to have to change a WLAN channel if my neighbor gets a new access point which occupies the same one that I had used before – stuff like that).

The three or four times that I had used WLAN before was on a Linux box using the graphical Network Manager which does all the magic behind the scenes. Yes, I’m aware that PC-BSD has its own tool which does the same job and GhostBSD has another for people like me who prefer a GTK application over a Qt one. I had neither PC-BSD nor GhostBSD on my laptop however. Just vanilla FreeBSD (with EDE as the desktop) and OpenBSD without any desktop (because I didn’t have time to install one, yet).

So there I was, offline and looking for a way to go online. Obviously “google it!” or some variant of that did not apply here. Sure, the adventure could have ended just there. But I am a weirdo who refuses to take a mobile with him everywhere he goes like most other people seem to do these days. Now if that’s shocking for you or you just cannot believe that someone who deals with tech does not have his mobile in reach all the time: Just imagine that I had one but it ran out of power (I’ve seen this happen to friends often enough to know that it’s quite common)! 😉

Ok, what now? Thinking about it for a second, I realized that I had made a mistake when installing my system. You don’t install doc when you’re setting up a new system, right? The (absolutely excellent) FreeBSD handbook is available online after all. So why should you? Yeah. So am I on my own here? No! It’s me and a man’s man(1)! Will that suffice to go online?

Help!

Thanks to my previous exposure to help systems, this was the moment where I could have felt a cold chill (which would actually have felt good due to the warm weather). Remember the Windows 9.x “help” system? I cannot remember a single time when it had actually helped me. It either found nothing even remotely connected to my problem or it gave some generic advice like “ask the network administrator” (I AM the “network administrator”, dammit! I’m the guy who plugged those four cables into the switch and gave static IPs to the PCs!). It was utterly useless – and in a later version they “improved” their help by adding a stupid yellow dog… (When PC people talk about “the good old times” this is what you should remind them of :p)

But let’s not waste any more time on the horrible demons of the past and skip to the friendly daemons of today! I’ve used manpages a few times on Linux systems. This was a much better experience but still a vain effort often enough. The worst thing: For a lot of commands there are both a manpage and an info page – and those two are not identical at all! With a bit of bad luck you skimmed through one help text but the relevant information is only present in the other. Even though I can see the limitations of the older manpage system and understand the intent to create something better… No, sorry. If GNU really wanted to go with info pages instead of manpages they should just have created manpages which point the reader at the info page for each command. Just don’t make me read both because they have different information in them!

FreeBSD has a natural advantage here due to its whole-system approach. If you install third-party packages (say GNU’s coreutils) you will be in for the same mess. But everything that belongs to the base system (and that’s a whole lot of stuff!) is a consistent effort down to the manpages. And from what you hear or read on the net, the BSDs pride themselves in dedicating a fair amount of time to write documentation that’s actually useful! Does the result live up to that claim? We’ll see.

Where to start?

Manpages… Ok, sure. Just what should I start to look for? As I said, I didn’t know too much about the topic. Hm! I couldn’t think of anything quickly, so I actually did a apropos wlan. It wasn’t a serious search and I didn’t really expect anything to show up. Here’s the output of that command from a Linux box:

apropos: nothing appropriate

So was I right there? No! I was in for a first pleasant surprise. Here’s the output on my FreeBSD machine:

snmp_wlan(3) - wireless networking module for bsnmpd 1
wlan(4) - generic 802.11 link-layer support
wlan_acl(4) - MAC-based ACL support for 802.11 devices
wlan_amrr(4) - AMRR rate adaptation algorithm support for 802.11 devices
wlan_ccmp(4) - AES-CCMP crypto support for 802.11 devices
wlan_tkip(4) - TKIP and Michael crypto support for 802.11 devices
wlan_wep(4) - WEP crypto support for 802.11 devices
wlan_xauth(4) - External authenticator support for 802.11 devices
wlandebug(8) - set/query 802.11 wireless debugging messages

Not bad, huh? 9 hits compared to… 0! I had nowhere better to go, so I read wlan. It provided a fair amount insight into things that I was not too interested in at that moment. But it had a rather big SEE ALSO section (which I feel kind of lacking in the Linux manpages that I’ve read so far). This proved extremely useful since a lot of device drivers were mentioned there and I figured that this would actually be a good place to really start.

Dmesg told me that my machine has an “Intel Centrino Advanced-N 6205” and that the corresponding driver was iwn. However ifconfig showed no iwn0 interface. There were only em0 and lo0 there. How’s that? I figured that it probably had to be set up somehow. And had I not just read about the generic wlan driver?

The wlan module is required by all native 802.11 drivers

The same manpage also pointed me to ifconfig(8) which makes sense if you want to do interface related stuff (unless you’re on newer Linux systems which sometimes do not even have ifconfig and you have to use the ip utils).

The ifconfig(8) manpage is a really detailed document that helped me a lot. So it’s only

ifconfig wlan0 create wlandev iwn0

and my wlan interface appears in the list showed by running just ifconfig! That was pretty easy for something which I would have never figured out by myself.

Let’s go on!

The first step of what could have been a painful search turned out to be so surprising easy that I was in a real light mood. So instead of just getting things to work somehow(tm), I decided to do it right instead. It was only one simple command so far but I wouldn’t want to enter it again after each reboot. So it was time to find out how to have the init system taking care of creating my interface during system startup.

Phew. That could be a tough one. What obscure configuration file (or worse: systemd “unit file”) could WLAN configuration stuff go into? Hey, this is FreeBSD! Want init to do something for you? Have a look at /etc/rc.conf!

Hm. Sometimes configuration files have their own manpages, right? But even if there was one, it could hardly cover everything. Would somebody take the time and put what I need in there? Ah, let’s just give it a shot and man 5 rc.conf. Yes, there’s a manpage for it. But not just a manpage. I mean… Wow, just wow. I’m still amazed by the level of detail everything is described with! Should you ever take a look, you’ll be in for a treat of over 2400 lines! Does it cover WLAN interface creation? You bet it does! And it holds more information about that topic than fits on one terminal screen. In my case it boils down to:

wlans_iwn0="wlan0"

Really simple again – which is really encouraging if you’re new to a topic (on an operating system you’re only slowly getting familiar with because you have to spend most of your time with Linux machines).

The manpage also mentions wpa_supplicant(8) and after reading a bit about it and wpa_supplicant.conf(5), I had my system automatically make a WLAN connection during startup: It received and ack’d a DHCP offer and got an IP. Great!

Hold captive by the portal

Time to fire up a browser and surf to some website to see if it works… Oh my. What’s that? A captive portal redirects me to a page with payment information! That’s not quite what I’d call “free WLAN”! What happened? The page says “Telekom” but the sticker said that the hotspot was provided by another company. So I must be connected to the wrong one…

So it’s reading ifconfig(8)’s manpage again. Turns out that ifconfig wlan0 scan returns a list of available networks. So far so good. Of course the manpage also explains how to manually connect to a network of your choice. But this is where things went into the wrong direction for me.

The SSID of the network that I wanted to connect to was too long to fit into the column that ifconfig reserves for the output… Gosh. Now how would I connect to that one? Guess the rest of the name? Probably not a good tactic. What else? I could not connect to the network that I knew was free and I didn’t want to just randomly try connecting to the others.

Autoconnection makes its decision by signal strength. It’s rather unfortunate that the stupid paid Telekom one had a better signal where I was sitting. But by blocking that one network there’d be a good chance that the right one would have the second best signal, right? So I only have to somehow blacklist the Telekom network.

A long story short: This proved to be a dead-end. I still have no idea if it’s even possible to blacklist a network using wpa_supplicant.conf. It probably isn’t and the only way to go is define the desired network with a higher priority than the undesired one. It took me quite some time to give up on this path that seemed to lead nowhere.

What now? It looked like I had to somehow get my hands on the complete SSID of the right network. But how to do that? I could of course always ask a waitress as she probably either knows it or at least could ask somebody who does. However after spending quite some time on the matter, I wanted to figure it out myself. Finally I came across ifconfig(8) again and it mentions the -v flag to show the long SSIDs (and some more info)!

With the full SSID known to me I could adjust my wpa_supplicant.conf – and after a reboot the system picked the right network. My browser was lead to a different captive portal and after I read and accepted the license terms (which were quite reasonable), I was free to surf wherever I wanted.

I quickly wrote and sent the mail that lead me to this adventure in the first place. Then I shutdown -p now my system, put the laptop in my car and drove to my second appointment.

Summary

I’ve had some Linux experience for almost two decades now and used it on a daily basis for about half of that time. In contrast to that I’m really new to the BSDs, seriously using FreeBSD for less than a year. I probably know less than 1% of the common taks on that OS – and even less on the topic of WLAN which I avoided as far as I could.

Getting my laptop to connect to the net via WLAN in a café using just the manpages because I was offline until I reached my goal seemed like a painful adventure full of potential pitfalls. Instead it proved to be an unexpectedly pleasant ride in unfamiliar territory.

There are many sources on the net that say BSD has far superior documentation compared to Linux. And I was impressed enough about that fact to add another one by writing this post. So if you’re a *BSD user and you need help I can only give the advice to take the time to read some manpages instead of looking or even asking on the net. It is much more rewarding to figure out things yourself using the documentation and the chance is quite high that you’ll learn another useful thing or two from it!

Can the same thing (connecting to a WLAN without graphical tools) be done on Linux? Certainly. How would you do that? I have no idea. Is there an easy way to figure things out just using the manpages? I kind of doubt it. With a lot more time on your hands: Probably. But after learning what real documentation tastes like, I don’t feel like trying it right now. I may do it in the future to complete the comparison. Or maybe not.