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