Document madwifi specific diversity and antenna settings (#3889
[openwrt/openwrt.git] / docs / wireless.tex
1 The WiFi settings are configured in the file \texttt{/etc/config/wireless}
2 (currently supported on Broadcom, Atheros and mac80211). When booting the router for the first time
3 it should detect your card and create a sample configuration file. By default '\texttt{option network lan}' is
4 commented. This prevents unsecured sharing of the network over the wireless interface.
5
6 Each wireless driver has its own configuration script in \texttt{/lib/wifi/driver\_name.sh} which handles
7 driver specific options and configurations. This script is also calling driver specific binaries like wlc for
8 Broadcom, or hostapd and wpa\_supplicant for atheros.
9
10 The reason for using such architecture, is that it abstracts the driver configuration.
11
12 \paragraph{Generic Broadcom wireless config:}
13
14 \begin{Verbatim}
15 config wifi-device "wl0"
16 option type "broadcom"
17 option channel "5"
18
19 config wifi-iface
20 option device "wl0"
21 # option network lan
22 option mode "ap"
23 option ssid "OpenWrt"
24 option hidden "0"
25 option encryption "none"
26 \end{Verbatim}
27
28 \paragraph{Generic Atheros wireless config:}
29
30 \begin{Verbatim}
31 config wifi-device "wifi0"
32 option type "atheros"
33 option channel "5"
34 option agmode "11g"
35
36 config wifi-iface
37 option device "wifi0"
38 # option network lan
39 option mode "ap"
40 option ssid "OpenWrt"
41 option hidden "0"
42 option encryption "none"
43 \end{Verbatim}
44
45 \paragraph{Generic mac80211 wireless config:}
46
47 \begin{Verbatim}
48 config wifi-device "wifi0"
49 option type "mac80211"
50 option channel "5"
51
52 config wifi-iface
53 option device "wlan0"
54 # option network lan
55 option mode "ap"
56 option ssid "OpenWrt"
57 option hidden "0"
58 option encryption "none"
59 \end{Verbatim}
60
61 \paragraph{Generic multi-radio Atheros wireless config:}
62
63 \begin{Verbatim}
64 config wifi-device wifi0
65 option type atheros
66 option channel 1
67
68 config wifi-iface
69 option device wifi0
70 # option network lan
71 option mode ap
72 option ssid OpenWrt_private
73 option hidden 0
74 option encryption none
75
76 config wifi-device wifi1
77 option type atheros
78 option channel 11
79
80 config wifi-iface
81 option device wifi1
82 # option network lan
83 option mode ap
84 option ssid OpenWrt_public
85 option hidden 1
86 option encryption none
87 \end{Verbatim}
88
89 There are two types of config sections in this file. The '\texttt{wifi-device}' refers to
90 the physical wifi interface and '\texttt{wifi-iface}' configures a virtual interface on top
91 of that (if supported by the driver).
92
93 A full outline of the wireless configuration file with description of each field:
94
95 \begin{Verbatim}
96 config wifi-device wifi device name
97 option type broadcom, atheros, mac80211
98 option country us, uk, fr, de, etc.
99 option channel 1-14
100 option maxassoc 1-128 (broadcom only)
101 option distance 1-n
102 option agmode 11b, 11g, 11a, 11bg (atheros only)
103
104 config wifi-iface
105 option network the interface you want wifi to bridge with
106 option device wifi0, wifi1, wifi2, wifiN
107 option mode ap, sta, adhoc, monitor, or wds
108 option ssid ssid name
109 option bssid bssid address
110 option encryption none, wep, psk, psk2, wpa, wpa2
111 option key encryption key
112 option key1 key 1
113 option key2 key 2
114 option key3 key 3
115 option key4 key 4
116 option server ip address
117 option port port
118 option hidden 0,1
119 option isolate 0,1
120 \end{Verbatim}
121
122 \paragraph{Options for the \texttt{wifi-device}:}
123
124 \begin{itemize}
125 \item \texttt{type} \\
126 The driver to use for this interface.
127
128 \item \texttt{country} \\
129 The country code used to determine the regulatory settings.
130
131 \item \texttt{channel} \\
132 The wifi channel (e.g. 1-14, depending on your country setting).
133
134 \item \texttt{maxassoc} \\
135 Optional: Maximum number of associated clients. This feature is supported only on the broadcom chipset.
136
137 \item \texttt{distance} \\
138 Optional: Distance between the ap and the furthest client in meters. This feature is supported only on the atheros chipset.
139
140 \item \texttt{mode} \\
141 The frequency band (\texttt{b}, \texttt{g}, \texttt{bg}, \texttt{a}). This feature is only supported on the atheros chipset.
142
143 \item \texttt{diversity} \\
144 Optional: Enable diversity for the Wi-Fi device. This feature is supported only on the atheros chipset.
145
146 \item \texttt{rxanteanna} \\
147 Optional: Antenna identifier (0, 1 or 2) for reception. This feature is supported only on the atheros chipset.
148
149 \item \texttt{txanteanna} \\
150 Optional: Antenna identifier (0, 1 or 2) for emission. This feature is supported only on the atheros chipset.
151
152 \end{itemize}
153
154 \paragraph{Options for the \texttt{wifi-iface}:}
155
156 \begin{itemize}
157 \item \texttt{network} \\
158 Selects the interface section from \texttt{/etc/config/network} to be
159 used with this interface
160
161 \item \texttt{device} \\
162 Set the wifi device name.
163
164 \item \texttt{mode} \\
165 Operating mode:
166
167 \begin{itemize}
168 \item \texttt{ap} \\
169 Access point mode
170
171 \item \texttt{sta} \\
172 Client mode
173
174 \item \texttt{adhoc} \\
175 Ad-Hoc mode
176
177 \item \texttt{monitor} \\
178 Monitor mode
179
180 \item \texttt{wds} \\
181 WDS point-to-point link
182
183 \end{itemize}
184
185 \item \texttt{ssid}
186 Set the SSID to be used on the wifi device.
187
188 \item \texttt{bssid}
189 Set the BSSID address to be used for wds to set the mac address of the other wds unit.
190
191 \item \texttt{encryption} \\
192 Encryption setting. Accepts the following values:
193
194 \begin{itemize}
195 \item \texttt{none}
196 \item \texttt{wep}
197 \item \texttt{psk}, \texttt{psk2} \\
198 WPA(2) Pre-shared Key
199
200 \item \texttt{wpa}, \texttt{wpa2} \\
201 WPA(2) RADIUS
202 \end{itemize}
203
204 \item \texttt{key, key1, key2, key3, key4} (wep, wpa and psk) \\
205 WEP key, WPA key (PSK mode) or the RADIUS shared secret (WPA RADIUS mode)
206
207 \item \texttt{server} (wpa) \\
208 The RADIUS server ip address
209
210 \item \texttt{port} (wpa) \\
211 The RADIUS server port (defaults to 1812)
212
213 \item \texttt{hidden} \\
214 0 broadcasts the ssid; 1 disables broadcasting of the ssid
215
216 \item \texttt{isolate} \\
217 Optional: Isolation is a mode usually set on hotspots that limits the clients to communicate only with the AP and not with other wireless clients.
218 0 disables ap isolation (default); 1 enables ap isolation.
219
220 \end{itemize}
221
222 \paragraph{Wireless Distribution System}
223
224 WDS is a non-standard mode which will be working between two Broadcom devices for instance
225 but not between a Broadcom and Atheros device.
226
227 \subparagraph{Unencrypted WDS connections}
228
229 This configuration example shows you how to setup unencrypted WDS connections.
230 We assume that the peer configured as below as the BSSID ca:fe:ba:be:00:01
231 and the remote WDS endpoint ca:fe:ba:be:00:02 (option bssid field).
232
233 \begin{Verbatim}
234 config wifi-device "wl0"
235 option type "broadcom"
236 option channel "5"
237
238 config wifi-iface
239 option device "wl0"
240 option network lan
241 option mode "ap"
242 option ssid "OpenWrt"
243 option hidden "0"
244 option encryption "none"
245
246 config wifi-iface
247 option device "wl0"
248 option network lan
249 option mode wds
250 option ssid "OpenWrt WDS"
251 option bssid "ca:fe:ba:be:00:02"
252 \end{Verbatim}
253
254 \subparagraph{Encrypted WDS connections}
255
256 It is also possible to encrypt WDS connections. \texttt{psk}, \texttt{psk2} and
257 \texttt{psk+psk2} modes are supported. Configuration below is an example
258 configuration using Pre-Shared-Keys with AES algorithm.
259
260 \begin{Verbatim}
261 config wifi-device wl0
262 option type broadcom
263 option channel 5
264
265 config wifi-iface
266 option device "wl0"
267 option network lan
268 option mode ap
269 option ssid "OpenWrt"
270 option encryption psk2
271 option key "<key for clients>"
272
273 config wifi-iface
274 option device "wl0"
275 option network lan
276 option mode wds
277 option bssid ca:fe:ba:be:00:02
278 option ssid "OpenWrt WDS"
279 option encryption psk2
280 option key "<psk for WDS>"
281 \end{Verbatim}
282
283 \paragraph{802.1x configurations}
284
285 OpenWrt supports both 802.1x client and Access Point
286 configurations. 802.1x client is only working with
287 Atheros or mac80211 drivers. Configuration only
288 supports EAP types TLS, TTLS or PEAP.
289
290 \subparagraph{EAP-TLS}
291
292 \begin{Verbatim}
293 config wifi-iface
294 option device "ath0"
295 option network lan
296 option ssid OpenWrt
297 option eap_type tls
298 option ca_cert "/etc/config/certs/ca.crt"
299 option priv_key "/etc/config/certs/priv.crt"
300 option priv_key_pwd "PKCS#12 passphrase"
301 \end{Verbatim}
302
303 \subparagraph{EAP-PEAP}
304
305 \begin{Verbatim}
306 config wifi-iface
307 option device "ath0"
308 option network lan
309 option ssid OpenWrt
310 option eap_type peap
311 option ca_cert "/etc/config/certs/ca.crt"
312 option auth MSCHAPV2
313 option identity username
314 option password password
315 \end{Verbatim}
316
317 \paragraph{Limitations:}
318
319 There are certain limitations when combining modes.
320 Only the following mode combinations are supported:
321
322 \begin{itemize}
323 \item \textbf{Broadcom}: \\
324 \begin{itemize}
325 \item 1x \texttt{sta}, 0-3x \texttt{ap}
326 \item 1-4x \texttt{ap}
327 \item 1x \texttt{adhoc}
328 \item 1x \texttt{monitor}
329 \end{itemize}
330
331 WDS links can only be used in pure AP mode and cannot use WEP (except when sharing the
332 settings with the master interface, which is done automatically).
333
334 \item \textbf{Atheros}: \\
335 \begin{itemize}
336 \item 1x \texttt{sta}, 0-Nx \texttt{ap}
337 \item 1-Nx \texttt{ap}
338 \item 1x \texttt{adhoc}
339 \end{itemize}
340
341 N is the maximum number of VAPs that the module allows, it defaults to 4, but can be
342 changed by loading the module with the maxvaps=N parameter.
343 \end{itemize}
344
345 \paragraph{Adding a new driver configuration}
346
347 Since we currently only support thread different wireless drivers : Broadcom, Atheros and mac80211,
348 you might be interested in adding support for another driver like Ralink RT2x00,
349 Texas Instruments ACX100/111.
350
351 The driver specific script should be placed in \texttt{/lib/wifi/<driver>.sh} and has to
352 include several functions providing :
353
354 \begin{itemize}
355 \item detection of the driver presence
356 \item enabling/disabling the wifi interface(s)
357 \item configuration reading and setting
358 \item third-party programs calling (nas, supplicant)
359 \end{itemize}
360
361 Each driver script should append the driver to a global DRIVERS variable :
362
363 \begin{Verbatim}
364 append DRIVERS "driver name"
365 \end{Verbatim}
366
367 \subparagraph{\texttt{scan\_<driver>}}
368
369 This function will parse the \texttt{/etc/config/wireless} and make sure there
370 are no configuration incompatibilities, like enabling hidden SSIDS with ad-hoc mode
371 for instance. This can be more complex if your driver supports a lof of configuration
372 options. It does not change the state of the interface.
373
374 Example:
375 \begin{Verbatim}
376 scan_dummy() {
377 local device="$1"
378
379 config_get vifs "$device" vifs
380 for vif in $vifs; do
381 # check config consistency for wifi-iface sections
382 done
383 # check mode combination
384 }
385 \end{Verbatim}
386
387 \subparagraph{\texttt{enable\_<driver>}}
388
389 This function will bring up the wifi device and optionally create application specific
390 configuration files, e.g. for the WPA authenticator or supplicant.
391
392 Example:
393 \begin{Verbatim}
394 enable_dummy() {
395 local device="$1"
396
397 config_get vifs "$device" vifs
398 for vif in $vifs; do
399 # bring up virtual interface belonging to
400 # the wifi-device "$device"
401 done
402 }
403 \end{Verbatim}
404
405 \subparagraph{\texttt{disable\_<driver>}}
406
407 This function will bring down the wifi device and all its virtual interfaces (if supported).
408
409 Example:
410 \begin{Verbatim}
411 disable_dummy() {
412 local device="$1"
413
414 # bring down virtual interfaces belonging to
415 # "$device" regardless of whether they are
416 # configured or not. Don't rely on the vifs
417 # variable at this point
418 }
419 \end{Verbatim}
420
421 \subparagraph{\texttt{detect\_<driver>}}
422
423 This function looks for interfaces that are usable with the driver. Template config sections
424 for new devices should be written to stdout. Must check for already existing config sections
425 belonging to the interfaces before creating new templates.
426
427 Example:
428 \begin{Verbatim}
429 detect_dummy() {
430 [ wifi-device = "$(config_get dummydev type)" ] && return 0
431 cat <<EOF
432 config wifi-device dummydev
433 option type dummy
434 # REMOVE THIS LINE TO ENABLE WIFI:
435 option disabled 1
436
437 config wifi-iface
438 option device dummydev
439 option mode ap
440 option ssid OpenWrt
441 EOF
442 }
443 \end{Verbatim}