System Recovery
dArkOSen includes a boot-time recovery system designed to provide a way back into the system when something has been broken badly enough that the normal user interface cannot be used.
The recovery system consists of a small systemd oneshot service and a recovery checker that runs very early during boot.
The checker looks for:
/boot/recovery.sh
If the file exists, it is executed.
recovery.sh can contain anything that can be executed by the system.
This is intentional.
The recovery system is not limited to a predefined set of repairs. It provides a root-level execution point that can be used to repair the installation before the normal dArkOSen environment starts.
Normally, a broken configuration can become difficult to repair if the component responsible for providing access to the filesystem is itself broken.
For example, if EmulationStation will not start, the user may have no practical way to reach a terminal or file manager from the console.
The recovery system removes that dependency.
Because the recovery script runs during boot, it can repair the system before EmulationStation or other normal userspace components are started.
This makes it useful for recovering from problems such as:
- Broken configuration files
- Deleted system files
- Damaged scripts
- Broken EmulationStation installation
- Incorrect permissions
- Failed modifications
- Bad customizations
- Incorrect emulator configuration
- A system that boots but cannot reach the normal interface
- Changes that need to be reverted remotely
The recovery mechanism is deliberately simple:
/boot/recovery.sh
If the file does not exist, normal boot continues.
If the file exists, the recovery service executes it.
This means the recovery file itself determines what happens next.
There is no special recovery command language and no fixed set of supported operations.
A recovery script can:
- Copy files
- Restore backups
- Remove files
- Repair permissions
- Replace configuration
- Start services
- Stop services
- Mount filesystems
- Start networking
- Start remote-access services
- Launch a management utility
- Modify system configuration
- Reboot the device
- Perform any other operation available to root
The recovery mechanism is therefore better thought of as a boot-time root execution hook than as a traditional recovery menu.
Suppose:
/etc/emulationstation/emulationstation
has been damaged, but a known-good backup exists.
A recovery script can restore the backup before the normal system starts and then reboot.
Conceptually:
Boot
↓
Recovery service
↓
recovery.sh
↓
Restore known-good file
↓
Reboot
↓
Normal dArkOSen startup
The recovery script can then be removed from /boot once the repair has been completed.
If the system partition is still intact but EmulationStation itself is unable to start, one of the existing file-manager launch mechanisms can be used from the recovery environment.
This provides access to the filesystem without requiring EmulationStation to function.
That can be enough to repair or replace the files that prevented normal startup.
The recovery mechanism does not require the repair to happen physically at the console.
A recovery script can initialize networking and a remote-access service before the normal interface starts.
For example, a recovery script could be used to initialize:
- Wi-Fi
- SSH
- Samba
Once network access is available, the system can potentially be repaired remotely.
Because the recovery process runs as root, remote recovery can provide access to the root filesystem rather than being limited to the normal user-accessible files.
This makes the recovery system particularly useful when the console's display, controls, EmulationStation configuration, or other frontend components are unusable.
The recovery mechanism can be useful for problems that occur much earlier or deeper in the system.
For example, it could be used to:
- Revert a system configuration change
- Restore a modified service file
- Repair file ownership or permissions
- Disable a problematic service
- Replace a damaged executable
- Restore a backup of a configuration directory
- Remove a startup script that causes a boot loop
- Collect diagnostic information
- Start a remote shell for troubleshooting
- Mount or repair an accessible filesystem
- Create a backup before making further changes
It can also be used as a controlled way to make system modifications that would otherwise require manually interrupting the normal boot process.
The recovery system becomes particularly powerful when combined with backups.
For example:
Known-good backup
+
recovery.sh
↓
restore damaged component
↓
reboot
A backup does not have to contain the entire operating system.
If the known-good copy of a single executable, configuration file, script, or directory is available, the recovery script can restore only that component.
This can be substantially faster than reinstalling the entire image.
A recovery script is simply a shell script placed at:
/boot/recovery.sh
It should be executable and should contain the commands required to perform the desired recovery operation.
For example, a very simple recovery script might restore a backup and reboot:
#!/bin/bash
cp -f /path/to/backup /etc/emulationstation/emulationstation
rebootThe actual commands required depend entirely on what is being repaired.
There is deliberately no universal recovery.sh template because the recovery system is intended to be general-purpose.
The recovery script executes with root privileges.
This means it can modify essentially the entire operating system.
That is the reason it can recover a badly damaged installation, but it also means that an incorrect recovery script can cause additional damage.
A malformed command, incorrect path, or destructive operation can modify or delete critical system files.
Test recovery scripts carefully.
Do not copy commands into recovery.sh without understanding what they will do.
Once recovery is complete, remove:
/boot/recovery.sh
If the script is intended to run only once, it should remove itself or otherwise ensure that the recovery operation does not repeat on every boot.
A recovery script that restores a file and reboots without removing or disabling itself can create a boot loop:
Boot
↓
recovery.sh
↓
repair
↓
reboot
↓
recovery.sh
↓
repair
↓
reboot
↓
...
This is one of the first things to check if a newly created recovery script prevents the system from reaching the normal interface.
The recovery system is intentionally simple.
It does not attempt to determine what is wrong with the installation.
It does not automatically repair arbitrary filesystem or software problems.
It provides an opportunity to run your own repair procedure before normal userspace startup.
That makes it useful for both simple recovery operations and advanced troubleshooting.
For someone comfortable working with Linux, /boot/recovery.sh effectively provides a way to turn the next boot into a controlled maintenance environment.
If the system can still boot far enough to execute the recovery service, there is usually a way to make it do something useful before the normal dArkOSen interface takes over.
dArkOSen is a passion project born out of love for the R36S. If you appreciate what I do and want to support the project you can show that support by buying me a coffee. Proceeds help fund the cost of SD cards and other expenses involved with development.