\chapter{Introduction} Welcome to FreeWRT! This handbook covers the building, installation and usage aspects of the FreeWRT 1.0 Linux distribution. FreeWRT is a portable, secure and functional Linux distribution for embedded systems. As FreeWRT is a source code distribution, it does not provide any pre-compiled firmware for embedded systems. The latest version of this document is always available at the FreeWRT website. If you have any comments, criticism or found some wrong description, please send us an eMail to freewrt-handbook@freewrt.org, we are always happy about getting feedback to this document, and will try to update or correct the issues mentioned by you. The handbook is split into five distinct sections. Appliance Development Kit covers the building of FreeWRT firmware images. The second section, Installing FreeWRT, covers all aspects regarding the installation and deinstallation of FreeWRT firmware images. The third section is a detailed description of the startup process of FreeWRT. The fourth section, Using FreeWRT, covers administrational tasks, such as network configuration, the FreeWRT configuration filesystem, package management and update mechanism. The last section helps troubleshooting problems and recovering a bad firmware installation. The appendix contains board specific information. For FreeWRT 1.0 these are only Broadcom based embedded systems. The intended audience for this handbook are advanced users with basic knowledge about Linux, networking and software development. The reader should be aware of basic command line tools, the vi editor and a shell. FreeWRT does not contain any high level administration tools (e.g. web based administration) and is fully configured via command line. \section{Typographic Conventions} Examples starting with \# indicate a command that must be invoked as super user. You can use su to gain super user privilges. \begin{Verbatim} # fwcf commit \end{Verbatim} Examples staring with \$ indicate a command that can be invoked as a normal user. The default user account on a freshly installed FreeWRT system is ,,admin''. \begin{Verbatim} $ cat /etc/banner \end{Verbatim} \chapter{Appliance Development Kit (ADK)} Our appliance development kit is called ,,buildroot''. The ADK is the core of FreeWRT and contains all scripts and sources to create firmware images for every supported embedded system. FreeWRT 1.0 supports the following embedded systems: \begin{itemize} \item Asus WL500g \item Asus WL500g deluxe \item Asus WL500g premium \item Linksys WRT54G v1.0 \item Linksys WRT54G v1.1 \item Linksys WRT54G v2.0 \item Linksys WRT54G v2.2 \item Linksys WRT54G v3.0 \item Linksys WRT54G v3.1 \item Linksys WRT54G v4.0 \item Linksys WRT54GS v1.0 \item Linksys WRT54GS v1.1 \item Linksys WRT54GS v4 \item Linksys WRT54G3G \item Netgear WGT634u \end{itemize} In this release we only support the Linux 2.4 kernel. The ADK contains over 300 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. \begin{itemize} \item Debian GNU/Linux 3.1 or newer \item Gentoo Linux \item Ubuntu Dapper Drake or newer \item Fedora Core 4 or newer \item OpenBSD 3.9 or newer \item MirOS BSD \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. Buildroot will warn you about any software you need to install to compile a specific package. Here is a list of the required software: \begin{itemize} \item gcc3 or higher \item g++ \item binutils \item patch \item gzip \item bzip2 \item unzip \item flex \item bison \item GNU make \item zlib (+headers) \item ncurses (+headers) \item (g)libc headers \item subversion \item perl \end{itemize} The buildroot checks for the required versions of these tools in advance. To build FreeWRT with buildroot it is recommended to have an unprivileged user. Please \underline{never} build FreeWRT as super user. Because all necessary source tarballs are downloaded from the internet automagically, your host system needs a working internet connection. \section{Getting the source} Now go to a directory where you want to build the firmware. Depending on the features you select you will need about 2.5-5 GB free disk space. This includes the buildroot itself, any source archives which will be downloaded and their extracted copies (for compiling). To get the initial FreeWRT 1.0 buildroot try one of these commands: \begin{Verbatim} $ svn co http://www.freewrt.org/svn/branches/freewrt_1_0 freewrt $ svn co svn://www.freewrt.org/branches/freewrt_1_0 freewrt \end{Verbatim} After successfully downloading, enter the directory: \begin{Verbatim} $ cd freewrt \end{Verbatim} This directory will be referred to as the ADK root later on. \section{Some Theory First} Building a FreeWRT firmware image is just like building a new Linux kernel, but a little more complex. There is a ncurses-based configuration menu at the beginning, the changes made are saved into a file named ,,.config'' in the ADK root. The build is done by the various Makefiles, compiling and linking the sources together accordingly to the symbols defined in ,,.config''. Unlike kernel compilation, FreeWRT needs to be cross-compiled always. This leads to special premises, as most of the tools need to be specially build. But no panic, FreeWRT will do this all for you. In fact, this is done at the second run of \texttt{make} (the first one opens the configuration), and therefore can be seen as part of the first firmware build. For clarity though, we will discuss these two things separately. \section{Preparing the Build Process} After downloading the FreeWRT ADK, it's time to prepare the ADK for the building of firmware Images (for explanations see the chapter above). \subsection{Creating A Configuration} The first step is to run \texttt{make}. After checking some prerequisites (see ,,Troubleshooting'' below for aid in problems), a console based configuration menu should start. Theoretically no choices have to be made, but it's proven usefull to at least: \begin{itemize} \item select a target (menu: ,,Embedded System'') \item select the root filesystem type (menu: ,,Target Firmware type'') \end{itemize} Then quit saving changes. If you forgot that, just run \texttt{make} again, redo your changes, then save. \subsection{Building ADK} Now that you have a (first) configuration, it is time to build the toolchain (compiler, libraries) for cross-compiling. To do this, just enter {{{make}}} again. The build starts downloading and compiling each needed part of the toolchain, and later continues with building the first firmware image. Later one can be taken as proof of a working ADK. Already experienced in compiling gcc? Then you know... If not, better be told that it takes \underline{really long} to finish. In the meantime I suggest reading the next (optional) chapter dealing with internals about cross-compiling. \section{Details Of Cross-Compiling} TODO: someone with enough knowledge about this may fill this chapter with \underline{interesting} information! \section{Building A FreeWRT Firmware Image} Ok. Your local copy of the FreeWRT ADK should now be prepared for building images. The next step is to do an extensive configuration for the image you want to create. To start the configuration menu, type {{{make menuconfig}}}. when selecting packages, \texttt{<*>} means it will be inserted into the firmware images and \texttt{} means it will be build as an addon package which can be installed later. The target device and filesystem should already been chosen by you to the right value, if not you will have to issue a \texttt{make clean} before actually building the firmware image, because otherwise things get messed up. (smooth rebuild is a (yet) missing feature in our buildroot.) For the packages, if unsure, you can just select one of the package collections. After that, you can still manually check the choices made by the collection and correct them if appropriate. Do not forget to save your configuration when leaving! Guess ... right, type \texttt{make} again to build the new FreeWRT firmware image. Depending on your package selections and underlying hardware, this will take different amounts of time. For your spare time there is the following chapter giving some explanation about what is done at this point. \section{Firmware Build Process In Detail} Just like when building the ADK's toolchain, the sources for the selected packages are downloaded from the internet first, then build using the cross-compiler and libraries of the ADK. TODO: more to follow by some more skilled people!! \section{Troubleshooting} This section deals with various tips for problems with ADK installation. \subsection{Errors During Prerequisites Check} To re-issue the checks, use ,,make prereq''. \begin{itemize} \item GNU make 3.80 too old On my FC4 buildsystem the first I get is \begin{Verbatim} $ make GNU make 3.80 too old. Please install GNU make 3.81 or higher to continue. You can override this check, see http://www.freewrt.org/faq for details. It is suggested to upgrade your copy of bison to GNU Bison 2.3 because of its bug fixes. make: *** [.prereq_done] Error 1 \end{Verbatim} it is quite a nice error that tells me to use more up to date software, but we can anyhow give this hostsystem a try and tell make to ignore those errors/warnings: \begin{Verbatim} make prereq-noerror \end{Verbatim} \end{itemize}