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 and mac80211.
   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 (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
 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, 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
 255 Mesh Point (802.11s) is only supported by some mac80211 drivers. It requires the iw package
 256 to be installed to setup mesh links. OpenWrt creates mshN mesh point interfaces. A sample
 257 configuration looks like this:
 258
 259 \begin{Verbatim}
 260 config wifi-device      "wlan0"
 261     option type         "mac80211"
 262     option channel      "5"
 263
 264 config 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
 273 WDS is a non-standard mode which will be working between two Broadcom devices for instance
 274 but not between a Broadcom and Atheros device.
 275
 276 \subparagraph{Unencrypted WDS connections}
 277
 278 This configuration example shows you how to setup unencrypted WDS connections.
 279 We assume that the peer configured as below as the BSSID ca:fe:ba:be:00:01
 280 and the remote WDS endpoint ca:fe:ba:be:00:02 (option bssid field).
 281
 282 \begin{Verbatim}
 283 config wifi-device      "wl0"
 284     option type         "broadcom"
 285     option channel      "5"
 286
 287 config 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
 295 config 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
 305 It is also possible to encrypt WDS connections. \texttt{psk}, \texttt{psk2} and
 306 \texttt{psk+psk2} modes are supported. Configuration below is an example
 307 configuration using Pre-Shared-Keys with AES algorithm.
 308
 309 \begin{Verbatim}
 310 config wifi-device  wl0
 311     option type     broadcom
 312     option channel  5
 313
 314 config 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
 322 config 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
 334 OpenWrt supports both 802.1x client and Access Point
 335 configurations. 802.1x client is only working with
 336 drivers supported by wpa-supplicant. Configuration
 337 only supports EAP types TLS, TTLS or PEAP.
 338
 339 \subparagraph{EAP-TLS}
 340
 341 \begin{Verbatim}
 342 config 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}
 355 config 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
 368 There are certain limitations when combining modes.
 369 Only 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
 396 Since we currently only support thread different wireless drivers : Broadcom, Atheros and mac80211,
 397 you might be interested in adding support for another driver like Ralink RT2x00,
 398 Texas Instruments ACX100/111.
 399
 400 The driver specific script should be placed in \texttt{/lib/wifi/<driver>.sh} and has to
 401 include 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
 410 Each driver script should append the driver to a global DRIVERS variable :
 411
 412 \begin{Verbatim}
 413 append DRIVERS "driver name"
 414 \end{Verbatim}
 415
 416 \subparagraph{\texttt{scan\_<driver>}}
 417
 418 This function will parse the \texttt{/etc/config/wireless} and make sure there
 419 are no configuration incompatibilities, like enabling hidden SSIDS with ad-hoc mode
 420 for instance. This can be more complex if your driver supports a lof of configuration
 421 options. It does not change the state of the interface.
 422
 423 Example:
 424 \begin{Verbatim}
 425 scan_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
 438 This function will bring up the wifi device and optionally create application specific
 439 configuration files, e.g. for the WPA authenticator or supplicant.
 440
 441 Example:
 442 \begin{Verbatim}
 443 enable_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
 456 This function will bring down the wifi device and all its virtual interfaces (if supported).
 457
 458 Example:
 459 \begin{Verbatim}
 460 disable_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
 472 This function looks for interfaces that are usable with the driver. Template config sections
 473 for new devices should be written to stdout. Must check for already existing config sections
 474 belonging to the interfaces before creating new templates.
 475
 476 Example:
 477 \begin{Verbatim}
 478 detect_dummy() {
 479         [ wifi-device = "$(config_get dummydev type)" ] && return 0
 480         cat <<EOF
 481 config wifi-device dummydev
 482         option type dummy
 483         # REMOVE THIS LINE TO ENABLE WIFI:
 484         option disabled 1
 485
 486 config wifi-iface
 487         option device dummydev
 488         option mode ap
 489         option ssid OpenWrt
 490 EOF
 491 }
 492 \end{Verbatim}