madwifi-tools
=============

The following paragraphs briefly describe the madwifi-tools. They are
crucial to the normal operation of the MadWifi modules.


1. VAP's
========

What are they and why are they so special?

Virtual AP (VAP) mode [1], allows the operation of multiple concurrent virtual
access points, and concurrent virtual interfaces running in both AP and station
mode (only one station mode VAP can exist per device).

By default, one station is created per device (emulating standard behaviour).
The autocreation behaviour [2] can be manipulated by providing an option to the
ath_pci module when it is loaded.

Usage: modprobe ath_pci autocreate=[none|sta|ap|wds|adhoc|ahdemo|monitor]

The following example would disable autocreation, and only the "base" device
would be present:- 

	# modprobe ath_pci autocreate=none

To make this behaviour default, create a /etc/modprobe.d/madwifi file with 
the following content:-

	options ath_pci autocreate=none

Disabling autocreate is encouraged if you would like to take advantage of the
automated VAP management techniques discussed in Section #3 of this article.

[1] http://madwifi.org/wiki/ngFeatures#VAPsandwlanconfig
[2] http://madwifi.org/wiki/UserDocs/autocreate


2. wlanconfig
=============

This is the master tool for creating and destroying VAP's [3]. On Debian
systems it is located at /usr/sbin/wlanconfig. It's usage is well described in
the wlanconfig(8) manpage.

[3] http://madwifi.org/wiki/UserDocs#CreatingInterfacesinmadwifing


3. Automating VAP creation in /etc/network/interfaces
=====================================================

The following examples do not work for hotpluggable cardbus cards and the
like that are started by ifupdown with `allow-hotplug'. To make use of VAP
autocreation techniques you are required to use the `auto' line for your
interface or invoke ifup manually. These methods assume that your device is
always present.

Use pre-up/post-down routines to automate VAP creation and destruction as in
the following example:-

	iface ath0 inet static
		pre-up wlanconfig ath0 create wlandev wifi0 wlanmode ap
		post-down wlanconfig ath0 destroy
		wireless-essid my-essid
		...

This package also provides useful scripts for allowing more comfortable
creation/destruction of madwifi VAP's via special macro's in an interfaces
/etc/network/interfaces stanza:-

	iface ath0 inet static
		madwifi-base wifi0
		madwifi-mode sta
		wireless-essid my-essid

In the above example an `ath0' VAP would be created in the pre-up phase of ifup
and destroyed in the post-down phase of ifdown. All VAP modes are supported via
`madwifi-mode' and `madwifi-base' defines the parent device that the VAP should
be created from.


4. Setting of country code
==========================

With some cards, and in some countries, you might benefit from country specific
frequencies by passing the parameter "countrycode" to the ath_pci kernel
module.

Under 2.6 kernels, this can be done by creating a /etc/modprobe.d/madwifi file
with the following content:-

	options ath_pci countrycode=123

An online list of country codes can be found at:-

	<http://www.unicode.org/onlinedat/countries.html>

Or in the iso-codes package under:-

	/usr/share/xml/iso-codes/iso_3166.xml

madwifi only recognizes a subset of these codes, eg. "France, Metropolitan"
(249) won't be recognized while "France" (250) is.

Passing a country code parameter forbids the use of "turbog" modes (where
multiple frequencies are used to transmit data between turbog-capable chips).

For more information on how and why madwifi must honor regdomain restrictions,
please see http://madwifi.org/wiki/UserDocs/CountryCode.


5. Debugging tools
==================

athdebug and 80211debug are two programs that can be used to control the amount
of debugging output (dmesg and /var/log/messages). They are best described at:-

	http://madwifi.org/wiki/DevDocs/AthDebug