Changeset fa2f0db in freewrt for docs

Timestamp:

Jan 26, 2007, 3:23:33 PM (19 years ago)

Author:

Phil Sutter <n0-1@…>

Branches:

freewrt_1_0, freewrt_2_0

Children:

31d285b

Parents:

7d6779bf

Message:

some cleanup, set svn:ignore properties, so latex output crap doesn't get recognized

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

Location:

docs/handbook/user

Files:

• 00-allinone.tex (deleted)
• freewrt-handbook.txt (deleted)
• handbook.tex (modified) (3 diffs)

docs/handbook/user/handbook.tex

@@ -1 +1 @@
 \documentclass[12pt,a4paper,openany,smallheadings,
-headinclude,headsepline,final]{scrreprt} 
+headinclude,headsepline,final]{scrreprt}
 \usepackage[utf8]{inputenc}
-\usepackage{amsmath} 
-\usepackage{amsfonts} 
+\usepackage{amsmath}
+\usepackage{amsfonts}
 \usepackage{amssymb}
 \usepackage{caption2}
@@ -37 +37 @@
 pdfview=FitV,
 pdfstartview=FitV,
-pdfstartpage={1}, 
-pdfpagelayout=SinglePage, 
+pdfstartpage={1},
+pdfpagelayout=SinglePage,
 pdfpagemode=None,
 pdfkeywords={FreeWRT}]{hyperref}
