A professional automation utility for GRUB bootloader diagnostics and repair
The GRUB Auto-Recovery System is a shell-based tool designed to maintain boot integrity across Linux distributions. It automates detection and resolution of common GRUB bootloader failures, offering a standardized recovery framework for both UEFI and Legacy BIOS systems.
- ✅ Automated Diagnostics: Detects misconfigurations, missing entries, or corrupted installations in GRUB.
- 🔧 Proactive Maintenance: Can run during boot to verify system health before issues escalate.
- 🛡️ Integrity Protection: Automatically creates backups before making any system modifications.
- 🐧 Cross-Distribution Support: Compatible with Debian, Ubuntu, Fedora, Arch Linux, and openSUSE.
- 💻 Dual-Boot Resilience: Recovers Linux boot entries often overwritten by Windows updates.
- Prerequisites
- Installation
- Operation Modes
- Log Interpretation
- Emergency Recovery
- Configuration
- Troubleshooting
Before using this tool, ensure the following:
- Root Privileges:
sudoor root access is required for all operations. - System Architecture: x86_64 (Intel/AMD) platforms only.
- Firmware Support: Works on both UEFI and Legacy BIOS systems.
- Required Tools: Standard GNU utilities must be available:
grep,awkmount,umountgrub-install,grub-mkconfig,grub-probelsblk,blkid,fsck
⚠️ Internet connectivity is required during installation from remote sources.
Download and install the script manually:
sudo wget -O /usr/local/sbin/grub-auto-recovery.sh \
https://raw.githubusercontent.com/BreachFinder777/Boot-Saviour/refs/heads/main/grub-auto-recovery.sh
sudo chmod +x /usr/local/sbin/grub-auto-recovery.shVerify installation:
grub-auto-recovery.sh --statusEnable automatic boot-time checks by installing the systemd service:
sudo grub-auto-recovery.sh --setup-serviceThis installs and enables a one-shot service that runs early in the boot process to validate GRUB integrity.
🔁 The service respects configuration settings in
/etc/grub-recovery.conf.
Run the script with different flags to control behavior.
| Mode | Command | Description |
|---|---|---|
| Status Assessment | sudo grub-auto-recovery.sh --status |
Checks bootloader state without applying changes. |
| Automated Repair | sudo grub-auto-recovery.sh |
Full workflow: diagnose → backup → repair → verify. |
| Interactive Recovery | sudo grub-auto-recovery.sh --interactive |
Step-by-step mode with user confirmation at each stage. |
| Forced Reinstall | sudo grub-auto-recovery.sh --force-repair |
Reinstalls GRUB regardless of current status. |
Logs are written to /var/log/grub-recovery.log with timestamped entries categorized by severity level.
| Level | Meaning | Action Required? |
|---|---|---|
| SUCCESS | Operation completed successfully; boot integrity confirmed. | No action needed. |
| INFO | General system information (e.g., detected partitions, kernel versions). | For auditing purposes. |
| WARN | Potential issue detected (e.g., outdated config, missing fallback entry). | Monitor or investigate. |
| ERROR | Critical failure (e.g., GRUB not installed, unbootable state). | Immediate repair required. |
💡 Use
tail -f /var/log/grub-recovery.logduring recovery to monitor progress.
If your system fails to boot, use a Live Linux environment (USB/DVD) to restore GRUB.
- Boot into a Live ISO (e.g., Ubuntu Live USB).
- Connect to the internet.
- Open a terminal and run:
wget https://raw.githubusercontent.com/BreachFinder777/Boot-Saviour/refs/heads/main/grub-auto-recovery.sh
chmod +x grub-auto-recovery.sh
sudo ./grub-auto-recovery.sh --force-repair📌 The script will attempt to auto-detect your installed Linux system. If detection fails, refer to Troubleshooting.
- Reboot after completion:
sudo reboot
⚠️ Ensure Secure Boot is disabled if using unsigned GRUB binaries.
Customize behavior via the configuration file:
/etc/grub-recovery.conf
| Parameter | Default | Description |
|---|---|---|
AUTO_RECOVERY_ENABLED |
true |
Enable/disable automatic repair on boot. |
RECOVERY_MODE |
auto |
One of: auto, force, check-only. |
MAX_RETRY_ATTEMPTS |
3 |
Number of retries for failed operations. |
ENABLE_NOTIFICATIONS |
false |
Send email alerts via local MTA (requires mailutils). |
Example: To disable auto-repair but keep logging:
AUTO_RECOVERY_ENABLED=false RECOVERY_MODE=check-only
Use the built-in configurator:
sudo grub-auto-recovery.sh --configThis launches an interactive editor to safely modify settings.
Solution: Manually specify the root partition in the config.
Edit /etc/grub-recovery.conf:
CUSTOM_ROOT_PARTITION="/dev/nvme0n1p2"
Replace with your actual root device (use lsblk to identify it).
Symptoms: "cannot find a GRUB drive for /dev/sda" or similar.
Causes & Fixes:
-
Filesystem corruption
Run:sudo fsck /dev/sdXY
-
**Missing or unmounted
/bootor ESP (EFI System Partition)** Ensure ESP is mounted at/boot/efi(UEFI) or/boot` (BIOS):sudo mount /dev/sdX1 /boot/efi
-
Device not recognized
Check output of:lsblk -f blkid
Ensure disks are visible and properly formatted.
This project is licensed under the MIT License — see LICENSE for details.
- Developed by Soham Datta
- Special thanks to the open-source Linux community for testing, feedback, and contributions.
- Inspired by real-world dual-boot resilience challenges faced by users worldwide.
🔄 Always keep a Live USB handy. Prevention is better than recovery.
- Fixed broken link syntax (removed unnecessary parentheses around URLs).
- Improved readability with consistent headers, lists, and spacing.
- Added icons and visual cues for enhanced scanning.
- Clarified technical language and commands.
- Structured tables and code blocks for clarity.
- Enhanced troubleshooting section with actionable steps.
- Made tone more professional yet accessible.
- Ensured cross-referencing works smoothly (e.g., linking sections).