SCM Repository

project home | /[freewrt]/branches/freewrt_1_0/docs/handbook/user/handbook.tex

Diff of /branches/freewrt_1_0/docs/handbook/user/handbook.tex

Parent Directory | Revision Log | View Patch Patch

-revision 2537 by n0-1,
Thu May 17 20:25:52 2007 UTC
+revision 2538 by n0-1,
Thu May 17 21:12:17 2007 UTC
 Line 109 
 Welcome to FreeWRT! This handbook covers
  aspects of the FreeWRT 1.0 Linux distribution.  FreeWRT is a portable, secure
  and functional Linux distribution for embedded systems. As FreeWRT is a source
  code distribution, it does not provide any pre-compiled firmware for embedded
- systems. The latest version of this document is always available at the
+ systems. The latest version of this document is always available at the FreeWRT
- FreeWRT website. If you have any comments, criticism or found some wrong
+ website. If you have any comments, criticism or found some wrong description,
- description, please send us an e-mail to
+ please send us an e-mail to
- \href{mailto:freewrt-handbook@freewrt.org}{freewrt-handbook@freewrt.org}, we are
+ \href{mailto:freewrt-handbook@freewrt.org}{freewrt-handbook@freewrt.org}, we
- always happy about getting feedback to this document, and will try to update
+ are always happy about getting feedback to this document, and will try to
- or correct the issues mentioned by you.
+ 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.
+ \nameref{ch:ADK} covers the building of FreeWRT firmware images.  In
- In \autoref{ch:installing}, \nameref{ch:installing}, all aspects regarding the
+ \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},
+ management and update mechanism. The last chapter,
- helps troubleshooting problems and recovering a bad firmware installation.  The
+ \nameref{ch:troubleshooting}, helps troubleshooting problems and recovering a
- appendix contains board specific information.  For FreeWRT 1.0 these are only
+ bad firmware installation.  The appendix contains board specific information.
- Broadcom based embedded systems.
+ For FreeWRT 1.0 these are only Broadcom based embedded systems.
- The intended audience for this handbook are advanced users with basic
+ The intended audience for this handbook are advanced users with basic knowledge
- knowledge about Linux, networking and software development. The reader should
+ about Linux, networking and software development. The reader should be aware of
- be aware of basic command line tools, the vi editor and a shell. FreeWRT does
+ basic command line tools, the vi editor and a shell. FreeWRT does not contain
- not contain any high level administration tools (e.g. web based
+ any high level administration tools (e.g. web based administration) and is
- administration) and is fully configured via command line.
+ fully configured via command line.
  \section{Typographic Conventions}
