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