source: freewrt/docs/handbook/freewrt-handbook.txt@ 025bc8e

FreeWRT 1.0 Handbook
====================

= 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.

== Typographic Conventions ==

Examples starting with # indicate a command that must be invoked as super
user. You can use su to gain super user privilges.

{{{
# fwcf commit
}}}

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". 

{{{
$ cat /etc/banner
}}}


= 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:

 * Asus WL500g
 * Asus WL500g deluxe
 * Asus WL500g premium
 * Linksys WRT54G v1.0
 * Linksys WRT54G v1.1
 * Linksys WRT54G v2.0
 * Linksys WRT54G v2.2
 * Linksys WRT54G v3.0
 * Linksys WRT54G v3.1
 * Linksys WRT54G v4.0
 * Linksys WRT54GS v1.0
 * Linksys WRT54GS v1.1
 * Linksys WRT54GS v4
 * Linksys WRT54G3G
 * Netgear WGT634u

In this release we only support the Linux 2.4 kernel. The ADK contains over
300 software packages. 

== 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.

 * Debian GNU/Linux 3.1 or newer
 * Gentoo Linux 
 * Ubuntu Dapper Drake or newer
 * Fedora Core 4 or newer
 * OpenBSD 3.9 or newer
 * MirOS BSD

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:

 * gcc3 or higher
 * g++
 * binutils
 * patch
 * gzip
 * bzip2
 * unzip
 * flex
 * bison
 * GNU make 
 * zlib (+headers)
 * ncurses (+headers)
 * (g)libc headers
 * subversion
 * perl

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 _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.

== 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:
{{{
$ svn co http://www.freewrt.org/svn/branches/freewrt_1_0 freewrt
$ svn co svn://www.freewrt.org/branches/freewrt_1_0 freewrt
}}}

After successfully downloading, enter the directory:
{{{
$ cd freewrt
}}}

This directory will be referred to as the ADK root later on.