- Examples starting with \code{\#} indicate a command that must be invoked as super
+ Examples starting with \code{\#} indicate a command that must be invoked as
- user. You can use \command{su} to gain super user privileges.
+ super user. You can use \command{su} to gain super user privileges.
  \begin{Verbatim}[label=example for a command line with super user privileges]
  # fwcf commit
 Line 178 
 following embedded systems:
          \item Netgear WGT634u
  \end{itemize}
- In this release we only support the Linux 2.4 kernel. The ADK contains over
+ In this release we only support the Linux 2.4 kernel. The ADK contains over 600
-software packages.
+ 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.
+ 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
-Line 194 
 The list of supported GNU/Linux build sy
+Line 196 
 The list of supported GNU/Linux build sy
          \item OpenSuSE
          \item Ubuntu GNU/Linux
          \item Fedora Core
-         \item OpenBSD (partial support)\footnote{some addon packages does not compile}
+         \item OpenBSD (partial support)
-         \item MirOS BSD (partial support)\footnote{some addon packages does not compile}
+                 \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
+ needed. The ADK host checks will warn you about any software you need to
- compile a specific package.  Here is a list of the required software:
+ install to compile a specific package.  Here is a list of the required
+ software:
  \begin{itemize}
          \item gcc3 or higher
-Line 222 
 compile a specific package.  Here is a l
+Line 227 
 compile a specific package.  Here is a l
  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
+ To build FreeWRT with the ADK it is recommended to have an unprivileged user.
- user. Please \underline{never} build FreeWRT as super user. Because all necessary source
+ Please \underline{never} build FreeWRT as super user. Because all necessary
- tarballs are downloaded from the internet automatically, your host system
+ source tarballs are downloaded from the internet automatically, your host
- needs a working internet connection.
+ 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
+ includes the ADK itself, any source archives which will be downloaded and their
- and their extracted copies (for compiling).
+ extracted copies (for compiling).
  To get the latest stable FreeWRT ADK try one of these commands:
  \begin{Verbatim}[label=Check out the 1.0-branch of FreeWRT ADK via HTTP protocol]
-Line 242 
 $ svn co http://www.freewrt.org/svn/tags
+Line 247 
 $ svn co http://www.freewrt.org/svn/tags
  $ svn co svn://www.freewrt.org/itags/freewrt_1_0_x freewrt
  \end{Verbatim}
- The value $x$ is a place holder for the latest minor release number.
+ The value $x$ is a place holder for the latest minor release number.  Take a
- Take a look at our project page to find out which minor release number is the latest one.
+ look at our project page to find out which minor release number is the latest
+ one.
  After successfully downloading, enter the directory:
-Line 255 
 This directory will be referred to as th
+Line 261 
 This directory will be referred to as th
  \section{Some Theory First}
- Building a FreeWRT firmware image is just like building a new Linux kernel,
+ Building a FreeWRT firmware image is just like building a new Linux kernel, but
- but a little more complex. There is a \app{ncurses}-based configuration menu at the
+ 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
+ beginning, the changes made are saved into a file named \file{.config} in the
- root. The build is done by the various Makefiles, compiling and linking 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
+ Unlike kernel compilation, FreeWRT needs to be cross-compiled. This leads to
- leads to special premises, as most of the tools need to be specially build.
+ special premises, as most of the tools need to be specially build.  But no
- But no panic, FreeWRT will do this all for you. In fact, this is done at the
+ panic, FreeWRT will do this all for you. In fact, this is done at the second
- second run of \command{make} (the first one opens the configuration), and
+ run of \command{make} (the first one opens the configuration), and therefore
- therefore can be seen as part of the first firmware build.  For clarity
+ can be seen as part of the first firmware build.  For clarity though, we will
- though, we will discuss these two things separately.
+ discuss these two things separately.
  \section{Preparing the Build Process}
-Line 276 
 building of firmware images (for explana
+Line 282 
 building of firmware images (for explana
  \subsection{Creating A Configuration}
  The first step is to run \command{make}. After checking some prerequisites (see
- \nameref{ch:troubleshooting} below for aid in problems), a console based configuration
+ \nameref{ch:troubleshooting} below for aid in problems), a console based
- menu should start. Theoretically no choices have to be made, but it's proven
+ configuration menu should start. Theoretically no choices have to be made, but
- useful to at least:
+ it's proven useful to at least:
  \begin{itemize}
          \item select a target (menu: \code{Embedded System})
          \item select the root filesystem type (menu: \code{Target Firmware type})
  \end{itemize}
- Then quit saving changes. If you forgot that, just run \command{make} again, redo
+ Then quit saving changes. If you forgot that, just run \command{make} again,
- your changes, then save.
+ redo your changes, then save.
  \subsection{Building ADK}
- Now that you have a first minimal configuration, it is time to build the toolchain
+ Now that you have a first minimal configuration, it is time to build the
- for cross-compiling. To do this, just enter \command{make} again. The build starts
+ toolchain for cross-compiling. To do this, just enter \command{make} again. The
- downloading and compiling each needed part of the toolchain, and later continues
+ build starts downloading and compiling each needed part of the toolchain, and
- with building the first firmware image. Later one can be taken as proof of a
+ later continues with building the first firmware image. Later one can be taken
- working ADK.
+ as proof of a working ADK.
- Already experienced in compiling \app{gcc}? Then you know\dots If not, better be told
+ Already experienced in compiling \app{gcc}? Then you know\dots If not, better
- that it takes \underline{really long} to finish. In the meantime I suggest reading the
+ be told that it takes \underline{really long} to finish. In the meantime I
- next chapter dealing with internals about cross-compiling.
+ 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,
+ A cross-compile toolchain exists of a set of tools: a compiler, linker,
- debugger and a C~library. A cross-compile toolchain runs on your host system and
+ assembler, debugger and a C~library. A cross-compile toolchain runs on your
- creates native binaries for your target system. A cross-compile toolchain is
+ host system and creates native binaries for your target system. A cross-compile
- basically created in six steps:
+ toolchain is basically created in six steps:
  \begin{enumerate}
          \item Get and prepare the Kernel and C~library headers of your target system
-Line 317 
 basically created in six steps:
+Line 323 
 basically created in six steps:
  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
+ Little Endian}. All the tools running on the host, but used to create, analyze
- for the target are kept in this directory. All addon headers and libraries
+ or debug for the target are kept in this directory. All addon headers and
- are installed to this directory.
+ libraries are installed to this directory.
  If you want to compile a simple application without using the ADK, just use the
  compiler directly (e.g. compiling a MIPS Little Endian application):
-Line 338 
 linked (uses shared libs), not stripped
+Line 344 
 linked (uses shared libs), not stripped
  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
  images and \code{<M>} means it will be build as an addon package which can be
-Line 346 
 installed later at runtime.
+Line 353 
 installed later at runtime.
  The target device and filesystem should already been chosen by you to the right
  value, if not you will have to issue a \command{make clean} before actually
- building the firmware image. Otherwise things get messed up. A smooth
+ building the firmware image. Otherwise things get messed up. A smooth rebuild
- rebuild is a missing feature in the current ADK. For the packages, if unsure, you
+ is a missing feature in the current ADK. For the packages, if unsure, you can
- can just select one of the package collections. After that, you can still manually
+ 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
+ check the choices made by the collection and correct them if appropriate. Do
- forget to save your configuration when leaving!
+ 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
+ underlying hardware, this will take different amounts of time. For your spare
- there is the following chapter giving some explanation about what is done at this
+ time there is the following chapter giving some explanation about what is done
- point.
+ at this point.
  \section{Firmware Build Process In Detail}
-Line 372 
 The detailed order of firmware image bui
+Line 379 
 The detailed order of firmware image bui
          \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)
+         \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/}.
+ The result of the build process is created in the directory \file{bin/}.  You
- You will find a firmware image in the top level directory. Check the size of
+ will find a firmware image in the top level directory. Check the size of the
- the binary image file to see if it is small enough to fit into flash memory of
+ binary image file to see if it is small enough to fit into flash memory of your
- your embedded system. Furthermore there is a directory \file{package/}, which
+ embedded system. Furthermore there is a directory \file{package/}, which
  contains all base and add--on packages.
  \section{Troubleshooting}
