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