OpenWrt failsafe and factory reset: recover configuration before wiping it

When OpenWrt becomes unreachable after a network or firewall change, I do not jump straight to a factory reset. Failsafe boots a minimal state so I can repair /etc/config, while a factory reset removes the overlay and installed packages. Recovery/re-flashing is a separate path controlled by the device bootloader.¹

Check the prerequisites

Failsafe is useful with a SquashFS image that has a read-only root and a separate overlay. It cannot repair failed hardware or a broken kernel. x86 builds using an ext4 read-write rootfs do not reset this way. First check:

1

grep squash /proc/mounts

A result similar to the following confirms a SquashFS /rom:

1

/dev/root /rom squashfs ro,relatime 0 0

Enter failsafe mode

Failsafe normally uses 192.168.1.1 with DHCP and Wi-Fi disabled. I assign the computer 192.168.1.10/24 with netmask 255.255.255.0, connect by Ethernet, and try LAN1 first; some DSA devices expose only LAN1. The button window may be four seconds on OpenWrt 24.10 and later and two seconds on 23.05 and earlier, but the target's device page remains authoritative.

The simplest path is to power on the router, watch the LED pattern, and press the WPS/Reset button documented for that model. A very fast blink commonly indicates failsafe; if the window is missed, power-cycle and try again. Do not generalize the button timing across models.

With a packet sniffer, wait for the broadcast to 192.168.1.255 on UDP port 4919, then press the button:

1

tcpdump -Ani eth0 port 4919 and udp

With a serial connection, wait for the boot message asking for f followed by Enter. Once in failsafe, use SSH or the serial keyboard. If OpenSSH reports Bad server host key: Invalid key length, the source calls out -oRSAMinSize=1024.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

...
Press the [f] key and hit [enter] to enter failsafe mode
Press the [1], [2], [3] or [4] key and hit [enter] to select the debug level
f
- failsafe -
/etc/preinit: line 1: /sbin/mtk_failsafe.sh: not found
/etc/preinit: line 1: dropbearkey: not found
/etc/preinit: line 1: dropbear: not found

BusyBox v1.25.1 () built-in shell (ash)

ash: can't access tty; job control turned off
     _________
    /        /\      _    ___ ___  ___
   /  LE    /  \    | |  | __|   \| __|
  /    DE  /    \   | |__| _|| |) | _|
 /________/  LE  \  |____|___|___/|___|                      lede-project.org
 \        \   DE /
  \    LE  \    /  -----------------------------------------------------------
   \  DE    \  /    Reboot (17.01-SNAPSHOT, r0-e88ba24)
    \________\/    -----------------------------------------------------------

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

admin@(none):/# firstboot && reboot
[  102.942293] jffs2reset: This will erase all settings and remove any installed packages. Are you sure? [N/y]
y
[  117.606813] jffs2reset: /dev/mtdblock6 is not mounted
[  117.612055] jffs2reset: /dev/mtdblock6 will be erased on next mount
reboot
admin@(none):/# [  119.810569] ===> rt_pci_shutdown()
...

Repair the configuration

DHCP is not running and only essential services are available. After connecting to 192.168.1.1 over SSH/serial, mount the overlay:

1

mount_root

The overlay is then available at /overlay. I edit only the file that caused the failure, using scp from Linux/macOS or WinSCP on Windows when needed. For extroot, the source's separate path is to unplug the external device, reboot, attach it again, mount the correct device, fix the mounted configuration, and verify fstab:¹

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# unplug external device
reboot

# plug external device
# mount external device, e.g.
block info
mount /dev/mmcblk0 /mnt

# fix the issue, e.g.
vi /mnt/upper/etc/config/network

# verify external device will be mounted automatically, e.g.
vi /overlay/upper/etc/config/fstab
reboot

If mount_root reports jffs2 not ready yet or the filesystem is full, check df -h first. When the source's recovery branch requires erasing rootfs_data, treat it as a destructive configuration wipe:

1

mtd -r erase rootfs_data

Factory reset

Factory reset works on SquashFS/overlay layouts. A large NOR may take three to five minutes to format; I do not declare the router dead during that interval. If the device has a physical reset button, follow the model-specific procedure: complete boot or enter failsafe, hold Reset for about ten seconds, release it, and wait for the reboot.

Soft factory reset

The file-based path uses firstboot; the source also notes that firstboot commonly calls jffs2reset and may not be enough when the overlay is abnormal:

1

firstboot && reboot

1

firstboot -y && reboot

Use -y inside a script so it does not wait for confirmation. Installed packages and overlay configuration can disappear, so I keep an offline backup first.

Hard factory reset

If a soft reset is insufficient, mtd marks rootfs_data for erasure at boot:

1

mtd -r erase rootfs_data

The source separately describes a physical reset: wait for the LED to stop blinking, hold Reset for ten seconds, release it, and wait several minutes. I only use that procedure after checking the exact model documentation.

Re-flash the firmware

To re-install firmware while discarding settings, use a sysupgrade image, not a factory image, and opt out of preserving configuration:

1

sysupgrade -n /path/to/firmware

Re-flashing does not fix a dead bootloader or failed hardware. I verify the device page, image, TFTP/serial method, and recovery button before starting.

JFFS2 reset

For a JFFS2 overlay, the source gives this unmount-and-reset path:

1

umount /overlay && jffs2reset && reboot

The source notes that jffs2reset was renamed to factoryreset in main/master after December 2024. I check the command available in the running release instead of blindly renaming it.

F2FS reset

The source also includes an F2FS example:

1

dd if=/dev/zero of=/dev/loop0 bs=1M; reboot

This is dangerous: I verify /dev/loop0 and the target layout before using it. I never assume that another F2FS router uses the same loop device.

Verify the recovery

After the router returns, test 192.168.1.1, log in with the release-appropriate credentials, inspect /etc/config and the required packages, and re-enable interfaces one at a time. If the kernel, flash, or hardware is damaged, stop and use the target's bootloader/debrick instructions; failsafe is not a debrick substitute.

Sources