-Line 401 
 To re-issue the checks, use \command{mak
+Line 409 
 To re-issue the checks, use \command{mak
     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
+    it is quite a nice error that tells you to use more up to date software, but
-    anyhow give this hostsystem a try and tell make to ignore those
+    we can anyhow give this hostsystem a try and tell make to ignore those
     errors/warnings running \command{make prereq-noerror}.
  \end{itemize}
  \subsection{Compilation errors}
  If you encounter any compilation errors, then first try to reproduce the error.
- First update your ADK tree via \command{svn update}, to be sure that the error is not
+ First update your ADK tree via \command{svn update}, to be sure that the error
- already fixed in the subversion repository. After that do a \command{make clean
+ is not already fixed in the subversion repository. After that do a
- \&\& make}, to reproduce your problem.
+ \command{make clean \&\& make}, to reproduce your problem.
  If you can reproduce the problem, please file a bug report. Please always
  report following information:
-Line 439 
 on serveral ways (ordered by needed skil
+Line 447 
 on serveral ways (ordered by needed skil
  \subsection{Web Interface Method}\label{sec:webinterface}
  The following text describes how to use the original firmware's web interface
- to flash FreeWRT. The object of demonstration is an \term{Asus WL500gP}, but this
+ to flash FreeWRT. The object of demonstration is an \term{Asus WL500gP}, but
- guide should fit more or less fine for other systems, too.
+ 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
+ If you flash a router from \term{Linksys}, we strongly suggest to use the
- \term{ping exploit} to allow recovery, if your image is broken or the flash
+ popular \term{ping exploit} to allow recovery, if your image is broken or the
- process was interrupted by a power shortage.
+ flash process was interrupted by a power shortage.
  There are some things that you should have done previously:
  \begin{itemize}
-Line 458 
 There are some things that you should ha
+Line 466 
 There are some things that you should ha
  \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
+ \command{192.168.1.1} into the address bar. You should reach the web
- startup page:
+ interface's startup page:
- }\hfill\parbox{20em}{\includegraphics[width=20em]{pics/asus-startup.png}} \\ [1em]
+ }\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
+ In the new menu click on \code{Firmware Upgrade}, and enter the name of your
- into the appropriate field:
+ firmware image into the appropriate field:
- }\hfill\parbox{20em}{\includegraphics[width=20em]{pics/asus-fw_upgrade.png}} \\ [1em]
+ }\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)
+ flash and rebooting (don't forget that it creates \app{ssh} hostkeys on first
- takes quite long (yes, a couple of minutes). Better go and get a coffee or tea.
+ 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
+ When everything went well, you can login using \app{ssh}. The default username
- "\code{FreeWRT}". It is possible to change this password in the ADK,
+ is "\code{admin}". The default password for images created via WIB or ADK is
- before image creation.
+ "\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
+ image to the router, preferably into \file{/tmp/}, the memory filesystem should
- big enough to hold the full image. If not, use \app{wget} to get the image
+ be big enough to hold the full image. If not, use \app{wget} to get the image
  via http or ftp and pipe the result into \app{mtd}.
  Then the image is written to flash using \app{mtd}, optionally giving
  additional options (see below).
- The \app{mtd} utility was written with simplicity and code size in mind.
+ The \app{mtd} utility was written with simplicity and code size in mind.  It's
- It's features were derived from the
+ features were derived from the
- \href{http://sources.redhat.com/jffs2/}{\app{mtd-utils}},
+ \href{http://sources.redhat.com/jffs2/}{\app{mtd-utils}}, combining the needed
- combining the needed parts into a single small tool providing all the
+ parts into a single small tool providing all the functionality necessary for
- functionality necessary for FreeWRT, and leaving everything out that's not.
+ 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
+         \item[erase] this is a filesystem independent method to delete all
-                 the flash. Basically this is like \app{format} in MS--DOS.
+                 contents on the flash. Basically this is like \app{format} in
-         \item[write] this is generally the same functionality as using
+                 MS--DOS.
-                 \app{dd} or \app{rawrite}, but \app{mtd} takes care of the quirks
+         \item[write] this is generally the same functionality as using \app{dd}
-                 that have to be paid attention to for correctly handling the type of flash
+                 or \app{rawrite}, but \app{mtd} takes care of the quirks that
-                 in use
+                 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
+ Further it can request your system to reboot. Some of the features mentioned
- also be combined, so it is e.g. possible to immediately reboot the system after
+ here can also be combined, so it is e.g. possible to immediately reboot the
- the flash has been written.
+ 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
+ Mostly, similar to the sample usage shown in the help output should be all that
- done to write the firmware to flash:
+ has to be done to write the firmware to flash:
  \begin{Verbatim}[label=write a previously downloaded new firmware-file into flash]
  # mtd -e linux -r write freewrt.bin linux &
  \end{Verbatim}
-Line 521 
 The parameters explained in detail:
+Line 537 
 The parameters explained in detail:
  \begin{description}
          \item[\command{-e linux}] erase existing data in flash
          \item[\command{-r}] trigger rebooting right after finishing work
-         \item[\command{write}] write the firmware image contained in the file given as
+         \item[\command{write}] write the firmware image contained in the file
-                 next parameter to flash
+                 given as next parameter to flash
-         \item[\command{freewrt.bin}] the actual image to write -- ignore the suffix,
+         \item[\command{freewrt.bin}] the actual image to write -- ignore the
-                 it is detected at runtime
+                 suffix, it is detected at runtime
-         \item[\command{linux}] this is an abstract identifier for a certain partition
+         \item[\command{linux}] this is an abstract identifier for a certain
-                 in flash, so don't change this
+                 partition in flash, so don't change this
-         \item[\command{\&}] put the process into background, to prevent accidentally
+         \item[\command{\&}] put the process into background, to prevent
-                 stopping
+                 accidentally stopping
  \end{description}
  \subsection{Installation using TFTP}\label{sec:tftp}
- All supported target devices are shipped with a builtin bootloader, comparable to
+ All supported target devices are shipped with a builtin bootloader, comparable
- the BIOS of \term{x86} machines. This bootloader is used to bootstrap the system until
+ to the BIOS of \term{x86} machines. This bootloader is used to bootstrap the
- it can boot a regular operating system. Besides the ability to load
+ system until it can boot a regular operating system. Besides the ability to
- the executable code from flash, it can be received from another node in the
+ load the executable code from flash, it can be received from another node in
- local area network via the famous TFTP protocol.
+ 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
+         \item the device acts as a client, asks the local \app{dhcpd} for a
-                 address of the next \app{tftpd} and the filename to download
+                 lease, the address of the next \app{tftpd} and the filename to
-         \item the device acts as a server, having a known IP address and waiting for
+                 download
-                 any TFTP client to connect and send the file
+         \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
+ device \term{Netgear WGT634u} is using the first method, the bootloader
- DHCP/TFTP client. Though this may be a little confusing to people being familiar
+ provides a DHCP/TFTP client. Though this may be a little confusing to people
- with netboot technologies, it is definitely the easier way of doing it. Otherwise
+ being familiar with netboot technologies, it is definitely the easier way of
- one had to setup both DHCP and TFTP servers and configure them right.
+ 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
-Line 571 
 images and to improve bootup time, of co
+Line 589 
 images and to improve bootup time, of co
  default. The following list shows what has to be done for a certain device to
  get it to wait at boot: \\
  \begin{center}
-         \begin{tabular}{l|l|p{7cm}} % TODO: fill this table
+ \begin{tabular}{l|l|p{7cm}} % TODO: fill this table
-                 \strong{Target Device} & \strong{Action to be taken} & \strong{Comments} \\
+ \strong{Target Device} & \strong{Action to be taken} & \strong{Comments} \\
-                 \hline
+ \hline
-                 All supported Linksys models & Ping Exploit & nvram variable \code{boot\_wait} needs to be on \\
+ All supported Linksys models & Ping Exploit & nvram variable \code{boot\_wait}
-                 All supported Asus models & Recovery mode & power off
+                                               needs to be on \\
-                                                             $\rightarrow$ push and hold the reset button
+ All supported Asus models & Recovery mode & power off $\rightarrow$ push and
-                                                             $\rightarrow$ power on
+                                             hold the reset button $\rightarrow$
-                                                             $\rightarrow$ power led is flashing\\
+                                             power on $\rightarrow$ power led is
-         \end{tabular}
+                                             flashing \\
+ \end{tabular}
  \end{center}
  \chapter{FreeWRT Administration}\label{ch:administration}
-Line 591 
 guides for using FreeWRT in general, of
+Line 610 
 guides for using FreeWRT in general, of
  \section{Network Configuration}
- The device names for real network interfaces in Linux are named \code{ethx} (\code{x} is
+ The device names for real network interfaces in Linux are named \code{ethx}
- \code{0--9}). If the device has a switch, the different ports are separated via VLAN
+ (\code{x} is \code{0--9}). If the device has a switch, the different ports are
- technology. The vlan interfaces are named \code{ethx.y}.  The network configuration in
+ separated via VLAN technology. The vlan interfaces are named \code{ethx.y}.
- FreeWRT is managed via \app{Busybox}'s \app{ifupdown} implementation. \app{Busybox}'s builtin \app{ip}
+ The network configuration in FreeWRT is managed via \app{Busybox}'s
- command configures the network interfaces. There is no \app{ifconfig} or \app{route}.
+ \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]
  $ ip addr show
-Line 615 
 iface <iface-name> inet <method>
+Line 635 
 iface <iface-name> inet <method>
    <option-z> <value>
  \end{Verbatim}
- \code{auto <iface-name>} is optional and, if set, tells the \app{ifup} script to
+ \code{auto <iface-name>} is optional and, if set, tells the \app{ifup} script
- start this interface automatically on bootup.
+ 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
+ either a physical interface or a logical interface name like \code{eth0.1} for
- physical VLAN or \code{umts} as a logical name for a PPP interface.
+ 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[static] use the given options to configure the interface
-         \item[dhcp] just start a dhcp client using the interface \code{iface-name}
+                 statically
-         \item[manual] don't configure the interface but start \code{pre-up.d} hook scripts
+         \item[dhcp] just start a dhcp client using the interface
-         \item[ppp] run \code{pon <provider>} where \code{<provider>} is given as an interface option
+                 \code{iface-name}
+         \item[manual] don't configure the interface but start \code{pre-up.d}
+                 hook scripts
+         \item[ppp] run \code{pon <provider>} where \code{<provider>} is given
+                 as an interface option
  \end{description}
  \subsection{Switch/VLAN}
-Line 659 
 This configures three VLAN interfaces \c
+Line 683 
 This configures three VLAN interfaces \c
  \code{eth0.1} on port 3 and 4 and \code{eth0.2} on port 0.
- If you need to do some advanced settings, because you have for example
+ If you need to do some advanced settings, because you have for example a
- a powerful switch with a VLAN trunking port connected to one of your switch
+ powerful switch with a VLAN trunking port connected to one of your switch
  ports, the configuration would look like this:
  \begin{Verbatim}[label=\file{/etc/network/interfaces}]
-Line 693 
 iface eth0.4 inet static
+Line 717 
 iface eth0.4 inet static
  \end{Verbatim}
- This configures four VLAN interfaces, \code{eth0.1} on physical ports 2, 3 and 4.
+ 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
+.  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.
-Line 703 
 Explanation:
+Line 727 
 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
+         \item[port 5] this special port represents the port where the
-                 connected to the switch
+                 router--board is connected to the switch
-         \item[*] one interface always need an asterisk behind port 5 which means it is
+         \item[*] one interface always need an asterisk behind port 5 which
-                 the default interface and gets all the packages with unknown tags.
+                 means it is the default interface and gets all the packages
+                 with unknown tags.
  \end{description}
  \subsection{Static IP configuration}
-Line 716 
 IP settings, so these are the commonly u
+Line 741 
 IP settings, so these are the commonly u
          \item[address] the IP address  --- required
          \item[netmask] the netmask     --- required
          \item[broadcast] broadcast address --- only required for legacy
-         applications (if using \code{+}, it will be calculated automatically by the kernel)
+                 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{DHCP}
-Line 732 
 Typically this configures the WAN-Port t
+Line 759 
 Typically this configures the WAN-Port t
  \subsection{Bridging}
- This is mostly needed to combine LAN and WLAN to a homogeneous network.
+ This is mostly needed to combine LAN and WLAN to a homogeneous network.  Be
- Be sure you have installed the package \app{bridge-utils}.
+ sure you have installed the package \app{bridge-utils}.
  \begin{Verbatim}[label=\file{/etc/network/interfaces}]
  auto eth0.0
-Line 754 
 iface br0 inet static
+Line 781 
 iface br0 inet static
  \end{Verbatim}
  This creates a new bridging interface \code{br0} which combines the VLAN
- interface \code{eth0.0} (representing the LAN-ports 1--4) and the WLAN interface
+ interface \code{eth0.0} (representing the LAN-ports 1--4) and the WLAN
- \code{eth1} (on some devices like \term{Asus WL500gP} this might be \code{eth2}).
+ interface \code{eth1} (on some devices like \term{Asus WL500gP} this might be
- The bridge interface needs always be the last one, otherwise it can not find
+ \code{eth2}).  The bridge interface needs always be the last one, otherwise it
- the interfaces in \code{bridge-ifaces}.
+ 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
+ (\term{Linksys}),\code{eth2} (\term{Asus WL500gP}) or on \term{Netgear WGT634u}
- WLAN chip, it is \code{ath0}, \code{ath1}, etc. You can use these interfaces
+ which has a Madwifi WLAN chip, it is \code{ath0}, \code{ath1}, etc. You can use
- standalone or bridged with other devices, e.g. the internal LAN.
+ these interfaces standalone or bridged with other devices, e.g. the internal
+ LAN.
  \subsubsection{Basic Settings}
-Line 773 
 Mandatory options and default parameters
+Line 801 
 Mandatory options and default parameters
  \begin{tabular}{l|l|p{10cm}}
  \strong{Option} & \strong{Parameter} & \strong{Description} \\
  \hline\hline
- \code{\strong{type}} & \code{broadcom}                & Broadcom based card \\
+ \code{\strong{type}} & \code{broadcom} & Broadcom based card \\
-                      & \code{atheros}                 & Madwifi driver \\
+                      & \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) \\
+ \code{\strong{mode}} & \code{ap}       & Access point mode \\
- \hline
+                      & \code{sta}      & Client mode \\
- \code{country}       & \code{\{ALL|DE|JP|US|\ldots\}} & The country code used to determine the regulatory settings. \\
+                      & \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}
-Line 792 
 Mandatory options and default parameters
