wireless.tex: update docs to reflect txpower move

[openwrt/openwrt.git] / docs / wireless.tex

diff --git a/docs/wireless.tex b/docs/wireless.tex
index 94d74f4fae770239937cdeb8ab5b203ba823b29a..dd6ec43dd9ead3d4a98644aeb623c595cd510752 100644 (file)
--- a/docs/wireless.tex
+++ b/docs/wireless.tex
@@ -1,6 +1,15 @@
 The WiFi settings are configured in the file \texttt{/etc/config/wireless}
 The WiFi settings are configured in the file \texttt{/etc/config/wireless}

-(currently supported on Broadcom only). When booting the router for the first time
-it should detect your card and create a sample configuration that looks like this:
+(currently supported on Broadcom, Atheros and mac80211). When booting the router for the first time
+it should detect your card and create a sample configuration file. By default '\texttt{option network  lan}' is
+commented. This prevents unsecured sharing of the network over the wireless interface.
+
+Each wireless driver has its own configuration script in \texttt{/lib/wifi/driver\_name.sh} which handles
+driver specific options and configurations. This script is also calling driver specific binaries like wlc for
+Broadcom, or hostapd and wpa\_supplicant for atheros.
+
+The reason for using such architecture, is that it abstracts the driver configuration. 
+
+\paragraph{Generic Broadcom wireless config:}

 
 \begin{Verbatim}
 config wifi-device      "wl0"
 
 \begin{Verbatim}
 config wifi-device      "wl0"


@@ -9,36 +18,156 @@ config wifi-device      "wl0"
 
 config wifi-iface
     option device       "wl0"
 
 config wifi-iface
     option device       "wl0"

+#   option network  lan
+    option mode         "ap"
+    option ssid         "OpenWrt"
+    option hidden       "0"
+    option encryption   "none"
+\end{Verbatim}
+
+\paragraph{Generic Atheros wireless config:}
+
+\begin{Verbatim}
+config wifi-device      "wifi0"
+    option type         "atheros"
+    option channel      "5"
+    option hwmode      "11g"
+
+config wifi-iface
+    option device       "wifi0"
+#   option network  lan
+    option mode         "ap"
+    option ssid         "OpenWrt"
+    option hidden       "0"
+    option encryption   "none"
+\end{Verbatim}
+
+\paragraph{Generic mac80211 wireless config:}
+
+\begin{Verbatim}
+config wifi-device      "wifi0"
+    option type         "mac80211"
+    option channel      "5"
+
+config wifi-iface
+    option device       "wlan0"
+#   option network  lan

     option mode         "ap"
     option ssid         "OpenWrt"
     option hidden       "0"
     option encryption   "none"
 \end{Verbatim}
 
     option mode         "ap"
     option ssid         "OpenWrt"
     option hidden       "0"
     option encryption   "none"
 \end{Verbatim}
 

+\paragraph{Generic multi-radio Atheros wireless config:}
+
+\begin{Verbatim}
+config wifi-device  wifi0
+    option type     atheros
+    option channel  1
+
+config wifi-iface
+    option device   wifi0
+#   option network  lan
+    option mode     ap
+    option ssid     OpenWrt_private
+    option hidden   0
+    option encryption none
+
+config wifi-device  wifi1
+    option type     atheros
+    option channel  11
+
+config wifi-iface
+    option device   wifi1
+#   option network  lan
+    option mode     ap
+    option ssid     OpenWrt_public
+    option hidden   1
+    option encryption none
+\end{Verbatim}
+

 There are two types of config sections in this file. The '\texttt{wifi-device}' refers to
 the physical wifi interface and '\texttt{wifi-iface}' configures a virtual interface on top
 of that (if supported by the driver).
 
 There are two types of config sections in this file. The '\texttt{wifi-device}' refers to
 the physical wifi interface and '\texttt{wifi-iface}' configures a virtual interface on top
 of that (if supported by the driver).
 

