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