+Line 823 
 Mandatory options and default parameters
  \begin{longtable}{l|l|p{10cm}}
  \strong{Option} & \strong{Parameter} & \strong{Description} \\
  \hline\hline
- \code{\strong{security}} & \code{none}            & No authorization \\
+ \code{\strong{security}} & \code{none}    & No authorization \\
-                          & \code{wep}             & WEP key \\
+                          & \code{wep}     & WEP key \\
-                          & \code{wpa-psk}         & WPA with preshared key \\
+                          & \code{wpa-psk} & WPA with preshared key \\
-                          & \code{8021x}           & IEEE 802.1X authentication \\
+                          & \code{8021x}   & IEEE 802.1X authentication \\
  \hline
  \code{\strong{authorization}} &                 & \strong{wpa-psk} \\
-                               & \code{psk}             & WPA PSK \\
+                               & \code{psk}      & WPA PSK \\
-                               & \code{psk2}            & WPA2 PSK \\
+                               & \code{psk2}     & WPA2 PSK \\
-                               & \code{psk psk2}        & WPA PSK and WPA2 PSK \\
+                               & \code{psk psk2} & WPA PSK and WPA2 PSK \\
-                               &                        & \strong{8021x} \\
+                               &                 & \strong{8021x} \\
-                               & \code{wpa}             & WPA with RADIUS \\
+                               & \code{wpa}      & WPA with RADIUS \\
-                               & \code{wpa2}            & WPA2 with RADIUS \\
+                               & \code{wpa2}     & WPA2 with RADIUS \\
-                               & \code{wpa wpa2}        & WPA and WPA2 \\
+                               & \code{wpa wpa2} & WPA and WPA2 \\
  \hline
