Root/docs/wireless.tex

1The 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
3it should detect your card and create a sample configuration file. By default '\texttt{option network lan}' is
4commented. This prevents unsecured sharing of the network over the wireless interface.
5
6Each wireless driver has its own configuration script in \texttt{/lib/wifi/driver\_name.sh} which handles
7driver specific options and configurations. This script is also calling driver specific binaries like wlc for
8Broadcom, or hostapd and wpa\_supplicant for atheros and mac80211.
9
10The reason for using such architecture, is that it abstracts the driver configuration.
11
12\paragraph{Generic Broadcom wireless config:}
13
14\begin{Verbatim}
15config wifi-device "wl0"
16    option type "broadcom"
17    option channel "5"
18
19config 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}
31config wifi-device "wifi0"
32    option type "atheros"
33    option channel "5"
34    option hwmode "11g"
35
36config 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}
48config wifi-device "wifi0"
49    option type "mac80211"
50    option channel "5"
51
52config 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}
64config wifi-device wifi0
65    option type atheros
66    option channel 1
67
68config 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
76config wifi-device wifi1
77    option type atheros
78    option channel 11
79
80config 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
89There are two types of config sections in this file. The '\texttt{wifi-device}' refers to
90the physical wifi interface and '\texttt{wifi-iface}' configures a virtual interface on top
91of that (if supported by the driver).
92
93A full outline of the wireless configuration file with description of each field:
94
95\begin{Verbatim}
96config 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
107config 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
255Mesh Point (802.11s) is only supported by some mac80211 drivers. It requires the iw package
256to be installed to setup mesh links. OpenWrt creates mshN mesh point interfaces. A sample
257configuration looks like this:
258
259\begin{Verbatim}
260config wifi-device "wlan0"
261    option type "mac80211"
262    option channel "5"
263
264config 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
273WDS is a non-standard mode which will be working between two Broadcom devices for instance
274but not between a Broadcom and Atheros device.
275
276\subparagraph{Unencrypted WDS connections}
277
278This configuration example shows you how to setup unencrypted WDS connections.
279We assume that the peer configured as below as the BSSID ca:fe:ba:be:00:01
280and the remote WDS endpoint ca:fe:ba:be:00:02 (option bssid field).
281
282\begin{Verbatim}
283config wifi-device "wl0"
284    option type "broadcom"
285    option channel "5"
286
287config 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
295config 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
305It is also possible to encrypt WDS connections. \texttt{psk}, \texttt{psk2} and
306\texttt{psk+psk2} modes are supported. Configuration below is an example
307configuration using Pre-Shared-Keys with AES algorithm.
308
309\begin{Verbatim}
310config wifi-device wl0
311    option type broadcom
312    option channel 5
313
314config 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
322config 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
334OpenWrt supports both 802.1x client and Access Point
335configurations. 802.1x client is only working with
336drivers supported by wpa-supplicant. Configuration
337only supports EAP types TLS, TTLS or PEAP.
338
339\subparagraph{EAP-TLS}
340
341\begin{Verbatim}
342config 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}
355config 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
368There are certain limitations when combining modes.
369Only 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
396Since we currently only support thread different wireless drivers : Broadcom, Atheros and mac80211,
397you might be interested in adding support for another driver like Ralink RT2x00,
398Texas Instruments ACX100/111.
399
400The driver specific script should be placed in \texttt{/lib/wifi/<driver>.sh} and has to
401include 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
410Each driver script should append the driver to a global DRIVERS variable :
411
412\begin{Verbatim}
413append DRIVERS "driver name"
414\end{Verbatim}
415
416\subparagraph{\texttt{scan\_<driver>}}
417
418This function will parse the \texttt{/etc/config/wireless} and make sure there
419are no configuration incompatibilities, like enabling hidden SSIDS with ad-hoc mode
420for instance. This can be more complex if your driver supports a lof of configuration
421options. It does not change the state of the interface.
422
423Example:
424\begin{Verbatim}
425scan_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
438This function will bring up the wifi device and optionally create application specific
439configuration files, e.g. for the WPA authenticator or supplicant.
440
441Example:
442\begin{Verbatim}
443enable_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
456This function will bring down the wifi device and all its virtual interfaces (if supported).
457
458Example:
459\begin{Verbatim}
460disable_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
472This function looks for interfaces that are usable with the driver. Template config sections
473for new devices should be written to stdout. Must check for already existing config sections
474belonging to the interfaces before creating new templates.
475
476Example:
477\begin{Verbatim}
478detect_dummy() {
479    [ wifi-device = "$(config_get dummydev type)" ] && return 0
480    cat <<EOF
481config wifi-device dummydev
482    option type dummy
483    # REMOVE THIS LINE TO ENABLE WIFI:
484    option disabled 1
485
486config wifi-iface
487    option device dummydev
488    option mode ap
489    option ssid OpenWrt
490EOF
491}
492\end{Verbatim}
493

Archive Download this file



interactive