Changeset 8ca8ce4 in freewrt for docs


Ignore:
Timestamp:
May 17, 2007, 10:25:52 PM (19 years ago)
Author:
Phil Sutter <n0-1@…>
Branches:
freewrt_1_0, freewrt_2_0
Children:
dac4ea5
Parents:
034cb53
Message:

Integrate some latex improvements into the handbook

  • many thanks to Lars Weiler for sending the patch
  • now there are latex commands for choosing the appropriate font style (\code{}, \app{}, \file{}, etc.)
  • some tabular environments were changed to longtable, to allow breaking them at page borders
  • always prefer Verbatim (fancyvrb) over verbatim (ugly standard)
  • added a TODO pointing to missing documentation about wireless gmodes, please someone with a clue document the different modes
  • tried to prevent automatic page breaks to keep diff small (will correct all long lines in another commit)

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

Location:
docs/handbook/user
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • docs/handbook/user/cover.tex

    r034cb53 r8ca8ce4  
    1818\\
    1919\rightline{%
    20 Revision 1.0.1}
     20Revision 1.0.1, \svnInfoRevision}
    2121\\
    2222\rightline{%
    23 World, \today
     23World, \svnToday
    2424}
    2525\vfill

  • docs/handbook/user/handbook.tex

    r034cb53 r8ca8ce4  
    1 \documentclass[12pt,a4paper,openany,smallheadings,
    2 headinclude,headsepline,final]{scrreprt}
    3 \usepackage[utf8]{inputenc}
    4 \usepackage{amsmath}
    5 \usepackage{amsfonts}
    6 \usepackage{amssymb}
    7 \usepackage{caption2}
    8 \usepackage[canadian]{babel}
    9 \usepackage{varioref}
    10 \usepackage{txfonts}
    11 \usepackage[pdftex]{graphicx}
     1\documentclass[12pt,a4paper,openany,smallheadings,headinclude,headsepline,final]{scrreprt}
     2%\usepackage{ucs} % Unicode support
     3\usepackage[utf8]{inputenc} % UTF-8 characters as input are allowed
     4%\usepackage{amsmath}
     5%\usepackage{amsfonts}
     6%\usepackage{amssymb}
     7%\usepackage{caption2}
     8\usepackage[english]{babel} % Sets the layout to English style
     9\usepackage{varioref} % Intelligent page references
     10%\usepackage{txfonts}
     11\usepackage[pdftex]{color} % Colour control for LaTeX documents
     12\usepackage[pdftex]{graphicx} % Enhanced support for graphics
    1213%\usepackage{listings}
    13 \usepackage{makeidx}
    14 \usepackage[T1]{fontenc}
    15 
    16 % fancy verbatim enables changing of font, fontsize, etc. in verbatim code
    17 % also set smaller font and a frame as default
    18 \usepackage{fancyvrb}
    19 \fvset{fontsize=\small, frame=single}
     14\usepackage{makeidx} % Standard LaTeX package for creating indexes
     15\usepackage{longtable} % Allow tables to flow over page boundaries
     16\usepackage[T1]{fontenc} % T1-fonts
     17\usepackage{fancyvrb} % Sophisticated verbatim text
     18\usepackage[a4paper,rmargin=2cm,lmargin=2cm,tmargin=2.5cm,bmargin=3.5cm]{geometry} % Flexible and complete interface to document dimensions
     19\usepackage{fixltx2e, mparhack} % Patches for LaTeX; A workaround for a LaTeX bug in marginpars
     20\usepackage[nofancy]{svninfo} % Typeset Subversion Keywords
     21\usepackage{float} % Improved interface for floating objects
     22\usepackage{hyperref} % Extensive support for hypertext in LaTeX
     23
    2024
    2125% marvosym macht Pfeil kaputt, also sichern
    2226% line 28, /usr/share/texmf/tex/latex/marvosym/marvosym.sty
    23 \let\RescueRightarrow=\Rightarrow
    24 \usepackage{marvosym}
    25 \renewcommand{\Rightarrow}{\RescueRightarrow}
    26 
    27 \usepackage[pdftex]{color}
     27%\let\RescueRightarrow=\Rightarrow
     28%\usepackage{marvosym}
     29%\renewcommand{\Rightarrow}{\RescueRightarrow}
     30
    2831\definecolor{skyblue}{rgb}{0,0.3323,0.5720}
    29 \usepackage[%
    30 colorlinks=true,anchorcolor=red,
    31 breaklinks=true,linkcolor=blue,urlcolor=red,
    32 citecolor=skyblue,
    33 pdfauthor={The FreeWRT Team},
    34 pdftitle={FreeWRT User Handbook},
    35 pdfcreator={tetex and VIM},
    36 pdfsubject={Open Source},
    37 pdfview=FitV,
    38 pdfstartview=FitV,
    39 pdfstartpage={1},
    40 pdfpagelayout=SinglePage,
    41 pdfpagemode=None,
    42 pdfkeywords={FreeWRT}]{hyperref}
    43 \usepackage{cancel}
     32\restylefloat{figure}
     33\hypersetup{
     34        colorlinks=true,anchorcolor=red,
     35        breaklinks=true,linkcolor=blue,urlcolor=red,
     36        citecolor=skyblue,
     37        pdfauthor={The FreeWRT Team},
     38        pdftitle={FreeWRT User Handbook},
     39        pdfcreator={tetex and VIM},
     40        pdfsubject={Open Source},
     41        pdfview=FitV,
     42        pdfstartview=FitV,
     43        pdfstartpage={1},
     44        pdfpagelayout=SinglePage,
     45        pdfpagemode=None,
     46        pdfkeywords={FreeWRT}
     47}
     48\fvset{fontsize=\small, frame=single} % fancyvrb: set small font size and enable frames
     49%\usepackage{cancel}
    4450%\usepackage[final, activate, verbose=true]{microtype}
    45 \usepackage{ngerman}
     51%\usepackage{ngerman}
    4652%\usepackage{bookman}
    4753%\usepackage[a4paper,twoside,rmargin=2cm,lmargin=2cm,tmargin=2.5cm]{geometry}
    48 \usepackage[a4paper,rmargin=2cm,lmargin=2cm,tmargin=2.5cm,bmargin=3.5cm]{geometry}
     54%\usepackage[a4paper,rmargin=2cm,lmargin=2cm,tmargin=2.5cm,bmargin=3.5cm]{geometry}
    4955%\usepackage{ncntrsbk}
    50 \usepackage{float}
    51 \restylefloat{figure}
     56%\usepackage{float}
     57%\restylefloat{figure}
    5258%\bibliographystyle{alphadin}
    53 \bibliographystyle{alpha}
    54 
    55 % Change Section, Chapter Layout
    56 % http://www.mackichan.com/index.html?techtalk/518.htm~mainFrame
    57 %\usepackage{sectsty}
    58 %\allsectionsfont{\raggedleft}
    59 %\chapterfont{\raggedleft}
    60 
    61 % BEGIN Fancy Header Extensions
    62 % Save Graphics in Latex box
    63 %\renewcommand{\headheight}{30pt} %Make height wider so picture is ok
    64 %\renewcommand{\footskip}{45pt} %Make height wider so picture is ok
    65 
    66 \usepackage{fixltx2e, mparhack}
     59%\bibliographystyle{alpha}
    6760
    6861% Generate index in preamble
    6962\makeindex
     63
    7064\begin{document}
     65\svnInfo $Id$
    7166\setlength{\marginparwidth}{10mm}
     67
    7268\include{cover}
     69
    7370\renewcommand{\thepage}{\roman{page}}
    7471\tableofcontents
    … …  
    8582\renewcommand{\sectionmark}[1]{\markright{\thesection.\ \scshape #1}}
    8683
    87 %Bilitz
    88 %\newcommand{\blitz}{ \mbox{\Huge \Lightning} }
    89 \newcommand{\blitz}{ \Lightning }
    90 \newcommand{\entspr}{\stackrel{\wedge}{=}}
    91 
     84
     85% Create some new commands for designing the text
     86% applications
     87\newcommand{\app}[1]{%
     88        \textsf{\textit{#1}}}
     89% terminology, vendor or product names
     90\newcommand{\term}[1]{%
     91        \textsc{#1}}
     92% filenames and directories
     93\newcommand{\file}[1]{%
     94        \textsf{#1}}
     95% user input
     96\newcommand{\command}[1]{%
     97        \texttt{\textbf{#1}}}
     98% example code, output of applications
     99\newcommand{\code}[1]{%
     100        \texttt{#1}}
     101% emphasized text (nicer than \emph{})
     102\newcommand{\strong}[1]{%
     103        \textbf{#1}}
    92104
    93105
    … …  
    100112systems. The latest version of this document is always available at the
    101113FreeWRT website. If you have any comments, criticism or found some wrong
    102 description, please send us an e-mail to freewrt-handbook@freewrt.org, we are
     114description, please send us an e-mail to
     115\href{mailto:freewrt-handbook@freewrt.org}{freewrt-handbook@freewrt.org}, we are
    103116always happy about getting feedback to this document, and will try to update
    104117or correct the issues mentioned by you.
    105118
    106 The FreeWRT User handbook is split into five distinct sections. Appliance
    107 Development Kit covers the building of FreeWRT firmware images. The second
    108 section, Installing FreeWRT, covers all aspects regarding the installation and
    109 deinstallation of FreeWRT firmware images. The third section is a detailed
    110 description of the startup process of FreeWRT.  The fourth section, Using FreeWRT,
    111 covers administrational tasks, such as network configuration, the FreeWRT
    112 configuration filesystem, package management and update mechanism. The last
    113 section helps troubleshooting problems and recovering a bad firmware installation.
    114 The appendix contains board specific information. For FreeWRT 1.0 these are only
     119The FreeWRT User handbook is split into several distinct chapters.
     120\nameref{ch:ADK} covers the building of FreeWRT firmware images.
     121In \autoref{ch:installing}, \nameref{ch:installing}, all aspects regarding the
     122installation and deinstallation of FreeWRT firmware images are covered.  The
     123next chapter, \nameref{ch:administration}, covers administrational tasks, such
     124as network configuration, the FreeWRT configuration filesystem, package
     125management and update mechanism. The last chapter, \nameref{ch:troubleshooting},
     126helps troubleshooting problems and recovering a bad firmware installation.  The
     127appendix contains board specific information. For FreeWRT 1.0 these are only
    115128Broadcom based embedded systems.
    116129
    … …  
    123136\section{Typographic Conventions}
    124137
    125 Examples starting with \# indicate a command that must be invoked as super
    126 user. You can use su to gain super user privileges.
    127 
    128 \begin{Verbatim}
     138Examples starting with \code{\#} indicate a command that must be invoked as super
     139user. You can use \command{su} to gain super user privileges.
     140
     141\begin{Verbatim}[label=example for a command line with super user privileges]
    129142# fwcf commit
    130143\end{Verbatim}
    131144
    132 Examples starting with \$ indicate a command that can be invoked as a normal
    133 user.  The default user account on a freshly installed FreeWRT system is
    134 ,,admin'', the password ,,FreeWRT''.
    135 
    136 \begin{Verbatim}
     145Examples starting with \code{\$} indicate a command that can be invoked as a
     146normal user.  The default user account on a freshly installed FreeWRT system is
     147"\code{admin}", the password "\code{FreeWRT}".
     148
     149\begin{Verbatim}[label=example for a command line as non-privileged user]
    137150$ cat /etc/banner
    138151\end{Verbatim}
    139152
    140 \chapter{Appliance Development Kit (ADK)}
     153%\chapter{Web Interface Builder (WIB)}\label{ch:WIB}
     154%
     155%FIXME It is named later in the text, but not explained what it is.  Probably
     156%this chapter can be joined with the chapter about ADK
     157
     158\chapter{Appliance Development Kit (ADK)}\label{ch:ADK}
    141159
    142160The ADK is the core of FreeWRT and contains all scripts and sources to create
    … …  
    145163
    146164\begin{itemize}
    147 \item Asus WL500g
    148 \item Asus WL500g deluxe
    149 \item Asus WL500g premium
    150 \item Linksys WRT54G v2.0
    151 \item Linksys WRT54G v2.2
    152 \item Linksys WRT54G v3.0
    153 \item Linksys WRT54G v3.1
    154 \item Linksys WRT54G v4.0
    155 \item Linksys WRT54GS v1.0
    156 \item Linksys WRT54GS v1.1
    157 \item Linksys WRT54GS v4
    158 \item Linksys WRT54G3G
    159 \item Linksys WRT54GL
    160 \item Netgear WGT634u
     165        \item Asus WL500g
     166        \item Asus WL500g deluxe
     167        \item Asus WL500g premium
     168        \item Linksys WRT54G v2.0
     169        \item Linksys WRT54G v2.2
     170        \item Linksys WRT54G v3.0
     171        \item Linksys WRT54G v3.1
     172        \item Linksys WRT54G v4.0
     173        \item Linksys WRT54GS v1.0
     174        \item Linksys WRT54GS v1.1
     175        \item Linksys WRT54GS v4
     176        \item Linksys WRT54G3G
     177        \item Linksys WRT54GL
     178        \item Netgear WGT634u
    161179\end{itemize}
    162180
    … …  
    172190
    173191\begin{itemize}
    174 \item Debian GNU/Linux
    175 \item Gentoo Linux
    176 \item OpenSuSE
    177 \item Ubuntu GNU/Linux
    178 \item Fedora Core
    179 \item OpenBSD (partial support)\footnote{some addon packages does not compile}
    180 \item MirOS BSD (partial support)\footnote{some addon packages does not compile}
     192        \item Debian GNU/Linux
     193        \item Gentoo Linux
     194        \item OpenSuSE
     195        \item Ubuntu GNU/Linux
     196        \item Fedora Core
     197        \item OpenBSD (partial support)\footnote{some addon packages does not compile}
     198        \item MirOS BSD (partial support)\footnote{some addon packages does not compile}
    181199\end{itemize}
    182200
    … …  
    187205
    188206\begin{itemize}
    189 \item gcc3 or higher
    190 \item g++
    191 \item binutils
    192 \item patch
    193 \item gzip
    194 \item bzip2
    195 \item unzip
    196 \item flex
    197 \item bison
    198 \item GNU make
    199 \item zlib (+headers)
    200 \item ncurses (+headers)
    201 \item (g)libc headers
    202 \item perl
     207        \item gcc3 or higher
     208        \item g++
     209        \item binutils
     210        \item patch
     211        \item gzip
     212        \item bzip2
     213        \item unzip
     214        \item flex
     215        \item bison
     216        \item GNU make
     217        \item zlib (+headers)
     218        \item ncurses (+headers)
     219        \item (g)libc headers
     220        \item perl
    203221\end{itemize}
    204222
    … …  
    213231
    214232Now go to a directory where you want to build the firmware. Depending on the
    215 features you select you will need about 2.5-5 GB free disk space. This
     233features you select you will need about 2.5--5 GB free disk space. This
    216234includes the ADK itself, any source archives which will be downloaded
    217235and their extracted copies (for compiling).
    218236
    219237To get the latest stable FreeWRT ADK try one of these commands:
    220 Via HTTP protocol:
    221 \begin{verbatim}
     238\begin{Verbatim}[label=Check out the 1.0-branch of FreeWRT ADK via HTTP protocol]
    222239$ svn co http://www.freewrt.org/svn/tags/freewrt_1_0_x freewrt
    223 \end{verbatim}
    224 Via subversion protocol:
    225 \begin{verbatim}
     240\end{Verbatim}
     241\begin{Verbatim}[label=Check out the 1.0-branch of FreeWRT ADK via subversion protocol]
    226242$ svn co svn://www.freewrt.org/itags/freewrt_1_0_x freewrt
    227 \end{verbatim}
    228 
    229 The value \dq{}x\dq{} is a place holder for the latest minor release number.
     243\end{Verbatim}
     244
     245The value $x$ is a place holder for the latest minor release number.
    230246Take a look at our project page to find out which minor release number is the latest one.
    231247
    … …  
    241257
    242258Building a FreeWRT firmware image is just like building a new Linux kernel,
    243 but a little more complex. There is a ncurses-based configuration menu at the
    244 beginning, the changes made are saved into a file named ,,.config'' in the ADK
     259but a little more complex. There is a \app{ncurses}-based configuration menu at the
     260beginning, the changes made are saved into a file named \file{.config} in the ADK
    245261root. The build is done by the various Makefiles, compiling and linking the
    246 sources together accordingly to the symbols defined in ,,.config''.
     262sources together accordingly to the symbols defined in \file{.config}.
    247263
    248264Unlike kernel compilation, FreeWRT needs to be cross-compiled. This
    249265leads to special premises, as most of the tools need to be specially build.
    250266But no panic, FreeWRT will do this all for you. In fact, this is done at the
    251 second run of \texttt{make} (the first one opens the configuration), and
     267second run of \command{make} (the first one opens the configuration), and
    252268therefore can be seen as part of the first firmware build.  For clarity
    253269though, we will discuss these two things separately.
    … …  
    259275
    260276\subsection{Creating A Configuration}
    261 The first step is to run \texttt{make}. After checking some prerequisites (see
    262 ,,Troubleshooting'' below for aid in problems), a console based configuration
     277
     278The first step is to run \command{make}. After checking some prerequisites (see
     279\nameref{ch:troubleshooting} below for aid in problems), a console based configuration
    263280menu should start. Theoretically no choices have to be made, but it's proven
    264281useful to at least:
    265282\begin{itemize}
    266 \item select a target (menu: ,,Embedded System'')
    267 \item select the root filesystem type (menu: ,,Target Firmware type'')
     283        \item select a target (menu: \code{Embedded System})
     284        \item select the root filesystem type (menu: \code{Target Firmware type})
    268285\end{itemize}
    269286
    270 Then quit saving changes. If you forgot that, just run \texttt{make} again, redo
     287Then quit saving changes. If you forgot that, just run \command{make} again, redo
    271288your changes, then save.
    272289
    … …  
    274291
    275292Now that you have a first minimal configuration, it is time to build the toolchain
    276 for cross-compiling. To do this, just enter {{{make}}} again. The build starts
     293for cross-compiling. To do this, just enter \command{make} again. The build starts
    277294downloading and compiling each needed part of the toolchain, and later continues
    278295with building the first firmware image. Later one can be taken as proof of a
    279296working ADK.
    280297
    281 Already experienced in compiling gcc? Then you know... If not, better be told
     298Already experienced in compiling \app{gcc}? Then you know\dots If not, better be told
    282299that it takes \underline{really long} to finish. In the meantime I suggest reading the
    283300next chapter dealing with internals about cross-compiling.
    … …  
    286303
    287304A cross-compile toolchain exists of a set of tools: a compiler, linker, assembler,
    288 debugger and a c library. A cross-compile toolchain runs on your host system and
     305debugger and a C~library. A cross-compile toolchain runs on your host system and
    289306creates native binaries for your target system. A cross-compile toolchain is
    290307basically created in six steps:
    291308
    292309\begin{enumerate}
    293 \item Get and prepare the Kernel and C Library headers of your target system
    294 \item Compile the binutils package for your target
    295 \item Compile a static C compiler for your target
    296 \item Compile and install a C library for your target
    297 \item Compile and install a full C/C++ compiler
    298 \item Compile and install the GNU debugger
     310        \item Get and prepare the Kernel and C~library headers of your target system
     311        \item Compile the binutils package for your target
     312        \item Compile a static C~compiler for your target
     313        \item Compile and install a C~library for your target
     314        \item Compile and install a full C/C++~compiler
     315        \item Compile and install the GNU debugger
    299316\end{enumerate}
    300317
    301318The cross-compile toolchain is created in
    302 ,,staging\_dir\_\$(cpu\_arch)''\footnote{f.e. mipsel, which stands for MIPS Little
    303 Endian)}. All the tools running on the host, but used to create, analyze or debug
     319\file{staging\_dir\_\$(cpu\_arch)}\footnote{e.g. mipsel, which stands for MIPS
     320Little Endian}. All the tools running on the host, but used to create, analyze or debug
    304321for the target are kept in this directory. All addon headers and libraries
    305322are installed to this directory.
    306323
    307324If you want to compile a simple application without using the ADK, just use the
    308 compiler directly (f.e. compiling a MIPS Little Endian application):
    309 \begin{verbatim}
     325compiler directly (e.g. compiling a MIPS Little Endian application):
     326\begin{Verbatim}[label=compile a simple application with the cross-compiler]
    310327./staging_dir_mipsel/bin/mipsel-linux-uclibc-gcc -o myapp myapp.c
    311 \end{verbatim}
    312 
    313 Check with ,,file'' if you got a MIPS binary:
    314 \begin{verbatim}
     328\end{Verbatim}
     329
     330Check with the tool \app{file} if you got a MIPS binary:
     331\begin{Verbatim}[label=check the binary with \app{file}]
    315332$ file myapp
    316333myapp: ELF 32-bit LSB MIPS-I executable, MIPS, version 1 (SYSV), dynamically
    317334linked (uses shared libs), not stripped
    318 \end{verbatim}
     335\end{Verbatim}
    319336
    320337\section{Building A FreeWRT Firmware Image}
    … …  
    322339Your local copy of the FreeWRT ADK should now be prepared for building firmware
    323340images. The next step is to do an extensive configuration for the image you
    324 want to create. To start the configuration menu, type ,,\texttt{make menuconfig}''.
    325 
    326 When selecting packages, \texttt{<*>} means it will be inserted into the firmware
    327 images and \texttt{<M>} means it will be build as an addon package which can be
     341want to create. To start the configuration menu, type \command{make menuconfig}.
     342
     343When selecting packages, \code{<*>} means it will be inserted into the firmware
     344images and \code{<M>} means it will be build as an addon package which can be
    328345installed later at runtime.
    329346
    330347The target device and filesystem should already been chosen by you to the right
    331 value, if not you will have to issue a ,,\texttt{make clean}'' before actually
     348value, if not you will have to issue a \command{make clean} before actually
    332349building the firmware image. Otherwise things get messed up. A smooth
    333350rebuild is a missing feature in the current ADK. For the packages, if unsure, you
    … …  
    336353forget to save your configuration when leaving!
    337354
    338 After leaving the menubased configuration, type ,,\texttt{make}'' again to build
     355After leaving the menubased configuration, type \command{make} again to build
    339356the new FreeWRT firmware image. Depending on your package selections and
    340357underlying hardware, this will take different amounts of time. For your spare time
    … …  
    345362
    346363Just like when building the ADK's toolchain, the sources for the selected
    347 packages are downloaded from the internet first, then build using the
     364packages are downloaded from the internet first, then built using the
    348365cross-compiler and libraries of the ADK.
    349366
    … …  
    351368
    352369\begin{itemize}
    353 \item compile the Linux kernel and all supported kernel modules
    354 \item compile all selected packages
    355 \item clean the target root directory
    356 \item install all packages to the target root directory
    357 \item create the root filesystem image
    358 \item create the firmware image (bootloader, kernel and root filesystem)
     370        \item compile the Linux kernel and all supported kernel modules
     371        \item compile all selected packages
     372        \item clean the target root directory
     373        \item install all packages to the target root directory
     374        \item create the root filesystem image
     375        \item create the firmware image (bootloader, kernel and root filesystem)
    359376\end{itemize}
    360377
    361 The result of the build process is created in the ,,bin'' directory.
     378The result of the build process is created in the directory \file{bin/}.
    362379You will find a firmware image in the top level directory. Check the size of
    363 the bin-file to see if it is small enough to fit into flash memory of
    364 your embedded system. Furthermore there is a ,,package'' directory, which
    365 contains all base and addon packages.
     380the binary image file to see if it is small enough to fit into flash memory of
     381your embedded system. Furthermore there is a directory \file{package/}, which
     382contains all base and add--on packages.
    366383
    367384\section{Troubleshooting}
     385
    368386This section deals with various tips for problems with the ADK installation.
    369387
    370388\subsection{Errors During Prerequisites Check}
    371 To re-issue the checks, use ,,make prereq''.
     389
     390To re-issue the checks, use \command{make prereq}.
    372391
    373392\begin{itemize}
    374 \item GNU make 3.80 too old
     393\item GNU make 3.80 too old \\
    375394   On a Fedora Core 4 hostsystem the first you'll get is
    376 \begin{verbatim}
     395        \begin{Verbatim}[label=error message with too old GNU make]
    377396   $ make
    378397   GNU make 3.80 too old.
    … …  
    382401   GNU Bison 2.3 because of its bug fixes.
    383402   make: *** [.prereq_done] Error 1
    384 \end{verbatim}
    385 
     403        \end{Verbatim}
    386404   it is quite a nice error that tells you to use more up to date software, but we can
    387    anyhow give this hostsystem a try and tell make to ignore those errors/warnings:
    388 \begin{verbatim}
    389      make prereq-noerror
    390 \end{verbatim}
     405   anyhow give this hostsystem a try and tell make to ignore those
     406   errors/warnings running \command{make prereq-noerror}.
    391407\end{itemize}
    392408
    … …  
    394410
    395411If you encounter any compilation errors, then first try to reproduce the error.
    396 First update your ADK tree via ,,svn update'', to be sure that the error is not
    397 already fixed in the subversion repository. After that do a ,,make clean \&\&
    398 make'', to reproduce your problem.
     412First update your ADK tree via \command{svn update}, to be sure that the error is not
     413already fixed in the subversion repository. After that do a \command{make clean
     414\&\& make}, to reproduce your problem.
    399415
    400416If you can reproduce the problem, please file a bug report. Please always
    401417report following information:
    402418\begin{itemize}
    403 \item Operating system type and version
    404 \item GCC and Binutils versions of your host system
    405 \item complete error message, not only the last 4 lines
     419        \item Operating system type and version
     420        \item GCC and Binutils versions of your host system
     421        \item complete error message, not only the last 4 lines
    406422\end{itemize}
    407423
    408 \chapter{Installing FreeWRT Firmware Images}
     424\chapter{Installing FreeWRT Firmware Images}\label{ch:installing}
    409425
    410426The FreeWRT ADK produces a single image holding both kernel and root
    411427filesystem. This image can be written into your hardware's builtin flash memory
    412428on serveral ways (ordered by needed skills, increasing downwards):
    413 \begin{itemize} % TODO: insert \ref's to jump to the appropriate section?
    414 \item via the original firmware's web interface
    415 \item via \texttt{mtd} when reflashing or migrating from another third party distribution
    416 \item via network using a TFTP client
     429\begin{itemize}
     430        \item via the original firmware's web interface
     431        (\autoref{sec:webinterface})
     432        \item via \texttt{mtd} when reflashing or migrating from another third
     433        party distribution (\autoref{sec:mtd})
     434        \item via network using a TFTP client (\autoref{sec:tftp})
    417435\end{itemize}
    418436
    419437\section{Flashing The Firmware}
    420438
    421 \subsection{Web Interface Method}
     439\subsection{Web Interface Method}\label{sec:webinterface}
     440
    422441The following text describes how to use the original firmware's web interface
    423 to flash FreeWRT. The object of demonstration is an Asus WL500gP, but this
     442to flash FreeWRT. The object of demonstration is an \term{Asus WL500gP}, but this
    424443guide should fit more or less fine for other systems, too.
    425444
    426 If you flash a router from Linksys, we strongly suggest to use the popular
    427 \textbf{ping exploit} to allow recovery, if your image is broken or the flash
     445If you flash a router from \term{Linksys}, we strongly suggest to use the popular
     446\term{ping exploit} to allow recovery, if your image is broken or the flash
    428447process was interrupted by a power shortage.
    429448
    430449There are some things that you should have done previously:
    431450\begin{itemize}
    432 \item read the special documentation page about your hardware in our wiki, some
    433       systems need special precaution before flashing
    434 \item a firmware image has to be built (matching the used hardware, of course)
    435 \item the router has to be powered on
    436 \item your computer needs to be connected to one of the LAN ports (using IP
    437 address 192.168.1.2)
     451        \item read the special documentation page about your hardware in our wiki, some
     452              systems need special precaution before flashing
     453        \item a firmware image has to be built (matching the used hardware, of course)
     454        \item the router has to be powered on
     455        \item your computer needs to be connected to one of the LAN ports
     456                (using IP address \file{192.168.1.2})
    438457\end{itemize}
    439458
    440459\parbox{17em}{
    441460After preparation is complete, open your favourite browser and type
    442 \texttt{192.168.1.1} into the address bar. You should reach the web interface's
     461\command{192.168.1.1} into the address bar. You should reach the web interface's
    443462startup page:
    444463}\hfill\parbox{20em}{\includegraphics[width=20em]{pics/asus-startup.png}} \\ [1em]
    445464\parbox{17em}{
    446 Then click \textit{System Setup}:
     465Then click on \code{System Setup}:
    447466}\hfill\parbox{20em}{\includegraphics[width=20em]{pics/asus-system_setup.png}} \\ [1em]
    448467\parbox{17em}{
    449 Then click \textit{Firmware Upgrade}, and enter the name of your firmware image
     468In the new menu click on \code{Firmware Upgrade}, and enter the name of your firmware image
    450469into the appropriate field:
    451470}\hfill\parbox{20em}{\includegraphics[width=20em]{pics/asus-fw_upgrade.png}} \\ [1em]
    452 Finally click \textit{Upload}. As the whole process of writing the image to
    453 flash and rebooting (don't forget that it creates ssh hostkeys on first boot)
    454 takes quite long, better go and get a coffee or tea.
    455 
    456 When everything went good, you can login using ssh. The default username is
    457 \dq{}admin\dq{}. The default password for images created via WIB or ADK is
    458 \dq{}FreeWRT\dq{}. It is possible to change this password in the ADK, before image
    459 creation.
    460 
    461 \subsection{\texttt{mtd} -- The Flash Utility}
     471Finally click on \code{Upload}. As the whole process of writing the image to
     472flash and rebooting (don't forget that it creates \app{ssh} hostkeys on first boot)
     473takes quite long (yes, a couple of minutes). Better go and get a coffee or tea.
     474
     475When everything went well, you can login using \app{ssh}. The default username is
     476"\code{admin}". The default password for images created via WIB or ADK is
     477"\code{FreeWRT}". It is possible to change this password in the ADK,
     478before image creation.
     479
     480\subsection{\texttt{mtd} -- The Flash Utility}\label{sec:mtd}
    462481
    463482For this method to work, you need to copy the file containing the firmware
    464 image to the router, preferably into /tmp, the memory filesystem should be
    465 big enough to hold the full image. If not, use wget to get the image
    466 via http or ftp and pipe the result into \texttt{mtd}.
    467 
    468 Then the image is written to flash using
    469 \texttt{mtd}, optionally giving additional options (see below).
    470 
    471 The \texttt{mtd} utility was written with simplicity and code size in mind.
    472 It's features were derived from the mtd-utils, %TODO: insert \ref to homepage
     483image to the router, preferably into \file{/tmp/}, the memory filesystem should be
     484big enough to hold the full image. If not, use \app{wget} to get the image
     485via http or ftp and pipe the result into \app{mtd}.
     486
     487Then the image is written to flash using \app{mtd}, optionally giving
     488additional options (see below).
     489
     490The \app{mtd} utility was written with simplicity and code size in mind.
     491It's features were derived from the
     492\href{http://sources.redhat.com/jffs2/}{\app{mtd-utils}},
    473493combining the needed parts into a single small tool providing all the
    474494functionality necessary for FreeWRT, and leaving everything out that's not.
    475495
    476 \texttt{mtd} provides the following features:
     496\app{mtd} provides the following features:
    477497\begin{description}
    478 \item[unlock] some chips need unlocking before they can be written to
    479 \item[erase] this is a filesystem independent method to delete all contents on
    480         the flash. Basically this is like \texttt{format} in MS--DOS.
    481 \item[write] this is generally the same functionality as using
    482         \texttt{dd} or \texttt{rawrite}, but \texttt{mtd} takes care of the quirks
    483         that have to be paid attention to for correctly handling the type of flash
    484         in use
     498        \item[unlock] some chips need unlocking before they can be written to
     499        \item[erase] this is a filesystem independent method to delete all contents on
     500                the flash. Basically this is like \app{format} in MS--DOS.
     501        \item[write] this is generally the same functionality as using
     502                \app{dd} or \app{rawrite}, but \app{mtd} takes care of the quirks
     503                that have to be paid attention to for correctly handling the type of flash
     504                in use
    485505\end{description}
    486506
    … …  
    491511Mostly, similar to the sample usage shown in the help output should be all that has to be
    492512done to write the firmware to flash:
    493 \begin{Verbatim}
     513\begin{Verbatim}[label=write a previously downloaded new firmware-file into flash]
    494514# mtd -e linux -r write freewrt.bin linux &
    495515\end{Verbatim}
    496516Or via wget pipe:
    497 \begin{Verbatim}
     517\begin{Verbatim}[label=download and write a new firmware-file into flash]
    498518# wget -O - http://www.yourserver.com/freewrt.bin | mtd -e linux -r write - linux &
    499519\end{Verbatim}
    500 The parameters explained in detail: \\
    501 \begin{tabular}{l|l}
    502 -e linux & erase existing data in flash\\
    503 -r & trigger rebooting right after finishing work\\
    504 write & write the firmware image contained in the file given as next parameter
    505                         to flash\\
    506 freewrt.bin & the actual image to write - ignore the suffix, it is detected at
    507                                 runtime\\
    508 linux & this is an abstract identifier for a certain partition in flash, so
    509 don't change this\\
    510 \& & put the process into background, to prevent accidentally stopping\\
    511 \end{tabular}
    512 
    513 \subsection{Installation using TFTP}
     520The parameters explained in detail:
     521\begin{description}
     522        \item[\command{-e linux}] erase existing data in flash
     523        \item[\command{-r}] trigger rebooting right after finishing work
     524        \item[\command{write}] write the firmware image contained in the file given as
     525                next parameter to flash
     526        \item[\command{freewrt.bin}] the actual image to write -- ignore the suffix,
     527                it is detected at runtime
     528        \item[\command{linux}] this is an abstract identifier for a certain partition
     529                in flash, so don't change this
     530        \item[\command{\&}] put the process into background, to prevent accidentally
     531                stopping
     532\end{description}
     533
     534\subsection{Installation using TFTP}\label{sec:tftp}
    514535
    515536All supported target devices are shipped with a builtin bootloader, comparable to
    516 the BIOS of x86--machines. This bootloader is used to bootstrap the system until
     537the BIOS of \term{x86} machines. This bootloader is used to bootstrap the system until
    517538it can boot a regular operating system. Besides the ability to load
    518539the executable code from flash, it can be received from another node in the
    519540local area network via the famous TFTP protocol.
    520541
    521 For doing this, there are two ways: \\
     542For doing this, there are two ways:
    522543\begin{itemize}
    523 \item the device acts as a client, asks the local dhcpd for a lease, the
    524 address of the next tftpd and the filename to download
    525 \item the device acts as a server, having a known IP address and waiting for
    526 any TFTP client to connect and send the file
     544        \item the device acts as a client, asks the local \app{dhcpd} for a lease, the
     545                address of the next \app{tftpd} and the filename to download
     546        \item the device acts as a server, having a known IP address and waiting for
     547                any TFTP client to connect and send the file
    527548\end{itemize}
    528549
    529550Most of the hardware supported by FreeWRT 1.0 uses the second method.  Only the
    530 device Netgear WGT634u is using the first method, the bootloader provides a
     551device \term{Netgear WGT634u} is using the first method, the bootloader provides a
    531552DHCP/TFTP client. Though this may be a little confusing to people being familiar
    532553with netboot technologies, it is definitely the easier way of doing it. Otherwise
    … …  
    536557made even more easy by providing a little shell script for the job. Invocation
    537558is as follows:
    538 \begin{Verbatim}
     559\begin{Verbatim}[label=sending the new firmware via TFTP]
    539560$ ./scripts/flash.sh firmware.bin [address]
    540561\end{Verbatim}
    541 The second Parameter \textit{address} is used to specify a different IP address
    542 of the target device than the default \textit{192.168.1.1}.
    543 
    544 \textbf{Beware:} do not rename the firmware image before flashing it using the
     562The second Parameter \code{address} is used to specify a different IP address
     563of the target device than the default \file{192.168.1.1}.
     564
     565\strong{Beware:} do not rename the firmware image before flashing it using the
    545566script as the original name is parsed to guess what hardware is to be flashed.
    546567
    … …  
    550571default. The following list shows what has to be done for a certain device to
    551572get it to wait at boot: \\
    552 \begin{center}\begin{tabular}{l|l|l} % TODO: fill this table
    553 \textbf{Target Device} & \textbf{Action to be taken} & \textbf{Comments} \\
    554 \hline
    555 All supported Linksys models & Ping Exploit & nvram variable boot\_wait needs to be on \\
    556 All supported Asus models & Recovery mode & power off, push and hold the
    557 reset button, power on, power led is flashing\\
    558 \end{tabular}\end{center}
    559 
    560 \chapter{FreeWRT Administration}
     573\begin{center}
     574        \begin{tabular}{l|l|p{7cm}} % TODO: fill this table
     575                \strong{Target Device} & \strong{Action to be taken} & \strong{Comments} \\
     576                \hline
     577                All supported Linksys models & Ping Exploit & nvram variable \code{boot\_wait} needs to be on \\
     578                All supported Asus models & Recovery mode & power off
     579                                                            $\rightarrow$ push and hold the reset button
     580                                                            $\rightarrow$ power on
     581                                                            $\rightarrow$ power led is flashing\\
     582        \end{tabular}
     583\end{center}
     584
     585\chapter{FreeWRT Administration}\label{ch:administration}
    561586
    562587After the FreeWRT firmware image has been built by the ADK and later flashed
    … …  
    567592\section{Network Configuration}
    568593
    569 The device names for real network interfaces in Linux are named ethx (x is
    570 0-9). If the device has a switch, the different ports are separated via VLAN
    571 technology. The vlan interfaces are named ethx.y.  The network configuration in
    572 FreeWRT is managed via Busybox's ifupdown implementation. Busybox's ip builtin
    573 command configures the network interfaces. There is no \texttt{ifconfig} or \texttt{route}.
     594The device names for real network interfaces in Linux are named \code{ethx} (\code{x} is
     595\code{0--9}). If the device has a switch, the different ports are separated via VLAN
     596technology. The vlan interfaces are named \code{ethx.y}.  The network configuration in
     597FreeWRT is managed via \app{Busybox}'s \app{ifupdown} implementation. \app{Busybox}'s builtin \app{ip}
     598command configures the network interfaces. There is no \app{ifconfig} or \app{route}.
    574599To show all configured network interfaces use:
    575 \begin{Verbatim}
     600\begin{Verbatim}[label=show IP address]
    576601$ ip addr show
    577602\end{Verbatim}
    578603To show the kernel routing table use:
    579 \begin{Verbatim}
     604\begin{Verbatim}[label=show routing table]
    580605$ ip route show
    581606\end{Verbatim}
    582607
    583 All available network settings can be found in \texttt{/etc/network/interfaces}
     608All available network settings can be found in \file{/etc/network/interfaces}
    584609which has the common form:
    585 \begin{Verbatim}[label=/etc/network/interfaces]
     610\begin{Verbatim}[label=common form of \file{/etc/network/interfaces}]
    586611auto <iface-name>
    587612iface <iface-name> inet <method>
    … …  
    591616\end{Verbatim}
    592617
    593 \texttt{auto <iface-name>} is optional and, if set, tells the "ifup" script to
     618\code{auto <iface-name>} is optional and, if set, tells the \app{ifup} script to
    594619start this interface automatically on bootup.
    595620
    596621Each interface needs a unique name which, depending on the method, represents
    597 either a physical interface or a logical interface name like "eth0.1" for a
    598 physical VLAN or "umts" as a logical name for a PPP interface.
     622either a physical interface or a logical interface name like \code{eth0.1} for a
     623physical VLAN or \code{umts} as a logical name for a PPP interface.
    599624
    600625Possible methods are:
    601626\begin{description}
    602 \item[static] use the given options to configure the interface statically
    603 \item[dhcp] just start a dhcp client using the interface \texttt{iface-name}
    604 \item[manual] don't configure the interface but start pre-up.d hook scripts
    605 \item[ppp] run \texttt{pon <provider>} where \texttt{<provider>} is given as an interface option
     627        \item[static] use the given options to configure the interface statically
     628        \item[dhcp] just start a dhcp client using the interface \code{iface-name}
     629        \item[manual] don't configure the interface but start \code{pre-up.d} hook scripts
     630        \item[ppp] run \code{pon <provider>} where \code{<provider>} is given as an interface option
    606631\end{description}
    607632
    … …  
    610635using VLAN tagging. You can configure the switch by simply adding the interface
    611636to the config file and giving the desired switch-ports:
    612 \begin{Verbatim}[label=/etc/network/interfaces]
     637\begin{Verbatim}[label=\file{/etc/network/interfaces}]
    613638auto eth0.0
    614639iface eth0.0 inet static
    … …  
    631656\end{Verbatim}
    632657
    633 This configures three VLAN interfaces \texttt{eth0.0} on ports 1 and 2,
    634 \texttt{eth0.1} on port 3 and 4 and \texttt{eth0.2} on port 0.
    635 
    636 
    637 If you need to do some advanced settings, because you have for example 
    638 a powerful switch with a VLAN trunking port connected to one of your switch 
     658This configures three VLAN interfaces \code{eth0.0} on ports 1 and 2,
     659\code{eth0.1} on port 3 and 4 and \code{eth0.2} on port 0.
     660
     661
     662If you need to do some advanced settings, because you have for example
     663a powerful switch with a VLAN trunking port connected to one of your switch
    639664ports, the configuration would look like this:
    640665
    641 \begin{Verbatim}[label=/etc/network/interfaces]
     666\begin{Verbatim}[label=\file{/etc/network/interfaces}]
    642667auto eth0.1
    643668iface eth0.1 inet static
    … …  
    669694\end{Verbatim}
    670695
    671 This configures four VLAN interfaces, \texttt{eth0.1} on physical ports 2, 3 and 4.
    672 The interfaces \texttt{eth0.2}, \texttt{eth0.3} and \texttt{eth0.4} are three
    673 different networks with VLAN ID 2-4. The physical port 1 needs to be connected
     696This configures four VLAN interfaces, \code{eth0.1} on physical ports 2, 3 and 4.
     697The interfaces \code{eth0.2}, \code{eth0.3} and \code{eth0.4} are three
     698different networks with VLAN ID 2--4. The physical port 1 needs to be connected
    674699to a VLAN trunking port on a switch with knows the same VLAN IDs.
    675700
    … …  
    677702Explanation:
    678703\begin{description}
    679 \item[port 0] this is typically the port labeled as WAN
    680 \item[port 1-4] these are typically the ports labeled as LAN
    681 \item[port 5] this special port represents the port where the router-board is
    682         connected to the switch
    683 \item[*] one interface always need an asterisk behind port 5 which means it is
    684         the default interface and gets all the packages with unknown tags.
     704        \item[port 0] this is typically the port labeled as WAN
     705        \item[port 1--4] these are typically the ports labeled as LAN
     706        \item[port 5] this special port represents the port where the router--board is
     707                connected to the switch
     708        \item[*] one interface always need an asterisk behind port 5 which means it is
     709                the default interface and gets all the packages with unknown tags.
    685710\end{description}
    686711
    … …  
    689714IP settings, so these are the commonly used options:
    690715\begin{description}
    691 \item[address] the IP address  - required
    692 \item[netmask] the netmask     - required
    693 \item[broadcast] broadcast address - only required for legacy applications (if using +, it will calculated automatically by the kernel)
    694 \item[gateway] an IP address added as default gateway if present
    695 \item[mac-address] if you need to change your MAC address (required for some DSL providers)
     716        \item[address] the IP address  --- required
     717        \item[netmask] the netmask     --- required
     718        \item[broadcast] broadcast address --- only required for legacy
     719        applications (if using \code{+}, it will be calculated automatically by the kernel)
     720        \item[gateway] an IP address added as default gateway if present
     721        \item[mac-address] if you need to change your MAC address (required for some DSL providers)
    696722\end{description}
    697723
    698724\subsection{DHCP}
    699725That's just as simple as:
    700 \begin{Verbatim}[label=/etc/network/interfaces]
     726\begin{Verbatim}[label=\file{/etc/network/interfaces}]
    701727auto eth0.1
    702728iface eth0.1 inet dhcp
    … …  
    708734
    709735This is mostly needed to combine LAN and WLAN to a homogeneous network.
    710 Be sure you have installed the package \texttt{bridge-utils}.
    711 
    712 \begin{Verbatim}[label=/etc/network/interfaces]
     736Be sure you have installed the package \app{bridge-utils}.
     737
     738\begin{Verbatim}[label=\file{/etc/network/interfaces}]
    713739auto eth0.0
    714740iface eth0.0 inet manual
    … …  
    728754\end{Verbatim}
    729755
    730 This creates a new bridging interface \texttt{br0} which combines the VLAN
    731 interface \texttt{eth0.0} (representing the LAN-ports 1-4) and the WLAN interface
    732 \texttt{eth1} (on some devices like Asus WL500gP this might be \texttt{eth2}).
     756This creates a new bridging interface \code{br0} which combines the VLAN
     757interface \code{eth0.0} (representing the LAN-ports 1--4) and the WLAN interface
     758\code{eth1} (on some devices like \term{Asus WL500gP} this might be \code{eth2}).
    733759The bridge interface needs always be the last one, otherwise it can not find
    734 the interfaces in bridge-ifaces.
     760the interfaces in \code{bridge-ifaces}.
    735761
    736762\subsection{WLAN}
    737763A router containing a WLAN interface has an additional ethernet device
    738 representing it. On Broadcom-based hardware it is typically \texttt{eth1}
    739 (Linksys),\texttt{eth2} (Asus WL500gP) or on Netgear WGT634u which has a Madwifi
    740 WLAN chip, it is \texttt{ath0}, \texttt{ath1}, etc. You can use these interfaces
     764representing it. On Broad\-com-based hardware it is typically \code{eth1}
     765(\term{Linksys}),\code{eth2} (\term{Asus WL500gP}) or on \term{Netgear WGT634u} which has a Madwifi
     766WLAN chip, it is \code{ath0}, \code{ath1}, etc. You can use these interfaces
    741767standalone or bridged with other devices, e.g. the internal LAN.
    742768
    … …  
    745771Mandatory options and default parameters are in bold font.
    746772
    747 \begin{tabular}{l|l|l}
    748 \textbf{Option} & \textbf{Parameter} & \textbf{Description} \\
    749 \hline
    750 \textbf{type}& broadcom        & Broadcom based card \\
    751              & atheros         & Madwifi driver \\
    752 \textbf{mode}& ap              & Access point mode \\
    753              & sta             & Client mode \\
    754              & adhoc           & Ad-Hoc mode \\
    755              & wds             & WDS point-to-point link over wireless\\
    756              & monitor         & The node acts as a passive monitor and only receives packets \\
    757 \textbf{ssid}& <String>        & Set the SSID (Network Name) \\
    758 country      & {ALL|DE|JP|US|...} & The country code used to determine the regulatory settings. \\
     773\begin{tabular}{l|l|p{10cm}}
     774\strong{Option} & \strong{Parameter} & \strong{Description} \\
     775\hline\hline
     776\code{\strong{type}} & \code{broadcom}                & Broadcom based card \\
     777                     & \code{atheros}                 & Madwifi driver \\
     778\hline
     779\code{\strong{mode}} & \code{ap}                      & Access point mode \\
     780                     & \code{sta}                     & Client mode \\
     781                     & \code{adhoc}                   & Ad-Hoc mode \\
     782                     & \code{wds}                     & WDS point-to-point link over wireless\\
     783                     & \code{monitor}                 & The node acts as a passive monitor and only receives packets \\
     784\hline
     785\code{\strong{ssid}} & \code{<String>}                & Set the SSID (Network Name) \\
     786\hline
     787\code{country}       & \code{\{ALL|DE|JP|US|\ldots\}} & The country code used to determine the regulatory settings. \\
     788\hline
    759789\end{tabular}
    760790
    761791\subsubsection{Security Settings}
    762 \begin{tabular}{l|l|l}
    763 \textbf{Option} & \textbf{Parameter} & \textbf{Description} \\
    764 \hline
    765 \textbf{security}& none            & No authorization \\
    766              & wep             & WEP key \\
    767              & wpa-psk         & WPA with preshared key \\
    768              & 8021x           & IEEE 802.1X authentication \\
    769 \textbf{authorization}&                 & \textbf{wpa-psk} \\
    770              & psk             & WPA PSK \\
    771              & psk2            & WPA2 PSK \\
    772              & psk psk2        & WPA PSK and WPA2 PSK \\
    773              &                 & \textbf{8021x} \\
    774              & wpa             & WPA with RADIUS \\
    775              & wpa2            & WPA2 with RADIUS \\
    776              & wpa wpa2        & WPA and WPA2 \\
    777 \textbf{encryption}&            & \textbf{wep} \\
    778              & -               & not needed, automatically by key size \\
    779              &                 & \textbf{wpa-psk} \\
    780              & tkip            & RC4 encryption \\
    781              & aes             & AES encryption \\
    782              & aes+tkip        & support both \\
    783              &                 & \textbf{8021x} \\
    784              & wep             & RC4 encryption (static) \\
    785              & tkip            & RC4 encryption \\
    786              & aes             & AES encryption \\
    787              & aes+tkip        & support both \\
    788 eap-type     &                 & \textbf{8021x} \\
    789              & \textbf{tls}    & Transport Layer Security \\
    790              & ttls            & Tunnelled TLS \\
    791              & peap            & Protected EAP \\
    792              & leap            & Cisco Wireless \\
    793 key          &                 & \textbf{wep} \\
    794              &\{\textbf{1}|2|3|4\}& Select WEP key to use. \\
    795 key[1..4]    &                 & \textbf{wep} \\
    796              & <String>        & WEP key.  The key must be 5, 13 or 16 bytes
    797                                  long, or 10, 26, 32, or 64 hex digits long.  The encryption
    798                                  algorithm is automatically selected based on the key size. key1 is
    799                                  the key for WEP client mode. \\
    800 wpa-key      &                 & \textbf{wpa-psk} \\
    801              & <String>        & Password to use with WPA/WPA2 PSK (at least 8,
    802                                  up to 63 chars) \\
    803 wpa-gtk-rekey &                & \textbf{wpa-psk}, \textbf{8021x} \\
    804              & <Int> (\textbf{3600}) & Rekeying interval in seconds. \\
    805 \textbf{radius-ipaddr}&             & \textbf{8021x} \\
    806              & <a.b.c.d>       & IP to connect. \\
    807 radius-port  &                 & \textbf{8021x} \\
    808              & <Int> (\textbf{1812}) & RADIUS-Port no. to connect \\
    809 \textbf{radius-key}&                & \textbf{8021x} \\
    810              & <String>        & Shared Secret for connection to the Radius server \\
     792\begin{longtable}{l|l|p{10cm}}
     793\strong{Option} & \strong{Parameter} & \strong{Description} \\
     794\hline\hline
     795\code{\strong{security}} & \code{none}            & No authorization \\
     796                         & \code{wep}             & WEP key \\
     797                         & \code{wpa-psk}         & WPA with preshared key \\
     798                         & \code{8021x}           & IEEE 802.1X authentication \\
     799\hline
     800\code{\strong{authorization}} &                 & \strong{wpa-psk} \\
     801                              & \code{psk}             & WPA PSK \\
     802                              & \code{psk2}            & WPA2 PSK \\
     803                              & \code{psk psk2}        & WPA PSK and WPA2 PSK \\
     804                              &                        & \strong{8021x} \\
     805                              & \code{wpa}             & WPA with RADIUS \\
     806                              & \code{wpa2}            & WPA2 with RADIUS \\
     807                              & \code{wpa wpa2}        & WPA and WPA2 \\
     808\hline
     809\code{\strong{encryption}} &                        & \strong{wep} \\
     810                           & ---                    & not needed, automatically by key size \\
     811                           &                        & \strong{wpa-psk} \\
     812                           & \code{tkip}            & RC4 encryption \\
     813                           & \code{aes}             & AES encryption \\
     814                           & \code{aes+tkip}        & support both \\
     815                           &                        & \strong{8021x} \\
     816                           & \code{wep}             & RC4 encryption (static) \\
     817                           & \code{tkip}            & RC4 encryption \\
     818                           & \code{aes}             & AES encryption \\
     819                           & \code{aes+tkip}        & support both \\
     820\hline
     821\code{eap-type} &                        & \strong{8021x} \\
     822                & \code{\strong{tls}}    & Transport Layer Security \\
     823                & \code{ttls}            & Tunnelled TLS \\
     824                & \code{peap}            & Protected EAP \\
     825                & \code{leap}            & Cisco Wireless \\
     826\hline
     827\code{key} &                            & \strong{wep} \\
     828           &\code{\{\strong{1}|2|3|4\}} & Select WEP key to use. \\
     829\hline
     830\code{key[1..4]} &                 & \strong{wep} \\
     831                 & \code{<String>} & WEP key.  The key must be 5, 13 or 16 bytes
     832                                     long, or 10, 26, 32, or 64 hex digits long.  The encryption
     833                                     algorithm is automatically selected based on the key size. key1 is
     834                                     the key for WEP client mode. \\
     835\hline
     836\code{wpa-key} &                 & \strong{wpa-psk} \\
     837               & <String>        & Password to use with WPA/WPA2 PSK (at least 8, up to 63 chars) \\
     838\hline
     839\code{wpa-gtk-rekey} &                              & \strong{wpa-psk}, \strong{8021x} \\
     840                     & \code{<Int>} (\strong{3600}) & Rekeying interval in seconds. \\
     841\hline
     842\code{\strong{radius-ipaddr}} &                  & \strong{8021x} \\
     843                              & \code{<a.b.c.d>} & IP to connect. \\
     844\hline
     845\code{radius-port} &                              & \strong{8021x} \\
     846                   & \code{<Int>} (\strong{1812}) & RADIUS-Port no. to connect \\
     847\hline
     848\strong{radius-key} &                 & \strong{8021x} \\
     849                    & \code{<String>} & Shared Secret for connection to the Radius server \\
     850\hline
     851\end{longtable}
     852
     853\subsubsection{MAC filter}
     854\begin{tabular}{l|l|p{10cm}}
     855\strong{Option} & \strong{Parameter} & \strong{Description} \\
     856\hline\hline
     857\code{macmode} & \code{\{0|1|2\}} & 0: Disable MAC address matching. \\
     858               &                  & 1: Deny association to stations on the MAC list. \\
     859               &                  & 2: Allow association to stations on the MAC list. \\
     860\hline
     861\code{maclist} & \code{<MAC1> \ldots <MACn>} & List of space separated mac addresses to
     862allow/deny according to \code{macmode}. Addresses should be entered with colons,
     863e.g.: "\code{00:02:2D:08:E2:1D 00:03:3E:05:E1:1B}"\\
    811864\end{tabular}
    812865
    813 \subsubsection{MAC filter}
    814 \begin{tabular}{l|l|l}
    815 \textbf{Option} & \textbf{Parameter} & \textbf{Description} \\
    816 macmode      & {0|1|2}         & 0 - Disable MAC address matching. \\
    817              &                 & 1 - Deny association to stations on the MAC list. \\
    818              &                 & 2 - Allow association to stations on the MAC list. \\
    819 maclist      & <MAC1> ... <MACn> & List of space separated mac addresses to
    820 allow/deny according to ''macmode''. Addresses should be entered with colons,
    821 e.g.: 00:02:2D:08:E2:1D 00:03:3E:05:E1:1B\\
     866\subsubsection{Wireless Distribution System (WDS)}
     867\begin{tabular}{l|l|p{10cm}}
     868\strong{Option}       & \strong{Parameter}          & \strong{Description} \\
     869\hline\hline
     870\code{lazywds}        & \code{\{0|1\}}              & Accept WDS connections from anyone \\
     871\hline
     872\code{wds-bridge}     & \code{br\{X\}}              & Add WDS peers to bridge brX \\
     873\hline
     874\code{wds-security}   & \code{\{wpa-psk\}}          & secure the wds bridge with WPA (optional)\\
     875\hline
     876\code{wds-encryption} & \code{\{aes|tkip\}}         & Use AES or TKIP as cipher\\
     877\hline
     878\code{wds-wpa-key}    & \code{<String>}             & Password to use with WPA PSK (at least 8, up to 63 chars) \\
     879\hline
     880\code{wds}            & \code{<MAC1> \ldots <MACn>} & List of WDS peer mac addresses (\code{xx:xx:xx:xx:xx:xx}, space separated) \\
     881\hline
    822882\end{tabular}
    823883
    824 \subsubsection{Wireless Distribution System (WDS)}
    825 \begin{tabular}{l|l|l}
    826 \texttt{Option} & \texttt{Parameter} & \texttt{Description} \\
    827 lazywds      & {0|1}           & Accept WDS connections from anyone \\
    828 wds-bridge   & {brX}           & Add WDS peers to bridge brX \\
    829 wds-security & {wpa-psk}           & secure the wds bridge with WPA (optional)\\
    830 wds-encryption & {aes|tkip}           & Use AES or TKIP as cipher\\
    831 wds-wpa-key & <String>        & Password to use with WPA PSK (at least 8, up to 63 chars) \\
    832 wds          & <MAC1> ... <MACn> & List of WDS peer mac addresses (xx:xx:xx:xx:xx:xx, space separated) \\
    833 \end{tabular}
    834 
    835884\subsubsection{Miscellaneous}
    836 \begin{tabular}{l|l|l}
    837 \textbf{Option} & \textbf{Parameter} & \textbf{Description} \\
    838 channel      & \{1-14\}          & The wifi channel \\
    839 maxassoc     & \{1-255\}         & Maximum number of associated clients \\
    840 gmode        & \{LegacyB| \textbf{Auto}| GOnly| BDeferred| Performance| LRS\} & Set the 54g Mode \\
    841 frameburst   & \{\textbf{0}|1\}        & Disable/Enable frameburst mode. \\
    842 txpower      & \{0-255|\textbf{-1}\}   & Set the transmit power in dBm \\
    843 rate         & <Int> (\textbf{-1})   & force a fixed rate \\
    844              &                 & valid values for 802.11a are (6, 9, 12, 18, 24, 36, 48, 54) \\
    845              &                 & valid values for 802.11b are (1, 2, 5.5, 11) \\
    846              &                 & valid values for 802.11g are (1, 2, 5.5, 6, 9, 11, 12, 18, 24, 36, 48, 54) \\
    847              &                 &-1 means automatically determine the best rate \\
    848 rts          & \{0-2347\}        & Set the RTS threshhold. \\
    849 frag         & \{256-2346\}      & Set the fragmentation threshhold. \\
    850 afterburner  & \{\textbf{0}|1\}        & Enable Afterburner capability \\
    851 isolate      & \{\textbf{0}|1\}        & Hide Clients from each other \\
    852 bridge-if    & \{br0...brX\}   & The bridge interface (optional)
    853 \end{tabular}
     885\begin{longtable}{l|l|p{10cm}}
     886\strong{Option} & \strong{Parameter} & \strong{Description} \\
     887\hline\hline
     888\code{channel}      & \code{\{1--14\}}                & The wifi channel \\
     889\hline
     890\code{maxassoc}     & \code{\{1--255\}}               & Maximum number of associated clients \\
     891\hline
     892% TODO: add descriptions to the different gmode settings
     893\code{gmode}        &                                 & Set the 54g Mode \\
     894                    & \code{\strong{Auto}}            & default \\
     895                    & \code{LegacyB}                  & \\
     896                    & \code{GOnly}                    & \\
     897                    & \code{BDeferred}                & \\
     898                    & \code{Performance}              & \\
     899                    & \code{LRS}                      & \\
     900\hline
     901\code{frameburst}   & \code{\{\strong{0}|1\}}         & Disable/Enable frameburst mode. \\
     902\hline
     903\code{txpower}      & \code{\{0--255|\strong{$-1$}\}} & Set the transmit power in dBm \\
     904\hline
     905\code{rate}         & \code{<Int> (\strong{$-1$})}    & force a fixed rate \\
     906                    &                                 & valid values for 802.11a are (6, 9, 12, 18, 24, 36, 48, 54) \\
     907                    &                                 & valid values for 802.11b are (1, 2, 5.5, 11) \\
     908                    &                                 & valid values for 802.11g are (1, 2, 5.5, 6, 9, 11, 12, 18, 24, 36, 48, 54) \\
     909                    &                                 & $-1$ means automatically determine the best rate \\
     910\hline
     911\code{rts}          & \code{\{0-2347\}}               & Set the RTS threshhold. \\
     912\hline
     913\code{frag}         & \code{\{256-2346\}}             & Set the fragmentation threshhold. \\
     914\hline
     915\code{afterburner}  & \code{\{\strong{0}|1\}}         & Enable Afterburner capability \\
     916\hline
     917\code{isolate}      & \code{\{\strong{0}|1\}}         & Hide Clients from each other \\
     918\hline
     919\code{bridge-if}    & \code{\{br0..brX\}}             & The bridge interface (optional) \\
     920\hline
     921\end{longtable}
    854922
    855923\subsubsection{Examples}
    856 WLAN with WEP128
    857 \begin{Verbatim}
     924\paragraph{WLAN with WEP128}
     925\begin{Verbatim}[label=\file{/etc/network/interfaces}]
    858926iface eth1 inet static
    859927        address 192.168.10.1
    … …  
    869937\end{Verbatim}
    870938
    871 WLAN without encryption
    872 \begin{Verbatim}
     939\paragraph{WLAN without encryption}
     940\begin{Verbatim}[label=\file{/etc/network/interfaces}]
    873941iface eth1 inet static
    874942        address 192.168.10.1
    … …  
    883951\end{Verbatim}
    884952
    885 WLAN with WPA2 (AES)
    886 \begin{Verbatim}
     953\paragraph{WLAN with WPA2 (AES)}
     954\begin{Verbatim}[label=\file{/etc/network/interfaces}]
    887955iface eth1 inet static
    888956        address 192.168.10.1
    … …  
    901969
    902970If you want to do MAC filtering, add the following to the sample above:
    903 \begin{Verbatim}
     971\begin{Verbatim}[label=\file{/etc/network/interfaces}]
    904972        wireless-macmode 2
    905973        wireless-mac 00:01:02:03:04:05 06:07:08:09:0a:0b
    … …  
    908976
    909977To enhance wireless performance, you can enable some flags like Broadcom's SpeedBooster. Normally, these flags are not dangerous:
    910 \begin{Verbatim}
     978\begin{Verbatim}[label=\file{/etc/network/interfaces}]
    911979        wireless-gmode performance
    912980        wireless-frameburst 1
    … …  
    914982\end{Verbatim}
    915983
    916 WLAN client with WPA2 (AES) (''untested'')
    917 \begin{Verbatim}
     984\paragraph{WLAN client with WPA2 (AES) (\strong{untested})}
     985\begin{Verbatim}[label=\file{/etc/network/interfaces}]
    918986iface eth1 inet static
    919987        address 192.168.10.1
    … …  
    930998\end{Verbatim}
    931999
    932 WLAN client with WEP128
    933 \begin{Verbatim}
     1000\paragraph{WLAN client with WEP128}
     1001\begin{Verbatim}[label=\file{/etc/network/interfaces}]
    9341002iface eth1 inet dhcp
    9351003        wireless-type broadcom
    … …  
    9441012SSID, channel and encryption parameters.
    9451013
    946 WDS node 1 (MAC of Wireless 06:05:04:03:02:01)
    947 \begin{Verbatim}
     1014WDS node 1 (MAC of Wireless \code{06:05:04:03:02:01})
     1015\begin{Verbatim}[label=\file{/etc/network/interfaces}]
    9481016iface br0 inet static
    9491017        bridge-ifaces eth1
    … …  
    9601028        wireless-wds-bridge br0
    9611029\end{Verbatim}
    962 WDS node 2 (MAC of Wireless 01:02:03:04:05:06)
    963 \begin{Verbatim}
     1030WDS node 2 (MAC of Wireless \code{01:02:03:04:05:06})
     1031\begin{Verbatim}[label=\file{/etc/network/interfaces}]
    9641032iface br0 inet static
    9651033        bridge-ifaces eth1
    … …  
    9771045\end{Verbatim}
    9781046
    979 Peer-to-Peer mode (no encryption, IP must be static)
    980 \begin{Verbatim}
     1047\paragraph{Peer-to-Peer mode (no encryption, IP must be static)}
     1048\begin{Verbatim}[label=\file{/etc/network/interfaces}]
    9811049iface eth1 inet static
    9821050        address 192.168.10.1
    … …  
    9941062
    9951063PPP comes in various flavours for different situations, the most commonly
    996 needed will likely be DSL and for WRT54G3G users UMTS. So there exists a
    997 hook-script that evaluates a "use-template" option and generates a ppp-peer.
     1064needed will likely be DSL and for \term{WRT54G3G} users UMTS. So there exists a
     1065hook-script that evaluates a \code{use-template} option and generates a ppp-peer.
    9981066This way everything needed so far can be configured within the
    999 \texttt{interfaces} file. Be sure you have installed the packages
    1000 \texttt{kmod-ppp}, \texttt{ppp} and \texttt{ppp-mod-pppoe}. For providers
    1001 using PPTP for authentication, instead of PPPoE, you need to install \texttt{pptp}.
     1067\code{interfaces} file. Be sure you have installed the packages
     1068\app{kmod-ppp}, \app{ppp} and \app{ppp-mod-pppoe}. For providers
     1069using PPTP for authentication, instead of PPPoE, you need to install \app{pptp}.
    10021070
    10031071\subsubsection{DSL with PPPoE}
    1004 \begin{Verbatim}
     1072\begin{Verbatim}[label=\file{/etc/network/interfaces}]
    10051073auto ppp0
    10061074iface ppp0 inet ppp
    … …  
    10121080\end{Verbatim}
    10131081
    1014 Now your DSL connection will be started on boot (\texttt{auto ppp0})
    1015 and you can manually shut it down with \texttt{ifdown ppp0} or start it up with
    1016 \texttt{ifup ppp0}.
    1017 The template \texttt{dsl} will configure a typical PPPoE peer for you.
     1082Now your DSL connection will be started on boot (\code{auto ppp0})
     1083and you can manually shut it down with \command{ifdown ppp0} or start it up with
     1084\command{ifup ppp0}.
     1085The template \code{dsl} will configure a typical PPPoE peer for you.
    10181086
    10191087\subsubsection{DSL with PPTP}
    1020 \begin{Verbatim}
     1088\begin{Verbatim}[label=\file{/etc/network/interfaces}]
    10211089auto ppp0
    10221090iface ppp0 inet ppp
    … …  
    10251093        ppp-username foo
    10261094        ppp-password bar
    1027         ppp-modemip 10.0.0.1
    1028         ppp-mtu 1480
     1095        ppp-modemip 10.0.0.1
     1096        ppp-mtu 1480
    10291097        ppp-device eth0.1
    10301098\end{Verbatim}
    10311099
    1032 Now your DSL connection will be started on boot (\texttt{auto ppp0})
    1033 and you can manually shut it down with \texttt{ifdown ppp0} or start it up with
    1034 \texttt{ifup ppp0}.
    1035 The template \texttt{pptp} will configure a typical PPTP peer for you.
     1100Now your DSL connection will be started on boot (\code{auto ppp0})
     1101and you can manually shut it down with \command{ifdown ppp0} or start it up with
     1102\command{ifup ppp0}.
     1103The template \code{pptp} will configure a typical PPTP peer for you.
    10361104
    10371105\subsubsection{UMTS}
    10381106Same footprint different template and some specific options. That is all that
    10391107is needed for an UMTS connection to Vodafone as it can be seen in this example.
    1040 \begin{Verbatim}
     1108\begin{Verbatim}[label=\file{/etc/network/interfaces}]
    10411109iface ppp0 inet ppp
    10421110        use-template    umts
    … …  
    10491117        umts-mode       umts_first
    10501118\end{Verbatim}
    1051 As you can see: unneeded options like \texttt{ppp-username} or
    1052 \texttt{ppp-password} can just be removed or commented out. Don't leave them
    1053 without a value as that causes a failure in \texttt{ipup}. It does work if you
    1054 give empty double quotes as value like "".
     1119As you can see: unneeded options like \code{ppp-username} or
     1120\code{ppp-password} can just be removed or commented out. Don't leave them
     1121without a value as that causes a failure in \app{ipup}. It does work if you
     1122give empty double quotes as value like \code{""}.
    10551123
    10561124Note that you have to set the correct APN, username and password for your provider!
    … …  
    10581126You may also remove the pin from your SIM-card and the configuration if you like.
    10591127
    1060 For Linksys WRT54G3G a package called \texttt{broadcom-watchbutton} will be
     1128For \term{Linksys WRT54G3G} a package called \app{broadcom-watchbutton} will be
    10611129installed, this is a small daemon that monitors the UMTS-button of the router
    1062 and executes \texttt{ifup umts} or \texttt{ifdown umts} on a button press.
    1063 You have to set \texttt{watchbutton=YES} in /etc/rc.conf to have it start automatically.
    1064 
    1065 This is totally independent from the \texttt{auto umts} setting. Even if you
     1130and executes \command{ifup umts} or \command{ifdown umts} on a button press.
     1131You have to set \code{watchbutton=YES} in /etc/rc.conf to have it start automatically.
     1132
     1133This is totally independent from the \code{auto umts} setting. Even if you
    10661134start the connection on bootup you can shut it down again with a button press.
    10671135
    … …  
    10691137\subsubsection{per interface}
    10701138You can execute various commands on interface startup or shutdown with special option:
    1071 \begin{Verbatim}
     1139\begin{Verbatim}[label=\file{/etc/network/interfaces}]
    10721140iface foobar inet static
    10731141    [...]
    … …  
    10811149You can give each option multiple times and their commands will be executed in given order.
    10821150\begin{description}
    1083 \item[pre-up] before the interface will be started
    1084 \item[up] after the interface was started successfully
    1085 \item[down] before the interface goes down
    1086 \item[post-down] after the interface shut down
     1151        \item[pre-up] before the interface will be started
     1152        \item[up] after the interface was started successfully
     1153        \item[down] before the interface goes down
     1154        \item[post-down] after the interface shut down
    10871155\end{description}
    10881156
    … …  
    10901158Additionally you can write scripts executed for each interface if you put them in
    10911159\begin{itemize}
    1092 \item \texttt{/etc/network/if-pre-up.d}
    1093 \item \texttt{/etc/network/if-up.d}
    1094 \item \texttt{/etc/network/if-down.d}
    1095 \item \texttt{/etc/network/if-post-down.d}
     1160        \item \texttt{/etc/network/if-pre-up.d}
     1161        \item \texttt{/etc/network/if-up.d}
     1162        \item \texttt{/etc/network/if-down.d}
     1163        \item \texttt{/etc/network/if-post-down.d}
    10961164\end{itemize}
    10971165Same semantics as above.
    … …  
    10991167\section{FWCF - FreeWRT Configuration Filesystem}
    11001168
    1101 FWCF is a separate flash partition for all changes made to the /etc directory.
    1102 There is a small tool named \texttt{fwcf}, which is used to setup the system or
     1169FWCF is a separate flash partition for all changes made to the \file{/etc/} directory.
     1170There is a small tool named \app{fwcf}, which is used to setup the system or
    11031171to commit changes to the fwcf partition.
    11041172
    1105 On bootup the script \texttt{/sbin/mount\_root} is executed, which calls \dq{}fwcf
    1106 setup\dq{} to setup /etc as memory filesystem and overlay the changes committed
     1173On bootup the script \file{/sbin/mount\_root} is executed, which calls
     1174\command{fwcf setup} to setup \file{/etc/} as memory filesystem and overlay the changes committed
    11071175to the fwcf partition.
    11081176
    1109 If you change anything in /etc and like to keep the change, it is required to
    1110 execute \dq{}fwcf commit\dq{}. This will compress all changed or new files in /etc
    1111 and write the result into the fwcf partition.  The fwcf partition is 128 Kb in
     1177If you change anything in \file{/etc/} and like to keep the change, it is required to
     1178execute \command{fwcf commit}. This will compress all changed or new files in
     1179\file{/etc/} and write the result into the fwcf partition.  The fwcf partition is 128 Kb in
    11121180size. This size is not changeable at the moment.
    11131181
    11141182If you need more detailed information, please read the specification of FWCF,
    11151183which can be found
    1116 here \url{http://www.freewrt.org/trac/wiki/Documentation/Specs/FwCf}
     1184at \url{http://www.freewrt.org/trac/wiki/Documentation/Specs/FwCf}
    11171185
    11181186If you want to remove all your changes and start your configuration from scratch,
    1119 use \dq{}fwcf erase\dq{}. This is also required if you switch between compression
     1187use \command{fwcf erase}. This is also required if you switch between compression
    11201188plugins. Right now LZO plugin is default.
    11211189
    … …  
    11231191
    11241192All software for FreeWRT is available as a IPKG package. IPKG is a package manager
    1125 very similar to Debian's dpkg/apt-get utilities. It is specially designed for
     1193very similar to Debian's \app{dpkg/apt-get} utilities. It is specially designed for
    11261194embedded systems and is widely used. The FreeWRT project use a special version,
    11271195which is embedded to the busybox binary. Normally the command line tool
    1128 \texttt{ipkg} is pre-installed.
    1129 
    1130 IPKG uses a configuration file similar to /etc/apt/sources.list, which
     1196\app{ipkg} is pre-installed.
     1197
     1198IPKG uses a configuration file similar to \file{/etc/apt/sources.list}, which
    11311199contains a list of software repositories available via HTTP or FTP.
    1132 The configuration file \texttt{/etc/ipkg.conf} contains the official
     1200The configuration file \file{/etc/ipkg.conf} contains the official
    11331201FreeWRT 1.0 repository for your board and kernel version.
    11341202
    11351203To update the list of available packages execute following command as root:
    1136 \begin{verbatim}
     1204\begin{Verbatim}[label=update list of available packages]
    11371205# ipkg update
    1138 \end{verbatim}
     1206\end{Verbatim}
    11391207
    11401208This command requires a working internet connection, because it will fetch a
    1141 package list from every repository declared in /etc/ipkg.conf.
     1209package list from every repository declared in \file{/etc/ipkg.conf}.
    11421210
    11431211To install a new package use following command:
    1144 \begin{verbatim}
     1212\begin{Verbatim}[label=example installation of \app{tcpdump}]
    11451213# ipkg install tcpdump
    1146 \end{verbatim}
    1147 
    1148 This will install the package tcpdump and all dependencies onto the flash.
     1214\end{Verbatim}
     1215
     1216This will install the package \app{tcpdump} and all dependencies onto the flash.
    11491217Where the data is saved depends on the root filesystem you decided to use while
    11501218installing FreeWRT. If you use jffs2 as root filesystem, then the package is
    … …  
    11551223symlinks to the read-only squashfs partition.
    11561224
    1157 You can also remove packages, but this is only useful if you are using JFFS2
     1225You can also remove packages, but this is only useful if you are using jffs2
    11581226as root filesystem:
    1159 \begin{verbatim}
     1227\begin{Verbatim}[label=example removal of \app{tcpdump}]
    11601228# ipkg remove tcpdump
    1161 \end{verbatim}
    1162 
    1163 This will not remove any dependencies, installed earlier. For example, libpcap
    1164 is still installed after executing this command.
     1229\end{Verbatim}
     1230
     1231This will not remove any dependencies, installed earlier. For example,
     1232\app{libpcap} is still installed after executing this command.
    11651233On jffs2 root filesystem you should never remove any essential packages like
    1166 busybox, fwcf or uclibc, otherwise you make the embedded system unusable.
    1167 
    1168 Nearly the same as for removing packages, counts for ipkg upgrade.  Please
    1169 \textbf{never ever} use ipkg upgrade to update your embedded system.  This command
     1234\app{busybox}, \app{fwcf} or \app{uclibc}, otherwise you make the embedded system unusable.
     1235
     1236Nearly the same as for removing packages, counts for \command{ipkg upgrade}.  Please
     1237\strong{never ever} use \command{ipkg upgrade} to update your embedded system.  This command
    11701238is only useful to upgrade single packages on a jffs2 rootfilesystem or data
    11711239partition.
    … …  
    11751243Some of the available packages containing software which start services at boot
    11761244time. For that we provide simple startup scripts, which are installed into the
    1177 directory \texttt{/etc/init.d}. See following example for
    1178 the package \texttt{dnsmasq}, a combined dns and dhcp
     1245directory \file{/etc/init.d}. See following example for
     1246the package \app{dnsmasq}, a combined dns and dhcp
    11791247server daemon:
    11801248
    1181 \begin{verbatim}
     1249\begin{Verbatim}[label=\file{/etc/init.d/S50dnsmasq}]
    11821250#!/bin/sh
    11831251
    … …  
    12051273esac
    12061274exit 0
    1207 \end{verbatim}
     1275\end{Verbatim}
    12081276
    12091277After installation the package postinst script will add all needed changes to the
    1210 /etc directory. For example packages can add new user and groups, add new
    1211 variables to /etc/rc.conf or just add new values to existing files as
    1212 /etc/services. It is FreeWRT policy to do not start any services after
     1278\file{/etc/} directory. For example packages can add new user and groups, add new
     1279variables to \file{/etc/rc.conf} or just add new values to existing files as
     1280\file{/etc/services}. It is FreeWRT policy not to start any services after
    12131281installation or in case of a new boot. To start services on bootup you need to set
    1214 \$servicename=YES in /etc/rc.conf and commit your changes via \dq{}fwcf
    1215 commit\dq{}. For every policy exist a exception, we start all essential services
     1282\code{\$servicename=YES} in \file{/etc/rc.conf} and commit your changes via
     1283\command{fwcf commit}. For every policy exists an exception, we start all essential services
    12161284by default, like ssh daemon, syslog and network initialisation.
    12171285
    1218 For some services you can control the startup behavior by modifying
    1219 the services\_flags variable in /etc/rc.conf.
    1220 
    1221 For example the variable \$ssh\_opts is provided as argument to the dropbear
    1222 ssh daemon to control its behavior.
     1286For some services you can control the startup behaviour by modifying
     1287the \code{\$servicename\_flags} variable in \file{/etc/rc.conf}.
     1288
     1289For example the variable \code{\$ssh\_opts} is provided as an argument to the dropbear
     1290ssh daemon to control its behaviour.
    12231291
    12241292Having this policy helps you to configure your FreeWRT embedded system without
    12251293shooting yourself in the foot. For example if you try to realize a firewall system
    1226 and trying to set the rules in /etc/firewall.user, which is read by
    1227 /etc/init.d/S45firewall, if the iptables package is installed. You can just
    1228 reload the changed ruleset via /etc/init.d/S45firewall restart. If you managed
     1294and trying to set the rules in \file{/etc/firewall.user}, which is read by
     1295\file{/etc/init.d/S45firewall}, if the iptables package is installed. You can just
     1296reload the changed ruleset via \code{/etc/init.d/S45firewall restart}. If you managed
    12291297to kick you out of the system, you can just reboot the system and you gain access
    12301298again. As soon as your are ready with the firewall configuration and you decide
    1231 to activate the firewall rules on bootup, you set \$firewall=YES in /etc/rc.conf,
    1232 commit your changes via \dq{}fwcf commit\dq{} and reboot. Now the firewall
     1299to activate the firewall rules on bootup, you set \code{firewall=YES} in
     1300\file{/etc/rc.conf},
     1301commit your changes via \command{fwcf commit} and reboot. Now the firewall
    12331302rules will be activated on bootup.
    12341303
    12351304
    1236 \chapter{Troubleshooting}
     1305\chapter{Troubleshooting}\label{ch:troubleshooting}
    12371306
    12381307\section{Failsafe Mode}
    … …  
    12461315It stops even before the root filesystem gets mounted read--write, and fwcf is
    12471316set up. It will just set the LAN interface up and give it the IP address
    1248 192.168.1.1 and netmask 255.255.255.0. Then it will start a telnet daemon, so
    1249 you get straight access (without depending on the installed SSH--daemon).
     1317\file{192.168.1.1} and netmask \file{255.255.255.0}. Then it will start a
     1318\app{telnet} daemon, so you get straight access (without depending on the installed SSH daemon).
    12501319
    12511320\subsection{How It Works}
    … …  
    12531322To get FreeWRT into failsafe mode you need physical access to the device and
    12541323the failsafe utility. The failsafe utility is built inside our ADK and
    1255 is available in the directory bin/ after a successful build.
     1324is available in the directory \file{bin/} after a successful build.
    12561325
    12571326If you just want to compile the tool and not a complete firmware image,
    12581327use following command:
    12591328
    1260 \begin{Verbatim}
     1329\begin{Verbatim}[label=building the failsafe utility for the host system]
    12611330$ make subdir=tools/failsafe install
    12621331\end{Verbatim}
    12631332
    12641333For some operating systems we provide ready to go binaries of failsafe.
    1265 Take a look at http://www.freewrt.org/downloads/tools/failsafe
     1334Take a look at \url{http://www.freewrt.org/downloads/tools/failsafe}
    12661335
    12671336The tool just opens a network socket and waits for a special UDP packet
    … …  
    12751344see the device specific page for the exact network port.
    12761345
    1277 Configure your network interface to the IP address 192.168.1.2 with network
    1278 mask 255.255.255.0. Now start the failsafe utility on your computer.
     1346Configure your network interface to the IP address \file{192.168.1.2} with network
     1347mask \file{255.255.255.0}. Now start the failsafe utility on your computer.
    12791348
    12801349\begin{Verbatim}
    … …  
    13191388\end{Verbatim}
    13201389
    1321 Now you can change files in /etc and repair your broken configuration.
     1390Now you can change files in \file{/etc/} and repair your broken configuration.
    13221391Do not forget to commit your changes afterwards.
    13231392
    … …  
    13261395\end{Verbatim}
    13271396
    1328 If you want to start over with the default /etc directory, just remove the fwcf
     1397If you want to start over with the default \file{/etc/} directory, just remove the fwcf
    13291398partition content with following command:
    13301399
    … …  
    13331402\end{Verbatim}
    13341403
    1335 You can either use "reboot -f" or "-r" for mtd to reboot the system.
     1404You can either use \command{reboot -f} or the option \command{-r} for \app{mtd} to reboot the system.
    13361405
    13371406%\section{Serial Console}
Note: See TracChangeset for help on using the changeset viewer.