Context Navigation

-              r8ca8ce4
+              rdac4ea5
 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.
+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
+\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.
+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.
+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]
 …
 \end{itemize}
 In this release we only support the Linux 2.4 kernel. The ADK contains over
 software packages.
+In this release we only support the Linux 2.4 kernel. The ADK contains over 600
+software packages.
 \section{Prerequisites}
 …
 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.
+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 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}
+        \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:
+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}
 …
 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.
+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).
+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:
 …
 \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.
+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:
 …
 \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
+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.
+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}
 …
 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:
+\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})
 …
 \end{itemize}
 Then quit saving changes. If you forgot that, just run \command{make} again, redo
 your changes, then save.
+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.
+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:
+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}
 …
 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.
+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
 …
 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}.
+want to create. To start the configuration menu, type \command{make
+menuconfig}.
 When selecting packages, \code{<*>} means it will be inserted into the firmware
 …
 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!
+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.
+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}
 …
         \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)
+        \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
+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.
 …
    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
+   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}
 …
 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.
+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
 …
 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.
+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:
 …
 \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]
+\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]
+}\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]
+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.
+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
+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}.
 …
 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.
+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
+        \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:
+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 &
 …
         \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
+        \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.
+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
+        \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.
+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
 …
 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}
+\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}
 …
 \section{Network Configuration}
+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}.
+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}.
 To show all configured network interfaces use:
 \begin{Verbatim}[label=show IP address]
 …
 \end{Verbatim}
 \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.
 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.
+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
+        \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}
 …
 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
+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:
 …
 \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
+This configures four VLAN interfaces, \code{eth0.1} on physical ports 2, 3 and
+.  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.
 …
         \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.
+        \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}
 …
         \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)
+                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)
+        \item[mac-address] if you need to change your MAC address (required for
+                some DSL providers)
 \end{description}
 …
 \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}.
+This is mostly needed to combine LAN and WLAN to a homogeneous network.  Be
+sure you have installed the package \app{bridge-utils}.
 \begin{Verbatim}[label=\file{/etc/network/interfaces}]
 …
 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}.
+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{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.
+(\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}
 …
 \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. \\
+\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}
 …
 \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 \\
+\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 \\
+                              & \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} \\
 …
 \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. \\
+                 & \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} \\
 …
 \hline
 \code{radius-port} &                              & \strong{8021x} \\
+                   & \code{<Int>} (\strong{1812}) & RADIUS-Port no. to connect \\
+                   & \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 \\
+                    & \code{<String>} & Shared Secret for connection to the
+                                        Radius server \\
 \hline
 \end{longtable}
 …
 \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}"\\
+               &                  & 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
+:03:3E:05:E1:1B}"\\
 \end{tabular}
 …
 \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) \\
+\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}
 …
 \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 \\
+\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) \\
+\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,
+, 12, 18, 24, 36, 48, 54) \\
+            &                              & valid values for 802.11b are (1,
+, 5.5, 11) \\
+            &                              & valid values for 802.11g are (1,
+, 5.5, 6, 9, 11, 12, 18, 24, 36,
+, 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}
 …
         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:
+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}[label=\file{/etc/network/interfaces}]
         wireless-gmode performance
 …
 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}.
+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}
 …
 \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.
+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}
 …
 \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.
+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}
 …
 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.
+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.
+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
 …
 \subsection{custom interface hooks}
 \subsubsection{per interface}
+You can execute various commands on interface startup or shutdown with special option:
+You can execute various commands on interface startup or shutdown with special
+option:
 \begin{Verbatim}[label=\file{/etc/network/interfaces}]
 iface foobar inet static
 …
 \end{Verbatim}
+You can give each option multiple times and their commands will be executed in given order.
+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
 …
 \subsubsection{general hooks}
+Additionally you can write scripts executed for each interface if you put them in
+Additionally you can write scripts executed for each interface if you put them
+in
 \begin{itemize}
         \item \texttt{/etc/network/if-pre-up.d}
 …
 \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.
+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.
+\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.
+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.
+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.
+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:
 …
 \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:
+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
 …
 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.
+\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:
+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}]
 …
 \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.
+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.
+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.
 …
 \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.
+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.
 …
 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).
+\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:
+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]
 …
 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.
+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}
 …
 \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:
+If you want to repair your configuration, you first need to mount the root
+filesystem read--writeable. This is best done via:
 \begin{Verbatim}
 …
 \end{Verbatim}
 If you want to start over with the default \file{/etc/} directory, just remove the fwcf
 partition content with following command:
+If you want to start over with the default \file{/etc/} directory, just remove
+the fwcf partition content with following command:
 \begin{Verbatim}
 …
 \end{Verbatim}
+You can either use \command{reboot -f} or the option \command{-r} for \app{mtd} to reboot the system.
+You can either use \command{reboot -f} or the option \command{-r} for \app{mtd}
+to reboot the system.
 %\section{Serial Console}

Note: See TracChangeset for help on using the changeset viewer.

Context Navigation

Changeset dac4ea5 in freewrt

Legend:

docs/handbook/user/handbook.tex

Download in other formats: