add a default template for Host/Install
[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.
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 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
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 chipset.
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 chipset.
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 chipset.
146
147 \item \texttt{diversity} \\
148 Optional: Enable diversity for the Wi-Fi device. This feature is supported only on the atheros chipset.
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.
239
240 \paragraph{Wireless Distribution System}
241
242 WDS is a non-standard mode which will be working between two Broadcom devices for instance
243 but not between a Broadcom and Atheros device.
244
245 \subparagraph{Unencrypted WDS connections}
246
247 This configuration example shows you how to setup unencrypted WDS connections.
248 We assume that the peer configured as below as the BSSID ca:fe:ba:be:00:01
249 and the remote WDS endpoint ca:fe:ba:be:00:02 (option bssid field).
250
251 \begin{Verbatim}
252 config wifi-device "wl0"
253 option type "broadcom"
254 option channel "5"
255
256 config wifi-iface
257 option device "wl0"
258 option network lan
259 option mode "ap"
260 option ssid "OpenWrt"
261 option hidden "0"
262 option encryption "none"
263
264 config wifi-iface
265 option device "wl0"
266 option network lan
267 option mode wds
268 option ssid "OpenWrt WDS"
269 option bssid "ca:fe:ba:be:00:02"
270 \end{Verbatim}
271
272 \subparagraph{Encrypted WDS connections}
273
274 It is also possible to encrypt WDS connections. \texttt{psk}, \texttt{psk2} and
275 \texttt{psk+psk2} modes are supported. Configuration below is an example
276 configuration using Pre-Shared-Keys with AES algorithm.
277
278 \begin{Verbatim}
279 config wifi-device wl0
280 option type broadcom
281 option channel 5
282
283 config wifi-iface
284 option device "wl0"
285 option network lan
286 option mode ap
287 option ssid "OpenWrt"
288 option encryption psk2
289 option key "<key for clients>"
290
291 config wifi-iface
292 option device "wl0"
293 option network lan
294 option mode wds
295 option bssid ca:fe:ba:be:00:02
296 option ssid "OpenWrt WDS"
297 option encryption psk2
298 option key "<psk for WDS>"
299 \end{Verbatim}
300
301 \paragraph{802.1x configurations}
302
303 OpenWrt supports both 802.1x client and Access Point
304 configurations. 802.1x client is only working with
305 Atheros or mac80211 drivers. Configuration only
306 supports EAP types TLS, TTLS or PEAP.
307
308 \subparagraph{EAP-TLS}
309
310 \begin{Verbatim}
311 config wifi-iface
312 option device "ath0"
313 option network lan
314 option ssid OpenWrt
315 option eap_type tls
316 option ca_cert "/etc/config/certs/ca.crt"
317 option priv_key "/etc/config/certs/priv.crt"
318 option priv_key_pwd "PKCS#12 passphrase"
319 \end{Verbatim}
320
321 \subparagraph{EAP-PEAP}
322
323 \begin{Verbatim}
324 config wifi-iface
325 option device "ath0"
326 option network lan
327 option ssid OpenWrt
328 option eap_type peap
329 option ca_cert "/etc/config/certs/ca.crt"
330 option auth MSCHAPV2
331 option identity username
332 option password password
333 \end{Verbatim}
334
335 \paragraph{Limitations:}
336
337 There are certain limitations when combining modes.
338 Only the following mode combinations are supported:
339
340 \begin{itemize}
341 \item \textbf{Broadcom}: \\
342 \begin{itemize}
343 \item 1x \texttt{sta}, 0-3x \texttt{ap}
344 \item 1-4x \texttt{ap}
345 \item 1x \texttt{adhoc}
346 \item 1x \texttt{monitor}
347 \end{itemize}
348
349 WDS links can only be used in pure AP mode and cannot use WEP (except when sharing the
350 settings with the master interface, which is done automatically).
351
352 \item \textbf{Atheros}: \\
353 \begin{itemize}
354 \item 1x \texttt{sta}, 0-Nx \texttt{ap}
355 \item 1-Nx \texttt{ap}
356 \item 1x \texttt{adhoc}
357 \end{itemize}
358
359 N is the maximum number of VAPs that the module allows, it defaults to 4, but can be
360 changed by loading the module with the maxvaps=N parameter.
361 \end{itemize}
362
363 \paragraph{Adding a new driver configuration}
364
365 Since we currently only support thread different wireless drivers : Broadcom, Atheros and mac80211,
366 you might be interested in adding support for another driver like Ralink RT2x00,
367 Texas Instruments ACX100/111.
368
369 The driver specific script should be placed in \texttt{/lib/wifi/<driver>.sh} and has to
370 include several functions providing :
371
372 \begin{itemize}
373 \item detection of the driver presence
374 \item enabling/disabling the wifi interface(s)
375 \item configuration reading and setting
376 \item third-party programs calling (nas, supplicant)
377 \end{itemize}
378
379 Each driver script should append the driver to a global DRIVERS variable :
380
381 \begin{Verbatim}
382 append DRIVERS "driver name"
383 \end{Verbatim}
384
385 \subparagraph{\texttt{scan\_<driver>}}
386
387 This function will parse the \texttt{/etc/config/wireless} and make sure there
388 are no configuration incompatibilities, like enabling hidden SSIDS with ad-hoc mode
389 for instance. This can be more complex if your driver supports a lof of configuration
390 options. It does not change the state of the interface.
391
392 Example:
393 \begin{Verbatim}
394 scan_dummy() {
395 local device="$1"
396
397 config_get vifs "$device" vifs
398 for vif in $vifs; do
399 # check config consistency for wifi-iface sections
400 done
401 # check mode combination
402 }
403 \end{Verbatim}
404
405 \subparagraph{\texttt{enable\_<driver>}}
406
407 This function will bring up the wifi device and optionally create application specific
408 configuration files, e.g. for the WPA authenticator or supplicant.
409
410 Example:
411 \begin{Verbatim}
412 enable_dummy() {
413 local device="$1"
414
415 config_get vifs "$device" vifs
416 for vif in $vifs; do
417 # bring up virtual interface belonging to
418 # the wifi-device "$device"
419 done
420 }
421 \end{Verbatim}
422
423 \subparagraph{\texttt{disable\_<driver>}}
424
425 This function will bring down the wifi device and all its virtual interfaces (if supported).
426
427 Example:
428 \begin{Verbatim}
429 disable_dummy() {
430 local device="$1"
431
432 # bring down virtual interfaces belonging to
433 # "$device" regardless of whether they are
434 # configured or not. Don't rely on the vifs
435 # variable at this point
436 }
437 \end{Verbatim}
438
439 \subparagraph{\texttt{detect\_<driver>}}
440
441 This function looks for interfaces that are usable with the driver. Template config sections
442 for new devices should be written to stdout. Must check for already existing config sections
443 belonging to the interfaces before creating new templates.
444
445 Example:
446 \begin{Verbatim}
447 detect_dummy() {
448 [ wifi-device = "$(config_get dummydev type)" ] && return 0
449 cat <<EOF
450 config wifi-device dummydev
451 option type dummy
452 # REMOVE THIS LINE TO ENABLE WIFI:
453 option disabled 1
454
455 config wifi-iface
456 option device dummydev
457 option mode ap
458 option ssid OpenWrt
459 EOF
460 }
461 \end{Verbatim}