Changeset cd78f74 in freewrt for docs

Timestamp:

Jan 24, 2007, 8:45:40 AM (19 years ago)

Author:

Waldemar Brodkorb <wbx@…>

Branches:

freewrt_1_0, freewrt_2_0

Children:

7d6779bf

Parents:

9ba8799

Message:

add sections about fwcf, startup scripts and ipkg

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

Location:

docs/handbook/user

Files:

• 00-allinone.tex (modified) (19 diffs)
• cover.tex (modified) (1 diff)

docs/handbook/user/00-allinone.tex

@@ -309 +309 @@
 The FreeWRT ADK produces a single image holding both kernel and root
 filesystem. This image can be written into your hardware's builtin flash memory
-on serveral ways (ordered by needed skillz, increasing downwards):
+on serveral ways (ordered by needed skills, increasing downwards):
 \begin{itemize} % TODO: insert \ref's to jump to the appropriate section?
 \item via the original firmware's web interface
@@ -323 +323 @@
 guide should fit more or less fine for other systems, too. 
 
+If you flash a router from Linksys, we strongly suggest to use the popular
+\textbf{ping exploit} to allow recovery, if your image is broken or the flash
+process was interrupted by a power shortage.
+
 There are some things that you should have done previously:
 \begin{itemize}
+\item read the special documentation page about your hardware in our wiki, some
+      systems need special precaution before flashing
 \item a firmware image has to be built (matching the used hardware, of course)
 \item the router has to be powered on
