handbook/user/handbook.tex

\documentclass[12pt,a4paper,openany,smallheadings,
headinclude,headsepline,final]{scrreprt}
\usepackage[utf8]{inputenc}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{caption2}
\usepackage[canadian]{babel}
\usepackage{varioref}
\usepackage{txfonts}
\usepackage[pdftex]{graphicx}
%\usepackage{listings}
\usepackage{makeidx}
\usepackage[T1]{fontenc}

% fancy verbatim enables changing of font, fontsize, etc. in verbatim code
% also set smaller font and a frame as default
\usepackage{fancyvrb}
\fvset{fontsize=\small, frame=single}

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

\usepackage[pdftex]{color}
\definecolor{skyblue}{rgb}{0,0.3323,0.5720}
\usepackage[%
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}]{hyperref}
%\usepackage{thumbpdf}
\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}

% Change Section, Chapter Layout
% http://www.mackichan.com/index.html?techtalk/518.htm~mainFrame
%\usepackage{sectsty}
%\allsectionsfont{\raggedleft}
%\chapterfont{\raggedleft}

% BEGIN Fancy Header Extensions
% Save Graphics in Latex box
%\renewcommand{\headheight}{30pt} %Make height wider so picture is ok
%\renewcommand{\footskip}{45pt} %Make height wider so picture is ok

\usepackage{fixltx2e, mparhack}

% Generate index in preamble
\makeindex
\begin{document}
\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}}

%Bilitz
%\newcommand{\blitz}{ \mbox{\Huge \Lightning} }
\newcommand{\blitz}{ \Lightning }
\newcommand{\entspr}{\stackrel{\wedge}{=}}


\chapter{Introduction}

Welcome to FreeWRT! This handbook covers the building, installation and usage
aspects of the FreeWRT 1.1 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 six chapters. We start with the introduction of the
Web Image Builder (WIB). The second chapter, Appliance Development Kit, covers
the building of FreeWRT firmware images from source.  The third section,
Installing FreeWRT, covers all aspects regarding the installation and
deinstallation of FreeWRT firmware images. The fourth section is a detailed
description of the startup process of FreeWRT.  The fifth 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. 

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

\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{Web Image Builder (WIB)}

The WIB is a Ruby-on-Rails webapplication, which combines pre-compiled parts of
the FreeWRT Linux distribution, into firmware images. In just five steps you get 
a ready-to-go firmware image for one of the supported embedded devices.

See a complete list here:

\begin{itemize}
\item Asus WL500g
\item Asus WL500g deluxe
\item Asus WL500g premium
\item Linksys WRT54G[L]\footnote{see a complete list of all supported revisions on our website} 
\item Linksys WRT54GS (v1.0/v1.1) 
\item Linksys WRT54GSv4
\item Linksys WRT54G3G
\item Mikrotik Routerboard 532
\item Netgear WGT634u
\end{itemize}

The five steps are, 
\begin{itemize}
\item choose your target
\item choose a Linux Kernel version (2.4/2.6)
\end{itemize}

\chapter{Appliance Development Kit (ADK)}

The ADK is the core of FreeWRT. It contains all the magic to create the FreeWRT
firmware for your embedded system. It will download the needed software
packages from the internet and will prepare, compile and combine all components
into a ready-to-go firmware image. The ADK is a combination of Makefiles, the
Kernel 2.6 configuration system, shell scripts and some other helper
applications. The ADK contains over 350 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 zlib (+headers)
\item ncurses (+headers)
\item (g)libc headers
\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:
Via HTTP protocol:
\begin{verbatim}
$ svn co http://www.freewrt.org/svn/tags/freewrt_1_1_x freewrt
\end{verbatim}
Via subversion protocol:
\begin{verbatim}
$ svn co svn://www.freewrt.org/itags/freewrt_1_1_x freewrt
\end{verbatim}

The value \dq{}x\dq{} 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 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''.

% FIXME, check for zlib missing on host
\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.

