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