docs/wireless.tex

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