@@ -92 +92 @@
 
 
-\include{00-allinone}
-%\include{01-Introduction}
-%\include{10-adk}
-%\include{20-installation}
-
-
-%\newpage
-%\bibliography{literatur}
-%\addcontentsline{toc}{chapter}{Literaturverzeichniss}
+
+\chapter{Introduction}
+
+Welcome to FreeWRT! This handbook covers the building, installation and usage
+aspects of the FreeWRT 1.0 Linux distribution.  FreeWRT is a portable, secure
+and functional Linux distribution for embedded systems. As FreeWRT is a source
+code distribution, it does not provide any pre-compiled firmware for embedded
+systems. The latest version of this document is always available at the
+FreeWRT website. If you have any comments, criticism or found some wrong
+description, please send us an e-mail to freewrt-handbook@freewrt.org, we are
+always happy about getting feedback to this document, and will try to update
+or correct the issues mentioned by you.
+
+The handbook is split into five distinct sections. Appliance Development Kit
+covers the building of FreeWRT firmware images. The second section, Installing
+FreeWRT, covers all aspects regarding the installation and deinstallation of
+FreeWRT firmware images. The third section is a detailed description of the
+startup process of FreeWRT.  The fourth section, Using FreeWRT, covers
+administrational tasks, such as network configuration, the FreeWRT
+configuration filesystem, package management and update mechanism. The last
+section helps troubleshooting problems and recovering a bad firmware
+installation. The appendix contains board specific information. For FreeWRT
+1.0 these are only Broadcom based embedded systems.
+
+The intended audience for this handbook are advanced users with basic
+knowledge about Linux, networking and software development. The reader should
+be aware of basic command line tools, the vi editor and a shell. FreeWRT does
+not contain any high level administration tools (e.g. web based
+administration) and is fully configured via command line.
+
+\section{Typographic Conventions}
+
+Examples starting with \# indicate a command that must be invoked as super
+user. You can use su to gain super user privilges.
+
+\begin{Verbatim}
+# fwcf commit
+\end{Verbatim}
+
+Examples starting with \$ indicate a command that can be invoked as a normal
+user.  The default user account on a freshly installed FreeWRT system is
+,,admin'', the password ,,FreeWRT''.
+
+\begin{Verbatim}
+$ cat /etc/banner
+\end{Verbatim}
+
+\chapter{Appliance Development Kit (ADK)}
+
+The ADK is the core of FreeWRT and contains all scripts and sources to create
+firmware images for every supported embedded system. FreeWRT 1.0 supports the
+following embedded systems:
+
+\begin{itemize}
+\item Asus WL500g
+\item Asus WL500g deluxe
+\item Asus WL500g premium
+\item Linksys WRT54G v1.0
+\item Linksys WRT54G v1.1
+\item Linksys WRT54G v2.0
+\item Linksys WRT54G v2.2
+\item Linksys WRT54G v3.0
+\item Linksys WRT54G v3.1
+\item Linksys WRT54G v4.0
+\item Linksys WRT54GS v1.0
+\item Linksys WRT54GS v1.1
+\item Linksys WRT54GS v4
+\item Linksys WRT54G3G
+\item Linksys WRT54GL
+\item Netgear WGT634u
+\end{itemize}
+
+In this release we only support the Linux 2.4 kernel. The ADK contains over
+600 software packages.
+
+\section{Prerequisites}
+
+Here is a list of all supported and tested host systems. The host system is
+needed to create a firmware for your embedded system.
+
+\begin{itemize}
+\item Debian GNU/Linux 3.1 or newer
+\item Gentoo Linux
+\item Ubuntu Dapper Drake or newer
+\item Fedora Core 4 or newer
+\item OpenBSD 3.9 or newer (partial support)\footnote{some addon packages does not compile}
+\item MirOS BSD (partial support)\footnote{some addon packages does not compile}
+\end{itemize}
+
+Please install the following software, which is needed to build a basic
+firmware image. If you choose more packages some more prerequisites might be
+needed. Buildroot will warn you about any software you need to install to
+compile a specific package.  Here is a list of the required software:
+
+\begin{itemize}
+\item gcc3 or higher
+\item g++
+\item binutils
+\item patch
+\item gzip
+\item bzip2
+\item unzip
+\item flex
+\item bison
+\item GNU make
+\item zlib (+headers)
+\item ncurses (+headers)
+\item (g)libc headers
+\item perl
+\end{itemize}
+
+The buildroot checks for the required versions of these tools in advance.
+
+To build FreeWRT with the ADK it is recommended to have an unprivileged
+user. Please \underline{never} build FreeWRT as super user. Because all necessary source
+tarballs are downloaded from the internet automatically, your host system
+needs a working internet connection.
+
+\section{Getting the source}
+
+Now go to a directory where you want to build the firmware. Depending on the
+features you select you will need about 2.5-5 GB free disk space. This
+includes the ADK itself, any source archives which will be downloaded
+and their extracted copies (for compiling).
+
+To get the initial FreeWRT 1.0 ADK try one of these commands:
+\begin{Verbatim}
+$ svn co http://www.freewrt.org/svn/branches/freewrt_1_0 freewrt
+$ svn co svn://www.freewrt.org/branches/freewrt_1_0 freewrt
+\end{Verbatim}
+
+After successfully downloading, enter the directory:
+
+\begin{Verbatim}
+$ cd freewrt
+\end{Verbatim}
+
+This directory will be referred to as the ADK root later on.
+
+\section{Some Theory First}
+
+Building a FreeWRT firmware image is just like building a new Linux kernel,
+but a little more complex. There is a ncurses-based configuration menu at the
+beginning, the changes made are saved into a file named ,,.config'' in the ADK
+root. The build is done by the various Makefiles, compiling and linking the
+sources together accordingly to the symbols defined in ,,.config''.
+
+Unlike kernel compilation, FreeWRT needs to be cross-compiled. This
+leads to special premises, as most of the tools need to be specially build.
+But no panic, FreeWRT will do this all for you. In fact, this is done at the
+second run of \texttt{make} (the first one opens the configuration), and
+therefore can be seen as part of the first firmware build.  For clarity
+though, we will discuss these two things separately.
+
+\section{Preparing the Build Process}
+
+After downloading the FreeWRT ADK, it's time to prepare the ADK for the
+building of firmware images (for explanations see the chapter above).
+
+\subsection{Creating A Configuration}
+The first step is to run \texttt{make}. After checking some prerequisites (see
+,,Troubleshooting'' below for aid in problems), a console based configuration
+menu should start. Theoretically no choices have to be made, but it's proven
+useful to at least:
+\begin{itemize}
+\item select a target (menu: ,,Embedded System'')
+\item select the root filesystem type (menu: ,,Target Firmware type'')
+\end{itemize}
+
+Then quit saving changes. If you forgot that, just run \texttt{make} again, redo
+your changes, then save.
+
+\subsection{Building ADK}
+
+Now that you have a first minimal configuration, it is time to build the toolchain
+for cross-compiling. To do this, just enter {{{make}}} again. The build starts
+downloading and compiling each needed part of the toolchain, and later continues
+with building the first firmware image. Later one can be taken as proof of a
+working ADK.
+
+Already experienced in compiling gcc? Then you know... If not, better be told
+that it takes \underline{really long} to finish. In the meantime I suggest reading the
+next chapter dealing with internals about cross-compiling.
+
+\section{Details Of Cross-Compiling}
+
+A cross-compile toolchain exists of a set of tools: a compiler, linker, assembler,
+debugger and a c library. A cross-compile toolchain runs on your host system and
+creates native binaries for your target system. A cross-compile toolchain is
+basically created in six steps:
+
+\begin{enumerate}
+\item Get and prepare the Kernel and C Library headers of your target system
+\item Compile the binutils package for your target
+\item Compile a static C compiler for your target
+\item Compile and install a C library for your target
+\item Compile and install a full C/C++ compiler
+\item Compile and install the GNU debugger
+\end{enumerate}
+
+The cross-compile toolchain is created in
+,,staging\_dir\_\$(cpu\_arch)''\footnote{f.e. mipsel, which stands for MIPS Little
+Endian)}.  All the tools running on the host, but used to create, analyze or debug
+for the target are kept in this directory. All addon headers and libraries
+are installed to this directory.
+
+If you want to compile a simple application without using the ADK, just use the
+compiler directly (f.e. compiling a MIPS Little Endian application):
+\begin{verbatim}
+./staging_dir_mipsel/bin/mipsel-linux-uclibc-gcc -o myapp myapp.c
+\end{verbatim}
+
+Check with ,,file'' if you got a MIPS binary:
+\begin{verbatim}
+$ file myapp
+myapp: ELF 32-bit LSB MIPS-I executable, MIPS, version 1 (SYSV), dynamically
+linked (uses shared libs), not stripped
+\end{verbatim}
+
+\section{Building A FreeWRT Firmware Image}
+
+Your local copy of the FreeWRT ADK should now be prepared for building firmware
+images. The next step is to do an extensive configuration for the image you
+want to create. To start the configuration menu, type ,,\texttt{make menuconfig}''.
+
+When selecting packages, \texttt{<*>} means it will be inserted into the firmware
+images and \texttt{<M>} means it will be build as an addon package which can be
+installed later at runtime.
+
+The target device and filesystem should already been chosen by you to the right
+value, if not you will have to issue a ,,\texttt{make clean}'' before actually
+building the firmware image. Otherwise things get messed up. A smooth
+rebuild is a missing feature in the current ADK. For the packages, if unsure, you
+can just select one of the package collections. After that, you can still manually
+check the choices made by the collection and correct them if appropriate. Do not
+forget to save your configuration when leaving!
+
+After leaving the menubased configuration, type ,,\texttt{make}'' again to build
+the new FreeWRT firmware image. Depending on your package selections and
+underlying hardware, this will take different amounts of time. For your spare time
+there is the following chapter giving some explanation about what is done at this
+point.
+
+\section{Firmware Build Process In Detail}
+
+Just like when building the ADK's toolchain, the sources for the selected
+packages are downloaded from the internet first, then build using the
+cross-compiler and libraries of the ADK.
+
+The detailed order of firmware image building is:
+
+\begin{itemize}
+\item compile the Linux kernel and all supported kernel modules
+\item compile all selected packages
+\item clean the target root directory
+\item install all packages to the target root directory
+\item create the root filesystem image
+\item create the firmware image (bootloader, kernel and root filesystem)
+\end{itemize}
+
+The result of the build process is created in the ,,bin'' directory.
+You will find a firmware image in the top level directory. Check the size of
+the bin-file to see if it is small enough to fit into flash memory of
+your embedded system. Furthermore there is a ,,package'' directory, which
+contains all base and addon packages.
+
+\section{Troubleshooting}
+This section deals with various tips for problems with the ADK installation.
+
+\subsection{Errors During Prerequisites Check}
+To re-issue the checks, use ,,make prereq''.
+
+\begin{itemize}
+\item GNU make 3.80 too old
+   On a Fedora Core 4 hostsystem the first you'll get is
+\begin{verbatim}
+   $ make
+   GNU make 3.80 too old.
+   Please install GNU make 3.81 or higher to continue.
+   You can override this check, see http://www.freewrt.org/faq for details.
+   It is suggested to upgrade your copy of bison to
+   GNU Bison 2.3 because of its bug fixes.
+   make: *** [.prereq_done] Error 1
+\end{verbatim}
+
+   it is quite a nice error that tells you to use more up to date software, but we can
+   anyhow give this hostsystem a try and tell make to ignore those errors/warnings:
+\begin{verbatim}
+     make prereq-noerror
+\end{verbatim}
+\end{itemize}
+
+\subsection{Compilation errors}
+
+If you encounter any compilation errors, then first try to reproduce the error.
+First update your ADK tree via ,,svn update'', to be sure that the error is not
+already fixed in the subversion repository. After that do a ,,make clean \&\&
+make'', to reproduce your problem.
+
+If you can reproduce the problem, please file a bug report. Please always
+report following information:
+\begin{itemize}
+\item Operating system type and version
+\item GCC and Binutils versions of your host system
+\item complete error message, not only the last 4 lines
+\end{itemize}
+
+\chapter{Installing FreeWRT Firmware Images}
+
+The FreeWRT ADK produces a single image holding both kernel and root
+filesystem. This image can be written into your hardware's builtin flash memory
+on serveral ways (ordered by needed skills, increasing downwards):
+\begin{itemize} % TODO: insert \ref's to jump to the appropriate section?
+\item via the original firmware's web interface
+\item via \texttt{mtd} when reflashing or migrating from another third party distribution
+\item via network using a TFTP client
+\end{itemize}
+
+\section{Flashing The Firmware}
+
+\subsection{Web Interface Method}
+The following text describes how to use the original firmware's web interface
+to flash FreeWRT. The object of demonstration is an Asus WL500gP, but this
+guide should fit more or less fine for other systems, too.
+
+If you flash a router from Linksys, we strongly suggest to use the popular
+\textbf{ping exploit} to allow recovery, if your image is broken or the flash
+process was interrupted by a power shortage.
+
+There are some things that you should have done previously:
+\begin{itemize}
+\item read the special documentation page about your hardware in our wiki, some
+      systems need special precaution before flashing
+\item a firmware image has to be built (matching the used hardware, of course)
+\item the router has to be powered on
+\item your computer needs to be connected to one of the LAN ports (using IP
+address 192.168.1.2)
+\end{itemize}
+
+\parbox{17em}{
+After preparation is complete, open your favourite browser and type
+\texttt{192.168.1.1} into the address bar. You should reach the web interface's
+startup page:
+}\hfill\parbox{20em}{\includegraphics[width=20em]{pics/asus-startup.png}} \\ [1em]
+\parbox{17em}{
+Then click \textit{System Setup}:
+}\hfill\parbox{20em}{\includegraphics[width=20em]{pics/asus-system_setup.png}} \\ [1em]
+\parbox{17em}{
+Then click \textit{Firmware Upgrade}, and enter the name of your firmware image
+into the appropriate field:
+}\hfill\parbox{20em}{\includegraphics[width=20em]{pics/asus-fw_upgrade.png}} \\ [1em]
+Finally click \textit{Upload}. As the whole process of writing the image to
+flash and rebooting (don't forget that it creates ssh hostkeys on first boot)
+takes quite long, better go and get a coffee or tea.
+
+When everything went good, you can login using ssh. The default username is
+\dq{}admin\dq{}. The default password for images created via WIB or ADK is
+\dq{}FreeWRT\dq{}. It is possible to change this password in the ADK, before image
+creation.
+
+\subsection{\texttt{mtd} -- The Flash Utility}
+
+For this method to work, you need to copy the file containing the firmware
+image to the router, preferably into /tmp, the memory filesystem should be
+big enough to hold the full image. If not, use wget to get the image
+via http or ftp and pipe the result into \texttt{mtd}.
+
+Then the image is written to flash using
+\texttt{mtd}, optionally giving additional options (see below).
+
+The \texttt{mtd} utility was written with simplicity and code size in mind.
+It's features were derived from the mtd-utils, %TODO: insert \ref to homepage
+combining the needed parts into a single small tool providing all the
+functionality necessary for FreeWRT, and leaving everything out that's not.
+
+\texttt{mtd} provides the following features:
+\begin{description}
+\item[unlock] some chips need unlocking before they can be written to
+\item[erase] this is a filesystem independent method to delete all contents on
+        the flash. Basically this is like \texttt{format} in MS--DOS.
+\item[write] this is generally the same functionality as using
+        \texttt{dd} or \texttt{rawrite}, but \texttt{mtd} takes care of the quirks
+        that have to be paid attention to for correctly handling the type of flash
+        in use
+\end{description}
+
+Further it can request your system to reboot. Some of the features mentioned here can
+also be combined, so it is e.g. possible to immediately reboot the system after
+the flash has been written.
+
+Mostly, similar to the sample usage shown in the help output should be all that has to be
+done to write the firmware to flash:
+\begin{Verbatim}
+# mtd -e linux -r write freewrt.bin linux &
+\end{Verbatim}
+Or via wget pipe:
+\begin{Verbatim}
+# wget -O - http://www.yourserver.com/freewrt.bin | mtd -e linux -r write - linux &
+\end{Verbatim}
+The parameters explained in detail: \\
+\begin{tabular}{l|l}
+-e linux & erase existing data in flash\\
+-r & trigger rebooting right after finishing work\\
+write & write the firmware image contained in the file given as next parameter
+                        to flash\\
+freewrt.bin & the actual image to write - ignore the suffix, it is detected at
+                                runtime\\
+linux & this is an abstract identifier for a certain partition in flash, so
+don't change this\\
+\& & put the process into background, to prevent accidentally stopping\\
+\end{tabular}
+
+\subsection{Installation using TFTP}
+
+All supported target devices are shipped with a builtin bootloader, comparable to
+the BIOS of x86--machines. This bootloader is used to bootstrap the system until
+it can boot a regular operating system. Besides the ability to load
+the executable code from flash, it can be received from another node in the
+local area network via the famous TFTP protocol.
+
+For doing this, there are two ways: \\
+\begin{itemize}
+\item the device acts as a client, asks the local dhcpd for a lease, the
+address of the next tftpd and the filename to download
+\item the device acts as a server, having a known IP address and waiting for
+any TFTP client to connect and send the file
+\end{itemize}
+
+Most of the hardware supported by FreeWRT 1.0 uses the second method.  Only the
+device Netgear WGT634u is using the first method, the bootloader provides a
+DHCP/TFTP client. Though this may be a little confusing to people being familiar
+with netboot technologies, it is definitely the easier way of doing it. Otherwise
+one had to setup both DHCP and TFTP servers and configure them right.
+
+The even quite simple task of sending the flash image to the target device is
+made even more easy by providing a little shell script for the job. Invocation
+is as follows:
+\begin{Verbatim}
+$ ./scripts/flash.sh firmware.bin [address]
+\end{Verbatim}
+The second Parameter \textit{address} is used to specify a different IP address
+of the target device than the default \textit{192.168.1.1}.
+
+\textbf{Beware:} do not rename the firmware image before flashing it using the
+script as the original name is parsed to guess what hardware is to be flashed.
+
+To actually being able to flash the device, it has to wait for a tftp
+connection when booting. To complicate installation of third vendor's firmware
+images and to improve bootup time, of course, this feature is disabled by
+default. The following list shows what has to be done for a certain device to
+get it to wait at boot: \\
+\begin{center}\begin{tabular}{l|l|l} % TODO: fill this table
+\textbf{Target Device} & \textbf{Action to be taken} & \textbf{Comments} \\
+\hline
+All supported Linksys models & Ping Exploit & nvram variable boot\_wait needs to be on \\
+All supported Asus models & Recovery mode & power off, push and hold the
+reset button, power on, power led is flashing\\
+\end{tabular}\end{center}
+
+\chapter{FreeWRT Administration}
+
+After the FreeWRT firmware image has been built by the ADK and later flashed
+onto the hardware, the resulting operating system has to be configured. 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.
+Be sure you have installed the package \texttt{bridge-utils}.
+
+\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 WL500gP 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),\texttt{eth2} (Asus WL500gP) or on Netgear WGT634u which has a Madwifi
+WLAN chip, 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}
+
+Mandatory options and default parameters are in bold font.
+
+\begin{tabular}{l|l|l}
+\textbf{Option} & \textbf{Parameter} & \textbf{Description} \\
+\hline
+\textbf{type}& broadcom        & Broadcom based card \\
+             & atheros         & Madwifi driver \\
+\textbf{mode}& 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 \\
+\textbf{ssid}& <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
+\textbf{security}& none            & No authorization \\
+             & wep             & WEP key \\
+             & wpa-psk         & WPA with preshared key \\
+             & 8021x           & IEEE 802.1X authentication \\
+\textbf{authorization}&            & \textbf{wep} \\
+             & open            & Only Open System Authentication \\
+             & shared          & Only Shared Key Authentication \\
+             & \textbf{open+shared}& 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 \\
+\textbf{encryption}&            & \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} \\
+             & \textbf{tls}    & Transport Layer Security \\
+             & ttls            & Tunnelled TLS \\
+             & peap            & Protected EAP \\
+             & leap            & Cisco Wireless \\
+key          &                 & \textbf{wep} \\
+             &\{\textbf{1}|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> (\textbf{3600}) & Rekeying interval in seconds. \\
+\textbf{radius-ipaddr}&             & \textbf{8021x} \\
+             & <a.b.c.d>       & IP to connect. \\
+radius-port  &                 & \textbf{8021x} \\
+             & <Int> (\textbf{1812}) & RADIUS-Port no. to connect \\
+\textbf{radius-key}&                & \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| \textbf{Auto}| GOnly| BDeferred| Performance| LRS\} & Set the 54g Mode \\
+frameburst   & \{\textbf{0}|1\}        & Disable/Enable frameburst mode. \\
+txpower      & \{0-255|\textbf{-1}\}   & Set the transmit power in dBm \\
+rate         & <Int> (\textbf{-1})   & 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  & \{\textbf{0}|1\}        & Enable Afterburner capability \\
+isolate      & \{\textbf{0}|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. Be sure you have installed the packages
+\texttt{kmod-ppp}, \texttt{ppp} and \texttt{ppp-mod-pppoe}.
+
+\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{watchbutton=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.
+
+\section{FWCF - FreeWRT Configuration Filesystem}
+
+FWCF is a separate flash partition for all changes made to the /etc directory.
+There is a small tool named \texttt{fwcf}, which is used to setup the system or
+to commit changes to the fwcf partition.
+
+On bootup the script \texttt{/sbin/mount\_root} is executed, which calls \dq{}fwcf
+setup\dq{} to setup /etc as memory filesystem and overlay the changes committet
+to the fwcf partition.
+
+If you change anything in /etc and like to keep the change, it is required to
+execute \dq{}fwcf commit\dq{}. This will compress all changed or new files in /etc
+and write the result into the fwcf partition.  The fwcf partition is 128 Kb in
+size. This size is not changeable at the moment.
+
+If you need more detailed information, please read the specification of FWCF,
+which can be found
+here\url{http://www.freewrt.org/trac/wiki/Documentation/Specs/FwCf}
+
+If you want to remove all your changes and start your configuration from scratch,
+use \dq{}fwcf erase\dq{}. This is also required if you switch between compression
+plugins. Right now LZO plugin is default.
+
+\section{IPKG - Packagemanagement}
+
+All software for FreeWRT is available as a IPKG package. IPKG is a package manager
+very similar to Debian's dpkg/apt-get utilities. It is specially designed for
+embedded systems and is widely used. The FreeWRT project use a special version,
+which is embedded to the busybox binary. Normally the command line tool
+\texttt{ipkg} is pre-installed.
+
+IPKG uses a configuration file similar to /etc/apt/sources.list, which
+contains a list of software repositories available via HTTP or FTP.
+The configuration file \texttt{/etc/ipkg.conf} contains the official
+FreeWRT 1.0 repository for your board and kernel version.
+
+To update the list of available packages execute following command as root:
+\begin{verbatim}
+# ipkg update
+\end{verbatim}
+
+This command requires a working internet connection, because it will fetch a
+package list from every repository declared in /etc/ipkg.conf.
+
+To install a new package use following command:
+\begin{verbatim}
+# ipkg install tcpdump
+\end{verbatim}
+
+This will install the package tcpdump and all dependencies onto the flash.
+Where the data is saved depends on the root filesystem you decided to use while
+installing FreeWRT. If you use jffs2 as root filesystem, then the package is
+installed on the big linux partition. If you use squashfs-overlay, then the
+package is installed on the mini-fo overlay filesystem which writes its data
+to the jffs2 data partition. If you use a squashfs-symlinks filesystem, then the
+package data is directly install into the jffs2 data partition, containing
+symlinks to the read-only squashfs partition.
+
+You can also remove packages, but this is only useful if you are using JFFS2
+as root filesystem:
+\begin{verbatim}
+# ipkg remove tcpdump
+\end{verbatim}
+
+This will not remove any dependencies, installed earlier. For example, libpcap
+is still installed after executing this command.
+On jffs2 root filesystem you should never remove any essential packages like
+busybox, fwcf or uclibc, otherwise you make the embedded system unusable.
+
+Nearly the same as for removing packages, counts for ipkg upgrade.  Please
+\textbf{never ever} use ipkg upgrade to update your embedded system.  This command
+is only useful to upgrade single packages on a jffs2 rootfilesystem or data
+partition.
+
+\section{Startup scripts}
+
+Some of the available packages containing software which start services at boot
+time. For that we provide simple startup scripts, which are installed into the
+directory \texttt{/etc/init.d}. See following example for
+the package \texttt{dnsmasq}, a combined dns and dhcp
+server daemon:
+
+\begin{verbatim}
+#!/bin/sh
+
+. /etc/rc.conf
+
+case $1 in
+autostart)
+        test x"${dns_dhcp:-NO}" = x"NO" && exit 0
+        exec $0 start
+        ;;
+start)
+        [ -f /etc/dnsmasq.conf ] || exit
+        /usr/sbin/dnsmasq
+        ;;
+stop)
+        killall dnsmasq
+        ;;
+restart)
+        $0 stop
+        $0 start
+        ;;
+*)
+        echo "Usage: $0 {start | stop | restart}"
+        ;;
+esac
+exit 0
+\end{verbatim}
+
+After installation the package postinst script will add all needed changes to the
+/etc directory. For example packages can add new user and groups, add new
+variables to /etc/rc.conf or just add new values to existing files as
+/etc/services. It is FreeWRT policy to do not start any services after
+installation or in case of a new boot. To start services on bootup you need to set
+\$servicename=YES in /etc/rc.conf and commit your changes via \dq{}fwcf
+commit\dq{}. For every policy exist a exception, we start all essential services
+by default, like ssh daemon, syslog and network initialisation.
+
+For some services you can control the startup behavior by modifying
+the services\_flags variable in /etc/rc.conf.
+
+For example the variable \$ssh\_opts is provided as argument to the dropbear
+ssh daemon to control its behavior.
+
+Having this policy helps you to configure your FreeWRT embedded system without
+shooting yourself in the foot. For example if you try to realize a firewall system
+and trying to set the rules in /etc/firewall.user, which is read by
+/etc/init.d/S45firewall, if the iptables package is installed. You can just
+reload the changed ruleset via /etc/init.d/S45firewall restart. If you managed
+to kick you out of the system, you can just reboot the system and you gain access
+again. As soon as your are ready with the firewall configuration and you decide
+to activate the firewall rules on bootup, you set \$firewall=YES in /etc/rc.conf,
+commit your changes via \dq{}fwcf commit\dq{} and reboot. Now the firewall
+rules will be activated on bootup.
+
+
+\chapter{Troubleshooting}
+
+\section{Failsafe Mode}
+
+Failsafe mode is very useful if you misconfigured your embedded system,
+so that you can not access it anymore. E.g. if you accidentially disabled
+secure shell or misconfigured the firewall, so that you can not login any
+more.
+
+When in failsafe mode, the device won't interpret any networking setup files.
+It stops even before the root filesystem gets mounted read--write, and fwcf is
+set up. It will just set the LAN interface up and give it the IP address
+192.168.1.1 and netmask 255.255.255.0. Then it will start a telnet daemon, so
+you get straight access (without depending on the installed SSH--daemon).
+
+\subsection{How It Works}
+
+To get FreeWRT into failsafe mode you need physical access to the device and
+the failsafe utility. The failsafe utility is built inside our ADK and
+is available in the directory bin/ after a successful build.
+
+If you just want to compile the tool and not a complete firmware image,
+use following command:
+
+\begin{Verbatim}
+$ make subdir=tools/failsafe install
+\end{Verbatim}
+
+For some operating systems we provide ready to go binaries of failsafe.
+Take a look at http://www.freewrt.org/downloads/tools/failsafe
+
+The tool just opens a network socket and waits for a special UDP packet
+from the embedded device. FreeWRT sends the UDP packet via the first
+recognized network interface (eth0).
+
+\subsection{Enabling Failsafe Mode}
+
+Connect your computer to the embedded system via direct or crossed network
+cable. Use the failsafe port (in most cases one of the LAN ports),
+see the device specific page for the exact network port.
+
+Configure your network interface to the IP address 192.168.1.2 with network
+mask 255.255.255.0. Now start the failsafe utility on your computer.
+
+\begin{Verbatim}
+$ ./failsafe
+\end{Verbatim}
+
+After that power on your embedded system and wait for the following message in
+your failsafe application running on your computer:
+
+\begin{Verbatim}
+Press reset now to enter Failsafe!
+\end{Verbatim}
+
+As soon as this message is displayed you should push the reset button of
+your embedded system. You have 2 seconds time to push the button. If you
+successfully enabled the failsafe mode, following message will be displayed:
+
+\begin{Verbatim}
+Entering Failsafe!
+\end{Verbatim}
+
+Now you should be able to login to your embedded system via a telnet
+application. Just use:
+
+\begin{Verbatim}
+$ telnet 192.168.1.1
+\end{Verbatim}
+
+\subsection{Repairing Your FreeWRT Configuration}
+
+If you want to repair your configuration, you first need to
+mount the root filesystem read--writeable. This is best done via:
+
+\begin{Verbatim}
+# mount_root
+\end{Verbatim}
+
+After that you need to enable the FreeWRT configuration filesystem:
+
+\begin{Verbatim}
+# fwcf setup
+\end{Verbatim}
+
+Now you can change files in /etc and repair your broken configuration.
+Do not forget to commit your changes afterwards.
+
+\begin{Verbatim}
+# fwcf commit
+\end{Verbatim}
+
+If you want to start over with the default /etc directory, just remove the fwcf
+partition content with following command:
+
+\begin{Verbatim}
+mtd erase fwcf
+\end{Verbatim}
+
+You can either use "reboot -f" or "-r" for mtd to reboot the system.
+
+\section{Serial Console}
+
+\section{JTAG}
 
 % Erstmal auskommentieren. Sind ja paar Seiten die erstmal keiner braucht