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