New upstream SVN snapshot.
[debian/madwifi.git] / debian / madwifi-tools.README.Debian
1 madwifi-tools
2 =============
3
4 The following paragraphs briefly describe the madwifi-tools. They are
5 crucial to the normal operation of the MadWifi modules.
6
7
8 1. VAP's
9 ========
10
11 What are they and why are they so special?
12
13 Virtual AP (VAP) mode [1], allows the operation of multiple concurrent virtual
14 access points, and concurrent virtual interfaces running in both AP and station
15 mode (only one station mode VAP can exist per device).
16
17 By default, one station is created per device (emulating standard behaviour).
18 The autocreation behaviour [2] can be manipulated by providing an option to the
19 ath_pci module when it is loaded.
20
21 Usage: modprobe ath_pci autocreate=[none|sta|ap|wds|adhoc|ahdemo|monitor]
22
23 The following example would disable autocreation, and only the "base" device
24 would be present:- 
25
26         # modprobe ath_pci autocreate=none
27
28 To make this behaviour default, create a /etc/modprobe.d/madwifi file with 
29 the following content:-
30
31         options ath_pci autocreate=none
32
33 Disabling autocreate is encouraged if you would like to take advantage of the
34 automated VAP management techniques discussed in Section #3 of this article.
35
36 [1] http://madwifi.org/wiki/ngFeatures#VAPsandwlanconfig
37 [2] http://madwifi.org/wiki/UserDocs/autocreate
38
39
40 2. wlanconfig
41 =============
42
43 This is the master tool for creating and destroying VAP's [3]. On Debian
44 systems it is located at /usr/sbin/wlanconfig. It's usage is well described in
45 the wlanconfig(8) manpage.
46
47 [3] http://madwifi.org/wiki/UserDocs#CreatingInterfacesinmadwifing
48
49
50 3. Automating VAP creation in /etc/network/interfaces
51 =====================================================
52
53 The following examples do not work for hotpluggable cardbus cards and the
54 like that are started by ifupdown with `allow-hotplug'. To make use of VAP
55 autocreation techniques you are required to use the `auto' line for your
56 interface or invoke ifup manually. These methods assume that your device is
57 always present.
58
59 Use pre-up/post-down routines to automate VAP creation and destruction as in
60 the following example:-
61
62         iface ath0 inet static
63                 pre-up wlanconfig ath0 create wlandev wifi0 wlanmode ap
64                 post-down wlanconfig ath0 destroy
65                 wireless-essid my-essid
66                 ...
67
68 This package also provides useful scripts for allowing more comfortable
69 creation/destruction of madwifi VAP's via special macro's in an interfaces
70 /etc/network/interfaces stanza:-
71
72         iface ath0 inet static
73                 madwifi-base wifi0
74                 madwifi-mode sta
75                 wireless-essid my-essid
76
77 In the above example an `ath0' VAP would be created in the pre-up phase of ifup
78 and destroyed in the post-down phase of ifdown. All VAP modes are supported via
79 `madwifi-mode' and `madwifi-base' defines the parent device that the VAP should
80 be created from.
81
82
83 4. Setting of country code
84 ==========================
85
86 With some cards, and in some countries, you might benefit from country specific
87 frequencies by passing the parameter "countrycode" to the ath_pci kernel
88 module.
89
90 Under 2.6 kernels, this can be done by creating a /etc/modprobe.d/madwifi file
91 with the following content:-
92
93         options ath_pci countrycode=123
94
95 An online list of country codes can be found at:-
96
97         <http://www.unicode.org/onlinedat/countries.html>
98
99 Or in the iso-codes package under:-
100
101         /usr/share/xml/iso-codes/iso_3166.xml
102
103 madwifi only recognizes a subset of these codes, eg. "France, Metropolitan"
104 (249) won't be recognized while "France" (250) is.
105
106 Passing a country code parameter forbids the use of "turbog" modes (where
107 multiple frequencies are used to transmit data between turbog-capable chips).
108
109 For more information on how and why madwifi must honor regdomain restrictions,
110 please see http://madwifi.org/wiki/UserDocs/CountryCode.
111
112
113 5. Debugging tools
114 ==================
115
116 athdebug and 80211debug are two programs that can be used to control the amount
117 of debugging output (dmesg and /var/log/messages). They are best described at:-
118
119         http://madwifi.org/wiki/DevDocs/AthDebug