[brcm-2.4] Update kernel to 2.4.37.2
[openwrt/svn-archive/archive.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 and mac80211.
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 hwmode "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 (meters)
102 option hwmode 11b, 11g, 11a, 11bg (atheros, mac80211)
103 option rxantenna 0,1,2 (atheros, broadcom)
104 option txantenna 0,1,2 (atheros, broadcom)
105 option txpower transmission power in dBm
106
107 config wifi-iface
108 option network the interface you want wifi to bridge with
109 option device wifi0, wifi1, wifi2, wifiN
110 option mode ap, sta, adhoc, monitor, mesh, or wds
111 option txpower (deprecated) transmission power in dBm
112 option ssid ssid name
113 option bssid bssid address
114 option encryption none, wep, psk, psk2, wpa, wpa2
115 option key encryption key
116 option key1 key 1
117 option key2 key 2
118 option key3 key 3
119 option key4 key 4
120 option server ip address
121 option port port
122 option hidden 0,1
123 option isolate 0,1 (broadcom)
124 \end{Verbatim}
125
126 \paragraph{Options for the \texttt{wifi-device}:}
127
128 \begin{itemize}
129 \item \texttt{type} \\
130 The driver to use for this interface.
131
132 \item \texttt{country} \\
133 The country code used to determine the regulatory settings.
134
135 \item \texttt{channel} \\
136 The wifi channel (e.g. 1-14, depending on your country setting).
137
138 \item \texttt{maxassoc} \\
139 Optional: Maximum number of associated clients. This feature is supported only on the Broadcom chipsets.
140
141 \item \texttt{distance} \\
142 Optional: Distance between the ap and the furthest client in meters. This feature is supported only on the Atheros chipsets.
143
144 \item \texttt{mode} \\
145 The frequency band (\texttt{b}, \texttt{g}, \texttt{bg}, \texttt{a}). This feature is only supported on the Atheros chipsets.
146
147 \item \texttt{diversity} \\
148 Optional: Enable diversity for the Wi-Fi device. This feature is supported only on the Atheros chipsets.
149
150 \item \texttt{rxantenna} \\
151 Optional: Antenna identifier (0, 1 or 2) for reception. This feature is supported by Atheros and some Broadcom chipsets.
152
153 \item \texttt{txantenna} \\
154 Optional: Antenna identifier (0, 1 or 2) for emission. This feature is supported by Atheros and some Broadcom chipsets.
155
156 \item \texttt{txpower}
157 Set the transmission power to be used. The amount is specified in dBm.
158
159 \end{itemize}
160
161 \paragraph{Options for the \texttt{wifi-iface}:}
162
163 \begin{itemize}
164 \item \texttt{network} \\
165 Selects the interface section from \texttt{/etc/config/network} to be
166 used with this interface
167
168 \item \texttt{device} \\
169 Set the wifi device name.
170
171 \item \texttt{mode} \\
172 Operating mode:
173
174 \begin{itemize}
175 \item \texttt{ap} \\
176 Access point mode
177
178 \item \texttt{sta} \\
179 Client mode
180
181 \item \texttt{adhoc} \\
182 Ad-Hoc mode
183
184 \item \texttt{monitor} \\
185 Monitor mode
186
187 \item \texttt{mesh} \\
188 Mesh Point mode (802.11s)
189
190 \item \texttt{wds} \\
191 WDS point-to-point link
192
193 \end{itemize}
194
195 \item \texttt{ssid}
196 Set the SSID to be used on the wifi device.
197
198 \item \texttt{bssid}
199 Set the BSSID address to be used for wds to set the mac address of the other wds unit.
200
201 \item \texttt{txpower}
202 (Deprecated, set in wifi-device) Set the transmission power to be used. The amount is specified in dBm.
203
204 \item \texttt{encryption} \\
205 Encryption setting. Accepts the following values:
206
207 \begin{itemize}
208 \item \texttt{none}
209 \item \texttt{wep}
210 \item \texttt{psk}, \texttt{psk2} \\
211 WPA(2) Pre-shared Key
212
213 \item \texttt{wpa}, \texttt{wpa2} \\
214 WPA(2) RADIUS
215 \end{itemize}
216
217 \item \texttt{key, key1, key2, key3, key4} (wep, wpa and psk) \\
218 WEP key, WPA key (PSK mode) or the RADIUS shared secret (WPA RADIUS mode)
219
220 \item \texttt{server} (wpa) \\
221 The RADIUS server ip address
222
223 \item \texttt{port} (wpa) \\
224 The RADIUS server port (defaults to 1812)
225
226 \item \texttt{hidden} \\
227 0 broadcasts the ssid; 1 disables broadcasting of the ssid
228
229 \item \texttt{isolate} \\
230 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.
231 0 disables ap isolation (default); 1 enables ap isolation.
232
233 \end{itemize}
234
235 \paragraph{Mesh Point}
236
237 Mesh Point (802.11s) is only supported by some mac80211 drivers. It requires the iw package
238 to be installed to setup mesh links. OpenWrt creates mshN mesh point interfaces. A sample
239 configuration looks like this:
240
241 \begin{Verbatim}
242 config wifi-device "wlan0"
243 option type "mac80211"
244 option channel "5"
245
246 config wifi-iface
247 option device "wlan0"
248 option network lan
249 option mode "mesh"
250 option mesh_id "OpenWrt"
251 \end{Verbatim}
252
253 \paragraph{Wireless Distribution System}
254
255 WDS is a non-standard mode which will be working between two Broadcom devices for instance
256 but not between a Broadcom and Atheros device.
257
258 \subparagraph{Unencrypted WDS connections}
259
260 This configuration example shows you how to setup unencrypted WDS connections.
261 We assume that the peer configured as below as the BSSID ca:fe:ba:be:00:01
262 and the remote WDS endpoint ca:fe:ba:be:00:02 (option bssid field).
263
264 \begin{Verbatim}
265 config wifi-device "wl0"
266 option type "broadcom"
267 option channel "5"
268
269 config wifi-iface
270 option device "wl0"
271 option network lan
272 option mode "ap"
273 option ssid "OpenWrt"
274 option hidden "0"
275 option encryption "none"
276
277 config wifi-iface
278 option device "wl0"
279 option network lan
280 option mode wds
281 option ssid "OpenWrt WDS"
282 option bssid "ca:fe:ba:be:00:02"
283 \end{Verbatim}
284
285 \subparagraph{Encrypted WDS connections}
286
287 It is also possible to encrypt WDS connections. \texttt{psk}, \texttt{psk2} and
288 \texttt{psk+psk2} modes are supported. Configuration below is an example
289 configuration using Pre-Shared-Keys with AES algorithm.
290
291 \begin{Verbatim}
292 config wifi-device wl0
293 option type broadcom
294 option channel 5
295
296 config wifi-iface
297 option device "wl0"
298 option network lan
299 option mode ap
300 option ssid "OpenWrt"
301 option encryption psk2
302 option key "<key for clients>"
303
304 config wifi-iface
305 option device "wl0"
306 option network lan
307 option mode wds
308 option bssid ca:fe:ba:be:00:02
309 option ssid "OpenWrt WDS"
310 option encryption psk2
311 option key "<psk for WDS>"
312 \end{Verbatim}
313
314 \paragraph{802.1x configurations}
315
316 OpenWrt supports both 802.1x client and Access Point
317 configurations. 802.1x client is only working with
318 drivers supported by wpa-supplicant. Configuration
319 only supports EAP types TLS, TTLS or PEAP.
320
321 \subparagraph{EAP-TLS}
322
323 \begin{Verbatim}
324 config wifi-iface
325 option device "ath0"
326 option network lan
327 option ssid OpenWrt
328 option eap_type tls
329 option ca_cert "/etc/config/certs/ca.crt"
330 option priv_key "/etc/config/certs/priv.crt"
331 option priv_key_pwd "PKCS#12 passphrase"
332 \end{Verbatim}
333
334 \subparagraph{EAP-PEAP}
335
336 \begin{Verbatim}
337 config wifi-iface
338 option device "ath0"
339 option network lan
340 option ssid OpenWrt
341 option eap_type peap
342 option ca_cert "/etc/config/certs/ca.crt"
343 option auth MSCHAPV2
344 option identity username
345 option password password
346 \end{Verbatim}
347
348 \paragraph{Limitations:}
349
350 There are certain limitations when combining modes.
351 Only the following mode combinations are supported:
352
353 \begin{itemize}
354 \item \textbf{Broadcom}: \\
355 \begin{itemize}
356 \item 1x \texttt{sta}, 0-3x \texttt{ap}
357 \item 1-4x \texttt{ap}
358 \item 1x \texttt{adhoc}
359 \item 1x \texttt{monitor}
360 \end{itemize}
361
362 WDS links can only be used in pure AP mode and cannot use WEP (except when sharing the
363 settings with the master interface, which is done automatically).
364
365 \item \textbf{Atheros}: \\
366 \begin{itemize}
367 \item 1x \texttt{sta}, 0-Nx \texttt{ap}
368 \item 1-Nx \texttt{ap}
369 \item 1x \texttt{adhoc}
370 \end{itemize}
371
372 N is the maximum number of VAPs that the module allows, it defaults to 4, but can be
373 changed by loading the module with the maxvaps=N parameter.
374 \end{itemize}
375
376 \paragraph{Adding a new driver configuration}
377
378 Since we currently only support thread different wireless drivers : Broadcom, Atheros and mac80211,
379 you might be interested in adding support for another driver like Ralink RT2x00,
380 Texas Instruments ACX100/111.
381
382 The driver specific script should be placed in \texttt{/lib/wifi/<driver>.sh} and has to
383 include several functions providing :
384
385 \begin{itemize}
386 \item detection of the driver presence
387 \item enabling/disabling the wifi interface(s)
388 \item configuration reading and setting
389 \item third-party programs calling (nas, supplicant)
390 \end{itemize}
391
392 Each driver script should append the driver to a global DRIVERS variable :
393
394 \begin{Verbatim}
395 append DRIVERS "driver name"
396 \end{Verbatim}
397
398 \subparagraph{\texttt{scan\_<driver>}}
399
400 This function will parse the \texttt{/etc/config/wireless} and make sure there
401 are no configuration incompatibilities, like enabling hidden SSIDS with ad-hoc mode
402 for instance. This can be more complex if your driver supports a lof of configuration
403 options. It does not change the state of the interface.
404
405 Example:
406 \begin{Verbatim}
407 scan_dummy() {
408 local device="$1"
409
410 config_get vifs "$device" vifs
411 for vif in $vifs; do
412 # check config consistency for wifi-iface sections
413 done
414 # check mode combination
415 }
416 \end{Verbatim}
417
418 \subparagraph{\texttt{enable\_<driver>}}
419
420 This function will bring up the wifi device and optionally create application specific
421 configuration files, e.g. for the WPA authenticator or supplicant.
422
423 Example:
424 \begin{Verbatim}
425 enable_dummy() {
426 local device="$1"
427
428 config_get vifs "$device" vifs
429 for vif in $vifs; do
430 # bring up virtual interface belonging to
431 # the wifi-device "$device"
432 done
433 }
434 \end{Verbatim}
435
436 \subparagraph{\texttt{disable\_<driver>}}
437
438 This function will bring down the wifi device and all its virtual interfaces (if supported).
439
440 Example:
441 \begin{Verbatim}
442 disable_dummy() {
443 local device="$1"
444
445 # bring down virtual interfaces belonging to
446 # "$device" regardless of whether they are
447 # configured or not. Don't rely on the vifs
448 # variable at this point
449 }
450 \end{Verbatim}
451
452 \subparagraph{\texttt{detect\_<driver>}}
453
454 This function looks for interfaces that are usable with the driver. Template config sections
455 for new devices should be written to stdout. Must check for already existing config sections
456 belonging to the interfaces before creating new templates.
457
458 Example:
459 \begin{Verbatim}
460 detect_dummy() {
461 [ wifi-device = "$(config_get dummydev type)" ] && return 0
462 cat <<EOF
463 config wifi-device dummydev
464 option type dummy
465 # REMOVE THIS LINE TO ENABLE WIFI:
466 option disabled 1
467
468 config wifi-iface
469 option device dummydev
470 option mode ap
471 option ssid OpenWrt
472 EOF
473 }
474 \end{Verbatim}