+A full outline of the wireless configuration file with description of each field:
+
+\begin{Verbatim}
+config wifi-device    wifi device name
+    option type       broadcom, atheros, mac80211
+    option country    us, uk, fr, de, etc.
+    option channel    1-14
+    option maxassoc   1-128 (broadcom only)
+    option distance   1-n
+    option hwmode     11b, 11g, 11a, 11bg (atheros, mac80211)
+    option rxantenna  0,1,2 (atheros, broadcom)
+    option txantenna  0,1,2 (atheros, broadcom)
+    option txpower  transmission power in dBm
+
+config wifi-iface
+    option network  the interface you want wifi to bridge with
+    option device   wifi0, wifi1, wifi2, wifiN
+    option mode     ap, sta, adhoc, monitor, or wds
+    option txpower  (deprecated) transmission power in dBm
+    option ssid     ssid name
+    option bssid    bssid address
+    option encryption none, wep, psk, psk2, wpa, wpa2
+    option key      encryption key
+    option key1     key 1
+    option key2     key 2
+    option key3     key 3
+    option key4     key 4
+    option server   ip address
+    option port     port
+    option hidden   0,1
+    option isolate  0,1
+\end{Verbatim}
+

 \paragraph{Options for the \texttt{wifi-device}:}
 
 \begin{itemize}
     \item \texttt{type} \\
         The driver to use for this interface.
 \paragraph{Options for the \texttt{wifi-device}:}
 
 \begin{itemize}
     \item \texttt{type} \\
         The driver to use for this interface.

-
+       

     \item \texttt{country} \\
         The country code used to determine the regulatory settings.
 
     \item \texttt{channel} \\
     \item \texttt{country} \\
         The country code used to determine the regulatory settings.
 
     \item \texttt{channel} \\

-        The wifi channel (1-14, depending on your country setting).
+        The wifi channel (e.g. 1-14, depending on your country setting).

 
     \item \texttt{maxassoc} \\
 
     \item \texttt{maxassoc} \\

-        Maximum number of associated clients
+        Optional: Maximum number of associated clients. This feature is supported only on the broadcom chipset.
+
+    \item \texttt{distance} \\
+       Optional: Distance between the ap and the furthest client in meters. This feature is supported only on the atheros chipset.
+
+       \item \texttt{mode} \\
+               The frequency band (\texttt{b}, \texttt{g}, \texttt{bg}, \texttt{a}). This feature is only supported on the atheros chipset.
+
+    \item \texttt{diversity} \\
+       Optional: Enable diversity for the Wi-Fi device. This feature is supported only on the atheros chipset.
+
+    \item \texttt{rxantenna} \\
+       Optional: Antenna identifier (0, 1 or 2) for reception. This feature is supported by atheros and some broadcom chipsets.
+
+    \item \texttt{txantenna} \\
+       Optional: Antenna identifier (0, 1 or 2) for emission. This feature is supported by atheros and some broadcom chipsets.
+
+    \item \texttt{txpower}
+       Set the transmission power to be used. The amount is specified in dBm.

 
 \end{itemize}
 
 \paragraph{Options for the \texttt{wifi-iface}:}
 
 \begin{itemize}
 
 \end{itemize}
 
 \paragraph{Options for the \texttt{wifi-iface}:}
 
 \begin{itemize}

+    \item \texttt{network} \\
+        Selects the interface section from \texttt{/etc/config/network} to be
+        used with this interface
+
+    \item \texttt{device} \\
+       Set the wifi device name.
+

     \item \texttt{mode} \\
         Operating mode:
 
     \item \texttt{mode} \\
         Operating mode:
 


@@ -52,52 +181,273 @@ of that (if supported by the driver).
             \item \texttt{adhoc} \\
                 Ad-Hoc mode
 
             \item \texttt{adhoc} \\
                 Ad-Hoc mode
 

+            \item \texttt{monitor} \\
+                Monitor mode
+

             \item \texttt{wds} \\
                 WDS point-to-point link
 
         \end{itemize}
             \item \texttt{wds} \\
                 WDS point-to-point link
 
         \end{itemize}

-    \item \texttt{network} \\
-        Selects the interface section from \texttt{/etc/config/network} to be
-        used with this interface
+
+    \item \texttt{ssid}
+       Set the SSID to be used on the wifi device.
+
+    \item \texttt{bssid}
+       Set the BSSID address to be used for wds to set the mac address of the other wds unit.
+
+    \item \texttt{txpower}
+       (Deprecated, set in wifi-device) Set the transmission power to be used. The amount is specified in dBm.

 
     \item \texttt{encryption} \\
         Encryption setting. Accepts the following values:
 
         \begin{itemize}
 
     \item \texttt{encryption} \\
         Encryption setting. Accepts the following values:
 
         \begin{itemize}