- \code{\strong{encryption}} &                        & \strong{wep} \\
+ \code{\strong{encryption}} &                 & \strong{wep} \\
-                            & ---                    & not needed, automatically by key size \\
+                            & ---             & not needed, automatically by key size \\
-                            &                        & \strong{wpa-psk} \\
+                            &                 & \strong{wpa-psk} \\
-                            & \code{tkip}            & RC4 encryption \\
+                            & \code{tkip}     & RC4 encryption \\
-                            & \code{aes}             & AES encryption \\
+                            & \code{aes}      & AES encryption \\
-                            & \code{aes+tkip}        & support both \\
+                            & \code{aes+tkip} & support both \\
-                            &                        & \strong{8021x} \\
+                            &                 & \strong{8021x} \\
-                            & \code{wep}             & RC4 encryption (static) \\
+                            & \code{wep}      & RC4 encryption (static) \\
-                            & \code{tkip}            & RC4 encryption \\
+                            & \code{tkip}     & RC4 encryption \\
-                            & \code{aes}             & AES encryption \\
+                            & \code{aes}      & AES encryption \\
-                            & \code{aes+tkip}        & support both \\
+                            & \code{aes+tkip} & support both \\
  \hline
- \code{eap-type} &                        & \strong{8021x} \\
+ \code{eap-type} &                     & \strong{8021x} \\
-                 & \code{\strong{tls}}    & Transport Layer Security \\
+                 & \code{\strong{tls}} & Transport Layer Security \\
-                 & \code{ttls}            & Tunnelled TLS \\
+                 & \code{ttls}         & Tunnelled TLS \\
-                 & \code{peap}            & Protected EAP \\
+                 & \code{peap}         & Protected EAP \\
-                 & \code{leap}            & Cisco Wireless \\
+                 & \code{leap}         & Cisco Wireless \\
  \hline
  \code{key} &                            & \strong{wep} \\
             &\code{\{\strong{1}|2|3|4\}} & Select WEP key to use. \\
  \hline
  \code{key[1..4]} &                 & \strong{wep} \\
-                  & \code{<String>} & WEP key.  The key must be 5, 13 or 16 bytes
+                  & \code{<String>} & WEP key.  The key must be 5, 13 or 16
-                                      long, or 10, 26, 32, or 64 hex digits long.  The encryption
+                                      bytes long, or 10, 26, 32, or 64 hex
-                                      algorithm is automatically selected based on the key size. key1 is
+                                      digits long.  The encryption algorithm is
-                                      the key for WEP client mode. \\
+                                      automatically selected based on the key
- \hline
+                                      size. key1 is the key for WEP client mode.
- \code{wpa-key} &                 & \strong{wpa-psk} \\
+                                      \\
-                & <String>        & Password to use with WPA/WPA2 PSK (at least 8, up to 63 chars) \\
+ \hline
- \hline
+ \code{wpa-key} &          & \strong{wpa-psk} \\
- \code{wpa-gtk-rekey} &                              & \strong{wpa-psk}, \strong{8021x} \\
+                & <String> & Password to use with WPA/WPA2 PSK (at least 8, up
-                      & \code{<Int>} (\strong{3600}) & Rekeying interval in seconds. \\
+                             to 63 chars) \\
+ \hline
+ \code{wpa-gtk-rekey} &                              & \strong{wpa-psk},
+                                                       \strong{8021x} \\
+                      & \code{<Int>} (\strong{3600}) & Rekeying interval in
+                                                       seconds. \\
  \hline
  \code{\strong{radius-ipaddr}} &                  & \strong{8021x} \\
                                & \code{<a.b.c.d>} & IP to connect. \\
  \hline
  \code{radius-port} &                              & \strong{8021x} \\
-                    & \code{<Int>} (\strong{1812}) & RADIUS-Port no. to connect \\
+                    & \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}
-Line 855 
 Mandatory options and default parameters
+Line 893 
 Mandatory options and default parameters
  \strong{Option} & \strong{Parameter} & \strong{Description} \\
  \hline\hline
  \code{macmode} & \code{\{0|1|2\}} & 0: Disable MAC address matching. \\
-                &                  & 1: Deny association to stations on the MAC list. \\
+                &                  & 1: Deny association to stations on the MAC
-                &                  & 2: Allow association to stations on the MAC list. \\
+                                        list. \\
- \hline
+                &                  & 2: Allow association to stations on the MAC
- \code{maclist} & \code{<MAC1> \ldots <MACn>} & List of space separated mac addresses to
+                                        list. \\
- allow/deny according to \code{macmode}. Addresses should be entered with colons,
+ \hline
- e.g.: "\code{00:02:2D:08:E2:1D 00:03:3E:05:E1:1B}"\\
+ \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}
  \subsubsection{Wireless Distribution System (WDS)}
  \begin{tabular}{l|l|p{10cm}}
  \strong{Option}       & \strong{Parameter}          & \strong{Description} \\
  \hline\hline