% FIXME: fwupdate
\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.


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=/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, \texttt{eth0.1} on physical ports 2, 3 and 4. 
The interfaces \texttt{eth0.2}, \texttt{eth0.3} and \texttt{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 +, it will 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=/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
    wireless-bridge-if br0
    [... other 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
    broadcast +
\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}).
The bridge interface needs always be the last one, otherwise it can not find
the interfaces in bridge-ifaces.

\subsection{WLAN}

A router containing a WLAN interface has an additional ethernet device
representing it. On Broadcom-based hardware it is typically \texttt{wl0} or on
Netgear WGT634u which has a Atheros 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 over wireless\\
             & 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{wpa-psk} \\
             & psk             & WPA PSK \\
             & psk2            & WPA2 PSK \\
             & psk psk2        & WPA PSK and WPA2 PSK \\
             &                 & \textbf{8021x} \\
             & 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\\
\end{tabular}

\subsubsection{Wireless Distribution System (WDS)}
\begin{tabular}{l|l|l}
\texttt{Option} & \texttt{Parameter} & \texttt{Description} \\
lazywds      & {0|1}           & Accept WDS connections from anyone \\
wds-bridge   & {brX}           & Add WDS peers to bridge brX \\
wds-security & {wpa-psk}           & secure the wds bridge with WPA (optional)\\
wds-encryption & {aes|tkip}           & Use AES or TKIP as cipher\\
wds-wpa-key & <String>        & Password to use with WPA PSK (at least 8, up to 63 chars) \\
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 \\
bridge-if    & \{br0...brX\}   & The bridge interface (optional)
\end{tabular}

\subsubsection{Examples}
WLAN with WEP128
\begin{Verbatim}
iface wl0 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 wep
        wireless-key1 11223344556677889900112233
        wireless-channel 11
\end{Verbatim}

WLAN without encryption
\begin{Verbatim}
iface wl0 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}

WLAN with WPA2 (AES)
\begin{Verbatim}
iface wl0 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 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)
\begin{Verbatim}
iface wl0 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 client with WEP128
\begin{Verbatim}
iface wl0 inet dhcp
        wireless-type broadcom
        wireless-country DE
        wireless-mode sta
        wireless-ssid FreeWRT
        wireless-security wep
        wireless-key1 11223344556677889900112233
\end{Verbatim}

WLAN with WDS nodes, the WDS nodes need to have the same
SSID, channel and encryption parameters.

WDS node 1 (MAC of Wireless 06:05:04:03:02:01)
\begin{Verbatim}
iface br0 inet static
        bridge-ifaces wl0
        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 none
        wireless-lazywds 0
        wireless-wds 01:02:03:04:05:06
        wireless-wds-bridge br0
\end{Verbatim}
WDS node 2 (MAC of Wireless 01:02:03:04:05:06)
\begin{Verbatim}
iface br0 inet static
        bridge-ifaces wl0
        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 none
        wireless-lazywds 0
        wireless-wds 06:05:04:03:02:01
        wireless-wds-bridge br0
\end{Verbatim}

Peer-to-Peer/AdHoc mode (no encryption, IP must be static)
\begin{Verbatim}
iface wl0 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{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}. For providers
using PPTP for authentication, instead of PPPoE, you need to install \texttt{pptp}.

\subsubsection{DSL with PPPoE}
\begin{Verbatim}
auto ppp0
iface ppp0 inet ppp
        use-template dsl
        provider foobar
        ppp-username 1234567890121234567890120001@bar.de
        ppp-password bar
        ppp-device eth0.1
\end{Verbatim}

Now your 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{DSL with PPTP}
\begin{Verbatim}
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 (\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{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}
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 committed
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.1 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}
#FWINIT 50
. /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 scripts.

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/firewall, if the FreeWRT firewall package (fwfirewall)  is
installed. You can just reload the changed ruleset via
\begin{verbatim}
/etc/init.d/firewall restart
\end{verbatim}

If you managed to kick yourself 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,
forgot your password 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
%\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