OpenWrt SquashFS-Images have a built-in failsafe mode. Booting into failsafe mode bypasses all configuration located on the JFFS2 partition (the writable 'overlay' filesystem), and instead uses a basic set of hard coded defaults located on the SquashFS partition (that is the read-only partition containing the router OS).
Failsafe mode can be used to fix a router which cannot be accessed in the usual ways because of a problem with configuration such as locked out users, locked out network connections, broken startup scripts, broken packages or configurations, full JFFS2 storage (or other JFFS2 content). It normally cannot fix more fundamental problems such as 'hard bricking' or issues with the hardware, kernel or squashFS images that prevent the router booting properly or making connections at the hardware level.
Failsafe mode can be triggered using three special procedures while the router boots - waiting for a flashing LED and pressing a button, waiting (with a packet sniffer) for a special broadcast packet and pressing a button, or watching for a boot message (on the serial port) and pressing a key ("f") on the serial keyboard. Usually watching for a flashing LED is easiest. Whichever trigger you use, the router enters failsafe mode and you can access the command line with telnet (always possible) or a serial keyboard. The procedures are described here, as well as useful tips once you get into failsafe mode.
Once failsafe mode is triggered, the router will boot with a network address of
192.168.1.1/24 on the
eth0 network interface, and with only essential services running. If your device has multiple network interfaces (eth0, eth1, …), usually eth0 is the interface connected to the switch (there may be very seldom exceptions). Using telnet or a serial connection you can mount the JFFS2 partition with the command
mount_root and diagnose or fix the problems on the JFFS2 partition.
You can trigger failsafe mode in three ways:
192.168.1.2, subnet mask
255.255.255.0. The router will be reached at
192.168.1.1when failsafe mode is running. (You may also use any other IP in the range
Immediately when the LED blink pattern or the network broadcast message is seen, click the device button. If your device has multiple buttons, any button should work. OpenWrt is configured in a way, that pressing of any button during preinit will trigger booting into failsafe mode. But in case a button should not work, try another. It can also help to press the button repeatedly until the blink speeds up or the "success" broadcast packet or other evidence of triggering failsafe mode successfully, is seen.
On many routers, OpenWrt will start to blink a "SYS" LED (may be "Power", may be other) on the front of the router when it is in its early boot cycle. Since r44056 there are three different LED blinking speeds for most of the routers (in trunk and CC15.05):
Some routers only have one hardware button, the reset button, which is often on the back of the unit (often labeled "Reset" or "WPS/Reset"). It may have a visible (external) button, or may be behind a hole (with button in the depth). If it is in a hole, you require a paper clip or similar tool to operate it. Please no not use a nail to press the button in the hole!
The exact steps will depend on the device you are using to watch for the broadcast packet. Details are given below for Linux and Windows. Most *nix/BSD/OS X/Android/Mac should be very similar to Linux (often identical). For many other devices and systems the same steps should be possible (but details not provided).
You will need to be sure the router is connected to the device/PC, the cable is working, the device's firewall will not block the packet, and that network LEDs or other diagnostics you may have, show the connection is working. You may also need to temporarily disable the firewall on your device or open a port on it - take care and secure it again after!
Linux (also most *nix/BSD/OS X/Android/Mac):Software is often built in or very easy to download. GUI
csharkor other. If you do not have any, then these are all very common open source ports and available + free on most platforms. Y you should be able to download one of these for your device easily in the usual way (or any other packet sniffer you like).
Windows:You can use the recvudp.exe utility software, or any other packet sniffer. There are also Windows versions of some of the above software as well.
destination address 192.168.1.255 port UDP 4919. So for example, in a terminal and using tcpdump, with the router connected to port eth0, you would enter the command
tcpdump -Ani eth0 port 4919 and udp
Up to today (Jan 11, 2013) this page didn't precise on which port to listen. In the case of TL-WR1043ND, it's the WAN port. If you find a contradictory example, it will be necessarry to remove or adapt this note.
'Broadcast packet and success packet under Linux (broadcast packet is the first part only!):'
'Broadcast packet and success packet under Windows (broadcast packet is the first line only!):'
Indications of failsafe mode:
If you are using a trunk snapshot, revision 46809 or newer, ssh to 192.168.1.1 from the computer and log in as root (no password required). The host key will be randomly generated. You can pass
-o "UserKnownHostsFile /dev/null" -o "StrictHostKeyChecking no" to ssh if you want to allow a different host key temporarily.
If you are using a release image, telnet (not SSH) to 192.168.1.1 from the computer. There is no username or password required.
Now go to section When you are in failsafe mode
You get a message similar or same like this (using OpenWrt 12.09):
=== IMPORTANT ============================ Use 'passwd' to set your login password this will disable telnet and enable SSH ------------------------------------------ BusyBox v1.19.4 (2013-03-14 11:28:31 UTC) built-in shell (ash) Enter 'help' for a list of built-in commands. _______ ________ __ | |.-----.-----.-----.| | | |.----.| |_ | - || _ | -__| || | | || _|| _| |_______|| __|_____|__|__||________||__| |____| |__| W I R E L E S S F R E E D O M ----------------------------------------------------- ATTITUDE ADJUSTMENT (12.09, r36088) ----------------------------------------------------- * 1/4 oz Vodka Pour all ingredients into mixing * 1/4 oz Gin tin with ice, strain into glass. * 1/4 oz Amaretto * 1/4 oz Triple sec * 1/4 oz Peach schnapps * 1/4 oz Sour mix * 1 splash Cranberry juice ----------------------------------------------------- root@(none):/#
Additional note (r42985):
================= FAILSAFE MODE active ================ special commands: firstboot reset settings to factory defaults mount_root mount root-partition with config files after mount_root: passwd change root's password /etc/config directory with config files for more help see: http://wiki.openwrt.org/doc/howto/generic.failsafe =======================================================
OpenWrt uses an overlay file system (JFFS2) which overlays the default router files on the SquashFS partition. JFFS2 contains all config, all packages, and any temp or other files which are not part of the default OpenWRT. Deleting a file from the JFFS2 effectively "resets" the JFFS2 file version back to default, because the original file will be seen on the SquashFS (if it existed). Deleting the entire contents of the JFFS2 will effective resets the router to OpenWRT default settings and packages.
The root file system in failsafe mode is the only the SquashFS partition and the JFFS2 is not present. To mount (access) the JFFS2 as read/write in failsafe mode you must manually mount it. Enter the command
mount_root to do this.
Once the JFFS2 file system is mounted read/write, you can view/edit/delete/fix the files which are changed from the default firmware. Any files that are changed will be accessible at
/overlay/upper/* on some routers).
The core config files are usually at
/overlay/upper/etc/config/*) and have names such as "network", "firewall" etc. Other copies may exist in the /rom subdirectory and the router's UI code may exist in subdirectories such as /lua
The UCI commandreads and writes the router's main configuration files, and is also the main command line tool for modifying the configuration. So it has a lot of helpful commands for troubleshooting and fixing config-related problems. (You can also edit the config files directly using any text editor). See The UCI System.
If you are not very familiar with Linux, many commands have a
--helpoption (for example:
grep --help) which can suggest the options you need. Often you only need basic commands to get started, such as
find -name *XYZ*(find all files from the current dir with XYZ in the name),
ls(change and list current directory),
less(view file with page up/down, use "q" to finish),
grep(show matching lines/text only), and so on. If a command "hangs" or takes too long,
ctrl-Cwill often kill it and return to a command line.
Specific commands and procedures:
uci get network.lan.ipaddr
Run the command
mount_root and then edit or delete such files as you need. To reset all of the JFFS2 (OpenWrt version of "factory reset") see the next section.
The core config files are usually at
/overlay/upper/etc/config/*) and have names such as "network", "firewall" etc which you can search using the
find -name command (see below). If you know your error is (say) some network switch or VLAN issue, then you can edit/delete the network config file and reboot. The router will keep all settings except the settings of the file you changed/deleted which will go back to default.
mount_root first (see above) to mount the JFFS2 partition. Once the JFFS2 partition is mounted for read/write, use any of these commands to erase the files on it, which resets the router:
rm -r /overlay/*(or /overlay/upper/* on some routers)
mtd -r erase rootfs_data(this will reboot the device as part of the process)
NOTE: there is a bug report that sometimes firstboot or mtd-r erase rootfs_data may not work and "hangs". If that happens then the files can be deleted using the "rm…" method. The overlay is "on top" of the SquashFS so deleting overlay files just leaves the original SquashFS files showing.
Let us assume the following:
nc -l -p 3333 < flash.bin
$ cat nxtfw.bin | pv -b | nc -l 3333
cat nxtfw.bin | pv -b | nc -l -p 3333
nc 192.168.1.123 3333 > /tmp/nxtfw.bin
root@(none):/# sysupgrade /tmp/nxtfw.bin Saving config files... killall: watchdog: no process killed Failed to connect to ubus Switching to ramdisk... Performing system upgrade... Unlocking firmware ... Writing from <stdin> to firmware ... Appending jffs2 data from /tmp/sysupgrade.tgz to firmware... Writing from <stdin> to firmware ... Upgrade completed Rebooting system... [217.460000] reboot: Restarting system
failsafe"kicks in" once activated