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