Add some more documentation
[openwrt/openwrt.git] / docs / wireless.tex
1 The WiFi settings are configured in the file \texttt{/etc/config/wireless}
2 (currently supported on Broadcom and Atheros). 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 multi-radio Atheros wireless config:}
46
47 \begin{Verbatim}
48 config wifi-device wifi0
49 option type atheros
50 option channel 1
51
52 config wifi-iface
53 option device wifi0
54 # option network lan
55 option mode ap
56 option ssid OpenWrt_private
57 option hidden 0
58 option encryption none
59
60 config wifi-device wifi1
61 option type atheros
62 option channel 11
63
64 config wifi-iface
65 option device wifi1
66 # option network lan
67 option mode ap
68 option ssid OpenWrt_public
69 option hidden 1
70 option encryption none
71 \end{Verbatim}
72
73 There are two types of config sections in this file. The '\texttt{wifi-device}' refers to
74 the physical wifi interface and '\texttt{wifi-iface}' configures a virtual interface on top
75 of that (if supported by the driver).
76
77 A full outline of the wireless configuration file with description of each field:
78
79 \begin{Verbatim}
80 config wifi-device wifi device name
81 option type broadcom, atheros
82 option country us, uk, fr, de, etc.
83 option channel 1-14
84 option maxassoc 1-128 (broadcom only)
85 option distance 1-n
86 option agmode 11b, 11g, 11a, 11bg (atheros only)
87
88 config wifi-iface
89 option network the interface you want wifi to bridge with
90 option device wifi0, wifi1, wifi2, wifiN
91 option mode ap, sta, adhoc, or wds
92 option ssid ssid name
93 option bssid bssid address
94 option encryption none, wep, psk, psk2, wpa, wpa2
95 option key encryption key
96 option key1 key 1
97 option key2 key 2
98 option key3 key 3
99 option key4 key 4
100 option server ip address
101 option port port
102 option hidden 0,1
103 option isolate 0,1
104 \end{Verbatim}
105
106 \paragraph{Options for the \texttt{wifi-device}:}
107
108 \begin{itemize}
109 \item \texttt{type} \\
110 The driver to use for this interface.
111
112 \item \texttt{country} \\
113 The country code used to determine the regulatory settings.
114
115 \item \texttt{channel} \\
116 The wifi channel (e.g. 1-14, depending on your country setting).
117
118 \item \texttt{maxassoc} \\
119 Optional: Maximum number of associated clients. This feature is supported only on the broadcom chipset.
120
121 \item \texttt{distance} \\
122 Optional: Distance between the ap and the furthest client in meters. This feature is supported only on the atheros chipset.
123
124 \item \texttt{mode} \\
125 The frequency band (\texttt{b}, \texttt{g}, \texttt{bg}, \texttt{a}). This feature is only supported on the atheros chipset.
126
127
128 \end{itemize}
129
130 \paragraph{Options for the \texttt{wifi-iface}:}
131
132 \begin{itemize}
133 \item \texttt{network} \\
134 Selects the interface section from \texttt{/etc/config/network} to be
135 used with this interface
136
137 \item \texttt{device} \\
138 Set the wifi device name.
139
140 \item \texttt{mode} \\
141 Operating mode:
142
143 \begin{itemize}
144 \item \texttt{ap} \\
145 Access point mode
146
147 \item \texttt{sta} \\
148 Client mode
149
150 \item \texttt{adhoc} \\
151 Ad-Hoc mode
152
153 \item \texttt{wds} \\
154 WDS point-to-point link
155
156 \end{itemize}
157
158 \item \texttt{ssid}
159 Set the SSID to be used on the wifi device.
160
161 \item \texttt{bssid}
162 Set the BSSID address to be used for wds to set the mac address of the other wds unit.
163
164 \item \texttt{encryption} \\
165 Encryption setting. Accepts the following values:
166
167 \begin{itemize}
168 \item \texttt{none}
169 \item \texttt{wep}
170 \item \texttt{psk}, \texttt{psk2} \\
171 WPA(2) Pre-shared Key
172
173 \item \texttt{wpa}, \texttt{wpa2} \\
174 WPA(2) RADIUS
175 \end{itemize}
176
177 \item \texttt{key, key1, key2, key3, key4} (wep, wpa and psk) \\
178 WEP key, WPA key (PSK mode) or the RADIUS shared secret (WPA RADIUS mode)
179
180 \item \texttt{server} (wpa) \\
181 The RADIUS server ip address
182
183 \item \texttt{port} (wpa) \\
184 The RADIUS server port
185
186 \item \texttt{hidden} \\
187 0 broadcasts the ssid; 1 disables broadcasting of the ssid
188
189 \item \texttt{isolate} \\
190 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.
191 0 disables ap isolation (default); 1 enables ap isolation.
192
193 \end{itemize}
194
195
196 \paragraph{Limitations:}
197
198 There are certain limitations when combining modes.
199 Only the following mode combinations are supported:
200
201 \begin{itemize}
202 \item \textbf{Broadcom}: \\
203 \begin{itemize}
204 \item 1x \texttt{sta}, 0-3x \texttt{ap}
205 \item 1-4x \texttt{ap}
206 \item 1x \texttt{adhoc}
207 \end{itemize}
208
209 WDS links can only be used in pure AP mode and cannot use WEP (except when sharing the
210 settings with the master interface, which is done automatically).
211
212 \item \textbf{Atheros}: \\
213 \begin{itemize}
214 \item 1x \texttt{sta}, 0-4x \texttt{ap}
215 \item 1-4x \texttt{ap}
216 \item 1x \texttt{adhoc}
217 \end{itemize}
218 \end{itemize}
219
220 \paragraph{Adding a new driver configuration}
221
222 Since we currently only support two different wireless drivers : Broadcom and Atheros,
223 you might be interested in adding support for another driver like Ralink RT2x00,
224 Texas Instruments ACX100/111.
225
226 The driver specific script should be placed in \texttt{/lib/wifi/<driver>.sh} and has to
227 include several functions providing :
228
229 \begin{itemize}
230 \item detection of the driver presence
231 \item enabling/disabling the wifi interface(s)
232 \item configuration reading and setting
233 \item third-party programs calling (nas, supplicant)
234 \end{itemize}
235
236 Each driver script should append the driver to a global DRIVERS variable :
237
238 \begin{verbatim}
239 append DRIVERS "driver name"
240 \end{verbatim}
241
242 \subparagraph{scan\_driver}
243
244 This function will parse the \texttt{/etc/config/wireless} and make sure there
245 are no configuration incompatibilities, like enabling hidden SSIDS with ad-hoc mode
246 for instance. This can be more complex if your driver supports a lof of configuration
247 options. It does not enable your wireless driver to work.
248
249 \subparagraph{enable\_driver}
250
251 This function will enable the driver and read the configuration file to create application
252 specific configuration files for the NAS or supplicant program. It will not check the
253 configuration consistency.
254
255 \subparagraph{disable\_driver}
256
257 This function should properly shutdown the wireless interfaces and kill associated programs
258 running on top of it.
259
260 \subparagraph{detec\_driver}
261
262 This function should reliably report the existence of the driver and of one or more of its
263 wireless interfaces. A basic configuration file has to be generated in the meantime.
264