Update wireless documentation

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

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.

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 agmode       "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
    option agmode     11b, 11g, 11a, 11bg (atheros only)

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 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.
        
    \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 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.


\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{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{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{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.

\end{itemize}


\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 two different wireless drivers : Broadcom and Atheros,
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}