docs/wireless.tex

   1 The WiFi settings are configured in the file \texttt{/etc/config/wireless}
   2 (currently supported on Broadcom and Atheros). 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 multi-radio Atheros wireless config:}
  46
  47 \begin{Verbatim}
  48 config wifi-device  wifi0
  49     option type     atheros
  50     option channel  1
  51
  52 config wifi-iface
  53     option device   wifi0
  54 #   option network  lan
  55     option mode     ap
  56     option ssid     OpenWrt_private
  57     option hidden   0
  58     option encryption none
  59
  60 config wifi-device  wifi1
  61     option type     atheros
  62     option channel  11
  63
  64 config wifi-iface
  65     option device   wifi1
  66 #   option network  lan
  67     option mode     ap
  68     option ssid     OpenWrt_public
  69     option hidden   1
  70     option encryption none
  71 \end{Verbatim}
  72
  73 There are two types of config sections in this file. The '\texttt{wifi-device}' refers to
  74 the physical wifi interface and '\texttt{wifi-iface}' configures a virtual interface on top
  75 of that (if supported by the driver).
  76
  77 A full outline of the wireless configuration file with description of each field:
  78
  79 \begin{Verbatim}
  80 config wifi-device     wifi device name
  81     option type     broadcom, atheros
  82     option country  us, uk, fr, de, etc.
  83     option channel  1-14
  84     option maxassoc 1-128 (broadcom only)
  85     option distance 1-n
  86     option agmode     11b, 11g, 11a, 11bg (atheros only)
  87
  88 config wifi-iface
  89     option network  the interface you want wifi to bridge with
  90     option device   wifi0, wifi1, wifi2, wifiN
  91     option mode     ap, sta, adhoc, or wds
  92     option ssid     ssid name
  93     option bssid    bssid address
  94     option encryption none, wep, psk, psk2, wpa, wpa2
  95     option key      encryption key
  96     option key1     key 1
  97     option key2     key 2
  98     option key3     key 3
  99     option key4     key 4
 100     option server   ip address
 101     option port     port
 102     option hidden   0,1
 103     option isolate  0,1
 104 \end{Verbatim}
 105
 106 \paragraph{Options for the \texttt{wifi-device}:}
 107
 108 \begin{itemize}
 109     \item \texttt{type} \\
 110         The driver to use for this interface.
 111
 112     \item \texttt{country} \\
 113         The country code used to determine the regulatory settings.
 114
 115     \item \texttt{channel} \\
 116         The wifi channel (e.g. 1-14, depending on your country setting).
 117
 118     \item \texttt{maxassoc} \\
 119         Optional: Maximum number of associated clients. This feature is supported only on the broadcom chipset.
 120
 121     \item \texttt{distance} \\
 122         Optional: Distance between the ap and the furthest client in meters. This feature is supported only on the atheros chipset.
 123
 124         \item \texttt{mode} \\
 125                 The frequency band (\texttt{b}, \texttt{g}, \texttt{bg}, \texttt{a}). This feature is only supported on the atheros chipset.
 126
 127
 128 \end{itemize}
 129
 130 \paragraph{Options for the \texttt{wifi-iface}:}
 131
 132 \begin{itemize}
 133     \item \texttt{network} \\
 134         Selects the interface section from \texttt{/etc/config/network} to be
 135         used with this interface
 136
 137     \item \texttt{device} \\
 138         Set the wifi device name.
 139
 140     \item \texttt{mode} \\
 141         Operating mode:
 142
 143         \begin{itemize}
 144             \item \texttt{ap} \\
 145                 Access point mode
 146
 147             \item \texttt{sta} \\
 148                 Client mode
 149
 150             \item \texttt{adhoc} \\
 151                 Ad-Hoc mode
 152
 153             \item \texttt{wds} \\
 154                 WDS point-to-point link
 155
 156         \end{itemize}
 157
 158     \item \texttt{ssid}
 159         Set the SSID to be used on the wifi device.
 160
 161     \item \texttt{bssid}
 162         Set the BSSID address to be used for wds to set the mac address of the other wds unit.
 163
 164     \item \texttt{encryption} \\
 165         Encryption setting. Accepts the following values:
 166
 167         \begin{itemize}
 168             \item \texttt{none}
 169             \item \texttt{wep}
 170             \item \texttt{psk}, \texttt{psk2} \\
 171                 WPA(2) Pre-shared Key
 172
 173             \item \texttt{wpa}, \texttt{wpa2} \\
 174                 WPA(2) RADIUS
 175         \end{itemize}
 176
 177     \item \texttt{key, key1, key2, key3, key4} (wep, wpa and psk) \\
 178         WEP key, WPA key (PSK mode) or the RADIUS shared secret (WPA RADIUS mode)
 179
 180     \item \texttt{server} (wpa) \\
 181         The RADIUS server ip address
 182
 183     \item \texttt{port} (wpa) \\
 184         The RADIUS server port
 185
 186     \item \texttt{hidden} \\
 187         0 broadcasts the ssid; 1 disables broadcasting of the ssid
 188
 189     \item \texttt{isolate} \\
 190         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.
 191         0 disables ap isolation (default); 1 enables ap isolation.
 192
 193 \end{itemize}
 194
 195
 196 \paragraph{Limitations:}
 197
 198 There are certain limitations when combining modes.
 199 Only the following mode combinations are supported:
 200
 201 \begin{itemize}
 202     \item \textbf{Broadcom}: \\
 203         \begin{itemize}
 204             \item 1x \texttt{sta}, 0-3x \texttt{ap}
 205             \item 1-4x \texttt{ap}
 206             \item 1x \texttt{adhoc}
 207         \end{itemize}
 208
 209         WDS links can only be used in pure AP mode and cannot use WEP (except when sharing the
 210         settings with the master interface, which is done automatically).
 211
 212     \item \textbf{Atheros}: \\
 213         \begin{itemize}
 214             \item 1x \texttt{sta}, 0-4x \texttt{ap}
 215             \item 1-4x \texttt{ap}
 216             \item 1x \texttt{adhoc}
 217         \end{itemize}
 218 \end{itemize}
 219
 220 \paragraph{Adding a new driver configuration}
 221
 222 Since we currently only support two different wireless drivers : Broadcom and Atheros,
 223 you might be interested in adding support for another driver like Ralink RT2x00,
 224 Texas Instruments ACX100/111.
 225
 226 The driver specific script should be placed in \texttt{/lib/wifi/<driver>.sh} and has to
 227 include several functions providing :
 228
 229 \begin{itemize}
 230         \item detection of the driver presence
 231         \item enabling/disabling the wifi interface(s)
 232         \item configuration reading and setting
 233         \item third-party programs calling (nas, supplicant)
 234 \end{itemize}
 235
 236 Each driver script should append the driver to a global DRIVERS variable :
 237
 238 \begin{Verbatim}
 239 append DRIVERS "driver name"
 240 \end{Verbatim}
 241
 242 \subparagraph{\texttt{scan\_<driver>}}
 243
 244 This function will parse the \texttt{/etc/config/wireless} and make sure there
 245 are no configuration incompatibilities, like enabling hidden SSIDS with ad-hoc mode
 246 for instance. This can be more complex if your driver supports a lof of configuration
 247 options. It does not change the state of the interface.
 248
 249 Example:
 250 \begin{Verbatim}
 251 scan_dummy() {
 252         local device="$1"
 253
 254         config_get vifs "$device" vifs
 255         for vif in $vifs; do
 256                 # check config consistency for wifi-iface sections
 257         done
 258         # check mode combination
 259 }
 260 \end{Verbatim}
 261
 262 \subparagraph{\texttt{enable\_<driver>}}
 263
 264 This function will bring up the wifi device and optionally create application specific
 265 configuration files, e.g. for the WPA authenticator or supplicant.
 266
 267 Example:
 268 \begin{Verbatim}
 269 enable_dummy() {
 270         local device="$1"
 271
 272         config_get vifs "$device" vifs
 273         for vif in $vifs; do
 274                 # bring up virtual interface belonging to
 275                 # the wifi-device "$device"
 276         done
 277 }
 278 \end{Verbatim}
 279
 280 \subparagraph{\texttt{disable\_<driver>}}
 281
 282 This function will bring down the wifi device and all its virtual interfaces (if supported).
 283
 284 Example:
 285 \begin{Verbatim}
 286 disable_dummy() {
 287         local device="$1"
 288
 289         # bring down virtual interfaces belonging to
 290         # "$device" regardless of whether they are
 291         # configured or not. Don't rely on the vifs
 292         # variable at this point
 293 }
 294 \end{Verbatim}
 295
 296 \subparagraph{\texttt{detect\_<driver>}}
 297
 298 This function looks for interfaces that are usable with the driver. Template config sections
 299 for new devices should be written to stdout. Must check for already existing config sections
 300 belonging to the interfaces before creating new templates.
 301
 302 Example:
 303 \begin{Verbatim}
 304 detect_dummy() {
 305         [ wifi-device = "$(config_get dummydev type)" ] && return 0
 306         cat <<EOF
 307 config wifi-device dummydev
 308         option type dummy
 309         # REMOVE THIS LINE TO ENABLE WIFI:
 310         option disabled 1
 311
 312 config wifi-iface
 313         option device dummydev
 314         option mode ap
 315         option ssid OpenWrt
 316 EOF
 317 }
 318 \end{Verbatim}