@@ -345 +351 @@
 Finally click \textit{Upload}. As the whole process of writing the image to
 flash and rebooting (don't forget that it creates ssh hostkeys on first boot)
-takes quite long, better go and get coffee.
-
-When everything went good, you can login using ssh.
+takes quite long, better go and get a coffee or tea.
+
+When everything went good, you can login using ssh. The default username is
+\dq{}admin\dq{}. The default password for images created via WIB or ADK is
+\dq{}FreeWRT\dq{}. It is possible to change this password in the ADK, before image
+creation.
 
 \subsection{\texttt{mtd} -- The Flash Utility}
+
 For this method to work, you need to copy the file containing the firmware
-image to the router, preferably into /tmp (the tmpfs should be big enough to
-hold the full image). Then the image is written to flash using
+image to the router, preferably into /tmp, the memory filesystem should be 
+big enough to hold the full image. If not, use wget to get the image 
+via http or ftp and pipe the result into \texttt{mtd}.
+
+Then the image is written to flash using
 \texttt{mtd}, optionally giving additional options (see below).
 
@@ -370 +383 @@
         in use
 \end{description}
-further it can request your system to reboot. Some of the features mentioned here can
+
+Further it can request your system to reboot. Some of the features mentioned here can
 also be combined, so it is e.g. possible to immediately reboot the system after
 the flash has been written.
@@ -377 +391 @@
 done to write the firmware to flash:
 \begin{Verbatim}
-# mtd -e linux -r write freewrt.bin linux
+# mtd -e linux -r write freewrt.bin linux &
+\end{Verbatim}
+Or via wget pipe:
+\begin{Verbatim}
+# wget -O - http://www.yourserver.com/freewrt.bin | mtd -e linux -r write - linux &
 \end{Verbatim}
 The parameters explained in detail: \\
@@ -385 +403 @@
 write & write the firmware image contained in the file given as next parameter
                         to flash\\
-linux.trx & the actual image to write - ignore the suffix, it is detected at
+freewrt.bin & the actual image to write - ignore the suffix, it is detected at
                                 runtime\\
 linux & this is an abstract identifier for a certain partition in flash, so
 don't change this\\
+\& & put the process into background, to prevent accidentally stopping\\ 
 \end{tabular}
 
 \subsection{Installation using TFTP}
-All supported target devices are shipped with a builtin firmware, comparable to
-the BIOS of x86--machines. This firmware is used to bootstrap the system until
-it can boot a regular operating system. Besides the (obvious) ability to load
+
+All supported target devices are shipped with a builtin bootloader, comparable to
+the BIOS of x86--machines. This bootloader is used to bootstrap the system until
+it can boot a regular operating system. Besides the ability to load
 the executable code from flash, it can be received from another node in the
 local area network via the famous TFTP protocol. 
@@ -405 +425 @@
 any TFTP client to connect and send the file
 \end{itemize}
-All the hardware supported by FreeWRT-1.0 uses the second method. % TODO: righty?
-Though this may be a little confusing to people being familiar with netboot
-technologies, it is definitely the easier way of doing it. Otherwise one had to
-setup both DHCP and TFTP servers and configure them right.
+
+Most of the hardware supported by FreeWRT 1.0 uses the second method.  Only the
+device Netgear WGT634u is using the first method, the bootloader provides a
+DHCP/TFTP client. Though this may be a little confusing to people being familiar
+with netboot technologies, it is definitely the easier way of doing it. Otherwise
+one had to setup both DHCP and TFTP servers and configure them right.
 
 The even quite simple task of sending the flash image to the target device is
@@ -430 +452 @@
 \textbf{Target Device} & \textbf{Action to be taken} & \textbf{Comments} \\
 \hline
-\ldots & \ldots & \ldots \\
+All supported Linksys models & Ping Exploit & nvram variable boot\_wait needs to be on \\
+All supported Asus models & Recovery mode & power off, push and hold the
+reset button, power on, power led is flashing\\
 \end{tabular}\end{center}
 
 \chapter{FreeWRT Administration}
+
 After the FreeWRT firmware image has been built by the ADK and later flashed
-onto the hardware, the resulting operating system has to be aministrated. This
+onto the hardware, the resulting operating system has to be configured. This
 section provides the necessary information to do that, including tips and
 guides for using FreeWRT in general, of course.
 
 \section{Network Configuration}
+
 The device names for real network interfaces in Linux are named ethx (x is
 0-9). If the device has a switch, the different ports are separated via VLAN
@@ -469 +495 @@
 Each interface needs a unique name which, depending on the method, represents
 either a physical interface or a logical interface name like "eth0.1" for a
-physical VLAN or "umts" as a logical name for a ppp interface.
+physical VLAN or "umts" as a logical name for a PPP interface.
 
 Possible methods are:
@@ -536 +562 @@
 
 \subsection{Bridging}
-This is mostly needed to combine LAN and WLAN to a homogeneous network like:
+
+This is mostly needed to combine LAN and WLAN to a homogeneous network.
+Be sure you have installed the package \texttt{bridge-utils}.
+
 \begin{Verbatim}[label=/etc/network/interfaces]
 auto eth0.0
@@ -552 +581 @@
     netmask 255.255.255.0
 \end{Verbatim}
+
 This creates a new bridging interface \texttt{br0} which combines the VLAN
-interface \texttt{eth0.0} (representing the LAN-ports 1-4) and the WLAN
-interface \texttt{eth1} (on some devices like Asus WL500g or Linksys WRT54G
-v1.1 this might be \texttt{eth2}).
+interface \texttt{eth0.0} (representing the LAN-ports 1-4) and the WLAN interface
+\texttt{eth1} (on some devices like Asus WL500gP this might be \texttt{eth2}).
 
 \subsection{WLAN}
 A router containing a WLAN interface has an additional ethernet device
 representing it. On Broadcom-based hardware it is typically \texttt{eth1}
-(Linksys) or \texttt{eth2} (Asus) (in the current driver version), on Madwifi
-devices it is \texttt{ath0}, \texttt{ath1}, etc. You can use these interfaces
+(Linksys),\texttt{eth2} (Asus WL500gP) or on Netgear WGT634u which has a Madwifi
+WLAN chip, it is \texttt{ath0}, \texttt{ath1}, etc. You can use these interfaces
 standalone or bridged with other devices, e.g. the internal LAN.
 
@@ -776 +805 @@
 
 \subsection{PPP}
+
 PPP comes in various flavours for different situations, the most commonly
 needed will likely be DSL and for WRT54G3G users UMTS. So there exists a
 hook-script that evaluates a "use-template" option and generates a ppp-peer.
 This way everything needed so far can be configured within the
-\texttt{interfaces} file.
+\texttt{interfaces} file. Be sure you have installed the packages
+\texttt{kmod-ppp}, \texttt{ppp} and \texttt{ppp-mod-pppoe}.
 
 \subsubsection{DSL}
@@ -824 +855 @@
 installed, this is a small daemon that monitors the UMTS-button of the router
 and executes \texttt{ifup umts} or \texttt{ifdown umts} on a button press.
-You have to set \texttt{watchdog=YES} in /etc/rc.conf to have it start automatically.
+You have to set \texttt{watchbutton=YES} in /etc/rc.conf to have it start automatically.
 
 This is totally independent from the \texttt{auto umts} setting. Even if you
@@ -860 +891 @@
 Same semantics as above.
 
-\section{Troubleshooting}
-
-\subsection{Failsafe Mode}
+\section{FWCF - FreeWRT Configuration Filesystem}
+
+FWCF is a separate flash partition for all changes made to the /etc directory.
+There is a small tool named \texttt{fwcf}, which is used to setup the system or
+to commit changes to the fwcf partition.
+
+On bootup the script \texttt{/sbin/mount\_root} is executed, which calls \dq{}fwcf
+setup\dq{} to setup /etc as memory filesystem and overlay the changes committet
+to the fwcf partition. 
+
+If you change anything in /etc and like to keep the change, it is required to
+execute \dq{}fwcf commit\dq{}. This will compress all changed or new files in /etc
+and write the result into the fwcf partition.  The fwcf partition is 128 Kb in
+size. This size is not changeable at the moment. 
+
+If you need more detailed information, please read the specification of FWCF,
+which can be found
+here\ref{http://www.freewrt.org/trac/wiki/Documentation/Specs/FwCf}
+
+If you want to remove all your changes and start your configuration from scratch,
+use \dq{}fwcf erase\dq{}. This is also required if you switch between compression
+plugins. Right now LZO plugin is default.  
+
+\section{IPKG - Packagemanagement}
+
+All software for FreeWRT is available as a IPKG package. IPKG is a package manager
+very similar to Debian's dpkg/apt-get utilities. It is specially designed for
+embedded systems and is widely used. The FreeWRT project use a special version,
+which is embedded to the busybox binary. Normally the command line tool
+\texttt{ipkg} is pre-installed.
+
+IPKG uses a configuration file similar to /etc/apt/sources.list, which
+contains a list of software repositories available via HTTP or FTP.
+The configuration file \texttt{/etc/ipkg.conf} contains the official
+FreeWRT 1.0 repository for your board and kernel version.
+
+To update the list of available packages execute following command as root:
+\begin{verbatim}
+# ipkg update
+\end{verbatim}
+
+This command requires a working internet connection, because it will fetch a
+package list from every repository declared in /etc/ipkg.conf.
+
+To install a new package use following command:
+\begin{verbatim}
+# ipkg install tcpdump
+\end{verbatim} 
+
+This will install the package tcpdump and all dependencies onto the flash.
+Where the data is saved depends on the root filesystem you decided to use while
+installing FreeWRT. If you use jffs2 as root filesystem, then the package is
+installed on the big linux partition. If you use squashfs-overlay, then the
+package is installed on the mini-fo overlay filesystem which writes its data
+to the jffs2 data partition. If you use a squashfs-symlinks filesystem, then the
+package data is directly install into the jffs2 data partition, containing
+symlinks to the read-only squashfs partition.
+
+You can also remove packages, but this is only useful if you are using JFFS2
+as root filesystem:
+\begin{verbatim}
+# ipkg remove tcpdump
+\end{verbatim}
+
+This will not remove any dependencies, installed earlier. For example, libpcap 
+is still installed after executing this command.
+On jffs2 root filesystem you should never remove any essential packages like
+busybox, fwcf or uclibc, otherwise you make the embedded system unusable.
+
+Nearly the same as for removing packages, counts for ipkg upgrade.  Please
+\textbf{never ever} use ipkg upgrade to update your embedded system.  This command
+is only useful to upgrade single packages on a jffs2 rootfilesystem or data
+partition.
+
+\section{Startup scripts}
+
+Some of the available packages containing software which start services at boot
+time. For that we provide simple startup scripts, which are installed into the
+directory \texttt{/etc/init.d}. See following example for 
+the package \texttt{dnsmasq}, a combined dns and dhcp
+server daemon:
+
+\begin{verbatim}
+#!/bin/sh
+
+. /etc/rc.conf
+
+case $1 in
+autostart)
+        test x"${dns_dhcp:-NO}" = x"NO" && exit 0
+        exec $0 start
+        ;;
+start)
+        [ -f /etc/dnsmasq.conf ] || exit
+        /usr/sbin/dnsmasq
+        ;;
+stop)
+        killall dnsmasq
+        ;;
+restart)
+        $0 stop
+        $0 start
+        ;;
+*)
+        echo "Usage: $0 {start | stop | restart}"
+        ;;
+esac
+exit 0
+\end{verbatim}
+
+After installation the package postinst script will add all needed changes to the
+/etc directory. For example packages can add new user and groups, add new
+variables to /etc/rc.conf or just add new values to existing files as
+/etc/services. It is FreeWRT policy to do not start any services after
+installation or in case of a new boot. To start services on bootup you need to set
+\$servicename=YES in /etc/rc.conf and commit your changes via \dq{}fwcf
+commit\dq{}. For every policy exist a exception, we start all essential services
+by default, like ssh daemon, syslog and network initialisation.
+
+For some services you can control the startup behavior by modifying
+the services\_flags variable in /etc/rc.conf. 
+
+For example the variable \$ssh\_opts is provided as argument to the dropbear
+ssh daemon to control its behavior. 
+
+Having this policy helps you to configure your FreeWRT embedded system without
+shooting yourself in the foot. For example if you try to realize a firewall system
+and trying to set the rules in /etc/firewall.user, which is read by
+/etc/init.d/S45firewall, if the iptables package is installed. You can just 
+reload the changed ruleset via /etc/init.d/S45firewall restart. If you managed
+to kick you out of the system, you can just reboot the system and you gain access
+again. As soon as your are ready with the firewall configuration and you decide 
+to activate the firewall rules on bootup, you set \$firewall=YES in /etc/rc.conf,
+commit your changes via \dq{}fwcf commit\dq{} and reboot. Now the firewall
+rules will be activated on bootup.
+
+
+\chapter{Troubleshooting}
+
+\section{Failsafe Mode}
 
 Failsafe mode is very useful if you misconfigured your embedded system,
