diff options
Diffstat (limited to 'docs/wireless.tex')
| -rw-r--r-- | docs/wireless.tex | 492 |
1 files changed, 0 insertions, 492 deletions
diff --git a/docs/wireless.tex b/docs/wireless.tex deleted file mode 100644 index efb07eafb4..0000000000 --- a/docs/wireless.tex +++ /dev/null @@ -1,492 +0,0 @@ -The WiFi settings are configured in the file \texttt{/etc/config/wireless} -(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 and mac80211. - -The reason for using such architecture, is that it abstracts the driver configuration. - -\paragraph{Generic Broadcom wireless config:} - -\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" -\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} - -\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). - -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 (meters) - 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, mesh, 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 passphrase 0,1 - option server ip address - option port port - option hidden 0,1 - option isolate 0,1 (broadcom) - option doth 0,1 (atheros, broadcom) - option wmm 0,1 (atheros, broadcom) -\end{Verbatim} - -\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} \\ - The wifi channel (e.g. 1-14, depending on your country setting). - - \item \texttt{maxassoc} \\ - Optional: Maximum number of associated clients. This feature is supported only on the Broadcom chipsets. - - \item \texttt{distance} \\ - Optional: Distance between the ap and the furthest client in meters. This feature is supported only on the Atheros chipsets. - - \item \texttt{mode} \\ - The frequency band (\texttt{b}, \texttt{g}, \texttt{bg}, \texttt{a}). This feature is only supported on the Atheros chipsets. - - \item \texttt{diversity} \\ - Optional: Enable diversity for the Wi-Fi device. This feature is supported only on the Atheros chipsets. - - \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} - \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: - - \begin{itemize} - \item \texttt{ap} \\ - Access point mode - - \item \texttt{sta} \\ - Client mode - - \item \texttt{adhoc} \\ - Ad-Hoc mode - - \item \texttt{monitor} \\ - Monitor mode - - \item \texttt{mesh} \\ - Mesh Point mode (802.11s) - - \item \texttt{wds} \\ - WDS point-to-point link - - \end{itemize} - - \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{none} - \item \texttt{wep} - \item \texttt{psk}, \texttt{psk2} \\ - WPA(2) Pre-shared Key - - \item \texttt{wpa}, \texttt{wpa2} \\ - WPA(2) RADIUS - \end{itemize} - - \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{passphrase} (wpa) \\ - 0 treats the wpa psk as a text passphrase; 1 treats wpa psk as - encoded passphrase. You can generate an encoded passphrase with - the wpa\_passphrase utility. This is especially useful if your - passphrase contains special characters. This option only works - when using mac80211 or atheros type devices. - - \item \texttt{server} (wpa) \\ - The RADIUS server ip address - - \item \texttt{port} (wpa) \\ - 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. - - \item \texttt{doth} \\ - Optional: Toggle 802.11h mode. - 0 disables 802.11h (default); 1 enables it. - - \item \texttt{wmm} \\ - Optional: Toggle 802.11e mode. - 0 disables 802.11e (default); 1 enables it. - -\end{itemize} - -\paragraph{Mesh Point} - -Mesh Point (802.11s) is only supported by some mac80211 drivers. It requires the iw package -to be installed to setup mesh links. OpenWrt creates mshN mesh point interfaces. A sample -configuration looks like this: - -\begin{Verbatim} -config wifi-device "wlan0" - option type "mac80211" - option channel "5" - -config wifi-iface - option device "wlan0" - option network lan - option mode "mesh" - option mesh_id "OpenWrt" -\end{Verbatim} - -\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 -drivers supported by wpa-supplicant. 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:} - -There are certain limitations when combining modes. -Only the following mode combinations are supported: - -\begin{itemize} - \item \textbf{Broadcom}: \\ - \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} - - 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). - - \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} - -\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} |