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 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 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 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/[[BR]] Then extract the files via tar xzvf freewrt-src-.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 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 # this is used for installing software ipkg remove # 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 == 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 inet }}} {{{auto }}} 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 " where "" 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^*^ || || 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''' || || || || 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''' || || || || Password to use with WPA/WPA2 PSK (at least 8, up to 63 chars) || || wpa-gtk-rekey || || '''wpa-psk''', '''8021x''' || || || (3600^*^) || Rekeying interval in seconds. || || radius-ipaddr^*^ || || '''8021x''' || || || || IP to connect. || || radius-port || || '''8021x''' || || || (1812^*^) || RADIUS-Port# to connect || || radius-key^*^ || || '''8021x''' || || || || 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 || ... || 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 || ... || 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 || (-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 up up down post-down }}} 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 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 * 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 }}} or from Windows: {{{ tftp -i 192.168.1.1 put }}} == 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 linux }}} If you update from older FreeWRT installations and you want to remove your changes to /etc, use: {{{ mtd -e fwcf -r write linux }}} The mtd application automatically convert bin to trx, so that a manual convert via dd is not necessary.