+           \item \texttt{none}
+           \item \texttt{wep}

             \item \texttt{psk}, \texttt{psk2} \\
                 WPA(2) Pre-shared Key
 
             \item \texttt{wpa}, \texttt{wpa2} \\
                 WPA(2) RADIUS
             \item \texttt{psk}, \texttt{psk2} \\
                 WPA(2) Pre-shared Key
 
             \item \texttt{wpa}, \texttt{wpa2} \\
                 WPA(2) RADIUS

-

         \end{itemize}
 
         \end{itemize}
 

-    \item \texttt{key} (wpa and psk) \\
-        Either the WPA key (PSK mode) or the RADIUS shared secret (WPA RADIUS mode)
+    \item \texttt{key, key1, key2, key3, key4} (wep, wpa and psk) \\
+        WEP key, WPA key (PSK mode) or the RADIUS shared secret (WPA RADIUS mode)

 
     \item \texttt{server} (wpa) \\
 
     \item \texttt{server} (wpa) \\

-        The RADIUS server address
+        The RADIUS server ip address

 
     \item \texttt{port} (wpa) \\
 
     \item \texttt{port} (wpa) \\

-        The RADIUS server port
+        The RADIUS server port (defaults to 1812)
+
+    \item \texttt{hidden} \\
+        0 broadcasts the ssid; 1 disables broadcasting of the ssid
+
+    \item \texttt{isolate} \\
+        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.
+        0 disables ap isolation (default); 1 enables ap isolation.

 
 \end{itemize}
 
 
 \end{itemize}
 

+\paragraph{Wireless Distribution System}
+
+WDS is a non-standard mode which will be working between two Broadcom devices for instance
+but not between a Broadcom and Atheros device.
+
+\subparagraph{Unencrypted WDS connections}
+
+This configuration example shows you how to setup unencrypted WDS connections.
+We assume that the peer configured as below as the BSSID ca:fe:ba:be:00:01
+and the remote WDS endpoint ca:fe:ba:be:00:02 (option bssid field).
+
+\begin{Verbatim}
+config wifi-device      "wl0"
+    option type                "broadcom"
+    option channel      "5"
+
+config wifi-iface
+    option device       "wl0"
+    option network     lan
+    option mode         "ap"
+    option ssid         "OpenWrt"
+    option hidden       "0"
+    option encryption   "none"
+
+config wifi-iface
+    option device       "wl0"
+    option network      lan
+    option mode         wds
+    option ssid         "OpenWrt WDS"
+    option bssid        "ca:fe:ba:be:00:02"
+\end{Verbatim}
+
+\subparagraph{Encrypted WDS connections}
+
+It is also possible to encrypt WDS connections. \texttt{psk}, \texttt{psk2} and
+\texttt{psk+psk2} modes are supported. Configuration below is an example
+configuration using Pre-Shared-Keys with AES algorithm.
+
+\begin{Verbatim}
+config wifi-device  wl0
+    option type     broadcom
+    option channel  5
+
+config wifi-iface
+    option device   "wl0"
+    option network  lan
+    option mode     ap
+    option ssid     "OpenWrt"
+    option encryption  psk2
+    option key      "<key for clients>"
+
+config wifi-iface
+    option device   "wl0"
+    option network  lan
+    option mode     wds
+    option bssid    ca:fe:ba:be:00:02
+    option ssid     "OpenWrt WDS"
+    option encryption  psk2
+    option key      "<psk for WDS>"
+\end{Verbatim}
+
+\paragraph{802.1x configurations}
+
+OpenWrt supports both 802.1x client and Access Point
+configurations. 802.1x client is only working with
+Atheros or mac80211 drivers. Configuration only
+supports EAP types TLS, TTLS or PEAP.
+
+\subparagraph{EAP-TLS}
+
+\begin{Verbatim}
+config wifi-iface
+    option device         "ath0"
+    option network        lan
+    option ssid           OpenWrt
+    option eap_type       tls
+    option ca_cert        "/etc/config/certs/ca.crt"
+    option priv_key       "/etc/config/certs/priv.crt"
+    option priv_key_pwd   "PKCS#12 passphrase"
+\end{Verbatim}
+
+\subparagraph{EAP-PEAP}
+
+\begin{Verbatim}
+config wifi-iface
+    option device         "ath0"
+    option network        lan
+    option ssid           OpenWrt
+    option eap_type       peap
+    option ca_cert        "/etc/config/certs/ca.crt"
+    option auth           MSCHAPV2
+    option identity       username
+    option password       password
+\end{Verbatim}
+

 \paragraph{Limitations:}
 
 \paragraph{Limitations:}
 

