User Tools

Site Tools


OpenWrt Failsafe

OpenWrt SquashFS-Images have a built-in failsafe mode. OpenWrt failsafe mode bypasses all configuration located on the JFFS2 partition (that is the writable partition), in favor of a few hard coded defaults located on the SquashFS partition (that is the read-only partition), resulting in a device that boots up as on the eth0 network interface with only essential services running. (In case your device has multiple network interfaces (eth0, eth1, …), usually eth0 is the interface connected to the switch. There may be very seldom exceptions.)

From this state you can telnet in, mount the JFFS2 partition with the command mount_root and fix problems located on the JFFS2 partition, e.g. forgotten password, bad firewall settings, broken startup scripts, etc. Please read OpenWrt Flash Layout to understand why OpenWrt failsafe is possible, and also Boot Process to understand how it works: basically OpenWrt contains an additional boot up stage, called preinit. This allows OpenWrt to boot into normal mode by default or boot into failsafe mode, if this was triggered by the user. The triggering can happen in two ways: via pressing a hardware button during preinit-stage or via keyboard command while connected over a serial cable to the PCB during preinit-stage. No matter how the booting into failsafe mode was triggered, once OpenWrt boots into failsafe mode, you can telnet in over Ethernet.



  • your device must have a configurable hardware button, if there's a button on your router, it's likely to be configurable. Check if there's specific info about failsafe mode for your device and make sure everything still works as expected everytime you update!
  • there must be a SquashFS-Image flashed to the device. Failsafe cannot be implemented on JFFS2-Images
  • everything but the JFFS2 partition, i.e. the kernel partition and the SquashFS partition, must be intact, so that…
    • …the boot process is able to get as far as required to register the pressing of the button
    • …the minimal required binaries and the configuration files with some default settings are available (all on SquashFS)

Triggering via Hardware Button (Standard OpenWrt method)

Stage 0: Router preparation

  • Power off the router
  • Unplug the WAN port (in case that WAN IP address and LAN IP address are same (address collision happened), if you do not plug out wan port, you cannot enter failsafe mode)

Stage 1: Computer IP settings

  • Set your computer's IP to, subnet mask The router will be reached at when failsafe mode is running. (You may use any IP in the range

Stage 2: Detect when failsafe mode can be triggered

  • To detect when failsafe mode can be triggered, there are two options: look for a bootup LED blink pattern, or look for a special broadcast packet from the router

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. The blink rate is about twice a second. Looking for a blink pattern is much more convenient to use instead of having to use a packet sniffer.

  • Power on the router.
  • As soon as this blink pattern is seen, press the any hardware button of the router.
  • The LED will change to faster blink pattern, indicating the router is now in failsafe mode.

Some routers has the button only on the back of the unit (often labeled "Reset" or "WPS/Reset"). The switch may have a visible (external) button, or may be behind a hole (with button in the depth). In this case and require a paper clip or similar tool to operate. Please no not use the nail when press the button in the hole.

At least one TP-Link router seems to respond better to repeatedly clicking the button before the SYS LED starts to blink, until the SYS LED lights with the rapid-flash pattern.

Stage 2 option 2: Trigger failsafe mode when the router sends a broadcast packet to UDP port 4919

If the LED blink detection method isn't desired, the alternative is to listen on the UDP 4919 port for a broadcast packet on the computer and then press the front button when this packet is seen.

Start a network sniffer under Linux

Run any sniffer: GUI wireshark or console tcpdump or cshark or other. Set the filter in the sniffer: port UDP/4919 and destination address

For example, in a terminal enter the command

tcpdump -Ani eth0 port 4919 and udp
Unverified Information!
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.

Start a network sniffer under Windows using recvudp.exe

You can employ the recvudp.exe utility software - Launch it. You may also need to temporarily disable firewall.

Look for the early boot network broadcast message

Power-cycle the router. The router will deliver a message telling it waits for your click on the button.

Message under Linux (only the firt part)

Run wireshark, cshark or tcpdump

Message under Windows (only the first line)

Monitor the special packet in a program recvudp.exe.


Not all versions of OpenWRT sends the "success" packet.

Stage 3: Trigger a failsafe boot using a button

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.

Stage 4: Log into the router using failsafe

Indications of failsafe mode:

  • Once in failsafe mode, a network broadcast confirmation message appears (not always, for the TL-WR1043ND no message comes).
  • On some router models (e.g. TP-LINK models), the SYS led blinks very quickly

If you are using a trunk snapshot, revision 46809 or newer, ssh to 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 from the computer. There is no username or password required.

Now go to section In failsafe mode


  • If the router does not boot in safe mode despite clicking the button, it may be a timing problem, missing the brief window when OpenWrt is looking for a button press. If so, immediately after turning the router on, rapidly click and keep clicking the button on the router for about 60 seconds to try to not miss the safe mode boot window.
  • If your router has a ridiculously long boot time (such as DIR-300 A), then you may do this for a longer time.

Triggering via keyboard key combination in a serial console

  1. Unplug the router's power cord.
  2. Connect the router's WAN port directly to your PC.
  3. Configure your PC with a static IP address between and E. g. (gateway and DNS is not required).
  4. Plugin the power.
  5. Connect via serial
  6. Wait until the following messages is passing: Press the [f] key and hit [enter] to enter failsafe mode
  7. Press "f" and the "enter" key
  8. You should be able to telnet (not SSH) to the router at now (no username and password)

Flash new firmware in failsafe mode

From linux desktop → router.

On linux machine

cat yourfirmware.bin | pv -b | nc -l -p 3333

  1. pv show progress, nc (netcat) listen on port 3333 transferring the firmware

On Router via Telnet

nc linux.machine.ip. 3333 > /tmp/yourfirmware.bin

install firmware with current settings.

sysupgrade /tmp/yourfirmware.bin

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

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:

NOTE: The root file system in failsafe mode is the only the SquashFS partition. The JFFS2 is not present. To mount JFFS2 in read-write mode run mount_root:


and then repair your system:

  • In case you forgot your password, you need to set a new one. Type:
  • In case you forgot the routers IP address, get it with
    uci get network.lan.ipaddr
  • In case you filled up the entire JFFS2 by installing too big/too many packages, clean the entire JFFS2 partition. All settings will be reset and all installed packages are removed. (OpenWrt equivalent of a factory reset)
    or (this will reboot the device as part of the process)
    mtd -r erase rootfs_data
    rm -r /overlay/*

If you are done with failsafe mode use

reboot -f
to reboot. Note: Normal /sbin/reboot will not work, because init is not running. Or power cycle the router.


  • the article process.boot may help you better understand when failsafe "kicks in" once activated
doc/howto/generic.failsafe.txt · Last modified: 2015/10/29 00:33 by salmander