Changeset 6d2a418 in freewrt for docs

Timestamp:

Dec 5, 2006, 7:38:17 PM (19 years ago)

Author:

Phil Sutter <n0-1@…>

Branches:

freewrt_1_0, freewrt_2_0

Children:

62a8cfc

Parents:

94fa7ac

Message:

imported networking howto

git-svn-id: ​svn://www.freewrt.org/branches/freewrt_1_0@1260 afb5a338-a214-0410-bd46-81f09a774fd1

File:

• docs/handbook/user/00-allinone.tex (modified) (1 diff)

docs/handbook/user/00-allinone.tex

@@ -284 +284 @@
 \end{Verbatim}
 \end{itemize}
+
+
+\chapter{The FreeWRT Operating System}
+After the FreeWRT firmware image has been built by the ADK and later flashed
+onto the hardware, the resulting operating system has to be aministrated. This
+section provides the necessary information to do that, including tips and
+guides for using FreeWRT in general, of course.
+
+\section{Network Configuration}
+The device names for real network interfaces in Linux are named ethx (x is
+0-9). If the device has a switch, the different ports are separated via VLAN
+technology. The vlan interfaces are named ethx.y.  The network configuration in
+FreeWRT is managed via Busybox's ifupdown implementation. Busybox's ip builtin
+command configures the network interfaces. There is no \texttt{ifconfig} or \texttt{route}. 
+To show all configured network interfaces use:
+\begin{Verbatim}
+$ ip addr show
+\end{Verbatim}
+To show the kernel routing table use:
+\begin{Verbatim}
+$ ip route show
+\end{Verbatim}
+
+All available network settings can be found in \texttt{/etc/network/interfaces}
+which has the common form:
+\begin{Verbatim}[label=/etc/network/interfaces]
+auto <iface-name>
+iface <iface-name> inet <method>
+  <option-x> <value>
+  <option-y> <value>
+  <option-z> <value>
+\end{Verbatim}
+
+\texttt{auto <iface-name>} is optional and, if set, tells the "ifup" script to
+start this interface automatically on bootup.
+
+Each interface needs a unique name which, depending on the method, represents
+either a physical interface or a logical interface name like "eth0.1" for a
+physical VLAN or "umts" as a logical name for a ppp interface.
+
+Possible methods are:
+\begin{description}
+\item[static] use the given options to configure the interface statically
+\item[dhcp] just start a dhcp client using the interface \texttt{iface-name}
+\item[manual] don't configure the interface but start pre-up.d hook scripts
+\item[ppp] run \texttt{pon <provider>} where \texttt{<provider>} is given as an interface option
+\end{description}
+
+\subsection{Switch/VLAN}
+The switch built-in into the most routers is capable of separating each port
+using VLAN tagging. You can configure the switch by simply adding the interface
+to the config file and giving the desired switch-ports:
+\begin{Verbatim}[label=/etc/network/interfaces]
+auto eth0.0
+iface eth0.0 inet static
+    switch-ports 1 2 5*
+    address 192.168.1.1
+    netmask 255.255.255.0
+
+auto eth0.1
+iface eth0.1 inet static
+    switch-ports  3 4 5
+    address 192.168.2.1
+    netmask 255.255.255.0
+
+auto eth0.2
+iface eth0.2 inet static
+    switch-ports 0 5
+    address 172.16.1.42
+    netmask 255.255.255.0
+    gateway 172.16.1.1
+\end{Verbatim}
+
+This configures three VLAN interfaces \texttt{eth0.0} on ports 1 and 2,
+\texttt{eth0.1} on port 3 and 4 and \texttt{eth0.2} on port 0.
+
+Explanation:
+\begin{description}
+\item[port 0] this is typically the port labeled as WAN
+\item[port 1-4] these are typically the ports labeled as LAN
+\item[port 5] this special port represents the port where the router-board is
+        connected to the switch
+\item[*] one interface always need an asterisk behind port 5 which means it is
+        the default interface and gets all the packages with unknown tags.
+\end{description}
+
+\subsection{Static IP configuration}
+As you can see in the VLAN example three interfaces were configured with static
+IP settings, so these are the commonly used options:
+\begin{description}
+\item[address] the IP address  - required
+\item[netmask] the netmask     - required
+\item[gateway] an IP address added as default gateway if present
+\end{description}
+
+\subsection{DHCP}
+That's just as simple as:
+\begin{Verbatim}[label=/etc/network/interfaces]
+auto eth0.1
+iface eth0.1 inet dhcp
+    switch-ports  0 5
+\end{Verbatim}
+Typically this configures the WAN-Port to start a DHCP request on bootup.
+
+\subsection{Bridging}
+This is mostly needed to combine LAN and WLAN to a homogeneous network like:
+\begin{Verbatim}[label=/etc/network/interfaces]
+auto eth0.0
+iface eth0.0 inet manual
+    switch-ports 1 2 3 4 5*
+
+auto eth1
+iface eth1 inet manual
+    [... wifi-settings, see below ...]
+
+auto br0
+iface br0 inet static
+    bridge-ifaces eth0.0 eth1
+    address 192.168.1.1
+    netmask 255.255.255.0
+\end{Verbatim}
+This creates a new bridging interface \texttt{br0} which combines the VLAN
+interface \texttt{eth0.0} (representing the LAN-ports 1-4) and the WLAN
+interface \texttt{eth1} (on some devices like Asus WL500g or Linksys WRT54G
+v1.1 this might be \texttt{eth2}).
+
+\subsection{WLAN}
+A router containing a WLAN interface has an additional ethernet device
+representing it. On Broadcom-based hardware it is typically \texttt{eth1}
+(Linksys) or \texttt{eth2} (Asus) (in the current driver version), on Madwifi
+devices it is \texttt{ath0}, \texttt{ath1}, etc. You can use these interfaces
+standalone or bridged with other devices, e.g. the internal LAN.
+
+\subsubsection{Basic Settings}
+$\star$ with Option means mandatory, $\star$ with Parameter means default.
+
+\begin{tabular}{l|l|l}
+\textbf{Option} & \textbf{Parameter} & \textbf{Description} \\
+\hline
+type$\star$  & broadcom        & Broadcom based card \\
+             & atheros         & Madwifi driver \\
+mode$\star$  & ap              & Access point mode \\
+             & sta             & Client mode \\
+             & adhoc           & Ad-Hoc mode \\
+             & wds             & WDS point-to-point link \\
+             & monitor         & The node acts as a passive monitor and only receives packets \\
+ssid$\star$  & <String>        & Set the SSID (Network Name) \\
+country      & {ALL|DE|JP|US|...} & The country code used to determine the regulatory settings. \\
+\end{tabular}
+
+\subsubsection{Security Settings}
+\begin{tabular}{l|l|l}
+\textbf{Option} & \textbf{Parameter} & \textbf{Description} \\
+\hline 
+security$\star$ & none            & No authorization \\
+             & wep             & WEP key \\
+             & wpa-psk         & WPA with preshared key \\
+             & 8021x           & IEEE 802.1X authentication \\
+authorization$\star$ &            & \textbf{wep} \\
+             & open            & Only Open System Authentication \\
+             & shared          & Only Shared Key Authentication \\
+             & open+shared$\star$ & Both Open System and Shared Key Authentication
+                                 \\
+             &                 & \textbf{wpa-psk} \\
+             & psk             & WPA PSK \\
+             & psk2            & WPA2 PSK \\
+             & psk psk2        & WPA PSK and WPA2 PSK \\
+             &                 & \textbf{8021x} \\
+             & open            & Only Open System Authentication \\
+             & shared          & Only Shared Key Authentication \\
+             & wpa             & WPA with RADIUS \\
+             & wpa2            & WPA2 with RADIUS \\
+             & wpa wpa2        & WPA and WPA2 \\
+encryption$\star$ &            & \textbf{wep} \\
+             & -               & not needed, automatically by key size \\
+             &                 & \textbf{wpa-psk} \\
+             & tkip            & RC4 encryption \\
+             & aes             & AES encryption \\
+             & aes+tkip        & support both \\
+             &                 & \textbf{8021x} \\
+             & wep             & RC4 encryption (static) \\
+             & tkip            & RC4 encryption \\
+             & aes             & AES encryption \\
+             & aes+tkip        & support both \\
+eap-type     &                 & \textbf{8021x} \\
+             & tls$\star$      & Transport Layer Security \\
+             & ttls            & Tunnelled TLS \\
+             & peap            & Protected EAP \\
+             & leap            & Cisco Wireless \\
+key          &                 & \textbf{wep} \\
+             & \{1$\star$|2|3|4\}    & Select WEP key to use. \\
+key[1..4]    &                 & \textbf{wep} \\
+             & <String>        & WEP key.  The key must be 5, 13 or 16 bytes
+                                 long, or 10, 26, 32, or 64 hex digits long.  The encryption
+                                 algorithm is automatically selected based on the key size. key1 is
+                                 the key for WEP client mode. \\
+wpa-key      &                 & \textbf{wpa-psk} \\
+             & <String>        & Password to use with WPA/WPA2 PSK (at least 8,
+                                 up to 63 chars) \\
+wpa-gtk-rekey &                & \textbf{wpa-psk}, \textbf{8021x} \\
+             & <Int> (3600$\star$) & Rekeying interval in seconds. \\
+radius-ipaddr$\star$ &             & \textbf{8021x} \\
+             & <a.b.c.d>       & IP to connect. \\
+radius-port  &                 & \textbf{8021x} \\
+             & <Int> (1812$\star$) & RADIUS-Port no. to connect \\
+radius-key$\star$ &                & \textbf{8021x} \\
+             & <String>        & Shared Secret for connection to the Radius server \\
+\end{tabular}
+
+\subsubsection{MAC filter}
+\begin{tabular}{l|l|l}
+\textbf{Option} & \textbf{Parameter} & \textbf{Description} \\
+macmode      & {0|1|2}         & 0 - Disable MAC address matching. \\
+             &                 & 1 - Deny association to stations on the MAC list. \\
+             &                 & 2 - Allow association to stations on the MAC list. \\
+maclist      & <MAC1> ... <MACn> & List of space separated mac addresses to
+allow/deny according to ''macmode''. Addresses should be entered with colons,
+e.g.: \"00:02:2D:08:E2:1D 00:03:3E:05:E1:1B\". note that if you have more than one mac use quotes or only the first will be recognized. \\
+\end{tabular}
+
+\subsubsection{Wireless Distribution System (WDS) / Repeater / Bridge}
+\begin{tabular}{l|l|l}
+\texttt{Option} & \texttt{Parameter} & \texttt{Description} \\
+lazywds      & {0|1}           & Accept WDS connections from anyone \\
+wds          & <MAC1> ... <MACn> & List of WDS peer mac addresses (xx:xx:xx:xx:xx:xx, space separated) \\
+\end{tabular}
+
+\subsubsection{Miscellaneous}
+\begin{tabular}{l|l|l}
+\textbf{Option} & \textbf{Parameter} & \textbf{Description} \\
+channel      & {1-14}          & The wifi channel \\
+maxassoc     & {1-255}         & Maximum number of associated clients \\
+gmode        & {LegacyB| Auto$\star$| GOnly| BDeferred| Performance| LRS} & Set the 54g Mode \\
+frameburst   & {0$\star$|1}        & Disable/Enable frameburst mode. \\
+txpower      & {0-255|-1$\star$}   & Set the transmit power in dBm \\
+rate         & <Int> (-1$\star$)   & force a fixed rate \\
+             &                 & valid values for 802.11a are (6, 9, 12, 18, 24, 36, 48, 54) \\
+             &                 & valid values for 802.11b are (1, 2, 5.5, 11) \\
+             &                 & valid values for 802.11g are (1, 2, 5.5, 6, 9, 11, 12, 18, 24, 36, 48, 54) \\
+             &                 &-1 means automatically determine the best rate \\
+rts          & {0-2347}        & Set the RTS threshhold. \\
+frag         & {256-2346}      & Set the fragmentation threshhold. \\
+afterburner  & {0$\star$|1}        & Enable Afterburner capability \\
+isolate      & {0$\star$|1}        & Hide Clients from each other \\
+\end{tabular}
+
+\subsubsection{Examples}
+WLAN with WEP128
+\begin{Verbatim}
+iface eth1 inet static
+        address 192.168.10.1
+        netmask 255.255.255.0
+        wireless-type broadcom
+        wireless-country DE
+        wireless-mode ap
+        wireless-ssid FreeWRT
+        wireless-security wep
+        wireless-key1 11223344556677889900112233
+        wireless-channel 11
+\end{Verbatim}
+
+WLAN without encryption                       
+\begin{Verbatim}
+iface eth1 inet static
+        address 192.168.10.1
+        netmask 255.255.255.0
+        wireless-type broadcom
+        wireless-country DE
+        wireless-mode ap
+        wireless-ssid FreeWRT
+        wireless-security none
+        wireless-channel 11
+\end{Verbatim}
+                                                
+WLAN with WPA2 (AES)
+\begin{Verbatim}
+iface eth1 inet static
+        address 192.168.10.1
+        netmask 255.255.255.0
+        wireless-type broadcom
+        wireless-country DE
+        wireless-mode ap
+        wireless-ssid FreeWRT
+        wireless-security wpa-psk
+        wireless-authorization psk2
+        wireless-encryption aes
+        wireless-wpa-key 12345678
+        wireless-channel 11
+\end{Verbatim}
+
+If you want to do MAC filtering, add the following to the sample above:
+\begin{Verbatim}
+        wireless-macmode 2
+        wireless-mac 00:01:02:03:04:05 06:07:08:09:0a:0b
+\end{Verbatim}
+this enables the filter and defines the list to contain addresses that should be allowed.
+
+To enhance wireless performance, you can enable some flags like Broadcom's SpeedBooster. Normally, these flags are not dangerous:
+\begin{Verbatim}
+        wireless-gmode performance
+        wireless-frameburst 1
+        wireless-afterburner 1
+\end{Verbatim}
+
+WLAN client with WPA2 (AES) (''untested'')
+\begin{Verbatim}
+iface eth1 inet static
+        address 192.168.10.1
+        netmask 255.255.255.0
+        wireless-type broadcom
+        wireless-country DE
+        wireless-mode sta
+        wireless-ssid FreeWRT
+        wireless-security wpa-psk
+        wireless-authorization psk2
+        wireless-encryption aes
+        wireless-wpa-key 12345678
+\end{Verbatim}
+
+WLAN client with WEP128
+\begin{Verbatim}
+iface eth1 inet dhcp
+        wireless-type broadcom
+        wireless-country DE
+        wireless-mode sta
+        wireless-ssid FreeWRT
+        wireless-security wep
+        wireless-key1 11223344556677889900112233
+\end{Verbatim}
+
+Peer-to-Peer mode (no encryption, IP must be static)
+\begin{Verbatim}
+iface eth1 inet static
+        address 192.168.10.1
+        netmask 255.255.255.0
+        wireless-type broadcom
+        wireless-country DE
+        wireless-mode adhoc
+        wireless-ssid FreeWRT
+        wireless-security none
+        wireless-channel 11
+\end{Verbatim}
+
+\subsection{PPP}
+PPP comes in various flavours for different situations, the most commonly
+needed will likely be DSL and for WRT54G3G users UMTS. So there exists a
+hook-script that evaluates a "use-template" option and generates a ppp-peer.
+This way everything needed so far can be configured within the
+\texttt{interfaces} file.
+
+\subsubsection{DSL}
+\begin{Verbatim}
+auto ppp0
+iface ppp0 inet ppp
+        use-template dsl
+        provider t-online
+        ppp-username 0001201234563200123456#0001@t-online.de
+        ppp-password fooBARfoo
+        ppp-device eth0.1
+\end{Verbatim}
+
+Now your t-online DSL connection will be started on boot (\texttt{auto ppp0})
+and you can manually shut it down with \texttt{ifdown ppp0} or start it up with
+\texttt{ifup ppp0}.
+The template \texttt{dsl} will configure a typical PPPoE peer for you.
+
+\subsubsection{UMTS}
+Same footprint different template and some specific options. That is all that
+is needed for an UMTS connection to Vodafone as it can be seen in this example.
+\begin{Verbatim}
+iface ppp0 inet ppp
+        use-template    umts
+        provider        umts
+        #ppp-username   ""
+        #ppp-password   ""
+        ppp-device      /dev/noz0
+        umts-apn        web.vodafone.de
+        umts-pincode    1234
+        umts-mode       umts_first
+\end{Verbatim}
+As you can see: unneeded options like \texttt{ppp-username} or
+\texttt{ppp-password} can just be removed or commented out. Don't leave them
+without a value as that causes a failure in \texttt{ipup}. It does work if you
+give empty double quotes as value like "".
+
+Note that you have to set the correct APN, username and password for your provider!
+
+You may also remove the pin from your SIM-card and the configuration if you like.
+
+For Linksys WRT54G3G a package called \texttt{broadcom-watchbutton} will be
+installed, this is a small daemon that monitors the UMTS-button of the router
+and executes \texttt{ifup umts} or \texttt{ifdown umts} on a button press.
+You have to set \texttt{watchdog=YES} in /etc/rc.conf to have it start automatically.
+
+This is totally independent from the \texttt{auto umts} setting. Even if you
+start the connection on bootup you can shut it down again with a button press.
+
+\subsection{custom interface hooks}
+\subsubsection{per interface}
+You can execute various commands on interface startup or shutdown with special option:
+\begin{Verbatim}
+iface foobar inet static
+    [...]
+    pre-up <command>
+    up <command>
+    up <command>
+    down <command>
+    post-down <command>
+\end{Verbatim}
+
+You can give each option multiple times and their commands will be executed in given order.
+\begin{description}
+\item[pre-up] before the interface will be started
+\item[up] after the interface was started successfully
+\item[down] before the interface goes down
+\item[post-down] after the interface shut down
+\end{description}
+
+\subsubsection{general hooks}
+Additionally you can write scripts executed for each interface if you put them in
+\begin{itemize}
+\item \texttt{/etc/network/if-pre-up.d}
+\item \texttt{/etc/network/if-up.d}
+\item \texttt{/etc/network/if-down.d}
+\item \texttt{/etc/network/if-post-down.d}
+\end{itemize}
+Same semantics as above.
+