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