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