- \code{lazywds}        & \code{\{0|1\}}              & Accept WDS connections from anyone \\
+ \code{lazywds}        & \code{\{0|1\}}              & Accept WDS connections
+                                                       from anyone \\
  \hline
- \code{wds-bridge}     & \code{br\{X\}}              & Add WDS peers to bridge brX \\
+ \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)\\
+ \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\\
+ \code{wds-encryption} & \code{\{aes|tkip\}}         & Use AES or TKIP as
- \hline
+                                                       cipher\\
- \code{wds-wpa-key}    & \code{<String>}             & Password to use with WPA PSK (at least 8, up to 63 chars) \\
+ \hline
- \hline
+ \code{wds-wpa-key}    & \code{<String>}             & Password to use with WPA
- \code{wds}            & \code{<MAC1> \ldots <MACn>} & List of WDS peer mac addresses (\code{xx:xx:xx:xx:xx:xx}, space separated) \\
+                                                       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}
-Line 885 
 e.g.: "\code{00:02:2D:08:E2:1D 00:03:3E:
+Line 938 
 e.g.: "\code{00:02:2D:08:E2:1D 00:03:3E:
  \begin{longtable}{l|l|p{10cm}}
  \strong{Option} & \strong{Parameter} & \strong{Description} \\
  \hline\hline
- \code{channel}      & \code{\{1--14\}}                & The wifi channel \\
+ \code{channel}  & \code{\{1--14\}}  & The wifi channel \\
  \hline
- \code{maxassoc}     & \code{\{1--255\}}               & Maximum number of associated clients \\
+ \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{gmode} &                      & Set the 54g Mode \\
-                     & \code{\strong{Auto}}            & default \\
+              & \code{\strong{Auto}} & default \\
-                     & \code{LegacyB}                  & \\
+              & \code{LegacyB}       & \\
-                     & \code{GOnly}                    & \\
+              & \code{GOnly}         & \\
-                     & \code{BDeferred}                & \\
+              & \code{BDeferred}     & \\
-                     & \code{Performance}              & \\
+              & \code{Performance}   & \\
-                     & \code{LRS}                      & \\
+              & \code{LRS}           & \\
  \hline
- \code{frameburst}   & \code{\{\strong{0}|1\}}         & Disable/Enable frameburst mode. \\
+ \code{frameburst} & \code{\{\strong{0}|1\}} & Disable/Enable frameburst mode. \\
  \hline
- \code{txpower}      & \code{\{0--255|\strong{$-1$}\}} & Set the transmit power in dBm \\
+ \code{txpower} & \code{\{0--255|\strong{$-1$}\}} & Set the transmit power in dBm \\
  \hline
- \code{rate}         & \code{<Int> (\strong{$-1$})}    & force a fixed rate \\
+ \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.11a are (6,
-                     &                                 & valid values for 802.11b are (1, 2, 5.5, 11) \\
+, 12, 18, 24, 36, 48, 54) \\
-                     &                                 & valid values for 802.11g are (1, 2, 5.5, 6, 9, 11, 12, 18, 24, 36, 48, 54) \\
+             &                              & valid values for 802.11b are (1,
-                     &                                 & $-1$ means automatically determine the best rate \\
+, 5.5, 11) \\
- \hline
+             &                              & valid values for 802.11g are (1,
- \code{rts}          & \code{\{0-2347\}}               & Set the RTS threshhold. \\
+, 5.5, 6, 9, 11, 12, 18, 24, 36,
- \hline
+, 54) \\
- \code{frag}         & \code{\{256-2346\}}             & Set the fragmentation threshhold. \\
+             &                              & $-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 \\
+ \code{afterburner}  & \code{\{\strong{0}|1\}} & Enable Afterburner capability
+                                                 \\
  \hline
- \code{isolate}      & \code{\{\strong{0}|1\}}         & Hide Clients from each other \\
+ \code{isolate}      & \code{\{\strong{0}|1\}} & Hide Clients from each other \\
  \hline
- \code{bridge-if}    & \code{\{br0..brX\}}             & The bridge interface (optional) \\
+ \code{bridge-if}    & \code{\{br0..brX\}}     & The bridge interface (optional)
+                                                 \\
  \hline
  \end{longtable}
-Line 972 
 If you want to do MAC filtering, add the
+Line 1033 
 If you want to do MAC filtering, add the
          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.
+ 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:
+ 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
          wireless-frameburst 1
-Line 1062 
 iface eth1 inet static
+Line 1125 
 iface eth1 inet static
  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.
+ hook-script that evaluates a \code{use-template} option and generates a
- This way everything needed so far can be configured within the
+ ppp-peer.  This way everything needed so far can be configured within the
- \code{interfaces} file. Be sure you have installed the packages
+ \code{interfaces} file. Be sure you have installed the packages \app{kmod-ppp},
- \app{kmod-ppp}, \app{ppp} and \app{ppp-mod-pppoe}. For providers
+ \app{ppp} and \app{ppp-mod-pppoe}. For providers using PPTP for authentication,
- using PPTP for authentication, instead of PPPoE, you need to install \app{pptp}.
+ instead of PPPoE, you need to install \app{pptp}.
  \subsubsection{DSL with PPPoE}
  \begin{Verbatim}[label=\file{/etc/network/interfaces}]
-Line 1079 
 iface ppp0 inet ppp
+Line 1142 
 iface ppp0 inet ppp
          ppp-device eth0.1
  \end{Verbatim}
- Now your DSL connection will be started on boot (\code{auto ppp0})
+ Now your DSL connection will be started on boot (\code{auto ppp0}) and you can
- and you can manually shut it down with \command{ifdown ppp0} or start it up with
+ manually shut it down with \command{ifdown ppp0} or start it up with
- \command{ifup ppp0}.
+ \command{ifup ppp0}.  The template \code{dsl} will configure a typical PPPoE
- The template \code{dsl} will configure a typical PPPoE peer for you.
+ peer for you.
  \subsubsection{DSL with PPTP}
  \begin{Verbatim}[label=\file{/etc/network/interfaces}]
-Line 1097 
 iface ppp0 inet ppp
+Line 1160 
 iface ppp0 inet ppp
          ppp-device eth0.1
  \end{Verbatim}
