handbook/user/handbook.tex

\documentclass[12pt,a4paper,openany,smallheadings,headinclude,headsepline,final]{scrreprt}
%\usepackage{ucs} % Unicode support
\usepackage[utf8]{inputenc} % UTF-8 characters as input are allowed
%\usepackage{amsmath}
%\usepackage{amsfonts}
%\usepackage{amssymb}
%\usepackage{caption2}
\usepackage[english]{babel} % Sets the layout to English style
\usepackage{varioref} % Intelligent page references
%\usepackage{txfonts}
\usepackage[pdftex]{color} % Colour control for LaTeX documents
\usepackage[pdftex]{graphicx} % Enhanced support for graphics
%\usepackage{listings}
\usepackage{makeidx} % Standard LaTeX package for creating indexes
\usepackage{longtable} % Allow tables to flow over page boundaries
\usepackage[T1]{fontenc} % T1-fonts
\usepackage{fancyvrb} % Sophisticated verbatim text
\usepackage[a4paper,rmargin=2cm,lmargin=2cm,tmargin=2.5cm,bmargin=3.5cm]{geometry} % Flexible and complete interface to document dimensions
\usepackage{fixltx2e, mparhack} % Patches for LaTeX; A workaround for a LaTeX bug in marginpars
\usepackage[nofancy]{svninfo} % Typeset Subversion Keywords
\usepackage{float} % Improved interface for floating objects
\usepackage{hyperref} % Extensive support for hypertext in LaTeX


% marvosym macht Pfeil kaputt, also sichern
% line 28, /usr/share/texmf/tex/latex/marvosym/marvosym.sty
%\let\RescueRightarrow=\Rightarrow
%\usepackage{marvosym}
%\renewcommand{\Rightarrow}{\RescueRightarrow}

\definecolor{skyblue}{rgb}{0,0.3323,0.5720}
\restylefloat{figure}
\hypersetup{
        colorlinks=true,anchorcolor=red,
        breaklinks=true,linkcolor=blue,urlcolor=red,
        citecolor=skyblue,
        pdfauthor={The FreeWRT Team},
        pdftitle={FreeWRT User Handbook},
        pdfcreator={tetex and VIM},
        pdfsubject={Open Source},
        pdfview=FitV,
        pdfstartview=FitV,
        pdfstartpage={1},
        pdfpagelayout=SinglePage,
        pdfpagemode=None,
        pdfkeywords={FreeWRT}
}
\fvset{fontsize=\small, frame=single} % fancyvrb: set small font size and enable frames
%\usepackage{cancel}
%\usepackage[final, activate, verbose=true]{microtype}
%\usepackage{ngerman}
%\usepackage{bookman}
%\usepackage[a4paper,twoside,rmargin=2cm,lmargin=2cm,tmargin=2.5cm]{geometry}
%\usepackage[a4paper,rmargin=2cm,lmargin=2cm,tmargin=2.5cm,bmargin=3.5cm]{geometry}
%\usepackage{ncntrsbk}
%\usepackage{float}
%\restylefloat{figure}
%\bibliographystyle{alphadin}
%\bibliographystyle{alpha}

% Generate index in preamble
\makeindex

\begin{document}
\svnInfo $Id$
\setlength{\marginparwidth}{10mm}

\include{cover}

\renewcommand{\thepage}{\roman{page}}
\tableofcontents
%Set Arabic Numbering 1,2,3,...
% Clear needed to renumber from the right position
\cleardoublepage
\renewcommand{\thepage}{\arabic{page}}
%Reset Counter
%\setcounter{page}{1}

% Set marks where it should Change
\renewcommand{\chaptermark}[1]{%
\markboth{\large \thechapter.\ \normalsize \scshape #1}{}}
\renewcommand{\sectionmark}[1]{\markright{\thesection.\ \scshape #1}}


% Create some new commands for designing the text
% applications
\newcommand{\app}[1]{%
        \textsf{\textit{#1}}}
% terminology, vendor or product names
\newcommand{\term}[1]{%
        \textsc{#1}}
% filenames and directories
\newcommand{\file}[1]{%
        \textsf{#1}}
% user input
\newcommand{\command}[1]{%
        \texttt{\textbf{#1}}}
% example code, output of applications
\newcommand{\code}[1]{%
        \texttt{#1}}
% emphasized text (nicer than \emph{})
\newcommand{\strong}[1]{%
        \textbf{#1}}


\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
\href{mailto:freewrt-handbook@freewrt.org}{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 FreeWRT User handbook is split into several distinct chapters.
\nameref{ch:ADK} covers the building of FreeWRT firmware images.  In
\autoref{ch:installing}, \nameref{ch:installing}, all aspects regarding the
installation and deinstallation of FreeWRT firmware images are covered.  The
next chapter, \nameref{ch:administration}, covers administrational tasks, such
as network configuration, the FreeWRT configuration filesystem, package
management and update mechanism. The last chapter,
\nameref{ch:troubleshooting}, 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 \code{\#} indicate a command that must be invoked as
super user. You can use \command{su} to gain super user privileges.

\begin{Verbatim}[label=example for a command line with super user privileges]
# fwcf commit
\end{Verbatim}

Examples starting with \code{\$} indicate a command that can be invoked as a
normal user.  The default user account on a freshly installed FreeWRT system is
"\code{admin}", the password "\code{FreeWRT}".

\begin{Verbatim}[label=example for a command line as non-privileged user]
$ cat /etc/banner
\end{Verbatim}

%\chapter{Web Interface Builder (WIB)}\label{ch:WIB}
%
%FIXME It is named later in the text, but not explained what it is.  Probably
%this chapter can be joined with the chapter about ADK

\chapter{Appliance Development Kit (ADK)}\label{ch: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 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.

The list of supported GNU/Linux build systems is not an exclusive one, these
are just the ones tested and verified. The other millions of linux
distributions are very likely to work, too.

\begin{itemize}
        \item Debian GNU/Linux
        \item Gentoo Linux
        \item OpenSuSE
        \item Ubuntu GNU/Linux
        \item Fedora Core
        \item OpenBSD (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. The ADK host checks 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 ADK scripts will check 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 latest stable FreeWRT ADK try one of these commands:
\begin{Verbatim}[label=Check out the 1.0-branch of FreeWRT ADK via HTTP protocol]
$ svn co http://www.freewrt.org/svn/tags/freewrt_1_0_x freewrt
\end{Verbatim}
\begin{Verbatim}[label=Check out the 1.0-branch of FreeWRT ADK via subversion protocol]
$ svn co svn://www.freewrt.org/itags/freewrt_1_0_x freewrt
\end{Verbatim}

The value $x$ is a place holder for the latest minor release number.  Take a
look at our project page to find out which minor release number is the latest
one.

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 \app{ncurses}-based configuration menu at the
beginning, the changes made are saved into a file named \file{.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 \file{.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 \command{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 \command{make}. After checking some prerequisites (see
\nameref{ch: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: \code{Embedded System})
        \item select the root filesystem type (menu: \code{Target Firmware type})
\end{itemize}

Then quit saving changes. If you forgot that, just run \command{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 \command{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 \app{gcc}? Then you know\dots 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
\file{staging\_dir\_\$(cpu\_arch)}\footnote{e.g. 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 (e.g. compiling a MIPS Little Endian application):
\begin{Verbatim}[label=compile a simple application with the cross-compiler]
./staging_dir_mipsel/bin/mipsel-linux-uclibc-gcc -o myapp myapp.c
\end{Verbatim}

Check with the tool \app{file} if you got a MIPS binary:
\begin{Verbatim}[label=check the binary with \app{file}]
$ 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 \command{make
menuconfig}.

When selecting packages, \code{<*>} means it will be inserted into the firmware
images and \code{<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 \command{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 \command{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 built 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 directory \file{bin/}.  You
will find a firmware image in the top level directory. Check the size of the
binary image file to see if it is small enough to fit into flash memory of your
embedded system. Furthermore there is a directory \file{package/}, which
contains all base and add--on 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 \command{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}[label=error message with too old GNU make]
   $ 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 running \command{make prereq-noerror}.
\end{itemize}

\subsection{Compilation errors}

If you encounter any compilation errors, then first try to reproduce the error.
First update your ADK tree via \command{svn update}, to be sure that the error
is not already fixed in the subversion repository. After that do a
\command{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}\label{ch:installing}

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}
        \item via the original firmware's web interface
        (\autoref{sec:webinterface})
        \item via \texttt{mtd} when reflashing or migrating from another third
        party distribution (\autoref{sec:mtd})
        \item via network using a TFTP client (\autoref{sec:tftp})
\end{itemize}

\section{Flashing The Firmware}

\subsection{Web Interface Method}\label{sec:webinterface}

The following text describes how to use the original firmware's web interface
to flash FreeWRT. The object of demonstration is an \term{Asus WL500gP}, but
this guide should fit more or less fine for other systems, too.

If you flash a router from \term{Linksys}, we strongly suggest to use the
popular \term{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 \file{192.168.1.2})
\end{itemize}

\parbox{17em}{
After preparation is complete, open your favourite browser and type
\command{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 on \code{System Setup}:
}\hfill\parbox{20em}{
        \includegraphics[width=20em]{pics/asus-system_setup.png}
} \\ [1em]
\parbox{17em}{
In the new menu click on \code{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 on \code{Upload}. As the whole process of writing the image to
flash and rebooting (don't forget that it creates \app{ssh} hostkeys on first
boot) takes quite long (yes, a couple of minutes). Better go and get a coffee
or tea.

When everything went well, you can login using \app{ssh}. The default username
is "\code{admin}". The default password for images created via WIB or ADK is
"\code{FreeWRT}". It is possible to change this password in the ADK, before
image creation.

\subsection{\texttt{mtd} -- The Flash Utility}\label{sec:mtd}

For this method to work, you need to copy the file containing the firmware
image to the router, preferably into \file{/tmp/}, the memory filesystem should
be big enough to hold the full image. If not, use \app{wget} to get the image
via http or ftp and pipe the result into \app{mtd}.

Then the image is written to flash using \app{mtd}, optionally giving
additional options (see below).

The \app{mtd} utility was written with simplicity and code size in mind.  It's
features were derived from the
\href{http://sources.redhat.com/jffs2/}{\app{mtd-utils}}, combining the needed
parts into a single small tool providing all the functionality necessary for
FreeWRT, and leaving everything out that's not.

\app{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 \app{format} in
                MS--DOS.
        \item[write] this is generally the same functionality as using \app{dd}
                or \app{rawrite}, but \app{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}[label=write a previously downloaded new firmware-file into flash]
# mtd -e linux -r write freewrt.bin linux &
\end{Verbatim}
Or via wget pipe:
\begin{Verbatim}[label=download and write a new firmware-file into flash]
# wget -O - http://www.yourserver.com/freewrt.bin | mtd -e linux -r write - linux &
\end{Verbatim}
The parameters explained in detail:
\begin{description}
        \item[\command{-e linux}] erase existing data in flash
        \item[\command{-r}] trigger rebooting right after finishing work
        \item[\command{write}] write the firmware image contained in the file
                given as next parameter to flash
        \item[\command{freewrt.bin}] the actual image to write -- ignore the
                suffix, it is detected at runtime
        \item[\command{linux}] this is an abstract identifier for a certain
                partition in flash, so don't change this
        \item[\command{\&}] put the process into background, to prevent
                accidentally stopping
\end{description}

\subsection{Installation using TFTP}\label{sec:tftp}

All supported target devices are shipped with a builtin bootloader, comparable
to the BIOS of \term{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 \app{dhcpd} for a
                lease, the address of the next \app{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 \term{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}[label=sending the new firmware via TFTP]
$ ./scripts/flash.sh firmware.bin [address]
\end{Verbatim}
The second Parameter \code{address} is used to specify a different IP address
of the target device than the default \file{192.168.1.1}.

\strong{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|p{7cm}} % TODO: fill this table
\strong{Target Device} & \strong{Action to be taken} & \strong{Comments} \\
\hline
All supported Linksys models & Ping Exploit & nvram variable \code{boot\_wait}
                                              needs to be on \\
All supported Asus models & Recovery mode & power off $\rightarrow$ push and
                                            hold the reset button $\rightarrow$
                                            power on $\rightarrow$ power led is
                                            flashing \\
\end{tabular}
\end{center}

\chapter{FreeWRT Administration}\label{ch: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}

<<<<<<< .mine
The device names for real network interfaces in Linux are named \code{ethx} (\code{x} is
\code{0--9}). If the device has a switch, the different ports are separated via VLAN
technology. The vlan interfaces are named \code{ethx.y}.  The network configuration in
FreeWRT is managed via \app{Busybox}'s \app{ifupdown} implementation. \app{Busybox}'s builtin \app{ip}
command configures the network interfaces. There is no \app{ifconfig} or \app{route}, you can activate
it in the ADK menue, if you like. 

=======
The device names for real network interfaces in Linux are named \code{ethx}
(\code{x} is \code{0--9}). If the device has a switch, the different ports are
separated via VLAN technology. The vlan interfaces are named \code{ethx.y}.
The network configuration in FreeWRT is managed via \app{Busybox}'s
\app{ifupdown} implementation. \app{Busybox}'s builtin \app{ip} command
configures the network interfaces. There is no \app{ifconfig} or \app{route}.
>>>>>>> .r2546
To show all configured network interfaces use:
\begin{Verbatim}[label=show IP address]
$ ip addr show
\end{Verbatim}
To show the kernel routing table use:
\begin{Verbatim}[label=show routing table]
$ ip route show
\end{Verbatim}

All available network settings can be found in \file{/etc/network/interfaces}
which has the common form:
\begin{Verbatim}[label=common form of \file{/etc/network/interfaces}]
auto <iface-name>
iface <iface-name> inet <method>
  <option-x> <value>
  <option-y> <value>
  <option-z> <value>
\end{Verbatim}

<<<<<<< .mine
<b>ATTENTION: Be sure you have no whitespaces at the and of any value!</b>

\code{auto <iface-name>} is optional and, if set, tells the \app{ifup} script to
start this interface automatically on bootup.
=======
\code{auto <iface-name>} is optional and, if set, tells the \app{ifup} script
to start this interface automatically on bootup.
>>>>>>> .r2546

Each interface needs a unique name which, depending on the method, represents
either a physical interface or a logical interface name like \code{eth0.1} for
a physical VLAN or \code{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
                \code{iface-name}
        \item[manual] don't configure the interface but start \code{pre-up.d}
                hook scripts
        \item[ppp] run \code{pon <provider>} where \code{<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=\file{/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 \code{eth0.0} on ports 1 and 2,
\code{eth0.1} on port 3 and 4 and \code{eth0.2} on port 0.


If you need to do some advanced settings, because you have for example a
powerful switch with a VLAN trunking port connected to one of your switch
ports, the configuration would look like this:

\begin{Verbatim}[label=\file{/etc/network/interfaces}]
auto eth0.1
iface eth0.1 inet static
    switch-ports 2 3 4 5*
    address 192.168.1.1
    netmask 255.255.255.0

auto eth0.2
iface eth0.2 inet static
    switch-ports 1t 5
    address 10.2.0.1
    netmask 255.255.255.0
    broadcast +

auto eth0.3
iface eth0.3 inet static
    switch-ports 1t 5
    address 10.3.0.1
    netmask 255.255.255.0
    broadcast +

auto eth0.4
iface eth0.4 inet static
    switch-ports 1t 5
    address 10.4.0.1
    netmask 255.255.255.0
    broadcast +

\end{Verbatim}

This configures four VLAN interfaces, \code{eth0.1} on physical ports 2, 3 and
4.  The interfaces \code{eth0.2}, \code{eth0.3} and \code{eth0.4} are three
different networks with VLAN ID 2--4. The physical port 1 needs to be connected
to a VLAN trunking port on a switch with knows the same VLAN IDs.


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[broadcast] broadcast address --- only required for legacy
                applications (if using \code{+}, it will be calculated
                automatically by the kernel)
        \item[gateway] an IP address added as default gateway if present
        \item[mac-address] if you need to change your MAC address (required for
                some DSL providers)
\end{description}

\subsection{DHCP}
That's just as simple as:
\begin{Verbatim}[label=\file{/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{WLAN}
A router containing a WLAN interface has an additional ethernet device
representing it. On Broad\-com-based hardware it is typically \code{eth1}
(\term{Linksys}),\code{eth2} (\term{Asus WL500gP}) or on \term{Netgear WGT634u}
which has a Madwifi WLAN chip, it is \code{ath0}, \code{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|p{10cm}}
\strong{Option} & \strong{Parameter} & \strong{Description} \\
\hline\hline
\code{\strong{type}} & \code{broadcom} & Broadcom based card \\
                     & \code{atheros}  & Madwifi driver \\
\hline
\code{\strong{mode}} & \code{ap}       & Access point mode \\
                     & \code{sta}      & Client mode \\
                     & \code{adhoc}    & Ad-Hoc mode \\
                     & \code{wds}      & WDS point-to-point link over wireless\\
                     & \code{monitor}  & The node acts as a passive monitor and
                                         only receives packets \\
\hline
\code{\strong{ssid}} & \code{<String>} & Set the SSID (Network Name) \\
\hline
\code{country}       & \code{\{ALL|DE|JP|US|\ldots\}} & The country code used
                                                        to determine the
                                                        regulatory settings. \\
\hline
\end{tabular}

\subsubsection{Security Settings}
\begin{longtable}{l|l|p{10cm}}
\strong{Option} & \strong{Parameter} & \strong{Description} \\
\hline\hline
\code{\strong{security}} & \code{none}    & No authorization \\
                         & \code{wep}     & WEP key \\
                         & \code{wpa-psk} & WPA with preshared key \\
                         & \code{8021x}   & IEEE 802.1X authentication \\
\hline
\code{\strong{authorization}} &                 & \strong{wpa-psk} \\
                              & \code{psk}      & WPA PSK \\
                              & \code{psk2}     & WPA2 PSK \\
                              & \code{psk psk2} & WPA PSK and WPA2 PSK \\
                              &                 & \strong{8021x} \\
                              & \code{wpa}      & WPA with RADIUS \\
                              & \code{wpa2}     & WPA2 with RADIUS \\
                              & \code{wpa wpa2} & WPA and WPA2 \\
\hline
\code{\strong{encryption}} &                 & \strong{wep} \\
                           & ---             & not needed, automatically by key size \\
                           &                 & \strong{wpa-psk} \\
                           & \code{tkip}     & RC4 encryption \\
                           & \code{aes}      & AES encryption \\
                           & \code{aes+tkip} & support both \\
                           &                 & \strong{8021x} \\
                           & \code{wep}      & RC4 encryption (static) \\
                           & \code{tkip}     & RC4 encryption \\
                           & \code{aes}      & AES encryption \\
                           & \code{aes+tkip} & support both \\
\hline
\code{eap-type} &                     & \strong{8021x} \\
                & \code{\strong{tls}} & Transport Layer Security \\
                & \code{ttls}         & Tunnelled TLS \\
                & \code{peap}         & Protected EAP \\
                & \code{leap}         & Cisco Wireless \\
\hline
\code{key} &                            & \strong{wep} \\
           &\code{\{\strong{1}|2|3|4\}} & Select WEP key to use. \\
\hline
\code{key[1..4]} &                 & \strong{wep} \\
                 & \code{<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.
                                     \\
\hline
\code{wpa-key} &          & \strong{wpa-psk} \\
               & <String> & Password to use with WPA/WPA2 PSK (at least 8, up
                            to 63 chars) \\
\hline
\code{wpa-gtk-rekey} &                              & \strong{wpa-psk},
                                                      \strong{8021x} \\
                     & \code{<Int>} (\strong{3600}) & Rekeying interval in
                                                      seconds. \\
\hline
\code{\strong{radius-ipaddr}} &                  & \strong{8021x} \\
                              & \code{<a.b.c.d>} & IP to connect. \\
\hline
\code{radius-port} &                              & \strong{8021x} \\
                   & \code{<Int>} (\strong{1812}) & RADIUS-Port no. to connect
                                                    \\
\hline
\strong{radius-key} &                 & \strong{8021x} \\
                    & \code{<String>} & Shared Secret for connection to the
                                        Radius server \\
\hline
\end{longtable}

\subsubsection{MAC filter}
\begin{tabular}{l|l|p{10cm}}
\strong{Option} & \strong{Parameter} & \strong{Description} \\
\hline\hline
\code{macmode} & \code{\{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. \\
\hline
\code{maclist} & \code{<MAC1> \ldots <MACn>} & List of space separated mac
                                               addresses to allow/deny
                                               according to \code{macmode}.
                                               Addresses should be entered with
                                               colons, e.g.:
                                               "\code{00:02:2D:08:E2:1D
                                               00:03:3E:05:E1:1B}"\\
\end{tabular}

\subsubsection{Wireless Distribution System (WDS)}
\begin{tabular}{l|l|p{10cm}}
\strong{Option}       & \strong{Parameter}          & \strong{Description} \\
\hline\hline
\code{lazywds}        & \code{\{0|1\}}              & Accept WDS connections
                                                      from anyone \\
\hline
\code{wds-bridge}     & \code{br\{X\}}              & Add WDS peers to bridge
                                                      brX \\
\hline
\code{wds-security}   & \code{\{wpa-psk\}}          & secure the wds bridge
                                                      with WPA (optional)\\
\hline
\code{wds-encryption} & \code{\{aes|tkip\}}         & Use AES or TKIP as
                                                      cipher\\
\hline
\code{wds-wpa-key}    & \code{<String>}             & Password to use with WPA
                                                      PSK (at least 8, up to 63
                                                      chars) \\
\hline
\code{wds}            & \code{<MAC1> \ldots <MACn>} & List of WDS peer mac
                                                      addresses
                                                      (\code{xx:xx:xx:xx:xx:xx},
                                                      space separated) \\
\hline
\end{tabular}

\subsubsection{Miscellaneous}
\begin{longtable}{l|l|p{10cm}}
\strong{Option} & \strong{Parameter} & \strong{Description} \\
\hline\hline
\code{channel}  & \code{\{1--14\}}  & The wifi channel \\
\hline
\code{maxassoc} & \code{\{1--255\}} & Maximum number of associated clients \\
\hline
% TODO: add descriptions to the different gmode settings
\code{gmode} &                      & Set the 54g Mode \\
             & \code{\strong{Auto}} & default \\
             & \code{LegacyB}       & \\
             & \code{GOnly}         & \\
             & \code{BDeferred}     & \\
             & \code{Performance}   & \\
             & \code{LRS}           & \\
\hline
\code{frameburst} & \code{\{\strong{0}|1\}} & Disable/Enable frameburst mode. \\
\hline
\code{txpower} & \code{\{0--255|\strong{$-1$}\}} & Set the transmit power in dBm \\
\hline
\code{rate} & \code{<Int> (\strong{$-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 \\
\hline
\code{rts}          & \code{\{0-2347\}}       & Set the RTS threshhold. \\
\hline
\code{frag}         & \code{\{256-2346\}}     & Set the fragmentation
                                                threshhold. \\
\hline
\code{afterburner}  & \code{\{\strong{0}|1\}} & Enable Afterburner capability
                                                \\
\hline
\code{isolate}      & \code{\{\strong{0}|1\}} & Hide Clients from each other \\
\hline
\code{bridge-if}    & \code{\{br0..brX\}}     & The bridge interface (optional)
                                                \\
\hline
\end{longtable}

\subsubsection{Examples for wireless configuration}

\paragraph{WLAN with WPA1/WPA2 AES+TKIP}

This combination works with any kind of WPA client implementation.

\begin{Verbatim}[label=\file{/etc/network/interfaces}]
auto eth1
iface eth1 inet static
        address 192.168.10.1
        netmask 255.255.255.0
        broadcast +
        wireless-type broadcom
        wireless-country DE
        wireless-mode ap
        wireless-ssid FreeWRT
        wireless-security wpa-psk
        wireless-authorization psk psk2
        wireless-encryption aes+tkip
        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}[label=\file{/etc/network/interfaces}]
        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.

\paragraph{WLAN without encryption}

If you already use VPN to secure your connection, you can just use an unencrypted setup
and setup the firewall on your embedded device.

\begin{Verbatim}[label=\file{/etc/network/interfaces}]
auto eth1
iface eth1 inet static
        address 192.168.10.1
        netmask 255.255.255.0
        broadcast +
        wireless-type broadcom
        wireless-country DE
        wireless-mode ap
        wireless-ssid FreeWRT
        wireless-security none
        wireless-channel 11
\end{Verbatim}

\paragraph{WLAN client with WPA2 (AES)}

This can only be used in routing mode, you can not bridge it with LAN or WAN interfaces.

\begin{Verbatim}[label=\file{/etc/network/interfaces}]
auto eth1
iface eth1 inet static
        address 192.168.10.1
        netmask 255.255.255.0
        broadcast +
        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 with WDS nodes, the WDS nodes need to have the same
SSID, channel and encryption parameters. The WDS connection is separetely
secured via WPA1 and AES. WPA2 for WDS connection security is \_not\_ working.

WDS node 1 (MAC of Wireless \code{06:05:04:03:02:01})
\begin{Verbatim}[label=\file{/etc/network/interfaces}]
auto br0
iface br0 inet static
        bridge-ifaces eth1
        address 192.168.10.1
        netmask 255.255.255.0
        broadcast +
        wireless-type broadcom
        wireless-country DE
        wireless-mode wds
        wireless-ssid FreeWRT-WDS
        wireless-security wpa-psk
        wireless-authorization psk psk2
        wireless-encryption aes+tkip
        wireless-wpa-key apkey
        wireless-lazywds 1
        wireless-wds-security wpa-psk
        wireless-wds-encryption aes
        wireless-wds-wpa-key wdskey
        wireless-wds 01:02:03:04:05:06
        wireless-wds-bridge br0
\end{Verbatim}
WDS node 2 (MAC of Wireless \code{01:02:03:04:05:06})
\begin{Verbatim}[label=\file{/etc/network/interfaces}]
auto br0
iface br0 inet static
        bridge-ifaces eth1
        address 192.168.10.2
        netmask 255.255.255.0
        broadcast +
        wireless-type broadcom
        wireless-country DE
        wireless-mode wds
        wireless-ssid FreeWRT-WDS
        wireless-security wpa-psk
        wireless-authorization psk psk2
        wireless-encryption aes+tkip
        wireless-wpa-key apkey
        wireless-lazywds 1
        wireless-wds-security wpa-psk
        wireless-wds-encryption aes
        wireless-wds-wpa-key wdskey
        wireless-wds 06:05:04:03:02:01
        wireless-wds-bridge br0
\end{Verbatim}

\paragraph{Peer-to-Peer/AdHoc mode (no encryption, IP must be static)}
\begin{Verbatim}[label=\file{/etc/network/interfaces}]
auto eth1
iface eth1 inet static
        address 192.168.10.1
        netmask 255.255.255.0
        broadcast +
        wireless-type broadcom
        wireless-country DE
        wireless-mode adhoc
        wireless-ssid FreeWRT
        wireless-security none
        wireless-channel 11
\end{Verbatim}

\subsection{Bridging}

This is mostly needed to combine LAN and WLAN to a homogeneous network.
Be sure you have installed the package \app{bridge-utils}.
See the example for a bridging setup, WLAN is secured via WPA/WPA2.

\begin{Verbatim}[label=\file{/etc/network/interfaces}]
auto eth0.0
iface eth0.0 inet manual
        switch-ports 1 2 3 4 5*

auto eth1
iface eth1 inet manual
        wireless-type broadcom                                     
        wireless-country DE                                               
        wireless-mode ap                                                  
        wireless-ssid FreeWRT                                             
        wireless-channel 11                                               
        wireless-security wpa-psk                                         
        wireless-authorization psk psk2                                   
        wireless-encryption aes+tkip                                      
        wireless-wpa-key MyWlanSecret                
        wireless-bridge-if br0

auto br0
iface br0 inet static
        bridge-ifaces eth0.0 eth1
        address 192.168.1.1
        netmask 255.255.255.0
        broadcast +
\end{Verbatim}

This creates a new bridging interface \code{br0} which combines the VLAN
interface \code{eth0.0} (representing the LAN-ports 1--4) and the WLAN interface
\code{eth1} (on some devices like \term{Asus WL500gP} this might be \code{eth2}).
The bridge interface needs always be the last one, otherwise it can not find
the interfaces in \code{bridge-ifaces}.

\subsection{PPP}

PPP comes in various flavours for different situations, the most commonly
needed will likely be DSL and for \term{WRT54G3G} users UMTS. So there exists a
hook-script that evaluates a \code{use-template} option and generates a
ppp-peer.  This way everything needed so far can be configured within the
\code{interfaces} file. Be sure you have installed the packages \app{kmod-ppp},
\app{ppp} and \app{ppp-mod-pppoe}. For providers using PPTP for authentication,
instead of PPPoE, you need to install \app{pptp}.

\subsubsection{DSL with PPPoE}
\begin{Verbatim}[label=\file{/etc/network/interfaces}]
auto ppp0
iface ppp0 inet ppp
        use-template dsl
        provider foobar
        ppp-username 0001201234563200123456#0001@bar.de
        ppp-password bar
        ppp-device eth0.1
\end{Verbatim}

Now your DSL connection will be started on boot (\code{auto ppp0}) and you can
manually shut it down with \command{ifdown ppp0} or start it up with
\command{ifup ppp0}.  The template \code{dsl} will configure a typical PPPoE
peer for you.

\subsubsection{DSL with PPTP}
\begin{Verbatim}[label=\file{/etc/network/interfaces}]
auto ppp0
iface ppp0 inet ppp
        use-template pptp
        provider foobar
        ppp-username foo
        ppp-password bar
        ppp-modemip 10.0.0.1
        ppp-mtu 1480
        ppp-device eth0.1
\end{Verbatim}

Now your DSL connection will be started on boot (\code{auto ppp0}) and you can
manually shut it down with \command{ifdown ppp0} or start it up with
\command{ifup ppp0}.  The template \code{pptp} will configure a typical PPTP
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}[label=\file{/etc/network/interfaces}]
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 \code{ppp-username} or
\code{ppp-password} can just be removed or commented out. Don't leave them
without a value as that causes a failure in \app{ipup}. It does work if you
give empty double quotes as value like \code{""}.

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 \term{Linksys WRT54G3G} a package called \app{broadcom-watchbutton} will be
installed, this is a small daemon that monitors the UMTS-button of the router
and executes \command{ifup umts} or \command{ifdown umts} on a button press.
You have to set \code{watchbutton=YES} in /etc/rc.conf to have it start
automatically.

This is totally independent from the \code{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}[label=\file{/etc/network/interfaces}]
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 \file{/etc/}
directory.  There is a small tool named \app{fwcf}, which is used to setup the
system or to commit changes to the fwcf partition.

On bootup the script \file{/sbin/mount\_root} is executed, which calls
\command{fwcf setup} to setup \file{/etc/} as memory filesystem and overlay the
changes committed to the fwcf partition.

If you change anything in \file{/etc/} and like to keep the change, it is
required to execute \command{fwcf commit}. This will compress all changed or
new files in \file{/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 at
\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 \command{fwcf erase}. 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 \app{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 \app{ipkg} is pre-installed.

IPKG uses a configuration file similar to \file{/etc/apt/sources.list}, which
contains a list of software repositories available via HTTP or FTP.  The
configuration file \file{/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}[label=update list of available packages]
# ipkg update
\end{Verbatim}

This command requires a working internet connection, because it will fetch a
package list from every repository declared in \file{/etc/ipkg.conf}.

To install a new package use following command:
\begin{Verbatim}[label=example installation of \app{tcpdump}]
# ipkg install tcpdump
\end{Verbatim}

This will install the package \app{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}[label=example removal of \app{tcpdump}]
# ipkg remove tcpdump
\end{Verbatim}

This will not remove any dependencies, installed earlier. For example,
\app{libpcap} is still installed after executing this command.  On jffs2 root
filesystem you should never remove any essential packages like \app{busybox},
\app{fwcf} or \app{uclibc}, otherwise you make the embedded system unusable.

Nearly the same as for removing packages, counts for \command{ipkg upgrade}.
Please \strong{never ever} use \command{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 \file{/etc/init.d}. See following example for the package
\app{dnsmasq}, a combined dns and dhcp server daemon:

\begin{Verbatim}[label=\file{/etc/init.d/S50dnsmasq}]
#!/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 \file{/etc/} directory. For example packages can add new user and groups,
add new variables to \file{/etc/rc.conf} or just add new values to existing
files as \file{/etc/services}. It is FreeWRT policy not to start any services
after installation or in case of a new boot. To start services on bootup you
need to set \code{\$servicename=YES} in \file{/etc/rc.conf} and commit your
changes via \command{fwcf commit}. For every policy exists an exception, we
start all essential services by default, like ssh daemon, syslog and network
initialisation.

For some services you can control the startup behaviour by modifying the
\code{\$servicename\_flags} variable in \file{/etc/rc.conf}.

For example the variable \code{\$ssh\_opts} is provided as an argument to the
dropbear ssh daemon to control its behaviour.

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 \file{/etc/firewall.user}, which is read
by \file{/etc/init.d/S45firewall}, if the iptables package is installed. You
can just reload the changed ruleset via \code{/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
\code{firewall=YES} in \file{/etc/rc.conf}, commit your changes via
\command{fwcf commit} and reboot. Now the firewall rules will be activated on
bootup.


\chapter{Troubleshooting}\label{ch: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
\file{192.168.1.1} and netmask \file{255.255.255.0}. Then it will start a
\app{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 \file{bin/} after a successful build.

If you just want to compile the tool and not a complete firmware image, use
following command:

\begin{Verbatim}[label=building the failsafe utility for the host system]
$ make subdir=tools/failsafe install
\end{Verbatim}

For some operating systems we provide ready to go binaries of failsafe.
Take a look at \url{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 \file{192.168.1.2} with
network mask \file{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 \file{/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 \file{/etc/} directory, just remove
the fwcf partition content with following command:

\begin{Verbatim}
mtd erase fwcf
\end{Verbatim}

You can either use \command{reboot -f} or the option \command{-r} for \app{mtd}
to reboot the system.

%\section{Serial Console}

%\section{JTAG}

% Erstmal auskommentieren. Sind ja paar Seiten die erstmal keiner braucht
%\begin{appendix}
%\include{A-blaetter}
%\end{appendix}

%\cleardoublepage
%\addcontentsline{toc}{chapter}{\glossaryname}
\end{document}
// Log In
// CVSweb
Project: FreeWRT
// Summary // Activity // Search // Tracker // Lists // News // SCM // Wiki