@@ -875 +1043 @@
 you get straight access (without depending on the installed SSH--daemon).
 
-\subsubsection{How It Works}
+\subsection{How It Works}
 
 To get FreeWRT into failsafe mode you need physical access to the device and
@@ -890 +1058 @@
 For some operating systems we provide ready to go binaries of failsafe.
 Take a look at http://www.freewrt.org/downloads/tools/failsafe
-% TODO: \ref fuer link
 
 The tool just opens a network socket and waits for a special UDP packet
@@ -896 +1063 @@
 recognized network interface (eth0).
 
-\subsubsection{Enabling Failsafe Mode}
+\subsection{Enabling Failsafe Mode}
 
 Connect your computer to the embedded system via direct or crossed network
@@ -931 +1098 @@
 \end{Verbatim}
 
-\subsubsection{Repairing Your FreeWRT Configuration}
+\subsection{Repairing Your FreeWRT Configuration}
 
 If you want to repair your configuration, you first need to
@@ -962 +1129 @@
 You can either use "reboot -f" or "-r" for mtd to reboot the system.
 
+\section{Serial Console}
+
+\section{JTAG}

docs/handbook/user/cover.tex

@@ -18 +18 @@
 \\
 \rightline{%
-Revision 1.0}
+Revision 1.0.1}
 \\
 \rightline{%