- Now your DSL connection will be started on boot (\code{auto ppp0})
+ Now your DSL connection will be started on boot (\code{auto ppp0}) and you can
- and you can manually shut it down with \command{ifdown ppp0} or start it up with
+ manually shut it down with \command{ifdown ppp0} or start it up with
- \command{ifup ppp0}.
+ \command{ifup ppp0}.  The template \code{pptp} will configure a typical PPTP
- The template \code{pptp} will configure a typical PPTP peer for you.
+ peer for you.
  \subsubsection{UMTS}
  Same footprint different template and some specific options. That is all that
-Line 1121 
 As you can see: unneeded options like \c
+Line 1184 
 As you can see: unneeded options like \c
  without a value as that causes a failure in \app{ipup}. It does work if you
  give empty double quotes as value like \code{""}.
- Note that you have to set the correct APN, username and password for your provider!
+ 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.
+ 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
  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:
+ You can execute various commands on interface startup or shutdown with special
+ option:
  \begin{Verbatim}[label=\file{/etc/network/interfaces}]
  iface foobar inet static
      [...]
-Line 1146 
 iface foobar inet static
+Line 1213 
 iface foobar inet static
      post-down <command>
  \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
          \item[up] after the interface was started successfully
-Line 1155 
 You can give each option multiple times
+Line 1223 
 You can give each option multiple times
  \end{description}
  \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}
          \item \texttt{/etc/network/if-up.d}
-Line 1166 
 Same semantics as above.
+Line 1235 
 Same semantics as above.
  \section{FWCF - FreeWRT Configuration Filesystem}