== 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 {{{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.

== 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).

=== Creating A Configuration ===
The first step is to run {{{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:
 * select a target (menu: "Embedded System")
 * select the root filesystem type (menu: "Target Firmware type")

Then quit saving changes. If you forgot that, just run {{{make}}} again, redo
your changes, then save.

=== 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 _really_long_ to finish. In the meantime I suggest reading the
next (optional) chapter dealing with internals about cross-compiling.

== Details Of Cross-Compiling ==

TODO: someone with enough knowledge about this may fill this chapter with
_interesting_ information!

== 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, <*> means it will be inserted into the firmware
images and <M> 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 {{{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 {{{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.

== 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!!

== Troubleshooting ==
This section deals with various tips for problems with ADK installation.

=== Errors During Prerequisites Check ===
To re-issue the checks, use "make prereq".

 * GNU make 3.80 too old
   On my FC4 buildsystem the first I get is
   {{{
   $ 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
   }}}

   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:
   {{{
     make prereq-noerror
   }}}


= Installing FreeWRT =

This document describes how to
 * build FreeWRT firmware images using the buildroot environment,
 * install the compiled firmware image to your router,
 * restore the original firmware.

== Configuring ==

To start a fresh new build, type {{{make}}}. Some early preparation and
checking is done, then a console based configuration menu should start.
See section "Troubleshooting" below if there are errors.

[[PICS]]

The ncurses based menu will aid you in configuring the firmware to be build.
At least:
 * select a target (menu: "Embedded System")
 * select the root filesystem type (menu: "Target Firmware type")

when selecting packages, <*> means it will be inserted into the firmware
images and <M> means it will be build as an addon package which can be
installed later.  If you change the target or root filesystem later you always
need to clean up before rebuilding using {{{make clean}}}. (smooth rebuild is
a (yet) missing feature in our buildroot)

After finishing your selections hit "exit" and save your configuration. As
already mentioned above, the file containing your configuration is ".config"
in buildroot's top directory. '''BEWARE:''' never mess with manually editing
this autogenerated file, it may lead to unexpected results. (such as exploding
embedded systems, etc.)

== Build it ==
You have a config now and the system starts to build whatever you configured
starting with the mandatory toolchain for crosscompiling. That looks like this:

  * download the sources for the toolchain
  * build the toolchain
  * download the next piece of source
  * and so on.

And after the toolchain is built it goes on with the kernel and the packages.
Finally the built binaries are tied together to a firmware image for your selected
target platform.

BTW: not only get a cup of coffee now but have a walk to the next coffee bar ...

== have fun ==
Coffe finished? Then it might be time to use your freshly built firmware now. If
you don't know how, you are absolutely right here, as this is the handbook,
currently pointing to the next chapter.

== Build your firmware image ==

Here is a step by step guide:
 * If you might want to remove FreeWRT and restore the original firmware of your
 * embedded system, you should get a working firmware image from the manufacturer
 * of your embedded system first.
 * Test the manufacturers firmware image, update the firmware on your embedded
 * system just to see that everything works fine!
 * For a minimum build of FreeWRT you need 1,2 GB free space on your hard disk of
 * your host system. If you compile a full build of all available packages you
 * might need up to 8 GB free space on your hard disk.
 * Either install subversion on your host system to get the latest source of the
 * buildroot or use the latest daily sourcecode snapshots from
 * http://www.freewrt.org/downloads/source/ .
 * Don't do the next steps as a priviliged user (f.e. root on a Linux system).
 * Change to an unpriviliged user first.
 * Create a directory in which the buildroot system will reside. Everything will
 * be done inside this directory. The command rm -Rf <directory name> will remove
 * all FreeWRT stuff, if you want to get rid of it, so don't worry!
 * Change to the newly created directory.
 * Get the FreeWRT buildroot environment:
  * svn co svn://www.freewrt.org/
  * wget http://www.freewrt.org/downloads/source/<name of the latest stable or
  * trunk archive>[[BR]]
    Then extract the files via tar xzvf freewrt-src-<version><date>.tar.gz
 * After downloading approx. 200MB do:[[BR]]
   cd www.freewrt.org/trunk/freewrt
 * Now type: make menuconfig.[[BR]]
   After a while a configuration menu will appear. If not you might need to
install the ncurses development package of your host system.
 * Select your embedded system model and select one of the target filesystems.
 * For every software or kernel module package you have three options
   1. not selected < >
   2. Build a s standalone package <M>
   3. Include the package into the firmware image <*>
 * Do not include too many packages into the firmware image file, it is limited in
 * size! (depends on your hardware). You can install additional packages later.
 * If you like, step through the configuration options to see whats available.
 * Quit the configuration menu and save your configuration.
 * To build the firmware image type "make" or "make v" for verbose mode.
 * Your compile has been started now. This will take some time (30 minutes (P4
 * 3GHZ) to 10 Hours (100 MHz P1) ) depending on your hardware. The toolchain for
 * crosscompiling will be build first, then the kernel for the system and at last
 * all selected packages.
 * For some packages to compile, some extra tools need to be installed on your
 * host system, please read the error messages carefully.
 * After the build has been completed you will find all packages and one firmware
 * image in the bin directory (do: cd bin ; ls -l)

== Flashing the compiled firmware to your embedded system ==
 * For Linksys Routers like WRT54GL, you can use the webinterface. Just select the
 * firmware upgrade page,      and select the FreeWRT image as firmware file. Do
 * NEVER remove power from your router while it flashes !!
 * Now type: ssh admin@192.168.1.1 (Use default password FreeWRT, if you didn't
 * changed it in the configuration process)
 * You should be logged into your router now. Congratulation. Use "su" to get root
 * access.

== How to install and remove software via the ipkg utility ==

Use the ipkg utility to install and remove software.

ipkg install <filename> # this is used for installing software
ipkg remove <package-name> # this is used for removing a package
ipkg list_installed # lists all installed packages by the name of the package

To install a new package you need to transfer the package to your router this can
be done by using scp or ftp.
When you want to use ftp you need to start vsftpd on your router first.
When the package has been transferred to your router, you can install it by
typing: ipkg install <package filname>


== First steps ==

== Startup process ==

=== Flash layout ===

The flash layout of the supported embedded systems is designed in the same way.
There are some model specific differences between the exact sizes and partition
offsets.

We always have a separate partition for the bootloader. After that we have a
partition for the kernel including a embedded root filesystem.

=== Bootloader ===

The bootloader initializes the hardware, f.e. CPU, cache and ethernet devices.
The different supported embedded systems have different bootloaders, with 
different features and sizes. To access the bootloader and a command line
prompt you always need a serial connection to the embedded system. 
Not all embedded systems have a serial device onboard or only some crippled
ones. Most of the time you can solder the board to get some working serial
device, but this is not part of this short technical introduction.

=== Kernel ===

The kernel is configured via append line to startup the ash compatible
/etc/preinit script.

=== Preinit ===

This is needed to first make some checks, which root filesystem is used and
then to switch the root filesystem to that. This is either a complete writable
root filesystem, which fills up the complete available flash.

The preinit script exports the environment variable PATH and then mounts the
virtual proc filesystem to /proc.

There is another board specific preinit script, which is used to setup
some board specific drivers or startup variables. (preinit.arch)
After that the script mount\_root will mount the root filesystem and
all other filesystems and startup init to start the system.

is_dirty:
reserved a byte for this flag at the end of the lzma loader
15:21 < nbd> (where it would not disturb the boot loader or the firmware)
15:22 < nbd> so the offset to this byte is the offset to the second partition - 1
15:23 < nbd> directly after flashing this byte is set to 0
15:23 < nbd> and in shell 0 == true :)
15:24 < nbd> jffs2root changes it
15:24 < nbd> --clean
15:24 < nbd> initially it's 0, jffs2root sets it to 1

=== Root filesystem ===

- mini-fo
- jffs2 
- symlinks

=== Init scripts ===

In /etc/inittab we use /etc/init.d/rcS to startup all services, which
are activated in /etc/rc.conf

== Configuration filesystem ==


== Network configuration ==

= 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 technology.
The vlan interfaces are named ethx.y.  
The network configuration in FreeWRT is managed via Busybox's ifupdown
implementation. Busybox's ip builtin
command configures the network interfaces. There is no "ifconfig" or "route". 
To show all configured network interfaces use:
{{{
$ ip addr show
}}}
To show the kernel routing table use:
{{{
$ ip route show
}}}

All available network settings can be found in {{{/etc/network/interfaces}}} which
has the common form:
{{{
auto <iface-name>
iface <iface-name> inet <method>
  <option-x> <value>
  <option-y> <value>
  <option-z> <value>
}}}

{{{auto <iface-name>}}} is optional and, if set, tells the "ifup" script to start
this interface automatically on bootup.

Each interface needs a unique name which, depending on the method, represent 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.

Possible methods are:
{{{
  static :use the given options to configure the interface statically
  dhcp   :just start a dhcp client using the interface "iface-name"
  manual :don't configure the interface but start pre-up.d hook scripts
  ppp    :run "pon <provider>" where "<provider>" is given as an interface option
}}}

== Switch/VLAN ==
The switch built-in in the most routers is capable of separating each port using
VLAN tagging. You can configure the switch simply by adding the interface to the
config file and give the desired switch-ports:
{{{
auto eth0.0
iface eth0.0 inet static
    switch-ports 1 2 5*
    address 192.168.1.1
    netmask 255.255.255.0

auto eth0.1
iface eth0.1 inet static
    switch-ports  3 4 5
    address 192.168.2.1
    netmask 255.255.255.0

auto eth0.2
iface eth0.2 inet static
    switch-ports 0 5
    address 172.16.1.42
    netmask 255.255.255.0
    gateway 172.16.1.1
}}}

This configures three VLAN interfaces "eth0.0" on "1" and "2", "eth0.1" on port
"3" and "4" and "eth0.2" on port "0".
Explanation:
{{{
    port 0   :this is typically the port labeled as WAN
    port 1-4 :these are typically the ports labeled as LAN
    port 5   :this special port represents the port where the
              router-board is connected to the switch
    *        :one interface always need an asterisk behind port 5
              which means it is the default interface and gets all
              the packages with unknown tags.
}}}

== Static IP configuration ==
As you can see in the VLAN example I configured three interfaces with static IP
settings, so these are the commonly used options:
{{{
    address  :the IP address  - required
    netmask  :the netmask     - required
    gateway  :an IP address added as default gateway if present
}}}

== DHCP ==
That's just as simple as:
{{{
auto eth0.1
iface eth0.1 inet dhcp
    switch-ports  0 5
}}}
Typically this configures the WAN-Port to start a DHCP request on bootup.

== Bridging ==
This is mostly needed to combine LAN and WLAN to a homogeneous network like:
{{{
auto eth0.0
iface eth0.0 inet manual
    switch-ports 1 2 3 4 5*

auto eth1
iface eth1 inet manual
    [... wifi-settings, see below ...]

auto br0
iface br0 inet static
    bridge-ifaces eth0.0 eth1
    address 192.168.1.1
    netmask 255.255.255.0
}}}
This creates a new bridging interface "br0" which combines the VLAN interface
eth0.0 (representing the LAN-ports 1-4) and the WLAN interface "eth1" (on some
devices like Asus WL500g or Linksys WRT54G v1.1 this might be eth2).

== WLAN ==
A router containing a WLAN interface has an additional ethernet device, which
represents it. On Broadcom based hardware it is typically eth1 (Linksys) or eth2
(Asus) (in the current driver version), on Madwifi devices it is ath0, ath1, etc.
You can use these interfaces standalone or bridged with other devices, e.g. the
internal LAN.

=== Basic Settings ===

^*^ with Option means mandatory, ^*^ with Parameter means default.

|| '''Option''' || '''Parameter''' || '''Description''' ||
|| type^*^      || broadcom        || Broadcom based card ||
||              || atheros         || Madwifi driver ||
|| mode^*^      || ap              || Access point mode ||
||              || sta             || Client mode ||
||              || adhoc           || Ad-Hoc mode ||
||              || wds             || WDS point-to-point link ||
||              || monitor         || The node acts as a passive monitor and only
receives packets ||
|| ssid^*^      || <String>        || Set the SSID (Network Name) ||
|| country      || {ALL|DE|JP|US|...} || The country code used to determine the
regulatory settings. ||

=== Security Settings ===

|| '''Option''' || '''Parameter''' || '''Description''' ||
|| security^*^  || open            || No authorization ||
||              || wep             || WEP key ||
||              || wpa-psk         || WPA with preshared key ||
||              || 8021x           || IEEE 802.1X authentication ||
|| authorization^*^ ||             || '''wep''' ||
||              || open            || Only Open System Authentication ||
||              || shared          || Only Shared Key Authentication ||
||              || open+shared^*^  || Both Open System and Shared Key
Authentication ||
||              ||                 || '''wpa-psk''' ||
||              || psk             || WPA PSK ||
||              || psk2            || WPA2 PSK ||
||              || psk psk2        || WPA PSK and WPA2 PSK ||
||              ||                 || '''8021x''' ||
||              || open            || Only Open System Authentication ||
||              || shared          || Only Shared Key Authentication ||
||              || wpa             || WPA with RADIUS ||
||              || wpa2            || WPA2 with RADIUS ||
||              || wpa wpa2        || WPA and WPA2 ||
|| encryption^*^ ||                || '''wep''' ||
||              || -               || not needed, automatically by key size ||
||              ||                 || '''wpa-psk''' ||
||              || tkip            || RC4 encryption ||
||              || aes             || AES encryption ||
||              || aes+tkip        || support both ||
||              ||                 || '''8021x''' ||
||              || wep             || RC4 encryption (static) ||
||              || tkip            || RC4 encryption ||
||              || aes             || AES encryption ||
||              || aes+tkip        || support both ||
|| eap-type     ||                 || '''8021x''' ||
||              || tls^*^          || Transport Layer Security ||
||              || ttls            || Tunnelled TLS ||
||              || peap            || Protected EAP ||
||              || leap            || Cisco Wireless ||
|| key          ||                 || '''wep''' ||
||              || {1^*^|2|3|4}    || Select WEP key to use. ||
|| key[1..4]    ||                 || '''wep''' ||
||              || <String>        || WEP key.  The key must be 5, 13 or 16 bytes
long, or 10, 26, 32, or 64 hex digits long.  The encryption algorithm is
automatically selected based on the key size. key1 is the key for WEP client mode.
||
|| wpa-key      ||                 || '''wpa-psk''' ||
||              || <String>        || Password to use with WPA/WPA2 PSK (at least
8, up to 63 chars) ||
|| wpa-gtk-rekey ||                || '''wpa-psk''', '''8021x''' ||
||              || <Int> (3600^*^) || Rekeying interval in seconds. ||
|| radius-ipaddr^*^ ||             || '''8021x''' ||
||              || <a.b.c.d>       || IP to connect. ||
|| radius-port  ||                 || '''8021x''' ||
||              || <Int> (1812^*^) || RADIUS-Port# to connect ||
|| radius-key^*^ ||                || '''8021x''' ||
||              || <String>        || Shared Secret for connection to the Radius
server ||

=== MAC filter ===

|| '''Option''' || '''Parameter''' || '''Description''' ||
|| macmode      || {0|1|2}         || 0 - Disable MAC address matching. ||
||              ||                 || 1 - Deny association to stations on the MAC
list. ||
||              ||                 || 2 - Allow association to stations on the MAC
list. ||
|| maclist      || <MAC1> ... <MACn> || List of space separated mac addresses to
allow/deny according to ''macmode''. Addresses should be entered with colons,
e.g.: "00:02:2D:08:E2:1D 00:03:3E:05:E1:1B". note that if you have more than one
mac use quotes or only the first will be recognized. ||

=== Wireless Distribution System (WDS) / Repeater / Bridge ===
|| '''Option''' || '''Parameter''' || '''Description''' ||
|| lazywds      || {0|1}           || Accept WDS connections from anyone ||
|| wds          || <MAC1> ... <MACn> || List of WDS peer mac addresses
(xx:xx:xx:xx:xx:xx, space separated) ||

=== Miscellaneous ===
|| '''Option''' || '''Parameter''' || '''Description''' ||
|| channel      || {1-14}          || The wifi channel ||
|| maxassoc     || {1-255}         || Maximum number of associated clients ||
|| gmode        || {LegacyB| Auto^*^| GOnly| BDeferred| Performance| LRS} || Set
the 54g Mode ||
|| frameburst   || {0^*^|1}        || Disable/Enable frameburst mode. ||
|| txpower      || {0-255|-1^*^}   || Set the transmit power in dBm ||
|| rate         || <Int> (-1^*^)   || force a fixed rate ||
||              ||                 || valid values for 802.11a are (6, 9, 12, 18,
24, 36, 48, 54) ||
||              ||                 || valid values for 802.11b are (1, 2, 5.5, 11)
||
||              ||                 || valid values for 802.11g are (1, 2, 5.5, 6,
9, 11, 12, 18, 24, 36, 48, 54) ||
||              ||                 ||-1 means automatically determine the best
rate ||
|| rts          || {0-2347}        || Set the RTS threshhold. ||
|| frag         || {256-2346}      || Set the fragmentation threshhold. ||
|| afterburner  || {0^*^|1}        || Enable Afterburner capability ||
|| isolate      || {0^*^|1}        || Hide Clients from each other ||

=== Examples ===
WLAN with WEP128
{{{
iface eth1 inet static
        address 192.168.10.1
        netmask 255.255.255.0
        wireless-type broadcom
        wireless-country DE
        wireless-mode ap
        wireless-ssid FreeWRT
        wireless-security wep
        wireless-key1 11223344556677889900112233
        wireless-channel 11
}}}

WLAN without encryption                       
{{{
iface eth1 inet static
        address 192.168.10.1
        netmask 255.255.255.0
        wireless-type broadcom
        wireless-country DE
        wireless-mode ap
        wireless-ssid FreeWRT
        wireless-security open
        wireless-channel 11
}}}
                                                
WLAN with WPA2 (AES)
{{{
iface eth1 inet static
        address 192.168.10.1
        netmask 255.255.255.0
        wireless-type broadcom
        wireless-country DE
        wireless-mode ap
        wireless-ssid FreeWRT
        wireless-security wpa-psk
        wireless-authorization psk2
        wireless-encryption aes
        wireless-wpa-key 12345678
        wireless-channel 11
}}}

If you want to do MAC filtering, add the following to the sample above:
{{{
        wireless-macmode 2
        wireless-mac 00:01:02:03:04:05 06:07:08:09:0a:0b
}}}
this enables the filter and defines the list to contain addresses that should be
allowed.

To enhanced wireless performance, you can enable some flags like Broadcom's
SpeedBooster. Normally, these flags are not dangerous:
{{{
        wireless-gmode performance
        wireless-frameburst 1
        wireless-afterburner 1
}}}

WLAN client with WPA2 (AES) (''untested'')
{{{
iface eth1 inet static
        address 192.168.10.1
        netmask 255.255.255.0
        wireless-type broadcom
        wireless-country DE
        wireless-mode sta
        wireless-ssid FreeWRT
        wireless-security wpa-psk
        wireless-authorization psk2
        wireless-encryption aes
        wireless-wpa-key 12345678
}}}

WLAN client with WEP128
{{{
iface eth1 inet dhcp
        wireless-type broadcom
        wireless-country DE
        wireless-mode sta
        wireless-ssid FreeWRT
        wireless-security wep
        wireless-key1 11223344556677889900112233
}}}

== PPP ==
PPP comes in various flavours for different situations, the most commonly needed
will be DSL I think and for WRT54G3G users UMTS. So we made 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 "interfaces" file.

=== DSL ===
{{{
auto ppp0
iface ppp0 inet ppp
        use-template dsl
        provider t-online
        ppp-username 0001201234563200123456#0001@t-online.de
        ppp-password fooBARfoo
        ppp-device eth0.1
}}}

Now your t-online dsl connection will be started on boot ("auto ppp0") and you can
manually shut it down with "ifdown ppp0" or start it up with "ifup ppp0".
The template "dsl" will configure a typical PPPoE peer for you.

=== UMTS ===
Same footprint different template and some specific options. That all needed for
an UMTS connection to Vodafone as it can be seen in this example.
{{{
iface ppp0 inet ppp
        use-template    umts
        provider        umts
        #ppp-username   ""
        #ppp-password   ""
        ppp-device      /dev/noz0
        umts-apn        web.vodafone.de
        umts-pincode    1234
        umts-mode       umts_first
}}}
As you can see: unneeded options like "ppp-username" or "ppp-password" can just be
removed or commented out. Don't leave them without a value as that causes a
failure in "ipup". It does work if you give empty double quotes as value like "".

Note that you have to set the correct APN, username and password for your
provider!

You may also remove the pin from your SIM-card and the configuration if you like.

For Linksys WRT54G3G a package called "broadcom-watchbutton" will be installed,
this is a small daemon that monitors the UMTS-button of the router and executes
"ifup umts" or "ifdown umts" on a button press.
You have to set "watchdog=YES" in /etc/rc.conf to have it start automagically.

This is totally independent from the "auto umts" setting. Even if you start the
connection on bootup you can shut it down again with a button press.

== custom interface hooks ==
=== per interface ===
You can execute various commands on interface startup or shutdown with special
option:
{{{
iface foobar inet static
    [...]
    pre-up <command>
    up <command>
    up <command>
    down <command>
    post-down <command>
}}}

You can give each option multiple times and their commands will be executed in
given order.
{{{
  pre-up    :before the interface will be started
  up        :after the interface was started successfully
  down      :before the interface goes down
  post-down :after the interface shut down
}}}

=== general hooks ===
Additionally you can write script executed for each interface if you put them in
  * /etc/network/if-pre-up.d
  * /etc/network/if-up.d
  * /etc/network/if-down.d
  * /etc/network/if-post-down.d
Same semantics as above.


== Package management ==

== Troubleshooting ==

=== Failsafe mode ===

Failsafe mode is very useful if you misconfigured your embedded system,
so that you can not access it anymore. For example you disabled accidently
secure shell or misconfigured the firewall, so that you can not login via
secure shell.

== How it works ==

To get FreeWRT into failsafe mode you need physical access to the device and
the failsafe utility. The failsafe utility is build inside our ADK and
is available in the directory bin/ after a successful build.

If you just want to compile the tool and not a complete firmware image,
use following command:
{{{
$ make subdir=tools/failsafe install
}}}

For some operating systems we provide ready to go binaries of failsafe.
Take a look at http://www.freewrt.org/downloads/tools/failsafe

The tool just opens a network socket and waits for a special UDP packet
from the embedded device. FreeWRT sends the UDP packet via the first
recognized network interface (eth0).

== Enable failsafe mode ==

Connect your computer to the embedded system via direct or crossed network
cable. Use the failsafe port, in most cases one of the LAN ports,
see the device specific page for the exact network port.

Configure your network interface to the IP address 192.168.1.2 with network
mask 255.255.255.0. Now start the failsafe utility on your computer.

{{{
./failsafe
}}}

After that startup your embedded system and wait for the following message in your
failsafe application running on your computer:
{{{
Press reset now to enter Failsafe!
}}}

As soon as this message is displayed you should push the reset button of
your embedded system. You have 2 seconds time to push the button. If you
successfully enabled the failsafe mode, following message is displayed:
{{{
Entering Failsafe!
}}}

Now you should be able to login to your embedded system via a telnet
application. Just use:
{{{
telnet 192.168.1.1
}}}

== Repair your FreeWRT configuration ==

If you want to repair your configuration, you first need to
mount the root filesystem via:
{{{
mount_root
}}}

After that you need to enable the FreeWRT configuration filesystem:
{{{
fwcf setup
}}}

Now you can change files in /etc and repair your broken configuration.
Do not forget to commit your changes afterwards. 
{{{
fwcf commit
}}}

If you want to start with the default /etc directory, just remove the fwcf 
partition content with following command:
{{{
mtd erase fwcf
}}}

Software reset/reboot does not work in failsafe, please disconnect the power cable
to restart.

== Serial console ==

== JTAG ==

== Restoring the original firmware ==

Removing FreeWRT and restoring the original Firmware is very simple. Just transfer
the original firmware image, which was downloaded before you installed FreeWRT to
your embedded system, to your embedded system via secure copy (scp/pscp). See the
following steps:

 * Transfer the manufacturers firmware image to the router. This can be done via
 * scp/pscp
 * For using scp do: scp <firmware-image-filename> admin@192.168.1.1:
 * Now login to your router via ssh and get root access.
 * Now write the firmware to the flash ROM by typing: mtd write -r
 * <firmware-image-filename> linux
 * Your router will reboot when the flash process is completed and the original
 * firmware has been restored.

= Broadcom specific notes =

=== Drivers ===

=== NVRAM ===

== Default settings ==
On many router models, you can completly erase the NVRAM, some values will then
reappear as default. This is often useful when you want to drop the relicts from
the original firmware. Please look into the model docs to make sure its safe.
{{{
mtd -r erase nvram
}}}

== boot_wait ==
On many router models (like Linksys), you can flash the router via tftp even in a
special failsafe mode. To make sure the router will wait long enough for the tftp
put command, set the special NVRAM parameter boot_wait
{{{
nvram set boot_wait=on
nvram commit
}}}

= Firmware =

== Flashing via TFTP ==
You have to set the router in failsafe mode (often done by holding the reset
button when  switching the router on), then you can upload the image. On most
routers, the default ip address is 192.168.1.1, unfortunately, Asus routers uses
the ip address saved in nvram.
{{{
tftp 192.168.1.1
tftp> binary
tftp> trace
tftp> rexmt 1
tftp> put <image.bin>
}}}

or from Windows:
{{{
tftp -i 192.168.1.1 put <image.bin>
}}}

== Flashing via mtd ==

If you have direct access to the router, you can use mtd to flash the firmware
locally. Copy the bin file via scp to the router (to /tmp memory filesystem) and
execute:
{{{
mtd -r write <image.bin> linux
}}}

If you update from older FreeWRT installations and you want to remove your changes
to /etc, use:
{{{
mtd -e fwcf -r write <image.bin> linux
}}}

The mtd application automatically convert bin to trx, so that a manual convert via
dd is not necessary.