source: branches/8.09/docs/wireless.tex @ 14312

Last change on this file since 14312 was 14312, checked in by agb, 8 years ago

merge r14306, r14307, r14309, and r14311 to 8.09:
[package] broadcom,madwifi,mac80211: move txpower from wifi-iface to wifi-device but retain backward compatiblity

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