Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Next revisionBoth sides next revision
docs:guide-user:troubleshooting:failsafe_and_factory_reset [2023/07/29 12:26] – reorganize contents vgaeteradocs:guide-user:troubleshooting:failsafe_and_factory_reset [2024/06/23 11:45] – Tweak failsafe to remind about setting static IP for the PC richb-hanover
Line 1: Line 1:
 ====== Failsafe mode, factory reset, and recovery mode ====== ====== Failsafe mode, factory reset, and recovery mode ======
-OpenWrt offers several ways to "start over" with your router +OpenWrt offers several ways to "start over" with your router: 
-  * **Failsafe Mode** is useful if you have lost control of your device, and it has become inaccessible, perhaps through a configuration error. It allows you to reboot the router into a basic operating state, retaining all your packages and (most) settings. ([[#failsafe_mode|see Failsafe Mode]]+  * **[[docs:guide-user:troubleshooting:failsafe_and_factory_reset#failsafe_mode|Failsafe mode]]** is useful if you have lost control of your device, and it has become inaccessible, perhaps through a configuration error. It allows you to reboot the router into a basic operating state, retaining all your packages and (most) settings. 
-  * **Factory Reset** erases all your packages and settings, returning the router to its initial state after installing OpenWrt. ([[#factory_reset|see Factory Reset]]) +  * **[[docs:guide-user:troubleshooting:failsafe_and_factory_reset#factory_reset|Factory reset]]** erases all your packages and settings, returning the router to its initial state after installing OpenWrt. 
-  * **Recovery Mode** allows you to install new firmware on a router that has become corrupted. ([[#recovery_mode|see Recovery Mode]]) +  * **[[docs:guide-user:troubleshooting:vendor_specific_rescue|Recovery mode]]** allows you to install new firmware on a router that has become corrupted.
- +
-<WRAP center round info 90%> +
-**Factory Reset** depends on completing the boot process. If **Factory Reset** is not working, try with **Failsafe Mode** instead. +
-</WRAP>+
  
 ===== Failsafe mode ===== ===== Failsafe mode =====
-//OpenWrt// allows you to boot into a **failsafe mode** that overrides its current configuration. If your device becomes inaccessible, e.g. after a configuration error, then failsafe mode is there to help you out. When you reboot in failsafe mode, the device starts up in a basic operating state, with a few hard coded defaults, and you can begin to fix the problem manually. +OpenWrt allows you to boot into a **failsafe mode** that overrides its current configuration. 
 +If your device becomes inaccessible, e.g. after a configuration error, then failsafe mode is there to help you out. 
 +When you reboot in failsafe mode, the device starts up in a basic operating state, with a few hard coded defaults, and you can begin to fix the problem manually.
  
-Failsafe mode **cannot**, however, fix more deeply rooted problems like faulty hardware or a broken kernelIt is similar to resethowever with failsafeyou can access your device and restore settings if desired, whereas a reset would just wipe everything.+Failsafe mode can be triggered by pressing (almost any) button on the device shortly after powering it on. 
 +Each router is unique, but OpenWrt watches for WPSResetor other button press.
  
-**Caveat:** Failsafe mode is only available if you have installed firmware from SquashFS imagethat includes the required read-only root partition. To verify whether your device has the SquashFS root partitioncheck for "squashfs" either in the //OpenWrt// image name or perform the following check on your device:+Failsafe mode **cannot**, however, fix more deeply rooted problems like faulty hardware or a broken kernel. 
 +It is similar to resethowever with failsafeyou can access your device and restore settings if desired, whereas a reset would just wipe everything.
  
-<code>+**Caveat:** Failsafe mode is only available if you have installed firmware from a Squashfs image, that includes the required read-only root partition. 
 +To verify whether your device has the SquashFS root partition, check for "squashfs" either in the OpenWrt image name or perform the following check on your device: 
 + 
 +<code bash>
 grep squash /proc/mounts grep squash /proc/mounts
 </code> </code>
Line 22: Line 25:
 The terminal should return something similar to this: The terminal should return something similar to this:
  
-<code>/dev/root /rom squashfs ro,relatime 0 0</code>+<code> 
 +/dev/root /rom squashfs ro,relatime 0 0 
 +</code> 
  
 ==== Entering failsafe mode ==== ==== Entering failsafe mode ====
-Make sure you use a wired connection, since the failsafe will disable your wireless connectivity. Sometimes you need to connect to a specific network port of your router to get connectivity. **Try the LAN 1 port first.** (For DSA enabled devices it will enable LAN 1 only, see **robimarko**'[[https://forum.openwrt.org/t/adding-openwrt-support-for-xiaomi-ax3600/55049/9760|answer]]).+Failsafe mode starts the router with the IP address 192.168.1.1, and disables 
 +DHCP and wireless connectivity. 
 +You will need to set your PC to a static address on the same subnet 
 +(e.g., 192.168.1.10) and connect via Ethernet. 
 +Sometimes you need to connect to a specific network port of your router 
 +to get connectivity. 
 +**Try the LAN1 port first.** 
 +DSA devices frequently enable [[https://forum.openwrt.org/t/adding-openwrt-support-for-xiaomi-ax3600/55049/9760|LAN1 only]].
  
-On most routers, OpenWrt will blink an LED (usually "Power") during the boot process after it gets control from the initial bootloader (like u-boot)OpenWrt will rather early in the boot cycle check if the user wants to enter the failsafe mode instead of a normal boot. It listens for a button press inside a specific two second window, which is indicated with LEDs and by transmitting a UDP packet.+On most routers, OpenWrt will blink an LED (usually "Power") during the boot process. 
 +Early in the boot cycle, OpenWrt watches for a button press (any button) 
 +inside a specific two second window to indicate that it should enter failsafe mode.
  
 **To enter failsafe mode, follow one of the procedures listed below:** **To enter failsafe mode, follow one of the procedures listed below:**
  
-**Recommended for most usersWait for a flashing LED and press a button.** This is usually the easiest method once you figure out the correct moment.+**Simplest - recommended for most peoplePower on the device, wait for a flashing LED and press a button.** 
 +This can be the WPS, Reset, or other button on the device.
  
-For most users and most devices, the LEDs now (2018) provide sufficient clues as to timing to be able to avoid older recommendations to "press the XXX button as fast as you can until ..." for entering failsafe mode+The LEDs provide clues for timing the button press. 
- +Watch the LED blinking speeds immediately after powering up the router
-There are three different (power) LED blinking speeds during boot for most of the routers:+Most routers show three different (power) LED blinking speeds during boot:
  
   * A power-on sequence of lights that is specific to the device's bootloader   * A power-on sequence of lights that is specific to the device's bootloader
-  * Then a fast 5-per-second blinking rhythm during two seconds, while router waits for user to trigger the failsafe mode, typically by a button press +  * Then a fast 5-per-second blinking rhythm during two seconds, while router waits for a button press 
-  * Then either +  * Then either: 
-       * A faster, 10-per-second blink if the user pressed a button and failsafe mode was triggered +       * A faster, 10-per-second blink if failsafe mode was triggered. The device is listening on 192.168.1.1 
-       * A slower, 2.5-per-second blink continuing to the end of boot, if the failsafe was not triggered and the normal boot continues+       * A slower, 2.5-per-second blink continuing to the end of normal boot, if the failsafe was not triggered 
 +  * If you missed the timing and see the slower blink rate, just power off the device, wait a couple seconds, and try again. 
 +   
 +**Alternate for expert users: Wait (with a packet sniffer) for a special broadcast packet and press a button.** The packet will be sent to destination address 192.168.1.255 port UDP 4919. 
 +The packet contains the text "//Please press button now to enter failsafe//"
 +So for example, in a terminal and using tcpdump, with the router connected to port eth0 of your computer, you would enter the command <code>tcpdump -Ani eth0 port 4919 and udp</code>
  
-**Alternate for expert users: Wait (with a packet sniffer) for a special broadcast packet and press a button.** The packet will be sent to destination address 192.168.1.255 port UDP 4919. The packet contains the text "//Please press button now to enter failsafe//". So for example, in a terminal and using tcpdump, with the router connected to port eth0 of your computer, you would enter the command <code>tcpdump -Ani eth0 port 4919 and udp</code>+**Alternate for expert users with serial connectionWatch for a boot message on the serial console and press a key ("f") on the serial keyboard.** This requires that you have attached a serial cable to the device. 
 +The message shown in the console is "//Press the [f] key and hit [Enter] to enter failsafe mode//"
  
-**Alternate for expert users with serial connection: Watch for a boot message on the serial console and press a key ("f"on the serial keyboard.** This requires that you have attached a serial cable to the device. The message shown in the console is "//Press the [f] key and hit [enter] to enter failsafe mode//"+Usually, it is easiest to watch the LEDs. 
 +However, do consult the available documentation for your device, as there is no default button assigned as reset button and not all procedures work on every device. 
 +Whichever trigger you use, the device will enter failsafe mode and you can access the command line with SSH (always possible) or a serial keyboard.
  
-Usually, it is easiest to watch the LEDs. However, do consult the available documentation for your device, as there is no default button assigned as a reset button and not all procedures work on every device. Whichever trigger you use, the device will enter failsafe mode and you can access the command line with SSH (always possible) or a serial keyboard.+Note that modern OpenWrt always uses SSH for terminal connections.
  
-Note that modern OpenWrt always uses SSH, but early OpenWrt releases (15.05 and before) offered a telnet connection in this state but no SSH.+ 
 +=================
  
 ==== Fixing your settings ==== ==== Fixing your settings ====
-Once failsafe mode is triggered, the router will boot with a network address of 192.168.1.1/24, usually on the //eth0// network interface, with only essential services running. When in failsafe mode, the DHCP server will not be running. You must set your computer's ethernet port to use a static IP address in the 192.168.1.0/24 network (valid IPs are 192.168.1.2 - 192.168.1.254, subnet mask 255.255.255.0)+Once failsafe mode is triggered, the router will boot with a network address of 192.168.1.1/24, usually on the ''eth0'' network interface, with only essential services running. 
 +When in failsafe mode, the DHCP server will not be running. 
 +You must set your computer's ethernet port to use a static IP address in the 192.168.1.0/24 network (valid IPs are 192.168.1.2 - 192.168.1.254, subnet mask 255.255.255.0)
  
 Using SSH or a serial connection, you can then mount the JFFS2 partition with the following command: Using SSH or a serial connection, you can then mount the JFFS2 partition with the following command:
  
-<code>+<code bash>
 mount_root mount_root
 </code> </code>
  
-After that, you can start looking around and fix what’s broken. The JFFS2 partition will be mounted to ///overlay//, as under normal operation.+After that, you can start looking around and fix what’s broken. 
 +The JFFS2 partition will be mounted to ''/overlay'', as under normal operation.
  
-**Failsafe extroot**+You can also transfer files by using scp command/protocol from Linux or macOS, or by using [[docs:guide-quick-start:sshadministration#winscp|WinSCP]] from Windows.
  
-If you use [[:docs:guide-user:additional-software:extroot_configuration]], the failsafe is pretty simple+Additional steps required for [[:docs:guide-user:additional-software:extroot_configuration|Extroot]] setups: 
-<code>+ 
 +<code bash>
 # unplug external device # unplug external device
 reboot reboot
 +
 # plug external device # plug external device
 # mount external device, e.g. # mount external device, e.g.
 block info block info
 mount /dev/mmcblk0 /mnt mount /dev/mmcblk0 /mnt
 +
 # fix the issue, e.g. # fix the issue, e.g.
 vi /mnt/upper/etc/config/network vi /mnt/upper/etc/config/network
 +
 # verify external device will be mounted automatically, e.g. # verify external device will be mounted automatically, e.g.
 vi /overlay/upper/etc/config/fstab vi /overlay/upper/etc/config/fstab
-reboot+reboot
 </code> </code>
  
 ===== Factory reset ===== ===== Factory reset =====
-A factory reset returns your router to the configuration it had just after flashing. This works on any install with a squashfs / overlayfs setup (the norm for most installations), since it is based on erasing and reformatting the overlayfs. +A factory reset returns your router to the configuration it had just after flashing. 
 +This works on any install with a squashfs / overlayfs setup (the norm for most installations), since it is based on erasing and reformatting the overlayfs.
  
-:!: x86 builds (made for PC/Server hardware) with an ext4 read-write rootfs cannot be reset this way.+With a large NOR chip, it can take 3 to 5 minutes for the overlayfs to be formatted in the flash. 
 +During this time, changes cannot be saved.
  
-With a large NOR chip, it can take 3 to 5 minutes for the overlayfs to be formatted in the flashDuring this timechanges cannot be saved.+**Caveat:** 
 +  * Factory reset depends on completing the boot processIf factory reset is not workingtry with failsafe mode instead. 
 +  * x86 builds (made for PC/Server hardware) with an ext4 read-write rootfs cannot be reset this way.
  
 ==== Reset button ==== ==== Reset button ====
Line 90: Line 126:
  
   - Power on the device and wait for the status led to stop flashing (or go into failsafe mode, as described above).   - Power on the device and wait for the status led to stop flashing (or go into failsafe mode, as described above).
-  - Press and hold the reset button for 10 seconds. +  - Press and hold the reset button for 10 seconds.
   - Release the reset button.   - Release the reset button.
  
-The device will do a hard factory reset (see below) and then reboot. This operation can be slow on some devices, so wait a few minutes before connecting again.+The device will do a hard factory reset (see below) and then reboot. 
 +This operation can be slow on some devices, so wait a few minutes before connecting again.
  
 ==== Soft factory reset ==== ==== Soft factory reset ====
-If you want a clean slate, there’s no need to flash again; just enter the following commands. Your device's settings will be reset to defaults like when OpenWrt was first installed.+If you want a clean slate, there’s no need to flash again; just enter the following commands. 
 +Your device's settings will be reset to defaults like when OpenWrt was first installed.
  
-Issuing "firstboot" or "jffs2reset" command will attempt to delete all files from the jffs2 overlay partition. Note that this "soft reset" is performed with file system actions, so in some cases it is not enough. +Issuing "firstboot" or "jffs2reset" command will attempt to delete all files from the jffs2 overlay partition. 
-<code> +Note that this "soft reset" is performed with file system actions, so in some cases it is not enough. 
-firstboot && reboot now+ 
 +<code bash
 +firstboot && reboot
 </code> </code>
  
Line 109: Line 149:
 Note: if you're issuing this command inside a bash script, remember to add the option -y to force firstboot: Note: if you're issuing this command inside a bash script, remember to add the option -y to force firstboot:
  
-<code> +<code bash
-firstboot -y && reboot now+firstboot -y && reboot
 </code> </code>
  
Line 149: Line 189:
 ======================================================= =======================================================
  
-admin@(none):/# firstboot && reboot now+admin@(none):/# firstboot && reboot
 [  102.942293] jffs2reset: This will erase all settings and remove any installed packages. Are you sure? [N/y] [  102.942293] jffs2reset: This will erase all settings and remove any installed packages. Are you sure? [N/y]
 y y
Line 158: Line 198:
 ...</code> ...</code>
  
-Tips**:** after (a openwrt based) router reboots or starts, it goes thru the bootmenu (selection menu for boot options) within 1 to 2 seconds (or, within 1 second, after preset delay time has passed). The boot menu accepts UP/DOWN ENTER buttons, so avoid those or any other buttons for that period of time. After that bootmenu stage, within 3 to 8 seconds later (depending on CPU speed, etc) the failsafe mode appears & passes, so you have to press the "f" button within that time only for once (one time), then press ENTER to enter into failsafe mode.+Tips**:** after (a OpenWrt based) router reboots or starts, it goes thru the bootmenu (selection menu for boot options) within 1 to 2 seconds (or, within 1 second, after preset delay time has passed). 
 +The boot menu accepts Up/Down Enter buttons, so avoid those or any other buttons for that period of time. 
 +After that bootmenu stage, within 3 to 8 seconds later (depending on CPU speed, etc) the failsafe mode appears & passes, so you have to press the "f" button within that time only for once (one time), then press Enter to enter into failsafe mode.
  
 ==== Hard factory reset ==== ==== Hard factory reset ====
-This command will erase and reformat the whole JFFS2 partition and create it again. They key for a real "hard reset" is to unmount the overlay partition first and only then issue the jffs2reset (or firstboot) command:+=== Re-flashing the firmware === 
 +Re-flash or upgrade the firmware discarding the settings.
  
-<code> +<code bash
-umount /overlay && jffs2reset && reboot now+sysupgrade -n /path/to/firmware
 </code> </code>
  
-While in most cases this is producing similar end-result as the "soft reset"this marks the whole flash area of the JFFS2 (read-write) overlay partition as a empty non-initialised JFFS2 partition. Thus the partition will be re-created at the next mount, usually at the next boot. So, this hard reset bypasses the current file system of the overlay.+OpenWrt preserves settings [[docs:guide-quick-start:admingui_sysupgrade_keepsettings|by default]]so you need to opt-out to achieve factory reset.
  
-Explanation: based on the mount status of the overlay, jffs2reset selects either a file-based delete operation or a partition mark-it-empty action:  +=== JFFS2 reset === 
-https://git.openwrt.org/?p=project/fstools.git;a=blob;f=jffs2reset.c;h=dbe049881f5;hb=HEAD#l43 +Reset the JFFS2 partition.
- +
-==== Erasing filesystem to factory reset ==== +
-OpenWrt can be forced to re-format F2FS and perform factory reset.+
  
 <code bash> <code bash>
-dd if=/dev/zero of=/dev/loop0 bs=1M; reboot+umount /overlay && jffs2reset && reboot
 </code> </code>
  
-==== Re-flashing to factory reset ==== +Based on the mount status of the overlay, jffs2reset [[commit>?p=project/fstools.git;a=blob;f=jffs2reset.c;h=dbe049881f5;hb=HEAD#l43|selects]] either a file-based delete operation or a partition mark-it-empty action to be re-created at boot. 
-Factory reset is an [[docs:guide-quick-start:admingui_sysupgrade_keepsettings|option]] available during OpenWrt firmware upgrade. + 
-Settings are preserved by default, but you can opt-out to achieve factory reset.+=== F2FS reset === 
 +Reset the F2FS partition.
  
 <code bash> <code bash>
-sysupgrade -n /path/to/file+dd if=/dev/zero of=/dev/loop0 bs=1M; reboot
 </code> </code>
- 
-==== File access through scp ==== 
-It's possible to edit and transfer files from the Failsafe mode, by using scp command/protocol from Linux or Mac, or by using [[docs:guide-quick-start:sshadministration#using_winscp|WinSCP]] from Windows. 
- 
-===== Recovery mode ===== 
-If neither Failsafe Mode nor Factory Reset returns control of your router, you can often replace the firmware of your device using one of the procedures described on the [[docs/guide-user/troubleshooting/vendor_specific_rescue|Recovery Mode page.]] 
  
  • Last modified: 2024/12/07 10:49
  • by hnyman