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