+There are certain limitations when combining modes.
+Only the following mode combinations are supported:
+

 \begin{itemize}
     \item \textbf{Broadcom}: \\
 \begin{itemize}
     \item \textbf{Broadcom}: \\

-        Only the following mode combinations are supported:
-

         \begin{itemize}
             \item 1x \texttt{sta}, 0-3x \texttt{ap}
             \item 1-4x \texttt{ap}
             \item 1x \texttt{adhoc}
         \begin{itemize}
             \item 1x \texttt{sta}, 0-3x \texttt{ap}
             \item 1-4x \texttt{ap}
             \item 1x \texttt{adhoc}

+            \item 1x \texttt{monitor}

         \end{itemize}
 
         \end{itemize}
 

-        WDS links can only be used in pure AP mode and can't use WEP (except when sharing the
+        WDS links can only be used in pure AP mode and cannot use WEP (except when sharing the

         settings with the master interface, which is done automatically).
 
         settings with the master interface, which is done automatically).
 

+    \item \textbf{Atheros}: \\
+        \begin{itemize}
+            \item 1x \texttt{sta}, 0-Nx \texttt{ap}
+            \item 1-Nx \texttt{ap}
+            \item 1x \texttt{adhoc}
+        \end{itemize}
+
+       N is the maximum number of VAPs that the module allows, it defaults to 4, but can be
+       changed by loading the module with the maxvaps=N parameter.

 \end{itemize}
 
 \end{itemize}
 

+\paragraph{Adding a new driver configuration}
+
+Since we currently only support thread different wireless drivers : Broadcom, Atheros and mac80211,
+you might be interested in adding support for another driver like Ralink RT2x00, 
+Texas Instruments ACX100/111.
+
+The driver specific script should be placed in \texttt{/lib/wifi/<driver>.sh} and has to
+include several functions providing :
+
+\begin{itemize}
+       \item detection of the driver presence
+       \item enabling/disabling the wifi interface(s)
+       \item configuration reading and setting
+       \item third-party programs calling (nas, supplicant)
+\end{itemize}
+
+Each driver script should append the driver to a global DRIVERS variable :
+
+\begin{Verbatim}
+append DRIVERS "driver name"
+\end{Verbatim}
+
+\subparagraph{\texttt{scan\_<driver>}}
+
+This function will parse the \texttt{/etc/config/wireless} and make sure there
+are no configuration incompatibilities, like enabling hidden SSIDS with ad-hoc mode
+for instance. This can be more complex if your driver supports a lof of configuration
+options. It does not change the state of the interface.
+
+Example:
+\begin{Verbatim}
+scan_dummy() {
+       local device="$1"
+
+       config_get vifs "$device" vifs
+       for vif in $vifs; do
+               # check config consistency for wifi-iface sections
+       done
+       # check mode combination
+}
+\end{Verbatim}
+
+\subparagraph{\texttt{enable\_<driver>}}

 
 

+This function will bring up the wifi device and optionally create application specific
+configuration files, e.g. for the WPA authenticator or supplicant.
+
+Example:
+\begin{Verbatim}
+enable_dummy() {
+       local device="$1"
+
+       config_get vifs "$device" vifs
+       for vif in $vifs; do
+               # bring up virtual interface belonging to
+               # the wifi-device "$device"
+       done
+}
+\end{Verbatim}
+
+\subparagraph{\texttt{disable\_<driver>}}
+
+This function will bring down the wifi device and all its virtual interfaces (if supported).
+
+Example:
+\begin{Verbatim}
+disable_dummy() {
+       local device="$1"
+
+       # bring down virtual interfaces belonging to
+       # "$device" regardless of whether they are
+       # configured or not. Don't rely on the vifs
+       # variable at this point
+}
+\end{Verbatim}
+
+\subparagraph{\texttt{detect\_<driver>}}
+
+This function looks for interfaces that are usable with the driver. Template config sections
+for new devices should be written to stdout. Must check for already existing config sections
+belonging to the interfaces before creating new templates.
+
+Example:
+\begin{Verbatim}
+detect_dummy() {
+       [ wifi-device = "$(config_get dummydev type)" ] && return 0
+       cat <<EOF
+config wifi-device dummydev
+       option type dummy
+       # REMOVE THIS LINE TO ENABLE WIFI:
+       option disabled 1
+
+config wifi-iface
+       option device dummydev
+       option mode ap
+       option ssid OpenWrt
+EOF
+}
+\end{Verbatim}