Hack 57 Getting Started with Host AP

Use a Prism II radio card with Linux as if it were a hardware access point.

The Host AP driver will allow a Prism-based radio card to operate as a BSS Master or Slave, and can also do IBSS mode. PCMCIA, PCI, and mini-PCI radios are all supported. It is highly recommended that you use a 2.4 Linux or later kernel if you use Host AP. To get started with Host AP, first download the driver at http://hostap.epitest.fi/. If you need to run a Hermes-based card (such as the Lucent/Orinoco/Avaya/Proxim), take a look at [Hack #61].

Once the driver is unpacked, you simply run a make with the name of the driver you want to build: make pccard builds the PCMCIA driver, make plx builds the non-PCMCIA (plx-based) PCI PC Card driver, and make pci builds the standard PCI driver. The hardware-independent driver code is automatically built regardless of the driver you choose. It doesn't hurt to build all of the drivers, unless space is a critical consideration on your system. To install the drivers, run make install_pccard, make install_plx, or make install_pci respectively.

PCMCIA

If you are installing the PCMCIA driver, the make process automatically copies hostap_cs.conf to your /etc/pcmcia/ directory, so that your cards will be properly detected when they are inserted. It doesn't hurt to stop and start PCMCIA services once you have installed the Host AP driver. Once installed, the wireless device will be called wlan0 (and the second is called wlan1, etc.).

Setting up radio parameters is very straightforward. If you are using the PCMCIA driver, all of the wireless parameters are set in /etc/pcmcia/wireless.opts.

Here's an example wireless.opts for BSS Master (i.e., Host AP) mode:

# # wireless.opts # case "$ADDRESS" in *,*,*,*)         INFO="A card in Host AP Master mode"         ESS         MODE="Master"     CHANNEL="6"         RATE="auto"         ;; esac

You may be thinking, "My God, it's full of stars...." But if you have ever worked with network.opts, the syntax is exactly the same. If you haven't, those asterisks allow for tremendous flexibility.

The script is passed a string in $ADDRESS that gives details about the card that was inserted, so you can have different entries for different cards. The address matching syntax is:

scheme, socket, instance, MAC address)

The scheme allows for setting up as many arbitrary profiles as you like. The most common use for schemes is on a client laptop, where you may have different network settings for your office wireless network than for your home network. You can display the current scheme by issuing the cardctl scheme command as root, and change it by using a command like cardctl scheme home or cardctl scheme office. Both wireless.opts and network.opts are scheme-aware, allowing you to change your network and wireless settings quickly with a single command.

The second parameter, socket, is the socket number that the PCMCIA card was inserted into. Usually, they start with 0 and go up to the number of PCMCIA slots you have available. To find out which is which, insert a card in one slot and issue the cardctl status command.

The third parameter, instance, is used for exotic network cards that have more than one interface. I haven't come across one of these, but if you have a network card that has more than one network device in it, use this to set different parameters for each device, starting with 0.

I find the last parameter very useful, as you can match the setting to a specific MAC address. You can even include wildcards, to match a partial MAC address, like this:

*,*,*,00:02:6F:*)

This would match a Senao/EnGenius card inserted in any slot, in any scheme. Keep in mind that the wireless.opts is only called to set radio parameters. Network settings (such as IP address, default gateway, and whether to use DHCP) are set in network.opts, just like any other PCMCIA network device.

One further caveat when using the PCMCIA Host AP driver: some machines (notably the Stylistic 1000) have a problem loading the Host AP driver with some Prism II cards. The symptom is that the card is detected on insert, but mysteriously fails to initialize, reporting an obscure error to the effect of "GetNextTuple: No more items". If you are having trouble with the driver, try adding this line to your hostap_cs.conf (replacing any existing module "hostap_cs" line):

module "hostap_cs" opts "ignore_cis_vcc=1"

Normally, the driver attempts to verify that one entry on the card's acceptable voltage table matches the voltage reported by your PCMCIA slot. In some cases, this voltage can be incorrectly reported, causing the driver to fail to initialize. This option causes the driver to ignore the reported voltage and load anyway. It works like a charm on my Stylistic 1000 with a Senao 200mW card.

PCI

Configuration of a PCI or mini-PCI Prism II card is much the same as any other network device. At some stage, you need to configure the radio parameters manually with calls to iwconfig. This is best done in the boot-up process after the kernel modules are all loaded, but before your device configures its IP stack. Simply create an initialization script with a line like this:

iwconfig wlan0 essid "NoCat" mode "Master" channel 6 rate "Auto"

Copy this script to /etc/init.d/, and symlink it to an appropriate place in /etc/rc2.d/, or wherever the appropriate place is for your default run level. Unfortunately, every Linux distribution has a slightly different mechanism for processing the boot up rc scripts, so if in doubt, consult your distribution's documentation.

Once your radio parameters are configured, treat the wlan0 device as if it were any other Ethernet interface. Give it an IP address, set up your routing, and bind processes to its IP as you normally would. The Host AP driver takes care of all of the details of managing your wireless clients for you. If you ever need to change the radio parameters of the card (whether using PCMCIA or PCI), you can always change parameters and view the current status with iwconfig:

root@pebble:~# iwconfig wlan0 wlan0     IEEE 802.11b  ESSID:"NoCat"             Mode:Master  Frequency:2.437GHz  Access Point: 00:02:6F:01:85:74             Bit Rate:11Mb/s   Tx-Power=24 dBm   Sensitivity=1/3             Retry min limit:8   RTS thr:off   Fragment thr:off           Encryption key:off           Power Management:off           Link Quality:0  Signal level:0  Noise level:0           Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0           Tx excessive retries:0  Invalid misc:0   Missed beacon:0

That is all you need to do to bring up a simple Host AP configuration. If you are curious about how to tweak your Host AP to perform more elaborate functions, or about how to monitor its status and that of all of your connected clients, see the other hacks in this section.