- FWCF is a separate flash partition for all changes made to the \file{/etc/} directory.
+ FWCF is a separate flash partition for all changes made to the \file{/etc/}
- There is a small tool named \app{fwcf}, which is used to setup the system or
+ directory.  There is a small tool named \app{fwcf}, which is used to setup the
- to commit changes to the fwcf partition.
+ 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
+ \command{fwcf setup} to setup \file{/etc/} as memory filesystem and overlay the
- to the fwcf partition.
+ changes committed to the fwcf partition.
- If you change anything in \file{/etc/} and like to keep the change, it is required to
+ If you change anything in \file{/etc/} and like to keep the change, it is
- execute \command{fwcf commit}. This will compress all changed or new files in
+ required to execute \command{fwcf commit}. This will compress all changed or
- \file{/etc/} and write the result into the fwcf partition.  The fwcf partition is 128 Kb in
+ new files in \file{/etc/} and write the result into the fwcf partition.  The
- size. This size is not changeable at the moment.
+ 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
+ which can be found at
- at \url{http://www.freewrt.org/trac/wiki/Documentation/Specs/FwCf}
+ \url{http://www.freewrt.org/trac/wiki/Documentation/Specs/FwCf}
- If you want to remove all your changes and start your configuration from scratch,
+ If you want to remove all your changes and start your configuration from
- use \command{fwcf erase}. This is also required if you switch between compression
+ scratch, use \command{fwcf erase}. This is also required if you switch between
- plugins. Right now LZO plugin is default.
+ 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
+ All software for FreeWRT is available as a IPKG package. IPKG is a package
- very similar to Debian's \app{dpkg/apt-get} utilities. It is specially designed for
+ manager very similar to Debian's \app{dpkg/apt-get} utilities. It is specially
- embedded systems and is widely used. The FreeWRT project use a special version,
+ designed for embedded systems and is widely used. The FreeWRT project use a
- which is embedded to the busybox binary. Normally the command line tool
+ special version, which is embedded to the busybox binary. Normally the command
- \app{ipkg} is pre-installed.
+ 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.
+ contains a list of software repositories available via HTTP or FTP.  The
- The configuration file \file{/etc/ipkg.conf} contains the official
+ configuration file \file{/etc/ipkg.conf} contains the official FreeWRT 1.0
- FreeWRT 1.0 repository for your board and kernel version.
+ repository for your board and kernel version.
  To update the list of available packages execute following command as root:
  \begin{Verbatim}[label=update list of available packages]
-Line 1213 
 To install a new package use following c
+Line 1282 
 To install a new package use following c
  # ipkg install tcpdump
  \end{Verbatim}
- This will install the package \app{tcpdump} and all dependencies onto the flash.
+ This will install the package \app{tcpdump} and all dependencies onto the
- Where the data is saved depends on the root filesystem you decided to use while
+ flash.  Where the data is saved depends on the root filesystem you decided to
- installing FreeWRT. If you use jffs2 as root filesystem, then the package is
+ use while installing FreeWRT. If you use jffs2 as root filesystem, then the
- installed on the big linux partition. If you use squashfs-overlay, then the
+ package is installed on the big linux partition. If you use squashfs-overlay,
- package is installed on the mini-fo overlay filesystem which writes its data
+ then the package is installed on the mini-fo overlay filesystem which writes
- to the jffs2 data partition. If you use a squashfs-symlinks filesystem, then the
+ its data to the jffs2 data partition. If you use a squashfs-symlinks
- package data is directly install into the jffs2 data partition, containing
+ filesystem, then the package data is directly install into the jffs2 data
- symlinks to the read-only squashfs partition.
+ partition, containing symlinks to the read-only squashfs partition.
- You can also remove packages, but this is only useful if you are using jffs2
+ You can also remove packages, but this is only useful if you are using jffs2 as
- as root filesystem:
+ root filesystem:
  \begin{Verbatim}[label=example removal of \app{tcpdump}]
  # ipkg remove tcpdump
  \end{Verbatim}
  This will not remove any dependencies, installed earlier. For example,
- \app{libpcap} is still installed after executing this command.
+ \app{libpcap} is still installed after executing this command.  On jffs2 root
- On jffs2 root filesystem you should never remove any essential packages like
+ filesystem you should never remove any essential packages like \app{busybox},
- \app{busybox}, \app{fwcf} or \app{uclibc}, otherwise you make the embedded system unusable.
+ \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
+ Nearly the same as for removing packages, counts for \command{ipkg upgrade}.
- \strong{never ever} use \command{ipkg upgrade} to update your embedded system.  This command
+ Please \strong{never ever} use \command{ipkg upgrade} to update your embedded
- is only useful to upgrade single packages on a jffs2 rootfilesystem or data
+ system.  This command is only useful to upgrade single packages on a jffs2
- partition.
+ 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
+ directory \file{/etc/init.d}. See following example for the package
- the package \app{dnsmasq}, a combined dns and dhcp
+ \app{dnsmasq}, a combined dns and dhcp server daemon:
- server daemon:
  \begin{Verbatim}[label=\file{/etc/init.d/S50dnsmasq}]
  #!/bin/sh
-Line 1274 
 esac
+Line 1342 
 esac
  exit 0
  \end{Verbatim}
- After installation the package postinst script will add all needed changes to the
+ After installation the package postinst script will add all needed changes to
- \file{/etc/} directory. For example packages can add new user and groups, add new
+ the \file{/etc/} directory. For example packages can add new user and groups,
- variables to \file{/etc/rc.conf} or just add new values to existing files as
+ add new variables to \file{/etc/rc.conf} or just add new values to existing
- \file{/etc/services}. It is FreeWRT policy not to start any services after
+ files as \file{/etc/services}. It is FreeWRT policy not to start any services
- installation or in case of a new boot. To start services on bootup you need to set
+ after installation or in case of a new boot. To start services on bootup you
- \code{\$servicename=YES} in \file{/etc/rc.conf} and commit your changes via
+ need to set \code{\$servicename=YES} in \file{/etc/rc.conf} and commit your
- \command{fwcf commit}. For every policy exists an exception, we start all essential services
+ changes via \command{fwcf commit}. For every policy exists an exception, we
- by default, like ssh daemon, syslog and network initialisation.
+ start all essential services by default, like ssh daemon, syslog and network
+ initialisation.
- For some services you can control the startup behaviour by modifying
+ For some services you can control the startup behaviour by modifying the
- the \code{\$servicename\_flags} variable in \file{/etc/rc.conf}.
+ \code{\$servicename\_flags} variable in \file{/etc/rc.conf}.
- For example the variable \code{\$ssh\_opts} is provided as an argument to the dropbear
+ For example the variable \code{\$ssh\_opts} is provided as an argument to the
- ssh daemon to control its behaviour.
+ 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
+ shooting yourself in the foot. For example if you try to realize a firewall
- and trying to set the rules in \file{/etc/firewall.user}, which is read by
+ system and trying to set the rules in \file{/etc/firewall.user}, which is read
- \file{/etc/init.d/S45firewall}, if the iptables package is installed. You can just
+ by \file{/etc/init.d/S45firewall}, if the iptables package is installed. You
- reload the changed ruleset via \code{/etc/init.d/S45firewall restart}. If you managed
+ can just reload the changed ruleset via \code{/etc/init.d/S45firewall restart}.
- to kick you out of the system, you can just reboot the system and you gain access
+ If you managed to kick you out of the system, you can just reboot the system
- again. As soon as your are ready with the firewall configuration and you decide
+ and you gain access again. As soon as your are ready with the firewall
- to activate the firewall rules on bootup, you set \code{firewall=YES} in
+ configuration and you decide to activate the firewall rules on bootup, you set
- \file{/etc/rc.conf},
+ \code{firewall=YES} in \file{/etc/rc.conf}, commit your changes via
- commit your changes via \command{fwcf commit} and reboot. Now the firewall
+ \command{fwcf commit} and reboot. Now the firewall rules will be activated on
- rules will be activated on bootup.
+ bootup.
  \chapter{Troubleshooting}\label{ch:troubleshooting}
  \section{Failsafe Mode}
- Failsafe mode is very useful if you misconfigured your embedded system,
+ Failsafe mode is very useful if you misconfigured your embedded system, so that
- so that you can not access it anymore. E.g. if you accidentially disabled
+ you can not access it anymore. E.g. if you accidentially disabled secure shell
- secure shell or misconfigured the firewall, so that you can not login any
+ or misconfigured the firewall, so that you can not login any more.
- more.
  When in failsafe mode, the device won't interpret any networking setup files.
  It stops even before the root filesystem gets mounted read--write, and fwcf is
  set up. It will just set the LAN interface up and give it the IP address
  \file{192.168.1.1} and netmask \file{255.255.255.0}. Then it will start a
- \app{telnet} daemon, so you get straight access (without depending on the installed SSH daemon).
+ \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
+ the failsafe utility. The failsafe utility is built inside our ADK and is
- is available in the directory \file{bin/} after a successful build.
+ available in the directory \file{bin/} after a successful build.
- If you just want to compile the tool and not a complete firmware image,
+ If you just want to compile the tool and not a complete firmware image, use
- use following command:
+ following command:
  \begin{Verbatim}[label=building the failsafe utility for the host system]
  $ make subdir=tools/failsafe install
-Line 1340 
 recognized network interface (eth0).
+Line 1409 
 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),
+ cable. Use the failsafe port (in most cases one of the LAN ports), see the
- see the device specific page for the exact network port.
+ device specific page for the exact network port.
- Configure your network interface to the IP address \file{192.168.1.2} with network
+ Configure your network interface to the IP address \file{192.168.1.2} with
- mask \file{255.255.255.0}. Now start the failsafe utility on your computer.
+ network mask \file{255.255.255.0}. Now start the failsafe utility on your
+ computer.
  \begin{Verbatim}
  $ ./failsafe
-Line 1374 
 $ telnet 192.168.1.1
+Line 1444 
 $ telnet 192.168.1.1
  \subsection{Repairing Your FreeWRT Configuration}
- If you want to repair your configuration, you first need to
+ If you want to repair your configuration, you first need to mount the root
- mount the root filesystem read--writeable. This is best done via:
+ filesystem read--writeable. This is best done via:
  \begin{Verbatim}
  # mount_root
-Line 1394 
 Do not forget to commit your changes aft
+Line 1464 
 Do not forget to commit your changes aft
  # fwcf commit
  \end{Verbatim}
- If you want to start over with the default \file{/etc/} directory, just remove the fwcf
+ If you want to start over with the default \file{/etc/} directory, just remove
- partition content with following command:
+ the fwcf partition content with following command:
  \begin{Verbatim}
  mtd erase fwcf
  \end{Verbatim}
- You can either use \command{reboot -f} or the option \command{-r} for \app{mtd} to reboot the system.
+ You can either use \command{reboot -f} or the option \command{-r} for \app{mtd}
+ to reboot the system.
  %\section{Serial Console}

 Legend:



Removed from v.2537
 


changed lines


 
Added in v.2538
 Legend:



Removed from v.2537
 


changed lines


 
Added in v.2538
-Removed from v.2537
+Added in v.2538

root@freewrt.org:443	ViewVC Help
Powered by ViewVC 1.1.20

// Log In
// CVSweb
Project: FreeWRT
// Summary // Activity // Search // Tracker // Lists // News // SCM // Wiki